GitLab Runner Helm 차트에 선택적 설정을 추가할 수 있습니다.

설정 템플릿과 함께 캐시 사용#

설정 템플릿과 함께 캐시를 사용하려면 values.yaml에 다음 변수를 설정하세요:

• runners.cache.secretName: 오브젝트 스토리지 공급자의 시크릿 이름. 옵션: s3access, gcsaccess, google-application-credentials, 또는 azureaccess.
• runners.config: TOML 형식의 캐시에 대한 기타 설정.

Amazon S3#

정적 자격 증명으로 Amazon S3 설정하려면:

1. values.yaml에 다음 예시를 추가하고 필요한 값을 변경하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           image = "ubuntu:22.04"
         [runners.cache]
           Type = "s3"
           Path = "runner"
           Shared = true
           [runners.cache.s3]
             ServerAddress = "s3.amazonaws.com"
             BucketName = "my_bucket_name"
             BucketLocation = "eu-west-1"
             Insecure = false
             AuthenticationType = "access-key"
   
     cache:
         secretName: s3access
   

2. accesskey와 secretkey를 포함하는 s3access Kubernetes 시크릿을 생성하세요:

   kubectl create secret generic s3access \
       --from-literal=accesskey="YourAccessKey" \
       --from-literal=secretkey="YourSecretKey"
   

Google Cloud Storage (GCS)#

Google Cloud Storage는 여러 방법으로 정적 자격 증명을 사용하여 설정할 수 있습니다.

직접 설정된 정적 자격 증명#

액세스 ID와 프라이빗 키를 사용하여 GCS에 자격 증명을 설정하려면:

1. values.yaml에 다음 예시를 추가하고 필요한 값을 변경하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           image = "ubuntu:22.04"
         [runners.cache]
           Type = "gcs"
           Path = "runner"
           Shared = true
           [runners.cache.gcs]
             BucketName = "runners-cache"
   
     cache:
       secretName: gcsaccess
   

2. gcs-access-id와 gcs-private-key를 포함하는 gcsaccess Kubernetes 시크릿을 생성하세요:

   kubectl create secret generic gcsaccess \
       --from-literal=gcs-access-id="YourAccessID" \
       --from-literal=gcs-private-key="YourPrivateKey"
   

GCP에서 다운로드한 JSON 파일의 정적 자격 증명#

Google Cloud Platform에서 다운로드한 JSON 파일의 자격 증명으로 GCS를 설정하려면:

1. values.yaml에 다음 예시를 추가하고 필요한 값을 변경하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           image = "ubuntu:22.04"
         [runners.cache]
           Type = "gcs"
           Path = "runner"
           Shared = true
           [runners.cache.gcs]
             BucketName = "runners-cache"
   
     cache:
         secretName: google-application-credentials
   
   secrets:
     - name: google-application-credentials
   

2. google-application-credentials라는 Kubernetes 시크릿을 생성하고 JSON 파일을 로드하세요. 필요에 따라 경로를 변경하세요:

   kubectl create secret generic google-application-credentials \
       --from-file=gcs-application-credentials-file=./PATH-TO-CREDENTIALS-FILE.json
   

Azure#

Azure Blob Storage를 설정하려면:

1. values.yaml에 다음 예시를 추가하고 필요한 값을 변경하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           image = "ubuntu:22.04"
         [runners.cache]
           Type = "azure"
           Path = "runner"
           Shared = true
           [runners.cache.azure]
             ContainerName = "CONTAINER_NAME"
             StorageDomain = "blob.core.windows.net"
   
     cache:
         secretName: azureaccess
   

2. azure-account-name과 azure-account-key를 포함하는 azureaccess Kubernetes 시크릿을 생성하세요:

   kubectl create secret generic azureaccess \
       --from-literal=azure-account-name="YourAccountName" \
       --from-literal=azure-account-key="YourAccountKey"
   

Helm 차트 캐싱에 대한 자세한 내용은 values.yaml을 참조하세요.

영구 볼륨 클레임#

오브젝트 스토리지 옵션이 적합하지 않은 경우 캐싱에 영구 볼륨 클레임(PVC)을 사용할 수 있습니다.

캐시가 PVC를 사용하도록 설정하려면:

