• runner가 Kubernetes pod를 생성하는 방법
• Kubernetes API에 연결
  • Kubernetes API 호출을 위한 베어러 토큰 설정
  • runner API 권한 구성
• 구성 설정
  • CPU 요청 및 제약
  • 메모리 요청 및 제한
  • 저장 공간 요청 및 제한
  • 기타 config.toml 설정
  • 구성 예제
• 실행자 서비스 계정 구성
• Pods 및 컨테이너
  • 작업 Pods를 위한 기본 주석
  • Pod 라이프사이클
  • Pod Toleration 덮어쓰기
  • Pod 라벨 덮어쓰기
  • 포드 주석 덮어쓰기
  • 생성된 포드 사양 덮어쓰기
    • Merge 패치 전략
    • JSON 패치 전략
    • 전략적 패치 전략
    • 모범 사례
    • 각 빌드 작업에 대한 PVC 만들기: Pod Spec 수정
  • Pod에 대한 보안 정책 설정
  • 오래된 runner pods 제거
  • 컨테이너의 보안 정책 설정
  • Pull 정책 설정
  • 컨테이너 capabilities 지정
  • 컨테이너 리소스 덮어쓰기
  • 서비스 디렉터리 정의
  • 서비스 컨테이너 리소스 덮어쓰기
  • Kubernetes 기본 서비스 계정 덮어쓰기
  • RuntimeClass 설정
• 노드
  • 노드 어핀리티 디렉터리 정의
  • 파드가 예정된 노드를 정의합니다
  • 노드 셀렉터 덮어쓰기
  • 빌드를 실행할 노드 지정
    • linux/arm64 예제
    • windows/amd64 예제
• 네트워킹
  • 컨테이너 라이프사이클 후크 구성
    • KubernetesLifecycleExecAction
    • KubernetesLifecycleHTTPGet
    • KubernetesLifecycleHTTPGetHeader
    • KubernetesLifecycleTcpSocket
  • 포드 DNS 설정 구성
    • KubernetesDNSConfigOption
    • 기본 삭제된 기능 디렉터리
  • 추가 호스트 별칭 추가
• 볼륨
  • Kubernetes executor와 함께 캐시 사용
  • 볼륨 유형 구성
    • hostPath 볼륨
    • persistentVolumeClaim 볼륨
    • configMap 볼륨
    • secret 볼륨
    • emptyDir 볼륨
    • csi 볼륨
  • 서비스 컨테이너에 볼륨 장착
  • 사용자 지정 볼륨 마운트
  • 영구적인 동시 빌드용 볼륨
  • 도우미 이미지 사용
• 빌드에서 Docker 사용
  • 노출된 /var/run/docker.sock
  • docker:dind 사용
  • 호스트 커널 노출 방지
  • kaniko를 사용하여 Docker 이미지 빌드하기
  • Docker 이미지 및 서비스 제한
  • Docker 풀 정책 제한
• 작업 실행
  • Kubernetes API의 요청 시도 횟수 구성
  • 컨테이너 entrypoint 알려진 문제점
  • 작업 변수 액세스 제한
• 준비 단계에서 리소스 확인
  • Kubernetes 네임스페이스 덮어쓰기

Kubernetes executor

Kubernetes executor를 사용하여 빌드에 Kubernetes 클러스터를 사용할 수 있습니다. Executor는 Kubernetes 클러스터 API를 호출하고 각 GitLab CI 작업에 대해 Pod를 생성합니다.

Kubernetes executor는 빌드를 여러 단계로 나눕니다:

1. 준비: Kubernetes 클러스터에 Pod를 생성합니다. 이는 빌드 및 서비스를 실행하는 데 필요한 컨테이너를 생성합니다.

2. 사전 빌드: 이전 단계에서 아티팩트를 복제하고 복원하며 다운로드합니다. 이 단계는 Pod의 일부로서 별도의 컨테이너에서 실행됩니다.

3. 빌드: 사용자 빌드

4. 사후 빌드: 캐시를 생성하고 GitLab에 아티팩트를 업로드합니다. 이 단계도 Pod의 일부로서 별도의 컨테이너를 사용합니다.

runner가 Kubernetes pod를 생성하는 방법

다음 다이어그램은 GitLab 인스턴스와 Kubernetes 클러스터에 호스팅된 runner 간의 상호 작용을 보여줍니다. runner는 클러스터에 Pod를 생성하기 위해 Kubernetes API를 호출합니다.

각 service에 대해 .gitlab-ci.yml 또는 config.toml 파일에 정의된 다음의 컨테이너로 구성된 Pod가 구성됩니다:

• build로 정의된 빌드 컨테이너
• helper로 정의된 도우미 컨테이너
• svc-X로 정의된 서비스 컨테이너, 여기서 X는 [0-9]+입니다.

서비스 및 컨테이너는 동일한 Kubernetes pod에서 실행되며 동일한 localhost 주소를 공유합니다. 다음 제한사항이 적용됩니다:

• GitLab Runner 12.8 및 Kubernetes 1.7 이상에서는 서비스가 DNS 이름을 통해 액세스할 수 있습니다. 이전 버전을 사용하는 경우 localhost를 사용해야 합니다.
• 동일한 포트를 사용하는 여러 서비스를 사용할 수 없습니다. 예를 들어 동시에 두 개의 mysql 서비스를 가질 수 없습니다.

다이어그램에서의 상호 작용은 모든 Kubernetes 클러스터에 대해 유효합니다. 예를 들어, 주요 공용 클라우드 제공 업체에 호스팅된 신속한 솔루션 또는 Self-managed Kubernetes 설치 등이 있습니다.

Kubernetes API에 연결

Kubernetes API에 연결하려면 다음 옵션을 사용하세요. 제공된 사용자 계정에는 지정된 네임스페이스의 Pod를 생성, 나열, 첨부할 수 있는 권한이 있어야 합니다.

GitLab Runner를 Kubernetes 클러스터에서 실행 중이라면 이러한 필드를 모두 생략하여 GitLab Runner가 Kubernetes API를 자동으로 찾을 수 있게 해야 합니다.

Kubernetes 클러스터 외부에서 GitLab Runner를 실행 중이라면 각 설정을 지정하고 GitLab Runner가 클러스터의 Kubernetes API에 액세스할 수 있도록 해야 합니다.

Kubernetes API 호출을 위한 베어러 토큰 설정

Pod를 생성하는 API 호출에 대한 베어러 토큰을 설정하려면 KUBERNETES_BEARER_TOKEN 변수를 사용하세요. 이를 통해 프로젝트 소유자는 프로젝트 비공개 변수를 사용하여 베어러 토큰을 지정할 수 있습니다.

베어러 토큰을 지정할 때는 Host 구성 설정을 지정해야 합니다.

variables:
  KUBERNETES_BEARER_TOKEN: 다른 네임스페이스에서 가져온 베어러 토큰

runner API 권한 구성

코어 API 그룹에 대한 권한을 구성하려면 GitLab Runner Helm 차트의 values.yml 파일을 업데이트하세요.

다음 중 하나를 선택할 수 있습니다:

• rbac.create를 true로 설정합니다.
• 다음 권한을 values.yml 파일에 있는 서비스 계정 rbac.serviceAccountName: <service_account_name>으로 지정합니다.

• serviceAccount 권한은 다음과 같은 경우에만 필요합니다:

  • GitLab 15.0 및 15.1에 대해
  • GitLab 15.0.1, 15.1.1, 및 15.2에서 resource_availability_check_max_attempts가 0보다 큰 값으로 설정된 경우.

• GitLab Runner 15.8부터 configmaps 권한은 더 이상 필요하지 않습니다.

• event 권한은 다음과 같은 경우에만 필요합니다:

  • GitLab 16.2.1 및 그 이후에

• namespace 권한은 다음과 같은 경우에만 필요합니다:

  • namespace_per_job를 통해 네임스페이스 격리를 활성화하는 경우_

구성 설정

config.toml 파일에서 다음 설정을 사용하여 Kubernetes executor를 구성하세요.

CPU 요청 및 제약

메모리 요청 및 제한

저장 공간 요청 및 제한

기타 config.toml 설정

구성 예제

다음 샘플은 Kubernetes 실행자를 위한 config.toml 파일의 구성 예제를 보여줍니다.

concurrent = 4

