• 구성 템플릿과 함께 캐시 사용하기
  • Amazon S3
  • Google Cloud Storage (GCS)
    • 직접 구성된 정적 자격 증명
    • GCP에서 다운로드한 JSON 파일의 정적 자격 증명
  • Azure
• RBAC(Role-Based Access Control) 지원 활성화
• Runner 동시성 제어
• GitLab Runner를 사용하여 Docker-in-Docker 컨테이너 실행
• 런너용 권한있는 컨테이너 사용
  • 권한없는 모드로 컨테이너 빌드하기 위한 모범 사례
• 개인 레지스트리에서 이미지 사용
• 사용자 정의 인증서로 GitLab에 액세스
  • 인증서 준비
  • Kubernetes 시크릿 생성
  • 차트의 비밀번호 제공
• 파드 라벨을 CI 환경 변수 키로 설정
• Ubuntu 기반 gitlab-runner 도커 이미지로 전환
• 루트 이외의 사용자로 실행
• 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. s3access 쿠버네티스 시크릿을 생성하고 accesskey와 secretkey를 포함시킵니다.

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

Google Cloud Storage (GCS)

Google Cloud Storage는 여러 방법으로 정적 자격 증명으로 구성할 수 있습니다.

직접 구성된 정적 자격 증명

GCS를 액세스 ID와 개인 키로 구성하는 방법은 다음과 같습니다:

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 쿠버네티스 시크릿을 생성하고 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 파일의 정적 자격 증명

GCP에서 다운로드한 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 쿠버네티스 시크릿을 생성하고 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. azureaccess 쿠버네티스 시크릿을 생성하고 azure-account-name과 azure-account-key를 포함시킵니다.

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

Helm 차트 캐싱에 대해 자세히 알아보려면 values.yaml를 참조하세요.

RBAC(Role-Based Access Control) 지원 활성화

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

• 차트가 대신 서비스 계정을 만들도록 하려면 rbac.create를 true로 설정합니다:

  rbac:
    create: true
  

• 기존 서비스 계정을 사용하려면 serviceAccountName을 설정합니다:

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

Runner 동시성 제어

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

## 동시 작업 수를 최대로 구성합니다.
## 참조: 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 Runner 문서에 설명된 리스크를 이해하셔야 합니다.
• GitLab Runner 인스턴스가 GitLab의 특정 프로젝트에 등록되어 있고 해당 CI/CD 작업을 신뢰해야 합니다.

values.yaml에서 privileged 모드를 활성화하려면 다음 라인을 추가하세요:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        # 모든 컨테이너를 권한있게 실행합니다.
        privileged = true
        ...

추가 정보는 [runners.kubernetes] 섹션에 대한 고급 구성 정보를 참조하세요.

권한없는 모드로 컨테이너 빌드하기 위한 모범 사례

Docker-in-Docker로 컨테이너 내에서 컨테이너를 빌드하려면 Docker 권한없는 모드가 필요합니다. 구글의 Kaniko는 권한없는 모드로 작동하는 대체 도구로 쿠버네티스 GitLab Runner에서 테스트되었습니다.

GitLab에서 Kaniko로 최소한의 권한을 가진 컨테이너 빌드 비디오는 Kaniko Docker 빌드의 작동 예제 프로젝트를 소개합니다. 다음 문서를 사용합니다: Kaniko 및 GitLab CI/CD를 사용하여 이미지 빌드.

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

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

개인 레지스트리에서 이미지를 사용하려면 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에 runners.config에서 제공된 템플릿을 사용하여 image_pull_secret를 설정하세요:

   runners:
     config: |
       [[runners]]
         [runners.kubernetes]
           ## 하나 이상의 imagePullSecrets를 지정하세요
           ## 참조: 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 "<SECRET_NAME>"를 추가합니다. 이로써 쿠버네티스 executor config.toml 설정에서 image_pull_secrets 매개변수를 구성할 필요가 없어집니다.

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

참고: imagePullSecrets의 값은 Kubernetes 리소스의 관례인 name 태그로 접두사가 되지 않습니다. 이 값은 하나 이상의 시크릿 이름의 배열을 필요로 합니다. 하나의 레지스트리 자격 증명만 사용하더라도 배열로 지정해야 합니다.

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

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

사용자 정의 인증서를 사용하려면 GitLab Runner Helm 차트에 Kubernetes secret를 제공하세요. 해당 시크릿은 컨테이너의 /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.hostname.crt> 형식에 따라 명령을 수정하세요:

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

  • <NAMESPACE>: GitLab Runner를 설치하려는 Kubernetes 네임스페이스입니다.
  • <SECRET_NAME>: gitlab-domain-cert와 같은 Kubernetes Secret 자원 이름입니다.
  • <CERTIFICATE_FILENAME>: 시크릿에 가져올 현재 디렉터리의 인증서 파일 이름입니다.

• 인증서가 다른 디렉터리에 있거나 <gitlab.hostname.crt> 형식이 아닌 경우 목표로 사용할 파일 이름을 지정해야 합니다:

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

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

차트의 비밀번호 제공

values.yaml에서 certsSecretName을 동일한 네임스페이스의 쿠버네티스 시크릿 오브젝트의 리소스 이름으로 설정하십시오. 이렇게 하면 GitLab Runner에서 사용할 사용자 정의 인증서를 전달할 수 있습니다. 이전 예제에서 리소스 이름은 gitlab-domain-cert였습니다:

 certsSecretName: <시크릿 이름>

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

파드 라벨을 CI 환경 변수 키로 설정

values.yaml 파일에서 환경 변수를 파드 라벨로 사용할 수 없습니다. 자세한 내용은 환경 변수 키를 파드 라벨로 설정할 수 없습니다를 참조하세요. 일시적인 해결책으로 이 문제에 설명된 워크어라운드을 사용하십시오.

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

기본적으로 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 차트와 특정 Runner 구성 옵션을 구체적으로 공유하지 않고도 실행기의 모든 필드를 구성할 수 있습니다. 예를 들면, values.yaml 파일의 기본 설정내에 있는 다음 설정:

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

config: 섹션의 값은 TOML을 사용해야 합니다(<parameter> = <value> 대신 <parameter>: <value>를 사용하지 않음). config.toml은 values.yaml에 임베드되어 있습니다.

실행기별 구성에 대한 자세한 내용은 다음 values.yaml 파일을 참조하세요.