1. 잡 파드가 실행될 네임스페이스에 PVC를 생성하세요.

   [!note] 여러 잡 파드가 동일한 캐시 PVC에 접근하도록 하려면 ReadWriteMany 액세스 모드가 있어야 합니다.

2. PVC를 /cache 디렉토리에 마운트하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           image = "ubuntu:22.04"
         [[runners.kubernetes.volumes.pvc]]
           name = "cache-pvc"
           mount_path = "/cache"
   

네트워크 파일 시스템#

오브젝트 스토리지를 사용할 수 없는 경우 캐싱에 네트워크 파일 시스템(NFS)을 사용합니다.

사전 요구 사항:

• Kubernetes 클러스터에서 NFS가 구성되고 접근 가능해야 합니다. 자세한 내용은 Kubernetes 문서의 nfs 볼륨을 참조하세요.

캐시가 NFS를 사용하도록 설정하려면:

• NFS 볼륨을 /cache 디렉터리에 마운트하세요:

  runners:
    config: |
      [[runners]]
        [runners.kubernetes]
          image = "ubuntu:22.04"
        [[runners.kubernetes.volumes.nfs]]
          name = "nfs"
          mount_path = "/cache"
          read_only = false
          server = "foo.bar.com"
          path = "/path/on/nfs-share"
  

RBAC 지원 활성화#

클러스터에 RBAC(권한 기반 액세스 제어)가 활성화된 경우, 차트가 자체 서비스 계정을 생성하거나 기존 서비스 계정을 제공할 수 있습니다.

• 차트가 서비스 계정을 생성하도록 하려면 rbac.create를 true로 설정하세요:

  rbac:
    create: true
  

• 기존 서비스 계정을 사용하려면 serviceAccount.name을 설정하세요:

  rbac:
    create: false
  serviceAccount:
    create: false
    name: your-service-account
  

최대 러너 동시성 제어#

Kubernetes에 배포된 단일 러너는 추가 Runner 파드를 시작하여 여러 잡을 병렬로 실행할 수 있습니다. 한 번에 허용되는 최대 파드 수를 변경하려면 concurrent 설정을 편집하세요. 기본값은 10입니다:

## 동시 잡의 최대 수를 설정합니다
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration/#the-global-section
##
concurrent: 10

이 설정에 대한 자세한 내용은 GitLab Runner 고급 설정 문서의 글로벌 섹션을 참조하세요.

GitLab Runner로 Docker-in-Docker 컨테이너 실행#

GitLab Runner로 Docker-in-Docker 컨테이너를 사용하려면:

• 활성화하려면 러너에 권한 있는 컨테이너 사용을 참조하세요.
• Docker-in-Docker 실행 지침은 GitLab Runner 문서를 참조하세요.

러너에 권한 있는 컨테이너 사용#

GitLab CI/CD 잡에서 Docker 실행 파일을 사용하려면 러너가 권한 있는 컨테이너를 사용하도록 설정하세요.

사전 요구 사항:

• GitLab CI/CD Runner 문서에 설명된 위험을 이해해야 합니다.
• GitLab Runner 인스턴스가 GitLab의 특정 프로젝트에 등록되어 있고, CI/CD 잡을 신뢰해야 합니다.

values.yaml에서 권한 있는 모드를 활성화하려면 다음 줄을 추가하세요:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        # 모든 컨테이너에 privileged 플래그를 활성화하여 실행합니다.
        privileged = true
        ...

자세한 내용은 [runners.kubernetes] 섹션에 대한 고급 설정 정보를 참조하세요.

프라이빗 레지스트리의 이미지 사용#

프라이빗 레지스트리의 이미지를 사용하려면 imagePullSecrets를 설정하세요.

1. CI/CD 잡에 사용되는 Kubernetes 네임스페이스에 하나 이상의 시크릿을 생성하세요. 이 명령은 image_pull_secrets와 함께 작동하는 시크릿을 생성합니다:

   kubectl create secret docker-registry  \
     --namespace  \
     --docker-server="https://" \
     --docker-username="" \
     --docker-password=""
   