[[runners]]
  name = "myRunner"
  url = "https://gitlab.com/ci"
  token = "......"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "https://45.67.34.123:4892"
    cert_file = "/etc/ssl/kubernetes/api.crt"
    key_file = "/etc/ssl/kubernetes/api.key"
    ca_file = "/etc/ssl/kubernetes/ca.crt"
    namespace = "gitlab"
    namespace_overwrite_allowed = "ci-.*"
    bearer_token_overwrite_allowed = true
    privileged = true
    cpu_limit = "1"
    memory_limit = "1Gi"
    service_cpu_limit = "1"
    service_memory_limit = "1Gi"
    helper_cpu_limit = "500m"
    helper_memory_limit = "100Mi"
    poll_interval = 5
    poll_timeout = 3600
    dns_policy = "cluster-first"
    priority_class_name = "priority-1"
    [runners.kubernetes.node_selector]
      gitlab = "true"
    [runners.kubernetes.node_tolerations]
      "node-role.kubernetes.io/master" = "NoSchedule"
      "custom.toleration=value" = "NoSchedule"
      "empty.value=" = "PreferNoSchedule"
      "onlyKey" = ""

실행자 서비스 계정 구성

실행자 서비스 계정을 구성하려면 KUBERNETES_SERVICE_ACCOUNT 환경 변수를 설정하거나 --kubernetes-service-account 플래그를 사용할 수 있습니다.

Pods 및 컨테이너

작업이 실행되는 방식을 제어하려면 Pods 및 컨테이너를 구성할 수 있습니다.

작업 Pods를 위한 기본 주석

• 소개됨 in GitLab Runner 15.9.

다음 주석은 작업을 실행하는 Pod에 기본적으로 추가됩니다:

기본 주석을 덮어쓰려면 GitLab Runner 구성의 pod_annotations를 사용합니다. 또한 .gitlab-ci.yml 파일에서 각 CI/CD 작업의 주석을 덮어쓸 수도 있습니다.

Pod 라이프사이클

Pod 라이프사이클 은 다음과 같이 영향을 받을 수 있습니다:

• TOML 구성 파일에서 pod_termination_grace_period_seconds 속성을 설정합니다. Pod에서 실행 중인 프로세스는 TERM 시그널이 보내진 후 지정된 기간 동안 실행될 수 있습니다. 이 기간을 초과하여 종료되지 않으면 kill 시그널이 보내집니다.
• FF_USE_POD_ACTIVE_DEADLINE_SECONDS 피처 플래그를 활성화합니다. 활성화되면 작업이 시간 초과되면 CI/CD 작업을 실행하는 Pod을 실패로 표시하고 모든 관련 컨테이너를 종료합니다. GitLab에서 작업이 먼저 시간 초과되도록 하려면 activeDeadlineSeconds를 구성된 시간 초과 + 1초로 설정합니다.

Pod Toleration 덮어쓰기

Kubernetes Pod tolerations을 덮어쓰려면:

1. config.toml이나 Helm values.yaml 파일에서 node_tolerations_overwrite_allowed에 대해 CI 작업 Pod tolerations 덮어쓰기를 활성화하려면 KUBERNETES_NODE_TOLERATIONS_로 시작하는 CI 변수 이름의 정규 표현식을 정의합니다. 이 정규 표현식은 node_tolerations_overwrite_allowed의 값을 검증합니다.

   runners:
    ...
    config: |
      [[runners]]
        [runners.kubernetes]
          node_tolerations_overwrite_allowed = ".*"
   

2. .gitlab-ci.yml 파일에서 하나 이상의 CI 변수를 정의하여 CI 작업 Pod tolerations를 덮어쓸 수 있습니다.

   variables:
     KUBERNETES_NODE_TOLERATIONS_1: 'node-role.kubernetes.io/master:NoSchedule'
     KUBERNETES_NODE_TOLERATIONS_2: 'custom.toleration=value:NoSchedule'
     KUBERNETES_NODE_TOLERATIONS_3: 'empty.value=:PreferNoSchedule'
     KUBERNETES_NODE_TOLERATIONS_4: 'onlyKey'
     KUBERNETES_NODE_TOLERATIONS_5: '' # 모든 테인트를 허용
   

Pod 라벨 덮어쓰기

각 CI/CD 작업에 대해 Kubernetes Pod 라벨을 덮어쓰려면:

1. .config.yaml 파일에 pod_labels_overwrite_allowed에 대한 정규 표현식을 정의합니다.

2. .gitlab-ci.yml 파일에서 KUBERNETES_POD_LABELS_* 변수를 key=value의 값으로 설정합니다. Pod 라벨은 key=value로 덮어쓰여집니다. 여러 값을 적용할 수 있습니다.

    variables:
      KUBERNETES_POD_LABELS_1: "Key1=Val1"
      KUBERNETES_POD_LABELS_2: "Key2=Val2"
      KUBERNETES_POD_LABELS_3: "Key3=Val3"
   

포드 주석 덮어쓰기

각 CI/CD 작업에 대해 Kubernetes 포드 주석을 덮어쓰려면:

1. .config.yaml 파일에서 pod_annotations_overwrite_allowed에 대한 정규 표현식을 정의합니다.

2. .gitlab-ci.yml 파일에서 KUBERNETES_POD_ANNOTATIONS_* 변수를 설정하고 값에 대해 key=value를 사용합니다. 포드 주석은 key=value로 덮어씌워집니다. 여러 주석을 지정할 수 있습니다:

   variables:
     KUBERNETES_POD_ANNOTATIONS_1: "Key1=Val1"
     KUBERNETES_POD_ANNOTATIONS_2: "Key2=Val2"
     KUBERNETES_POD_ANNOTATIONS_3: "Key3=Val3"
   

아래 예시에서 pod_annotations 및 pod_annotations_overwrite_allowed가 설정됩니다. 이 구성은 config.toml에서 구성된 pod_annotations 중 어떤 것이든 덮어쓰기를 허용합니다.

[[runners]]
  # 일반적인 구성
  executor = "kubernetes"
  [runners.kubernetes]
    image = "alpine"
    pod_annotations_overwrite_allowed = "*"
    [runners.kubernetes.pod_annotations]
      "Key1" = "Val1"
      "Key2" = "Val2"
      "Key3" = "Val3"
      "Key4" = "Val4"

생성된 포드 사양 덮어쓰기

• GitLab Runner 15.10에서 도입됨.

이 기능은 베타 상태입니다. 운영 환경 클러스터에서 사용하기 전에 테스트 Kubernetes 클러스터에서 이 기능을 사용하는 것을 강력히 권장합니다. 이 기능을 사용하려면 FF_USE_ADVANCED_POD_SPEC_CONFIGURATION 피처 플래그를 활성화해야 합니다.

기능이 일반적으로 사용할 수 있게 되기 전에 개선 사항에 대한 피드백을 추가하려면 이 이슈를 사용하세요.

러너(runner) 매니저에 의해 생성된 PodSpec을 수정하려면 config.toml 파일의 pod_spec 설정을 사용하세요.

pod_spec 설정:

• 생성된 포드 사양의 필드를 덮어쓰고 완성합니다.
• GitLab Runner에서 설정할 수 있는 값들을 덮어씌웁니다.

여러 pod_spec 설정을 구성할 수 있습니다.

동일한 pod_spec 구성에서 patch_path와 patch를 동시에 설정할 수 없으며, 그렇게 하면 오류가 발생합니다.

config.toml의 여러 pod_spec 구성 예시:

[[runners]]
  [runners.kubernetes]
    [[runners.kubernetes.pod_spec]]
      name = "hostname"
      patch = '''
        hostname: "custom-pod-hostname"
      '''
      patch_type = "merge"
    [[runners.kubernetes.pod_spec]]
      name = "subdomain"
      patch = '''
        subdomain: "subdomain"
      '''
      patch_type = "strategic"
    [[runners.kubernetes.pod_spec]]
      name = "terminationGracePeriodSeconds"
      patch = '''
        [{"op": "replace", "path": "/terminationGracePeriodSeconds", "value": 60}]
      '''
      patch_type = "json"

Merge 패치 전략

merge 패치 전략은 기존 PodSpec에 키-값 교체를 적용합니다. 이 전략을 사용하면 config.toml의 pod_spec 구성이 최종 PodSpec 개체의 값들을 덮어씁니다. 값들이 완전히 덮어씌워지기 때문에 이 패치 전략은 신중하게 사용해야 합니다.

merge 패치 전략을 사용하는 pod_spec 구성 예시:

