• 구성 템플릿과 함께 캐시 사용
  • Amazon S3
  • Google Cloud Storage (GCS)
    • 직접 구성된 정적 자격 증명
    • GCP에서 다운로드한 JSON 파일의 정적 자격 증명
  • Azure
• RBAC 지원 활성화
• 최대 러너 동시성 제어
• GitLab Runner에서 Docker-in-Docker 컨테이너 실행
• 러너를 위한 특권 컨테이너 사용
  • 권한 없는 모드에서 컨테이너 빌드를 위한 모범 사례
• 개인 레지스트리에서 이미지 사용
• GitLab에 사용자 정의 인증서로 액세스하기
  • 인증서 준비하기
  • Kubernetes secret 생성하기
  • 차트에 비밀 제공하기
• 포드 레이블을 CI 환경 변수 키로 설정하기
• Ubuntu 기반 gitlab-runner Docker 이미지로 전환
• 비루트 사용자로 실행
• FIPS 준수 GitLab Runner 사용
• 구성 템플릿 사용

GitLab Runner Helm 차트 구성

이 페이지는 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. gcsaccess Kubernetes 비밀을 생성하여 gcs-access-id와 gcs-private-key를 포함하세요:

   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을 참조하세요.

RBAC 지원 활성화

클러스터에 RBAC(역할 기반 접근 제어)가 활성화되어 있는 경우, 차트는 자체 서비스 계정을 생성하거나 하나를 제공할 수 있습니다.

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

  rbac:
    create: true
  

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

  rbac:
    create: false
    serviceAccountName: your-service-account
  

최대 러너 동시성 제어

Kubernetes에 배포된 단일 러너는 추가 러너 팟을 시작하여 여러 작업을 병렬로 실행할 수 있습니다.

동시 허용 최대 팟 수를 변경하려면 concurrent 설정을 편집하세요. 기본값은 10입니다:

## 동시 작업의 최대 수 구성
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#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 러너 문서에 설명되어 있습니다.
• GitLab Runner 인스턴스가 GitLab의 특정 프로젝트에 등록되어 있으며, 해당 CI/CD 작업을 신뢰해야 합니다.

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

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        # 모든 컨테이너를 특권 플래그가 활성화된 상태로 실행합니다.
        privileged = true
        ...

자세한 내용은 [runners.kubernetes] 섹션의 고급 구성 정보를 참조하세요.

권한 없는 모드에서 컨테이너 빌드를 위한 모범 사례

Docker-in-Docker에서 컨테이너를 빌드하려면 Docker 권한 모드가 필요합니다. Google의 Kaniko는 권한 모드 없이 작동하는 대안이며, Kubernetes GitLab Runner에서 테스트되었습니다.

GitLab에서 Kaniko로 최소 권한 컨테이너 빌드 비디오는 Kaniko Docker Build 작업 예제 프로젝트의 안내서입니다. 이 문서는 Kaniko 및 GitLab CI/CD로 이미지 빌드 문서를 사용합니다.

테스트를 위해, 작업 예제 프로젝트를 귀하의 그룹이나 인스턴스에 복사하세요. 사용 가능한 다른 GitLab CI/CD 패턴에 대한 자세한 내용은 Kaniko Docker Build를 참조하세요.

개인 레지스트리에서 이미지 사용

개인 레지스트리에서 이미지를 사용하려면 imagePullSecrets를 구성하십시오.

1. CI/CD 작업에 사용되는 Kubernetes 네임스페이스에 하나 이상의 비밀을 만듭니다. 이 명령은 image_pull_secrets와 함께 작동하는 비밀을 생성합니다:

   kubectl create secret docker-registry <SECRET_NAME> \
     --namespace <NAMESPACE> \
     --docker-server="https://<REGISTRY_SERVER>" \
     --docker-username="<REGISTRY_USERNAME>" \
     --docker-password="<REGISTRY_PASSWORD>"
   

2. GitLab Runner Helm 차트 버전 0.53.x 이상에서, config.toml에서 제공된 템플릿에서 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에 값을 설정합니다. 이 값을 설정하면, 컨테이너는 이미지 entrypoint 스크립트에 --kubernetes-image-pull-secrets "<SECRET_NAME>"를 추가합니다. 이를 통해 Kubernetes 실행자의 config.toml 설정에서 image_pull_secrets 매개변수를 구성할 필요가 없습니다.

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