2. GitLab Runner Helm 차트 버전 0.53.x 이상의 경우, config.toml에서 runners.config에 제공된 템플릿으로부터 image_pull_secret을 설정하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           ## 하나 이상의 imagePullSecrets 지정
           ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
           ##
           image_pull_secrets = [your-image-pull-secret]
   

   자세한 내용은 Kubernetes 문서의 프라이빗 레지스트리에서 이미지 풀을 참조하세요.

3. GitLab Runner Helm 차트 버전 0.52 이하의 경우, values.yaml에서 runners.imagePullSecrets 값을 설정하세요. 이 값을 설정하면 컨테이너가 이미지 진입점 스크립트에 --kubernetes-image-pull-secrets ""을 추가합니다. 이렇게 하면 Kubernetes executor config.toml 설정에서 image_pull_secrets 파라미터를 설정할 필요가 없어집니다.

   runners:
     imagePullSecrets: [your-image-pull-secret]
   

imagePullSecrets 생성 방법에 대한 자세한 내용은 Kubernetes 문서의 프라이빗 레지스트리에서 이미지 풀을 참조하세요.

잡 파드가 생성될 때 GitLab Runner는 두 단계로 이미지 접근을 자동으로 처리합니다:

1. GitLab Runner는 기존 Docker 자격 증명을 Kubernetes 시크릿으로 변환하여 레지스트리에서 이미지를 풀할 수 있도록 합니다. 수동으로 설정된 imagePullSecrets가 클러스터에 실제로 존재하는지도 확인합니다. 정적으로 정의된 자격 증명, 자격 증명 저장소, 또는 자격 증명 헬퍼에 대한 자세한 내용은 프라이빗 컨테이너 레지스트리에서 이미지 접근을 참조하세요.
2. GitLab Runner는 잡 파드를 생성하고 두 유형의 자격 증명을 모두 연결합니다: imagePullSecrets와 변환된 Docker 자격 증명을 해당 순서로 연결합니다.

Kubernetes가 컨테이너 이미지를 풀해야 할 때, 작동하는 자격 증명을 찾을 때까지 하나씩 시도합니다.

사용자 정의 인증서로 GitLab 접근#

사용자 정의 인증서를 사용하려면 GitLab Runner Helm 차트에 Kubernetes 시크릿을 제공하세요. 이 시크릿은 컨테이너의 /home/gitlab-runner/.gitlab-runner/certs 디렉토리에 추가됩니다:

1. 인증서 준비
2. Kubernetes 시크릿 생성
3. 차트에 시크릿 제공

인증서 준비#

Kubernetes 시크릿의 각 키 이름은 디렉토리의 파일 이름으로 사용되며, 파일 내용은 키에 연결된 값입니다:

• 사용되는 파일 이름은 <gitlab.hostname>.crt 형식이어야 합니다. 예: gitlab.your-domain.com.crt.
• 중간 인증서를 서버 인증서와 함께 동일한 파일에 연결하세요.
• 사용된 호스트 이름은 인증서가 등록된 호스트 이름이어야 합니다.

Kubernetes 시크릿 생성#

자동 생성된 자체 서명 와일드카드 인증서 방법을 사용하여 GitLab Helm 차트를 설치한 경우 시크릿이 자동으로 생성됩니다.

자동 생성된 자체 서명 와일드카드 인증서로 GitLab Helm 차트를 설치하지 않은 경우 시크릿을 생성하세요. 이 명령들은 인증서를 Kubernetes 시크릿으로 저장하고 GitLab Runner 컨테이너에 파일로 제공합니다.

• 인증서가 현재 디렉토리에 있고 <gitlab.hostname.crt> 형식을 따르는 경우, 필요에 따라 이 명령을 수정하세요:

  kubectl create secret generic  \
    --namespace  \
    --from-file=
  

  • : GitLab Runner를 설치할 Kubernetes 네임스페이스.
  • : gitlab-domain-cert와 같은 Kubernetes Secret 리소스 이름.
  • : 시크릿으로 가져올 현재 디렉토리의 인증서 파일 이름.

• 인증서가 다른 디렉토리에 있거나 <gitlab.hostname.crt> 형식을 따르지 않는 경우, 대상으로 사용할 파일 이름을 지정해야 합니다:

  kubectl create secret generic  \
    --namespace  \
    --from-file==
  

  • 은 Runner 컨테이너에 제공되는 인증서 파일 이름입니다. 예: gitlab.hostname.crt.
  • 은 시크릿으로 가져올 현재 디렉토리 기준의 인증서 파일 이름입니다. 예: cert-directory/my-gitlab-certificate.crt.