concurrent = 1
check_interval = 1
log_level = "debug"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = ""
  url = "https://gitlab.example.com"
  id = 0
  token = "__REDACTED__"
  token_obtained_at = 0001-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "kubernetes"
  shell = "bash"
  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
  [runners.kubernetes]
    image = "alpine"
    ...
    [[runners.kubernetes.pod_spec]]
      name = "build envvars"
      patch = '''
        containers:
        - env:
          - name: env1
            value: "value1"
          - name: env2
            value: "value2"
          name: build
      '''
      patch_type = "merge"

이 구성에서 최종 PodSpec에는 build라고 불리는 단일 컨테이너만 있고, 두 개의 환경 변수 env1 및 env2만 포함됩니다. 위 예시는 다음과 같은 이유로 관련 CI 작업에 실패합니다:

• helper 컨테이너 명세가 제거됨.
• build 컨테이너 명세가 GitLab Runner에 의해 필요한 모든 구성을 잃었습니다.

이 예시에서 작업이 실패하는 것을 방지하려면 pod_spec에 GitLab Runner에 의해 생성된 기본 속성이 포함되어야 합니다.

JSON 패치 전략

json 패치 전략은 PodSpec 개체 및 배열에 대한 제어를 제공하기 위해 JSON Patch specification을 사용합니다. 이 전략은 array 속성에는 사용할 수 없습니다.

json 패치 전략을 사용한 pod_spec 구성의 예입니다. 이 구성에서 기존 nodeSelector에 새로운 key: value pair가 추가됩니다. 기존 값은 덮어쓰지 않습니다.

concurrent = 1
check_interval = 1
log_level = "debug"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = ""
  url = "https://gitlab.example.com"
  id = 0
  token = "__REDACTED__"
  token_obtained_at = 0001-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "kubernetes"
  shell = "bash"
  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
  [runners.kubernetes]
    image = "alpine"
    ...
    [[runners.kubernetes.pod_spec]]
      name = "val1 node"
      patch = '''
        { "op": "add", "path": "/nodeSelector", "value": { key1: "val1" } }
      '''
      patch_type = "json"

전략적 패치 전략

이 strategic 패치 전략은 PodSpec 개체의 각 필드에 적용된 기존 patchStrategy를 사용합니다.

strategic 패치 전략을 사용한 pod_spec 구성의 예입니다. 이 구성에서 build container에 resource request가 설정됩니다.

concurrent = 1
check_interval = 1
log_level = "debug"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = ""
  url = "https://gitlab.example.com"
  id = 0
  token = "__REDACTED__"
  token_obtained_at = 0001-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "kubernetes"
  shell = "bash"
  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
  [runners.kubernetes]
    image = "alpine"
    ...
    [[runners.kubernetes.pod_spec]]
      name = "cpu request 500m"
      patch = '''
        containers:
        - name: build
          resources:
            requests:
              cpu: "500m"
      '''
      patch_type = "strategic"

이 구성으로 resource request가 build container에 설정됩니다.

모범 사례

• Merge 전에 프로덕션 환경에서 먼저 pod_spec을 테스트합니다.
• pod_spec 구성이 GitLab Runner에서 생성된 사양에 부정적인 영향을 미치지 않도록 합니다.
• 복잡한 pod 구성 업데이트에 대해 merge 패치 전략을 사용하지 않습니다.
• 가능한 경우 구성이 사용 가능한 경우 config.toml을 사용합니다. 예를 들어, 다음 구성은 GitLab Runner에서 설정한 첫 번째 환경 변수를 기존 디렉터리에 추가하는 대신 사용자 정의 pod_spec에 설정된 환경 변수로 대체합니다.

concurrent = 1
check_interval = 1
log_level = "debug"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = ""
  url = "https://gitlab.example.com"
  id = 0
  token = "__REDACTED__"
  token_obtained_at = 0001-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "kubernetes"
  shell = "bash"
  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true", "CUSTOM_VAR=value"]
  [runners.kubernetes]
    image = "alpine"
    ...
    [[runners.kubernetes.pod_spec]]
      name = "build envvars"
      patch = '''
        containers:
        - env:
          - name: env1
            value: "value1"
          name: build
      '''
      patch_type = "strategic"

각 빌드 작업에 대한 PVC 만들기: Pod Spec 수정

각 빌드 작업에 대한 PersistentVolumeClaim를 만들려면 Pod Spec 기능을 활성화하는 방법을 확인하세요.

Kubernetes에서는 Pod 수명주기에 연결된 임시 PersistentVolumeClaim을 만들 수 있습니다. 이렇게 하면 클러스터에서 dynamic provisioning이 가능하고 각 PVC가 새로운 Volume을 요청할 수 있는 경우 작동합니다. 이 Volume도 Pod의 수명과 연결됩니다.

dynamic provisioning을 활성화한 후 config.toml을 다음과 같이 수정하여 임시 PVC를 만들 수 있습니다:

[[runners.kubernetes.pod_spec]]
  name = "ephemeral-pvc"
  patch = '''
    containers:
    - name: build
      volumeMounts:
      - name: builds
        mountPath: /builds
    - name: helper
      volumeMounts:
      - name: builds
        mountPath: /builds
    volumes:
    - name: builds
      ephemeral:
        volumeClaimTemplate:
          spec:
            storageClassName: <동적으로 볼륨을 할당할 수 있는 스토리지 클래스>
            accessModes: [ ReadWriteOnce ]
            resources:
              requests:
                storage: 1Gi
  '''

Pod에 대한 보안 정책 설정

빌드 Pod에 대한 보안 정책을 설정하려면 config.toml에서 보안 컨텍스트를 구성하세요.

다음 옵션을 사용하세요:

config.toml에서의 pod 보안 컨텍스트의 예:

concurrent = %(concurrent)s
check_interval = 30
  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    [runners.kubernetes]
      helper_image = "gitlab-registry.example.com/helper:latest"
      [runners.kubernetes.pod_security_context]
        run_as_non_root = true
        run_as_user = 59417
        run_as_group = 59417
        fs_group = 59417

오래된 runner pods 제거

• GitLab Runner 14.6에 도입되었습니다. 여기에서 확인.

가끔씩 예기치 않게 runner manager가 종료되면 오래된 runner pods가 제거되지 않을 수 있습니다.

이 상황을 처리하려면 GitLab Runner Pod Cleanup 애플리케이션을 사용하여 오래된 pods를 정기적으로 정리할 수 있습니다. 자세한 정보는 아래를 참조하세요:

• GitLab Runner Pod Cleanup 프로젝트 README.
• GitLab Runner Pod Cleanup 문서.

컨테이너의 보안 정책 설정

• GitLab Runner 14.5에 도입되었습니다. 여기에서 확인.

config.toml 실행기에서 container security context를 구성하여 빌드, 도우미 또는 서비스 pods의 컨테이너 보안 정책을 설정합니다.

다음 옵션을 사용하세요:

다음은 config.toml의 보안 컨텍스트 구성을 보여주는 예시입니다:

• pod 보안 컨텍스트를 설정합니다.
• 빌드 및 도우미 컨테이너에 대해 run_as_user와 run_as_group를 재정의합니다.
• 모든 서비스 컨테이너가 pod 보안 컨텍스트로부터 run_as_user와 run_as_group를 상속받도록 지정합니다.

concurrent = 4
check_interval = 30
  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    [runners.kubernetes]
      helper_image = "gitlab-registry.example.com/helper:latest"
      [runners.kubernetes.pod_security_context]
        run_as_non_root = true
        run_as_user = 59417
        run_as_group = 59417
        fs_group = 59417
      [runners.kubernetes.init_permissions_container_security_context]
        run_as_user = 1000
        run_as_group = 1000
      [runners.kubernetes.build_container_security_context]
        run_as_user = 65534
        run_as_group = 65534
        [runners.kubernetes.build_container_security_context.capabilities]
          add = ["NET_ADMIN"]
      [runners.kubernetes.helper_container_security_context]
        run_as_user = 1000
        run_as_group = 1000
      [runners.kubernetes.service_container_security_context]
        run_as_user = 1000
        run_as_group = 1000

Pull 정책 설정

config.toml 파일의 pull_policy 매개변수를 사용하여 단일 또는 다중 pull 정책을 지정합니다. 이 정책은 이미지의 검색 및 업데이트를 제어하며 빌드 이미지, 도우미 이미지 및 서비스에 적용됩니다.

