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

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

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

• runners.cache.secretName: 오브젝트 스토리지 공급자의 시크릿 이름. 옵션: s3access, gcsaccess, google-application-credentials, 또는 azureaccess.

• runners.config: TOML 형식의 캐시에 대한 기타 설정.

Amazon S3#

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

필요한 값을 변경하여 이 예시를 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

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에 자격 증명을 설정하려면:

필요한 값을 변경하여 이 예시를 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

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를 설정하려면:

필요한 값을 변경하여 이 예시를 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

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를 설정하려면:

필요한 값을 변경하여 이 예시를 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

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를 사용하도록 설정하려면:

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

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

- 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

최대 러너 동시성 제어#

쿠버네티스에 배포된 단일 러너는 추가 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]
        # Run all containers with the privileged flag enabled.
        privileged = true
        ...

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

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

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

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

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

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

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        ## Specify one or more imagePullSecrets
        ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
        ##
        image_pull_secrets = [your-image-pull-secret]

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

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 리소스의 관례처럼 `name` 태그로 시작하지 않습니다. 이 값은 레지스트리 자격 증명이 하나만 사용되더라도 하나 이상의 시크릿 이름 배열이 필요합니다.

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

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

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

• GitLab Runner는 잡 파드를 생성하고 두 유형의 자격 증명을 모두 연결합니다: imagePullSecrets와 변환된 Docker 자격 증명을 해당 순서로 연결합니다.

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

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

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

• 인증서 준비

• Kubernetes 시크릿 생성

• 차트에 시크릿 제공

인증서 준비#

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: 

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

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

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

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

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

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

# Specify the Ubuntu image, and set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v17.3.0

# Update the security context values to the user ID in the Ubuntu image
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"

설정 템플릿 사용#

쿠버네티스에서 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 파일을 참조하세요.