차트에 시크릿 제공#

values.yaml에서 certsSecretName을 동일 네임스페이스의 Kubernetes 시크릿 오브젝트 리소스 이름으로 설정하세요. 이를 통해 GitLab Runner가 사용할 사용자 정의 인증서를 전달할 수 있습니다. 이전 예시에서 리소스 이름은 gitlab-domain-cert였습니다:

certsSecretName:  NAME>

자세한 내용은 GitLab 서버를 대상으로 하는 자체 서명 인증서의 지원 옵션을 참조하세요.

CI 환경 변수 키로 파드 레이블 설정#

values.yaml 파일에서 파드 레이블로 환경 변수를 사용할 수 없습니다. 자세한 내용은 환경 변수 키를 파드 레이블로 설정할 수 없음을 참조하세요. 임시 해결 방법으로 이슈에 설명된 우회 방법을 사용하세요.

Ubuntu 기반 gitlab-runner Docker 이미지로 전환#

기본적으로 GitLab Runner Helm 차트는 musl libc를 사용하는 gitlab/gitlab-runner 이미지의 Alpine 버전을 사용합니다. glibc를 사용하는 Ubuntu 기반 이미지로 전환해야 할 수도 있습니다.

이 작업을 수행하려면 values.yaml 파일에 다음 값을 사용하여 이미지를 지정하세요:

# Ubuntu 이미지를 지정하고 버전을 설정합니다. `ubuntu` 또는 `latest` 태그를 사용할 수도 있습니다.
image: gitlab/gitlab-runner:v17.3.0

# Ubuntu 이미지의 사용자 ID에 맞게 보안 컨텍스트 값을 업데이트합니다
securityContext:
  fsGroup: 999
  runAsUser: 999

루트가 아닌 사용자로 실행#

기본적으로 GitLab Runner 이미지는 루트가 아닌 사용자와 함께 작동하지 않습니다. GitLab Runner UBI와 GitLab Runner Helper UBI 이미지는 이 시나리오를 위해 설계되었습니다.

이를 사용하려면 values.yaml에서 GitLab Runner 및 GitLab Runner Helper 이미지를 변경하세요:

image:
  registry: registry.gitlab.com
  image: gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp
  tag: v16.11.0

securityContext:
    runAsNonRoot: true
    runAsUser: 999

runners:
    config: |
        [[runners]]
          [runners.kubernetes]
            helper_image = "registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:x86_64-v16.11.0"
            [runners.kubernetes.pod_security_context]
              run_as_non_root = true
              run_as_user = 59417

run_as_user가 nonroot 사용자의 사용자 ID(59417)를 가리키지만, 이미지는 모든 사용자 ID와 함께 작동합니다. 이 사용자 ID가 루트 그룹의 일부인 것이 중요합니다. 루트 그룹의 일부라고 해서 특별한 권한이 부여되지는 않습니다.

FIPS 준수 GitLab Runner 사용#

FIPS 준수 GitLab Runner를 사용하려면 values.yaml에서 GitLab Runner 이미지와 Helper 이미지를 변경하세요:

image:
  registry: docker.io
  image: gitlab/gitlab-runner
  tag: ubi-fips

runners:
    config: |
        [[runners]]
          [runners.kubernetes]
            helper_image_flavor = "ubi-fips"

설정 템플릿 사용#

Kubernetes에서 GitLab Runner 빌드 파드의 동작을 설정하려면 설정 템플릿 파일을 사용하세요. 설정 템플릿은 특정 러너 설정 옵션을 Helm 차트와 공유하지 않고도 러너의 모든 필드를 설정할 수 있습니다. 예를 들어, chart 리포지터리의 values.yaml 파일에서 찾을 수 있는 기본 설정:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:22.04"

config: 섹션의 값은 config.toml이 values.yaml에 임베드되어 있으므로 TOML(<parameter>: <value> 대신 <parameter> = <value>)을 사용해야 합니다.

executor별 설정은 values.yaml 파일을 참조하세요.