어떤 정책을 사용할지 결정하려면 Kubernetes pull 정책에 대한 문서를 참조하세요.

단일 pull 정책의 경우:

[runners.kubernetes]
  pull_policy = "never"

다중 pull 정책의 경우:

[runners.kubernetes]
  # 다중 pull 정책 사용
  pull_policy = ["always", "if-not-present"]

여러 정책을 정의할 때 이미지가 성공적으로 획득될 때까지 각 정책이 시도됩니다. 예를 들어, [always, if-not-present]를 사용하면 always 정책이 일시적인 레지스트리 문제로 실패할 경우 if-not-present 정책이 사용됩니다.

실패한 pull을 재시도하려면:

[runners.kubernetes]
  pull_policy = ["always", "always"]

GitLab의 명명 규칙은 Kubernetes의 규칙과 다릅니다.

컨테이너 capabilities 지정

컨테이너에서 사용할 Kubernetes capabilities를 지정할 수 있습니다.

컨테이너 capabilities를 지정하려면 config.toml의 cap_add 및 cap_drop 옵션을 사용하면 됩니다. 컨테이너 런타임은 기본적으로 capabilities의 기본 디렉터리을 정의할 수 있습니다. 예를 들어, Docker 또는 container에 있는 것과 같은 디렉터리입니다.

기본적으로 runner는 버리는 기능(capabilities) 디렉터리이 있습니다. cap_add 옵션에 나열된 capabilities는 버리는 것에서 제외됩니다.

config.toml 파일의 예시 구성:

concurrent = 1
check_interval = 30
[[runners]]
  name = "myRunner"
  url = "gitlab.example.com"
  executor = "kubernetes"
  [runners.kubernetes]
    # ...
    cap_add = ["SYS_TIME", "IPC_LOCK"]
    cap_drop = ["SYS_ADMIN"]
    # ...

capabilities를 지정할 때:

• 사용자 정의 cap_drop이 사용자 정의 cap_add보다 우선순위를 갖습니다. 두 설정에서 동일한 capability를 정의하면 cap_drop에서만 기능이 컨테이너로 전달됩니다.

• 컨테이너 구성에 전달되는 기능 식별자에서 CAP_ 접두사를 제거하세요. 예를 들어, CAP_SYS_TIME 기능을 추가하거나 제거하려면 설정 파일에서 SYS_TIME 문자열을 입력하세요.

• Kubernetes 클러스터의 소유자는 특정 기능을 허용하거나 제한하거나 기본적으로 추가할 수 있는 PodSecurityPolicy를 정의할 수 있습니다. 이러한 규칙은 사용자 정의 설정보다 우선합니다.

컨테이너 리소스 덮어쓰기

각 CI/CD 작업에 대해 Kubernetes CPU 및 메모리 할당을 덮어쓸 수 있습니다. 빌드, 헬퍼 및 서비스 컨테이너에 대한 요청(requests) 및 제한(limits) 설정을 적용할 수 있습니다.

컨테이너 리소스를 덮어쓰려면 .gitlab-ci.yml 파일에서 다음 변수를 사용합니다.

변수의 값은 해당 리소스에 대한 최대 덮어쓰기 설정으로 제한됩니다. 최대 덮어쓰기가 리소스에 대해 설정되지 않은 경우 해당 변수는 사용되지 않습니다.

 variables:
   KUBERNETES_CPU_REQUEST: "3"
   KUBERNETES_CPU_LIMIT: "5"
   KUBERNETES_MEMORY_REQUEST: "2Gi"
   KUBERNETES_MEMORY_LIMIT: "4Gi"
   KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "512Mi"
   KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "1Gi"
   
   KUBERNETES_HELPER_CPU_REQUEST: "3"
   KUBERNETES_HELPER_CPU_LIMIT: "5"
   KUBERNETES_HELPER_MEMORY_REQUEST: "2Gi"
   KUBERNETES_HELPER_MEMORY_LIMIT: "4Gi"
   KUBERNETES_HELPER_EPHEMERAL_STORAGE_REQUEST: "512Mi"
   KUBERNETES_HELPER_EPHEMERAL_STORAGE_LIMIT: "1Gi"
   
   KUBERNETES_SERVICE_CPU_REQUEST: "3"
   KUBERNETES_SERVICE_CPU_LIMIT: "5"
   KUBERNETES_SERVICE_MEMORY_REQUEST: "2Gi"
   KUBERNETES_SERVICE_MEMORY_LIMIT: "4Gi"
   KUBERNETES_SERVICE_EPHEMERAL_STORAGE_REQUEST: "512Mi"
   KUBERNETES_SERVICE_EPHEMERAL_STORAGE_LIMIT: "1Gi"

서비스 디렉터리 정의

• GitLab Runner 16.9에서 HEALTCHECK_TCP_SERVICES 지원 도입.

config.toml에서 서비스 디렉터리을 정의합니다.

concurrent = 1
check_interval = 30
  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    [runners.kubernetes]
      helper_image = "gitlab-registy.example.com/helper:latest"
      [[runners.kubernetes.services]]
        name = "postgres:12-alpine"
        alias = "db1"
      [[runners.kubernetes.services]]
        name = "registry.example.com/svc1"
        alias = "svc1"
        entrypoint = ["entrypoint.sh"]
        command = ["executable","param1","param2"]
        environment = ["ENV=value1", "ENV2=value2"]

서비스 환경에 HEALTHCHECK_TCP_PORT가 포함된 경우, GitLab Runner는 해당 포트에서 서비스가 응답할 때까지 사용자 CI 스크립트를 시작하지 않습니다. 또한, .gitlab-ci.yml의 services 섹션에서 HEALTHCHECK_TCP_PORT 환경 변수를 구성할 수 있습니다.

서비스 컨테이너 리소스 덮어쓰기

작업에 여러 서비스 컨테이너가 있는 경우 각 서비스 컨테이너에 명시적인 리소스 요청 및 제한을 설정할 수 있습니다. 각 서비스의 변수 속성을 사용하여 .gitlab-ci.yml에서 지정된 컨테이너 리소스를 덮어쓸 수 있습니다.

  services:
    - name: redis:5
      alias: redis5
      variables:
        KUBERNETES_SERVICE_CPU_REQUEST: "3"
        KUBERNETES_SERVICE_CPU_LIMIT: "6"
        KUBERNETES_SERVICE_MEMORY_REQUEST: "3Gi"
        KUBERNETES_SERVICE_MEMORY_LIMIT: "6Gi"
        KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "2Gi"
        KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "3Gi"
    - name: postgres:12
      alias: MY_relational-database.12
      variables:
        KUBERNETES_CPU_REQUEST: "2"
        KUBERNETES_CPU_LIMIT: "4"
        KUBERNETES_MEMORY_REQUEST: "1Gi"
        KUBERNETES_MEMORY_LIMIT: "2Gi"
        KUBERNETES_EPHEMERAL_STORAGE_REQUEST: "1Gi"
        KUBERNETES_EPHEMERAL_STORAGE_LIMIT: "2Gi"

이러한 구체적인 설정은 작업에 대한 일반 설정보다 우선합니다. 값은 여전히 해당 리소스에 대한 최대 덮어쓰기 설정으로 제한됩니다.

Kubernetes 기본 서비스 계정 덮어쓰기

각 CI/CD 작업에 대해 .gitlab-ci.yml 파일에서 Kubernetes 서비스 계정을 덮어쓰기 위해 KUBERNETES_SERVICE_ACCOUNT_OVERWRITE 변수를 설정합니다.

이 변수를 사용하여 복잡한 RBAC 구성에 필요한 네임스페이스에 첨부된 서비스 계정을 지정할 수 있습니다.

variables:
  KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: ci-service-account

CI 실행 중에 지정된 서비스 계정만 사용되도록 보장하려면 다음 중 하나에 대한 정규 표현식을 정의합니다.

• service_account_overwrite_allowed 설정.
• KUBERNETES_SERVICE_ACCOUNT_OVERWRITE_ALLOWED 환경 변수.

둘 중 하나도 설정하지 않으면 덮어쓰기가 비활성화됩니다.

RuntimeClass 설정

• GitLab Runner 14.9에서 도입.

runtime_class_name을 사용하여 각 작업 컨테이너에 RuntimeClass를 설정합니다.

RuntimeClass 이름을 지정하고 클러스터에 구성되지 않았거나 해당 기능이 지원되지 않는 경우, 실행자는 작업을 생성하지 못합니다.