참고: imagePullSecrets의 값은 Kubernetes 리소스에서의 관습처럼 name 태그로 접두사가 붙지 않습니다. 이 값은 하나 이상의 비밀 이름의 배열을 요구하며, 하나의 레지스트리 자격 증명만 사용하는 경우에도 마찬가지입니다.

imagePullSecrets 생성 방법에 대한 자세한 내용은 Kubernetes 문서에서 개인 레지스트리에서 이미지 가져오기를 참조하세요.

GitLab에 사용자 정의 인증서로 액세스하기

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

1. 인증서 준비하기
2. Kubernetes secret 생성하기
3. 차트에 비밀 제공하기

인증서 준비하기

Kubernetes secret의 각 키 이름은 디렉터리 내 파일 이름으로 사용되며, 파일 내용은 키와 연관된 값입니다:

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

Kubernetes secret 생성하기

자동 생성된 자체 서명 와일드카드 인증서(auto-generated self-signed wildcard certificate) 방법을 사용하여 GitLab Helm 차트를 설치했다면, 비밀이 자동으로 생성되었습니다.

자동 생성된 자체 서명 와일드카드 인증서를 사용하여 GitLab Helm 차트를 설치하지 않은 경우 비밀을 생성하세요.

이 명령들은 Kubernetes에 인증서를 비밀로 저장하고, GitLab Runner 컨테이너에 파일로 제공됩니다.

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

  kubectl create secret generic <SECRET_NAME> \
    --namespace <NAMESPACE> \
    --from-file=<CERTIFICATE_FILENAME>
  

  • <NAMESPACE>: GitLab Runner를 설치할 Kubernetes 네임스페이스입니다.
  • <SECRET_NAME>: gitlab-domain-cert와 같은 Kubernetes 비밀 리소스 이름입니다.
  • <CERTIFICATE_FILENAME>: 비밀로 가져올 현재 디렉터리의 인증서 파일 이름입니다.

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

  kubectl create secret generic <SECRET_NAME> \
    --namespace <NAMESPACE> \
    --from-file=<TARGET_FILENAME>=<CERTIFICATE_FILENAME>
  

  • <TARGET_FILENAME>은 Runner 컨테이너에 제공되는 인증서 파일의 이름입니다. 예: gitlab.hostname.crt.
  • <CERTIFICATE_FILENAME>은 비밀로 가져올 인증서의 현재 디렉터리에 대한 상대 파일 이름입니다. 예: cert-directory/my-gitlab-certificate.crt.

차트에 비밀 제공하기

values.yaml에서 certsSecretName을 같은 네임스페이스 내의 Kubernetes secret 객체의 리소스 이름으로 설정하세요. 이렇게 하면 GitLab Runner가 사용할 사용자 정의 인증서를 전달할 수 있습니다. 이전 예에서 리소스 이름은 gitlab-domain-cert였습니다:

 certsSecretName: <SECRET NAME>

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

포드 레이블을 CI 환경 변수 키로 설정하기

values.yaml 파일에서 환경 변수를 포드 레이블로 사용할 수 없습니다.

자세한 내용은 환경 변수 키를 포드 레이블로 설정할 수 없습니다를 참조하세요.

문제에 설명된 해결 방법을 임시 해결책으로 사용하세요.

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

기본적으로, GitLab Runner Helm 차트는 musl libc를 사용하는 Alpine 버전의 gitlab/gitlab-runner 이미지를 사용합니다.

Ubuntu 기반 이미지를 사용해야 할 수도 있으며, 이 이미지는 glibc를 사용합니다.

이를 위해 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 빌드 파드의 동작을 구성하려면, 구성 템플릿 파일을 사용하세요.

구성 템플릿은 특정 Runner 구성 옵션을 Helm 차트와 공유하지 않고도 Runner의 모든 필드를 구성할 수 있습니다.

예를 들어, chart 리포지토리의 values.yaml 파일에서 발견되는 이러한 기본 설정:

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

config: 섹션의 값은 TOML 형식을 사용해야 하며 (<parameter> = <value> 대신 <parameter>: <value>), config.toml은 values.yaml에 포함되어 있습니다.

특정 실행자 구성에 대해서는 values.yaml 파일을 참조하세요.