concurrent = 1
check_interval = 30
  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    [runners.kubernetes]
      runtime_class_name = "myclass"

노드

노드 어핀리티 디렉터리 정의

빌드 시간에 파드 스펙에 추가할 노드 어핀리티 디렉터리을 정의합니다.

config.toml에서의 구성 예시:

concurrent = 1
[[runners]]
  name = "myRunner"
  url = "gitlab.example.com"
  executor = "kubernetes"
  [runners.kubernetes]
    [runners.kubernetes.affinity]
      [runners.kubernetes.affinity.node_affinity]
        [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution]]
          weight = 100
          [runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference]
            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
              key = "cpu_speed"
              operator = "In"
              values = ["fast"]
            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
              key = "mem_speed"
              operator = "In"
              values = ["fast"]
        [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution]]
          weight = 50
          [runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference]
            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_expressions]]
              key = "core_count"
              operator = "In"
              values = ["high", "32"]
            [[runners.kubernetes.affinity.node_affinity.preferred_during_scheduling_ignored_during_execution.preference.match_fields]]
              key = "cpu_type"
              operator = "In"
              values = ["arm64"]
      [runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution]
        [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms]]
          [[runners.kubernetes.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms.match_expressions]]
            key = "kubernetes.io/e2e-az-name"
            operator = "In"
            values = [
              "e2e-az1",
              "e2e-az2"
            ]

파드가 예정된 노드를 정의합니다

• GitLab Runner 14.3에서 소개되었습니다.

노드를 제한을 위해 파드 어피니티 및 안티-어피니티를 사용하여 다른 파드의 라벨을 기반으로 파드가 예정된 노드를 제한할 수 있습니다. 귀하의 파드가 예정된 노드를 선택할 수 있습니다.

config.toml에서의 예제 구성:

concurrent = 1
[[runners]]
  name = "myRunner"
  url = "gitlab.example.com"
  executor = "kubernetes"
  [runners.kubernetes]
    [runners.kubernetes.affinity]
      [runners.kubernetes.affinity.pod_affinity]
        [[runners.kubernetes.affinity.pod_affinity.required_during_scheduling_ignored_during_execution]]
          topology_key = "failure-domain.beta.kubernetes.io/zone"
          namespaces = ["namespace_1", "namespace_2"]
          [runners.kubernetes.affinity.pod_affinity.required_during_scheduling_ignored_during_execution.label_selector]
            [[runners.kubernetes.affinity.pod_affinity.required_during_scheduling_ignored_during_execution.label_selector.match_expressions]]
              key = "security"
              operator = "In"
              values = ["S1"]
        [[runners.kubernetes.affinity.pod_affinity.preferred_during_scheduling_ignored_during_execution]]
        weight = 100
        [runners.kubernetes.affinity.pod_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term]
          topology_key = "failure-domain.beta.kubernetes.io/zone"
          [runners.kubernetes.affinity.pod_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.label_selector]
            [[runners.kubernetes.affinity.pod_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.label_selector.match_expressions]]
              key = "security_2"
              operator = "In"
              values = ["S2"]
      [runners.kubernetes.affinity.pod_anti_affinity]
        [[runners.kubernetes.affinity.pod_anti_affinity.required_during_scheduling_ignored_during_execution]]
          topology_key = "failure-domain.beta.kubernetes.io/zone"
          namespaces = ["namespace_1", "namespace_2"]
          [runners.kubernetes.affinity.pod_anti_affinity.required_during_scheduling_ignored_during_execution.label_selector]
            [[runners.kubernetes.affinity.pod_anti_affinity.required_during_scheduling_ignored_during_execution.label_selector.match_expressions]]
              key = "security"
              operator = "In"
              values = ["S1"]
          [runners.kubernetes.affinity.pod_anti_affinity.required_during_scheduling_ignored_during_execution.namespace_selector]
            [[runners.kubernetes.affinity.pod_anti_affinity.required_during_scheduling_ignored_during_execution.namespace_selector.match_expressions]]
              key = "security"
              operator = "In"
              values = ["S1"]
        [[runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution]]
        weight = 100
        [runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term]
          topology_key = "failure-domain.beta.kubernetes.io/zone"
          [runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.label_selector]
            [[runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.label_selector.match_expressions]]
              key = "security_2"
              operator = "In"
              values = ["S2"]
          [runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.namespace_selector]
            [[runners.kubernetes.affinity.pod_anti_affinity.preferred_during_scheduling_ignored_during_execution.pod_affinity_term.namespace_selector.match_expressions]]
              key = "security_2"
              operator = "In"
              values = ["S2"]

노드 셀렉터 덮어쓰기

노드 셀렉터를 덮어쓰려면:

1. config.toml 또는 Helm values.yaml 파일에서 노드 셀렉터 덮어쓰기를 활성화합니다:

   runners:
    ...
    config: |
      [[runners]]
        [runners.kubernetes]
          node_selector_overwrite_allowed = ".*"
   

2. .gitlab-ci.yml 파일에서 노드 셀렉터를 덮어쓰기하기 위한 변수를 정의합니다:

   variables:
     KUBERNETES_NODE_SELECTOR_* = ''
   

다음 예제에서는 Kubernetes 노드 아키텍처를 덮어쓰기하기 위해 config.toml 및 .gitlab-ci.yml에서 설정을 구성합니다:

concurrent = 1
check_interval = 1
log_level = "debug"
shutdown_timeout = 0

listen_address = ':9252'

[session_server]
  session_timeout = 1800

[[runners]]
  name = ""
  url = "https://gitlab.com/"
  id = 0
  token = "__REDACTED__"
  token_obtained_at = "0001-01-01T00:00:00Z"
  token_expires_at = "0001-01-01T00:00:00Z"
  executor = "kubernetes"
  shell = "bash"
  [runners.kubernetes]
    host = ""
    bearer_token_overwrite_allowed = false
    image = "alpine"
    namespace = ""
    namespace_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    service_account_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    node_selector_overwrite_allowed = "kubernetes.io/arch=.*" # <--- 아키텍처 덮어쓰기를 허용

  job:
    image: IMAGE_NAME
    variables:
      KUBERNETES_NODE_SELECTOR_ARCH: 'kubernetes.io/arch=amd64' # <--- 올바른 아키텍처를 선택

빌드를 실행할 노드 지정

node_selector 옵션을 사용하여 쿠버네티스 클러스터의 특정 노드에서 빌드를 실행할 수 있습니다. 이는 string=string 형식의 key=value 쌍으로 이루어진 테이블입니다 (환경 변수의 경우 string:string 형식).

러너는 제공된 정보를 사용하여 빌드의 OS와 아키텍처를 결정합니다. 이는 올바른 도우미 이미지가 사용되도록 보장합니다. 기본적으로 OS 및 아키텍처는 linux/amd64로 가정됩니다.

특정 레이블을 사용하여 다른 운영 체제 및 아키텍처를 가진 노드를 예약할 수 있습니다.

linux/arm64 예제

  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    
    [runners.kubernetes.node_selector]
      "kubernetes.io/arch" = "arm64"
      "kubernetes.io/os" = "linux"

windows/amd64 예제

Windows용 Kubernetes에는 특정 제한 사항이 있으므로 프로세스 격리를 사용하는 경우, 특정 windows 빌드 버전도 node.kubernetes.io/windows-build 레이블과 함께 제공해야 합니다.

  [[runners]]
    name = "myRunner"
    url = "gitlab.example.com"
    executor = "kubernetes"
    
    # Runner가 Linux 환경에서 Windows 노드를 대상으로 작동할 때 Powershell이 올바르게 경로를 해석하려면 FF_USE_POWERSHELL_PATH_RESOLVER 피처 플래그를 활성화해야 합니다.
    environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=true"]
    
    [runners.kubernetes.node_selector]
      "kubernetes.io/arch" = "amd64"
      "kubernetes.io/os" = "windows"
      "node.kubernetes.io/windows-build" = "10.0.20348"

네트워킹

컨테이너 라이프사이클 후크 구성

• GitLab Runner 14.2에서 소개.

컨테이너 라이프사이클 후크를 사용하여 해당 라이프사이클 후크가 실행될 때 구성된 코드를 실행할 수 있습니다.

두 가지 유형의 후크를 구성할 수 있습니다: PreStop 및 PostStart. 각각의 후크는 하나의 핸들러 유형만 설정할 수 있습니다.

config.toml 파일의 예제 구성:

[[runners]]
  name = "kubernetes"
  url = "https://gitlab.example.com/"
  executor = "kubernetes"
  token = "yrnZW46BrtBFqM7xDzE7dddd"
  [runners.kubernetes]
    image = "alpine:3.11"
    privileged = true
    namespace = "default"
    [runners.kubernetes.container_lifecycle.post_start.exec]
      command = ["touch", "/builds/postStart.txt"]
    [runners.kubernetes.container_lifecycle.pre_stop.http_get]
      port = 8080
      host = "localhost"
      path = "/test"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_1"
        value = "header_value_1"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_2"
        value = "header_value_2"

각 라이프사이클 후크를 구성하는 방법은 다음과 같습니다.

KubernetesLifecycleExecAction

KubernetesLifecycleHTTPGet

KubernetesLifecycleHTTPGetHeader

KubernetesLifecycleTcpSocket

포드 DNS 설정 구성

파드의 DNS 설정을 구성하는 데 다음 옵션을 사용합니다.

config.toml 파일의 예제 구성:

concurrent = 1
check_interval = 30
[[runners]]
  name = "myRunner"
  url = "https://gitlab.example.com"
  token = "__REDACTED__"
  executor = "kubernetes"
  [runners.kubernetes]
    image = "alpine:latest"
    [runners.kubernetes.dns_config]
      nameservers = [
        "1.2.3.4",
      ]
      searches = [
        "ns1.svc.cluster-domain.example",
        "my.dns.search.suffix",
      ]
      
      [[runners.kubernetes.dns_config.options]]
        name = "ndots"
        value = "2"
      
      [[runners.kubernetes.dns_config.options]]
        name = "edns0"

KubernetesDNSConfigOption

기본 삭제된 기능 디렉터리

GitLab Runner는 기본적으로 다음 기능을 삭제합니다.

사용자 정의 cap_add는 기본 삭제된 기능 디렉터리보다 우선합니다. 기본적으로 삭제된 기능을 추가하려면 cap_add에 추가하십시오.

• NET_RAW

추가 호스트 별칭 추가

이 기능은 Kubernetes 1.7 이상에서 사용할 수 있습니다.

호스트 별칭을 구성하여 Kubernetes가 컨테이너의 /etc/hosts 파일에 항목을 추가하도록 지시합니다.

다음 옵션을 사용합니다:

config.toml 파일의 예 구성:

concurrent = 4

[[runners]]
  # 일반적인 구성
  executor = "kubernetes"
  [runners.kubernetes]
    [[runners.kubernetes.host_aliases]]
      ip = "127.0.0.1"
      hostnames = ["web1", "web2"]
    [[runners.kubernetes.host_aliases]]
      ip = "192.168.1.1"
      hostnames = ["web14", "web15"]

볼륨

Kubernetes executor와 함께 캐시 사용

캐시가 Kubernetes executor와 함께 사용될 때, /cache라는 볼륨이 pod에 장착됩니다. 작업 중에 캐시된 데이터가 필요한 경우, runner는 캐시된 데이터가 있는지 확인합니다. 압축된 파일이 캐시 볼륨에 있는 경우 캐시된 데이터를 사용할 수 있습니다.

캐시 볼륨을 설정하려면 config.toml 파일의 cache_dir 설정을 사용하십시오.

• 가능한 경우, 압축된 파일은 빌드 폴더로 추출되어 그 작업에서 사용할 수 있습니다.
• 그렇지 않은 경우, 캐시된 데이터는 구성된 리포지터리에서 다운로드되어 캐시 디렉터리에 압축 파일로 저장됩니다. 그런 다음 압축 파일은 빌드 폴더로 추출됩니다.

볼륨 유형 구성

다음과 같은 볼륨 유형을 장착할 수 있습니다:

• hostPath
• persistentVolumeClaim
• configMap
• secret
• emptyDir
• csi

여러 볼륨 유형을 가진 구성 예시:

concurrent = 4

[[runners]]
  # 일반적인 구성
  executor = "kubernetes"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.host_path]]
      name = "hostpath-1"
      mount_path = "/path/to/mount/point"
      read_only = true
      host_path = "/path/on/host"
    [[runners.kubernetes.volumes.host_path]]
      name = "hostpath-2"
      mount_path = "/path/to/mount/point_2"
      read_only = true
    [[runners.kubernetes.volumes.pvc]]
      name = "pvc-1"
      mount_path = "/path/to/mount/point1"
    [[runners.kubernetes.volumes.config_map]]
      name = "config-map-1"
      mount_path = "/path/to/directory"
      [runners.kubernetes.volumes.config_map.items]
        "key_1" = "relative/path/to/key_1_file"
        "key_2" = "key_2"
    [[runners.kubernetes.volumes.secret]]
      name = "secrets"
      mount_path = "/path/to/directory1"
      read_only = true
      [runners.kubernetes.volumes.secret.items]
        "secret_1" = "relative/path/to/secret_1_file"
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty-dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"
    [[runners.kubernetes.volumes.csi]]
      name = "csi-volume"
      mount_path = "/path/to/csi/volume"
      driver = "my-csi-driver"
      [runners.kubernetes.volumes.csi.volume_attributes]
        size = "2Gi"

hostPath 볼륨

hostPath 볼륨을 구성하여 Kubernetes에게 컨테이너에 지정된 호스트 경로를 마운트하도록 지시합니다.

config.toml 파일에서 다음 옵션을 사용하십시오:

persistentVolumeClaim 볼륨

persistentVolumeClaim 볼륨을 구성하여 쿠버네티스에게 쿠버네티스 클러스터에 정의된 persistentVolumeClaim을 사용하도록 지시하고 컨테이너에 마운트합니다.

config.toml 파일에서 다음 옵션을 사용하십시오:

configMap 볼륨

configMap 볼륨을 구성하여 쿠버네티스에 정의된 configMap을 지시하고, 컨테이너에 장착합니다.

config.toml에서 다음 옵션을 사용합니다:

각 configMap 키는 파일로 변환되어 장착 경로에 저장됩니다. 기본적으로:

• 모든 키가 포함됩니다.
• configMap 키가 파일 이름으로 사용됩니다.
• 값이 파일 내용에 저장됩니다.

기본 키 및 값 저장을 변경하려면 items 옵션을 사용하십시오. items 옵션을 사용하면 지정된 키만 볼륨에 추가되고 다른 모든 키는 건너뜁니다.

secret 볼륨

쿠버네티스에 정의된 secret를 지시하고, 컨테이너에 장착하도록 secret 볼륨을 구성합니다.

config.toml 파일에서 다음 옵션을 사용합니다:

선택한 secret의 각 키는 파일로 변환되어 선택한 장착 경로에 저장됩니다. 기본적으로:

• 모든 키가 포함됩니다.
• configMap 키가 파일 이름으로 사용됩니다.
• 값이 파일 내용에 저장됩니다.

기본 키 및 값 저장을 변경하려면 items 옵션을 사용하십시오. items 옵션을 사용하면 지정된 키만 볼륨에 추가되고 다른 모든 키는 건너뜁니다.

emptyDir 볼륨

쿠버네티스에 빈 디렉터리를 장착하도록 하는 emptyDir 볼륨을 구성합니다.

config.toml 파일에서 다음 옵션을 사용합니다:

csi 볼륨

컨테이너 내에 임의의 리포지터리 시스템을 장착하도록 쿠버네티스에 사용자 정의 csi 드라이버를 사용하도록 하는 컨테이너 스토리지 인터페이스 (csi) 볼륨을 구성합니다.

config.toml에서 다음 옵션을 사용합니다:

서비스 컨테이너에 볼륨 장착

빌드 컨테이너에 정의된 볼륨은 모든 서비스 컨테이너에 자동으로 장착됩니다. 이 기능을 사용하여 Docker 실행기에만 사용 가능한 services_tmpfs의 대체로 사용하여 RAM에 데이터베이스 리포지터리를 더 빨리 마운트할 수 있습니다.

config.toml 파일에서의 예시 구성:

[[runners]]
  # 일반적인 구성
  executor = "kubernetes"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "mysql-tmpfs"
      mount_path = "/var/lib/mysql"
      medium = "Memory"

사용자 지정 볼륨 마운트

작업용 빌드 디렉터리를 저장하려면 구성된 builds_dir(/builds가 기본값)에 대한 사용자 정의 볼륨 마운트를 정의하세요. PVC 볼륨을 사용하는 경우, 접근 모드에 따라 한 노드에서 작업을 실행하는 것이 제한될 수 있습니다.

config.toml 파일의 구성 예시:

concurrent = 4

[[runners]]
  # 평소 구성
  executor = "kubernetes"
  builds_dir = "/builds"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "repo"
      mount_path = "/builds"
      medium = "Memory"

영구적인 동시 빌드용 볼륨

• GitLab 16.3에서 pvc.name에 대한 변수 주입 지원 도입.

Kubernetes CI 작업의 빌드 디렉터리는 기본적으로 일시적입니다. GIT_STRATEGY=fetch를 사용하여 Git 클론을 작업 간에 지속하려면 빌드 폴더에 지속적인 볼륨 클레임을 마운트해야 합니다. 여러 작업이 동시에 실행될 수 있으므로 ReadWriteMany 볼륨을 사용하거나 동일한 러너에서 잠재적인 동시 작업별로 하나의 볼륨을 가져야 합니다. 후자가 성능 면에서 더 우수할 가능성이 있습니다. 이와 같은 구성의 예시는 다음과 같습니다:

concurrent = 4

[[runners]]
  executor = "kubernetes"
  builds_dir = "/mnt/builds"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.pvc]]
      # CI_CONCURRENT_ID는 동일한 러너의 병렬 작업을 식별합니다.
      name = "build-pvc-$CI_CONCURRENT_ID"
      mount_path = "/mnt/builds"

이 예시에서는 build-pvc-0에서 build-pvc-3으로 명명된 영구 볼륨 클레임을 직접 생성하세요. 러너의 concurrent 설정에 따라 생성하세요.

도우미 이미지 사용

보안 정책을 설정한 후, 도우미 이미지는 해당 정책을 준수해야 합니다. 이 이미지는 루트 그룹에서 권한을 받지 않으므로 사용자 ID가 루트 그룹의 일부인지 확인해야 합니다.

다음은 사용자 및 nonroot 그룹을 생성하고 도우미 이미지를 해당 사용자로 실행하도록 설정하는 예시입니다.

ARG tag
FROM registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:${tag}
USER root
RUN groupadd -g 59417 nonroot && \
    useradd -u 59417 nonroot -g nonroot
WORKDIR /home/nonroot
USER 59417:59417

빌드에서 Docker 사용

빌드에서 Docker를 사용하는 경우 고려해야 할 사항이 몇 가지 있습니다.

노출된 /var/run/docker.sock

호스트의 /var/run/docker.sock을 빌드 컨테이너 내부로 노출하는 runners.kubernetes.volumes.host_path 옵션을 사용하면 특정 위험 요소가 있습니다. 노드의 컨테이너는 빌드 컨테이너에서 접근할 수 있으며, 빌드를 프로덕션 컨테이너에서 실행할 때 해당 클러스터에서 빌드를 실행하는 경우 현명하지 않을 수 있습니다.

docker:dind 사용

docker:dind, 즉 docker-in-docker 이미지를 실행하는 경우 컨테이너는 권한 부여된 모드에서 실행되어야 합니다. 이렇게 하면 잠재적인 위험 요소가 있을 수 있습니다.

도커 데몬은 .gitlab-ci.yml에서 일반적으로 service로 시작되므로 별도의 컨테이너로 실행됩니다. pod 내의 컨테이너는 할당된 볼륨과 상호간 사용할 IP 주소만 공유합니다. localhost를 사용하여 서로 통신합니다. docker:dind 컨테이너는 /var/run/docker.sock를 공유하지 않으며, 기본적으로 docker 바이너리를 사용합니다.

클라이언트를 구성하여 도커 데몬에 연락하기 위해 다음 컨테이너의 환경 변수를 포함하세요:

• 무 TLS 연결을 위해 DOCKER_HOST=tcp://<hostname>:2375.
• TLS 연결을 위해 DOCKER_HOST=tcp://<hostname>:2376.

hostname에 대해 다음 값을 설정하세요:

• GitLab Runner 12.7 및 이전, 그리고 Kubernetes 1.6 및 이전의 경우 localhost.
• GitLab Runner 12.8 및 이후, 그리고 Kubernetes 1.7 및 이후의 경우 docker.

Docker 19.03 이상의 경우 TLS가 기본적으로 활성화되지만 클라이언트에 인증서를 매핑해야 합니다. DIND의 비 TLS 연결을 활성화하거나 인증서를 마운트할 수 있습니다. 자세한 정보는 도커 익스큐터를 사용한 Docker In Docker Workflow 사용를 참조하세요.

호스트 커널 노출 방지

docker:dind 또는 /var/run/docker.sock을 사용하는 경우, 도커 데몬은 호스트 머신의 기본 커널에 액세스할 수 있습니다. 이는 쿠버네티스에 의해 생성된 도커 이미지의 제한이 동작하지 않음을 의미합니다. Docker 데몬은 노드의 전체 용량을 보고하며, 쿠버네티스에 의해 생성된 도커 빌드 컨테이너에 부과된 제한과 무관합니다.

빌드 컨테이너를 권한 부여된 모드로 실행하거나 /var/run/docker.sock이 노출된 경우, 호스트 커널이 빌드 컨테이너에 노출될 수 있습니다. 개체가 배포되기 전에 노드 일치하는 레이블을 지정하려면 node_selector 옵션에 레이블을 지정하세요. 예를 들어 role=ci 레이블을 지정하면 빌드 컨테이너는 role=ci 레이블이 지정된 노드에서만 실행되고 모든 다른 프로덕션 서비스는 다른 노드에서 실행됩니다.

빌드 컨테이너를 추가로 분리하려면 노드 부정을 사용할 수 있습니다. 부정을 사용하면 다른 파드에 대한 추가 구성 없이 빌드 파드가 동일한 노드에 예약되지 않도록 할 수 있습니다.

kaniko를 사용하여 Docker 이미지 빌드하기

Kaniko를 사용하여 Kubernetes 클러스터 내에서 Docker 이미지를 빌드할 수 있습니다.

Kaniko는 Docker 데몬 없이 작동하며 특권 액세스 없이 이미지를 빌드합니다.

자세한 내용은 kaniko 및 GitLab CI/CD를 사용하여 이미지 빌드를 참조하십시오.

kaniko를 사용하여 멀티 스테이지 Dockerfile을 빌드할 때 알려진 문제가 있습니다. 파이프라인 작업에 after_script 섹션이 포함된 경우, after_script 섹션이 실행될 때 다음 오류 메시지로 실패합니다. 그러나 작업은 여전히 성공적으로 완료됩니다.

OCI runtime exec failed: exec failed: container_linux.go:380: starting container process caused: chdir to cwd
("/workspace") set in config.json failed: no such file or directory: unknown

이 섹션은 kaniko가 멀티 스테이지 Dockerfile을 빌드할 때 해당 컨테이너의 WORKDIR을 삭제하기 때문에 실패합니다. 이는 kubectl exec 및 그와 유사한 SDK API가 컨테이너에 첨부되는 것을 방해합니다.

이 문제에 대한 두 가지 해결책이 있습니다:

• kaniko 실행기 호출에 --ignore-path /workspace를 추가합니다.
• 작업의 script 이후에 mkdir -p /workspace을 추가합니다.

자세한 내용은 이슈 30769를 참조하십시오.

Docker 이미지 및 서비스 제한

• GitLab Runner 14.2에서 Kubernetes 실행기용으로 추가됨.

사용되는 Docker 이미지를 제한할 수 있습니다. 이를 위해 와일드카드 패턴을 지정합니다. 예를 들어, 개인 Docker 레지스트리에서 이미지를 허용하려면:

[[runners]]
  (...)
  executor = "kubernetes"
  [runners.kubernetes]
    (...)
    allowed_images = ["my.registry.tld:5000/*:*"]
    allowed_services = ["my.registry.tld:5000/*:*"]

또는 해당 레지스트리의 특정 이미지 디렉터리으로 제한하려면:

[[runners]]
  (...)
  executor = "kubernetes"
  [runners.kubernetes]
    (...)
    allowed_images = ["my.registry.tld:5000/ruby:*", "my.registry.tld:5000/node:*"]
    allowed_services = ["postgres:9.4", "postgres:latest"]

Docker 풀 정책 제한

• GitLab 15.1에서 도입됨.

.gitlab-ci.yml 파일에서 풀 정책을 지정할 수 있습니다. 이 정책은 CI/CD 작업이 이미지를 가져오는 방식을 결정합니다.

.gitlab-ci.yml 파일에서 사용할 수 있는 풀 정책을 제한하려면 allowed_pull_policies를 사용할 수 있습니다.

예를 들어, always 및 if-not-present 풀 정책만 허용하려면 다음과 같이 지정합니다:

[[runners]]
  (...)
  executor = "kubernetes"
  [runners.kubernetes]
    (...)
    allowed_pull_policies = ["always", "if-not-present"]

• allowed_pull_policies를 지정하지 않으면, 기본값은 pull_policy 키워드의 값입니다.
• pull_policy을 지정하지 않으면, 클러스터의 이미지 기본 풀 정책이 사용됩니다.
• 기존의 pull_policy 키워드에 allowed_pull_policies에 지정되지 않은 풀 정책이 포함되어 있으면, 작업이 오류를 반환합니다.

작업 실행

• 기본적으로 활성화된 피처 플래그 FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY 사용.
• GitLab Runner 14.0에서 기본적으로 attach 사용.

GitLab Runner는 기본적으로 kube exec 대신 kube attach를 사용합니다. 이로써 작업이 중간에 성공으로 표시된 경우와 같은 불안정한 네트워크 환경에서 발생하는 문제를 피할 수 있습니다.

GitLab Runner 14.0로 업데이트한 후 문제가 발생하는 경우, 피처 플래그 FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY를 true로 전환하고 이슈를 제출하세요.

레거시 실행 전략 제거에 대한 진행 상황은 이슈 #27976을 참고하십시오.

Kubernetes API의 요청 시도 횟수 구성

기본적으로 Kubernetes 실행기는 Kubernetes API로의 특정 요청을 5번의 실패한 시도 후에 재시도합니다. 지연 시간은 500밀리초 이상 2초 미만인 백오프 알고리즘에 의해 제어됩니다. 재시도 횟수를 구성하려면 config.toml 파일의 retry_limit 옵션을 사용합니다. 다음과 같은 실패는 자동으로 재시도됩니다:

• error dialing backend
• TLS handshake timeout
• read: connection timed out
• connect: connection timed out
• Timeout occurred
• http2: client connection lost
• connection refused
• tls: internal error
• io.unexpected EOF
• syscall.ECONNRESET
• syscall.ECONNREFUSED
• syscall.ECONNABORTED
• syscall.EPIPE

각 오류별로 재시도 수를 제어하려면 retry_limits 옵션을 사용합니다. retry_limits는 각 오류에 대한 재시도 횟수를 별도로 지정하며, 오류 메시지와 재시도 횟수의 맵입니다. 오류 메시지는 Kubernetes API에서 반환된 오류 메시지의 부분 문자열일 수 있습니다. retry_limits 옵션은 retry_limit 옵션보다 높은 우선순위를 가집니다.

예를 들어, 환경에서 TLS 관련 오류의 재시도 횟수를 제어해야 하는 경우, retry_limits 옵션을 구성하여 기본값인 5회가 아닌 해당 오류를 10회 재시도하도록 설정할 수 있습니다:

[[runners]]
  name = "myRunner"
  url = "https://gitlab.example.com/"
  executor = "kubernetes"
  [runners.kubernetes]
    retry_limit = 5
    
    [runners.kubernetes.retry_limits]
        "TLS handshake timeout" = 10
        "tls: internal error" = 10

예를 들어, 할당량 초과와 같은 완전히 다른 오류를 20회 재시도해야 하는 경우:

[[runners]]
  name = "myRunner"
  url = "https://gitlab.example.com/"
  executor = "kubernetes"
  [runners.kubernetes]
    retry_limit = 5
    
    [runners.kubernetes.retry_limits]
        "exceeded quota" = 20

컨테이너 entrypoint 알려진 문제점

• GitLab Runner 14.5에서 도입됨.
• GitLab Runner 15.1에서 업데이트됨.

컨테이너 entry point에는 다음과 같은 알려진 문제점이 있습니다:

• 이미지의 Dockerfile에 entrypoint가 정의된 경우 유효한 셸을 여야 합니다. 그렇지 않으면 작업이 대기 상태에 머무릅니다.
• entrypoint가 실행될 때 파일 형식의 CI/CD 변수는 디스크에 쓰여지지 않습니다. 파일은 스크립트 실행 중에만 접근할 수 있습니다.
• entrypoint에서 다음의 CI/CD 변수에 액세스할 수 없습니다. 스크립트 명령을 실행하기 전에 before_script를 사용하여 설정 변경을 할 수 있습니다:
  • 설정에 정의된 CI/CD 변수.
  • 마스킹된 CI/CD 변수

작업 변수 액세스 제한

Kubernetes executor를 사용할 때, Kubernetes 클러스터에 액세스 권한이 있는 사용자는 작업에서 사용된 변수를 읽을 수 있습니다. 기본적으로 작업 변수는 다음에 저장됩니다:

• Pod의 환경 섹션

작업 변수 데이터에 대한 액세스를 제한하려면, GitLab Runner가 사용하는 네임스페이스에 대한 액세스 권한을 가진 GitLab 관리자만 액세스할 수 있도록 롤 기반 액세스 제어(RBAC)를 사용해야 합니다.

다른 사용자가 GitLab Runner 네임스페이스에 액세스해야 하는 경우, GitLab Runner 네임스페이스에서 사용자가 가질 수 있는 액세스 유형을 제한하기 위해 다음 동사를 설정해야 합니다:

• pods 및 configmaps의 경우:
  • get
  • watch
  • list
• pods/exec 및 pods/attach의 경우 create를 사용합니다.

인가된 사용자를 위한 RBAC 정의 예시:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: gitlab-runner-authorized-users
rules:
- apiGroups: [""]
  resources: ["configmaps", "pods"]
  verbs: ["get", "watch", "list"]
- apiGroups: [""]
  resources: ["pods/exec", "pods/attach"]
  verbs: ["create"]

준비 단계에서 리소스 확인

• GitLab 15.0에서 도입됨.
• GitLab 15.2에서 업데이트됨.

전제 조건:

• image_pull_secrets 또는 service_account가 설정되어 있어야 합니다.
• resource_availability_check_max_attempts는 0보다 큰 숫자로 설정되어 있어야 합니다.
• Kubernetes serviceAccount가 get 및 list 권한을 사용해야 합니다.

GitLab Runner는 시도 사이에 5초의 간격으로 새로운 서비스 계정이나 시크릿이 사용 가능한지 확인합니다.

• GitLab 15.0 및 15.1에서는 이 기능을 비활성화할 수 없으며, 음수 값이 설정된 경우 기본값은 5입니다.
• GitLab 15.0.1, 15.1.1, 15.2 이상에서는 이 기능이 기본적으로 비활성화되어 있습니다. 이 기능을 활성화하려면 resource_availability_check_max_attempts를 0이 아닌 다른 값으로 설정하세요. 설정한 값은 runner가 서비스 계정이나 시크릿을 확인하는 횟수를 정의합니다.

Kubernetes 네임스페이스 덮어쓰기

전제 조건:

• GitLab Runner Helm 차트의 values.yml 파일에서 rbac.clusterWideAccess가 true로 설정되어 있어야 합니다.
• runner가 핵심 API 그룹에 구성된 권한을 가져야 합니다.

CI 용도로 네임스페이스 지정 및 사용자 지정 pod을 배치하기 위해 Kubernetes 네임스페이스를 덮어쓸 수 있습니다. Runner에 의해 생성된 pod은 CI 단계 중에 컨테이너 간 액세스를 활성화하기 위해 덮어쓰여진 네임스페이스에 있습니다.

각 CI/CD 작업에 대해 Kubernetes 네임스페이스를 덮어쓰려면 .gitlab-ci.yml 파일에서 KUBERNETES_NAMESPACE_OVERWRITE 변수를 설정하세요.

variables:
  KUBERNETES_NAMESPACE_OVERWRITE: ci-${CI_COMMIT_REF_SLUG}

CI 실행 중에 지정된 네임스페이스만 사용하려면, config.toml 파일에서 namespace_overwrite_allowed에 대한 정규 표현식을 정의하세요:

[runners.kubernetes]
    ...
    namespace_overwrite_allowed = "ci-.*"