# Kubernetes executor
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** GitLab.com, Self-managed
Kubernetes executor를 사용하여 Kubernetes 클러스터를 빌드에 활용하세요. 이 executor는 Kubernetes 클러스터 API를 호출하고 각 GitLab CI 작업에 대해 Pod를 생성합니다.
Kubernetes executor는 빌드를 다음 단계로 나눕니다:
1. **준비**: Kubernetes 클러스터에 Pod를 생성합니다.
이는 빌드에 필요한 컨테이너와 서비스를 생성합니다.
1. **빌드 전**: 이전 단계의 코드를 복제하고 캐시를 복원하며 아티팩트를 다운로드합니다.
이 단계는 Pod의 일부인 특수한 컨테이너에서 실행됩니다.
1. **빌드**: 사용자 빌드입니다.
1. **빌드 후**: 캐시를 생성하고 아티팩트를 GitLab에 업로드합니다.
이 단계도 Pod의 일부인 특수한 컨테이너를 사용합니다.
## 실행자가 Kubernetes Pods를 생성하는 방법
다음 다이어그램은 GitLab 인스턴스와 Kubernetes 클러스터에 호스팅된 실행자 간의 상호 작용을 보여줍니다. 실행자는 클러스터상에 Pods를 생성하기 위해 Kubernetes API를 호출합니다.
각 `service`가 `.gitlab-ci.yml` 또는 `config.toml` 파일에서 정의된 경우 Pod에는 다음과 같은 컨테이너가 포함됩니다:
- `build`로 정의된 빌드 컨테이너.
- `helper`로 정의된 도우미 컨테이너.
- `[0-9]+` 중 `X`로 정의된 `svc-X`로 정의된 서비스 컨테이너.
서비스와 컨테이너는 동일한 Kubernetes Pod에서 실행되며 동일한 로컬호스트 주소를 공유합니다. 다음 제한이 적용됩니다:
- GitLab Runner 12.8 및 Kubernetes 1.7 이상에서는 서비스에 DNS 이름을 통해 액세스할 수 있습니다. 이전 버전을 사용하는 경우 `localhost`를 사용해야 합니다.
- 동일한 포트를 사용하는 여러 서비스를 사용할 수 없습니다. 예를 들어 동시에 두 개의 `mysql` 서비스를 가질 수 없습니다.
```mermaid
sequenceDiagram
participant G as GitLab 인스턴스
participant R as Kubernetes 클러스터에 호스팅된 실행자
participant Kube as Kubernetes API
participant P as POD
R->>+G: CI 작업 가져오기.
loop
G-->R: ;
end
Note over R,G: POST /api/v4/jobs/request
G->>+R: CI 작업 데이터.
R-->>-Kube: CI 작업을 실행할 POD 생성.
Note over R,Kube: Kube API로 POST
P->>+P: 작업 실행.
Note over P: CI 빌드 작업 = 준비 + 빌드 전 + 빌드 + 빌드 후
P->>+G: 작업 로그
다이어그램에서의 상호 작용은 모든 Kubernetes 클러스터에 대해 유효합니다. 예를 들어, 주요 공개 클라우드 제공업체에 호스팅된 키턴 솔루션 또는 Self-managed Kubernetes 설치 등이 있습니다.
Kubernetes API에 연결
Kubernetes API에 연결하려면 다음 옵션을 사용하세요. 제공된 사용자 계정에는 지정된 네임스페이스에서 Pod를 생성, 나열 및 첨부하는 권한이 있어야 합니다.
옵션 | 설명 |
---|---|
host
| 옵션: Kubernetes apiserver 호스트 URL(지정되지 않은 경우 자동 탐지를 시도함). |
cert_file
| 옵션: Kubernetes apiserver 사용자 인증 인증서. |
key_file
| 옵션: Kubernetes apiserver 사용자 인증 사설 키. |
ca_file
| 옵션: Kubernetes apiserver ca 인증서. |
만약 GitLab Runner를 Kubernetes 클러스터 내에서 실행 중이라면, 이러한 필드들을 모두 생략하여 GitLab Runner가 Kubernetes API를 자동으로 탐지하도록 해야 합니다.
만약 GitLab Runner가 클러스터 외부에서 실행 중이라면, 각 설정을 설정하고 GitLab Runner가 클러스터의 Kubernetes API에 액세스할 수 있도록 해야 합니다.
Kubernetes API 호출용 베어러 토큰 설정
POD를 생성하기 위한 API 호출에 대해 베어러 토큰을 설정하려면 KUBERNETES_BEARER_TOKEN
변수를 사용하세요. 이를 통해 프로젝트 소유자는 프로젝트 비공개 변수를 사용하여 베어러 토큰을 지정할 수 있습니다.
베어러 토큰을 지정할 때는 Host
구성 설정을 설정해야 합니다.
variables:
KUBERNETES_BEARER_TOKEN: 다른 네임스페이스의 베어러 토큰
실행자 API 권한 구성
핵심 API 그룹의 권한을 구성하려면 GitLab Runner Helm 차트의 values.yml
파일을 업데이트하세요.
다음 중 하나를 선택할 수 있습니다:
-
rbac.create
를true
로 설정합니다. -
values.yml
파일에서 다음 권한을 가진 서비스 계정rbac.serviceAccountName: <service_account_name>
을 지정합니다.
자원 | 동사 (옵션 기능 플래그) |
---|---|
이벤트 | list (FF_RETRIEVE_POD_WARNING_EVENTS=true ), watch (FF_PRINT_POD_EVENTS=true )
|
namespaces | create, delete |
pods | attach (FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false ), create, delete, exec, get
|
pods/logs | get (FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false ), list (FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false )
|
비밀 | create, delete, get, update |
serviceAccounts | get |
services | create, get |
If you have any more segments feel free to ask! I'd be glad to assist you!
## 구성 설정
`config.toml` 파일에서 Kubernetes executor를 구성하려면 다음 설정을 사용하십시오.
### CPU 요청 및 제한
| 설정 | 설명 |
|---------|-------------|
| `cpu_limit` | 빌드 컨테이너에 할당된 CPU. |
| `cpu_limit_overwrite_max_allowed` | 빌드 컨테이너의 CPU 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 제한 덮어쓰기 기능이 비활성화됩니다. |
| `cpu_request` | 빌드 컨테이너에 요청된 CPU 할당량. |
| `cpu_request_overwrite_max_allowed` | 빌드 컨테이너의 CPU 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 요청 덮어쓰기 기능이 비활성화됩니다. |
| `helper_cpu_limit` | 빌드 보조 컨테이너에 할당된 CPU. |
| `helper_cpu_limit_overwrite_max_allowed` | 보조 컨테이너의 CPU 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 제한 덮어쓰기 기능이 비활성화됩니다. |
| `helper_cpu_request` | 빌드 보조 컨테이너에 요청된 CPU 할당량. |
| `helper_cpu_request_overwrite_max_allowed` | 보조 컨테이너의 CPU 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 요청 덮어쓰기 기능이 비활성화됩니다. |
| `service_cpu_limit` | 빌드 서비스 컨테이너에 할당된 CPU. |
| `service_cpu_limit_overwrite_max_allowed` | 서비스 컨테이너의 CPU 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 제한 덮어쓰기 기능이 비활성화됩니다. |
| `service_cpu_request` | 빌드 서비스 컨테이너에 요청된 CPU 할당량. |
| `service_cpu_request_overwrite_max_allowed` | 서비스 컨테이너의 CPU 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 CPU 요청 덮어쓰기 기능이 비활성화됩니다. |
### Memory 요청 및 제한
| 설정 | 설명 |
|---------|-------------|
| `memory_limit` | 빌드 컨테이너에 할당된 메모리 양. |
| `memory_limit_overwrite_max_allowed` | 빌드 컨테이너의 메모리 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 제한 덮어쓰기 기능이 비활성화됩니다. |
| `memory_request` | 빌드 컨테이너에서 요청한 메모리 양. |
| `memory_request_overwrite_max_allowed` | 빌드 컨테이너의 메모리 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 요청 덮어쓰기 기능이 비활성화됩니다. |
| `helper_memory_limit` | 빌드 보조 컨테이너에 할당된 메모리 양. |
| `helper_memory_limit_overwrite_max_allowed` | 보조 컨테이너의 메모리 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 제한 덮어쓰기 기능이 비활성화됩니다. |
| `helper_memory_request` | 빌드 보조 컨테이너에서 요청한 메모리 양. |
| `helper_memory_request_overwrite_max_allowed` | 보조 컨테이너의 메모리 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 요청 덮어쓰기 기능이 비활성화됩니다. |
| `service_memory_limit` | 빌드 서비스 컨테이너에 할당된 메모리 양. |
| `service_memory_limit_overwrite_max_allowed` | 서비스 컨테이너의 메모리 할당량을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 제한 덮어쓰기 기능이 비활성화됩니다. |
| `service_memory_request` | 빌드 서비스 컨테이너에서 요청한 메모리 양. |
| `service_memory_request_overwrite_max_allowed` | 서비스 컨테이너의 메모리 할당 요청을 덮어쓸 수 있는 최대량. 비어 있으면 메모리 요청 덮어쓰기 기능이 비활성화됩니다. |
### 스토리지 요청 및 제한
| 설정 | 설명 |
|---------|-------------|
| `ephemeral_storage_limit` | 빌드 컨테이너의 임시 스토리지 제한. |
| `ephemeral_storage_limit_overwrite_max_allowed` | 빌드 컨테이너의 임시 스토리지 제한을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 제한 덮어쓰기 기능이 비활성화됩니다. |
| `ephemeral_storage_request` | 빌드 컨테이너에 제공된 임시 스토리지 요청. |
| `ephemeral_storage_request_overwrite_max_allowed` | 빌드 컨테이너의 임시 스토리지 요청을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 요청 덮어쓰기 기능이 비활성화됩니다. |
| `helper_ephemeral_storage_limit` | 빌드 보조 컨테이너에 제공된 임시 스토리지 제한. |
| `helper_ephemeral_storage_limit_overwrite_max_allowed` | 보조 컨테이너의 임시 스토리지 제한을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 요청 덮어쓰기 기능이 비활성화됩니다. |
| `helper_ephemeral_storage_request` | 빌드 보조 컨테이너에 제공된 임시 스토리지 요청. |
| `helper_ephemeral_storage_request_overwrite_max_allowed` | 보조 컨테이너의 임시 스토리지 요청을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 요청 덮어쓰기 기능이 비활성화됩니다. |
| `service_ephemeral_storage_limit` | 빌드 서비스 컨테이너에 제공된 임시 스토리지 제한. |
| `service_ephemeral_storage_limit_overwrite_max_allowed` | 서비스 컨테이너의 임시 스토리지 제한을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 요청 덮어쓰기 기능이 비활성화됩니다. |
| `service_ephemeral_storage_request` | 빌드 서비스 컨테이너에 제공된 임시 스토리지 요청. |
| `service_ephemeral_storage_request_overwrite_max_allowed` | 서비스 컨테이너의 임시 스토리지 요청을 덮어쓸 수 있는 최대량. 비어 있으면 임시 스토리지 요청 덮어쓰기 기능이 비활성화됩니다. |
### 기타 `config.toml` 설정
| 설정 | 설명 |
|---------|-------------|
| `affinity` | 빌드를 실행할 노드를 결정하는 affinity 규칙을 지정합니다. [affinity 사용](#define-a-list-of-node-affinities)에 대해 자세히 알아보세요. |
| `allow_privilege_escalation` | `allowPrivilegeEscalation` 플래그를 활성화하여 모든 컨테이너를 실행합니다. 비어 있으면 컨테이너 `SecurityContext`에 `allowPrivilegeEscalation` 플래그를 정의하지 않고 Kubernetes가 기본 [privilege escalation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) 동작을 사용합니다. |
| `allowed_images` | `.gitlab-ci.yml`에서 지정할 수 있는 이미지의 와일드카드 목록입니다. 지정되지 않으면 모든 이미지가 허용됩니다 (`["*/*:*"]`와 동등). [세부 정보 보기](#restrict-docker-images-and-services). |
| `allowed_pull_policies` | `.gitlab-ci.yml` 파일이나 `config.toml` 파일에서 지정할 수 있는 풀(policy) 정책 목록입니다. |
| `allowed_services` | `.gitlab-ci.yml`에서 지정할 수 있는 서비스의 와일드카드 목록입니다. 지정되지 않으면 모든 이미지가 허용됩니다 (`["*/*:*"]`와 동등). [세부 정보 보기](#restrict-docker-images-and-services). |
| `automount_service_account_token` | 빌드 파드에서 서비스 계정 토큰의 자동 마운트를 제어하는 부울 값입니다. |
| `bearer_token` | 빌드 파드를 시작하는 데 사용되는 기본 bearer 토큰입니다. |
| `bearer_token_overwrite_allowed` | 프로젝트가 빌드 파드를 만드는 데 사용할 bearer 토큰을 지정할 수 있도록 하는 부울 값입니다. |
| `build_container_security_context` | 빌드 컨테이너에 대한 컨테이너 보안 컨텍스트를 설정합니다. [보안 컨텍스트에 대해 자세히 알아보기](#set-a-security-policy-for-the-pod). |
| `cap_add` | 작업 파드 컨테이너에 추가해야 하는 Linux 기능을 지정합니다. Kubernetes 실행기에서 기능 구성에 대해 자세히 알아보기](#specify-container-capabilities). |
| `cap_drop` | 작업 파드 컨테이너에서 제외해야 하는 Linux 기능을 지정합니다. Kubernetes 실행기에서 기능 구성에 대해 자세히 알아보기](#specify-container-capabilities). |
| `cleanup_grace_period_seconds` | 작업이 완료된 후 파드가 정상적으로 종료되기까지의 기간(초 단위). 이 기간이 지나면 프로세스가 kill 시그널로 강제로 중지됩니다. `terminationGracePeriodSeconds`가 지정된 경우 무시됩니다. |
| `dns_policy` | 파드를 구성할 때 사용할 DNS 정책을 지정합니다: `none`, `default`, `cluster-first`, `cluster-first-with-host-net`. 설정되지 않으면 Kubernetes의 기본 설정인 `cluster-first`가 사용됩니다. |
| `dns_config` | 파드의 DNS 구성을 지정합니다. [파드의 DNS 구성 사용에 대해 자세히 알아보기](#configure-pod-dns-settings). |
| `helper_container_security_context` | 도우미 컨테이너에 대한 컨테이너 보안 컨텍스트를 설정합니다. [보안 컨텍스트에 대해 자세히 알아보기](#set-a-security-policy-for-the-pod). |
| `helper_image` | (고급) 리포지토리를 복제하고 아티팩트를 업로드하는 데 사용되는 기본 도우미 이미지를 [재정의](../../configuration/advanced-configuration.md#helper-image)합니다. |
| `helper_image_flavor` | 도우미 이미지 플레이버(`alpine`, `alpine3.16`, `alpine3.17`, `alpine3.18`, `alpine3.19`, 또는 `ubuntu`)를 설정합니다. 기본값은 `alpine`입니다. `alpine` 사용은 `alpine3.18`과 동일합니다. |
| `host_aliases` | 모든 컨테이너에 추가될 추가 호스트 이름 별칭의 목록입니다. [추가 호스트 별칭 사용에 대해 자세히 알아보기](#add-extra-host-aliases). |
| `image_pull_secrets` | 개인 레지스트리에서 Docker 이미지를 인증하는 데 사용되는 Kubernetes `docker-registry` 시크릿 이름을 포함하는 항목 배열입니다. |
| `init_permissions_container_security_context` | init-permissions 컨테이너에 대한 컨테이너 보안 컨텍스트를 설정합니다. [보안 컨텍스트에 대해 자세히 알아보기](#set-a-security-policy-for-the-pod). |
| `namespace` | Kubernetes 파드를 실행할 네임스페이스입니다. |
| `namespace_per_job` | 작업을 별도의 네임스페이스에서 격리합니다. 활성화되면 `namespace` 및 `namespace_overwrite_allowed`가 무시됩니다. |
| `namespace_overwrite_allowed` | 네임스페이스 덮어쓰기 환경 변수의 내용을 유효성 검사하기 위한 정규식입니다. 비어 있으면 네임스페이스 덮어쓰기 기능이 비활성화됩니다. |
| `node_selector` | `string=string` (`환경 변수의 경우 string:string`) 형식의 `키=값` 쌍으로 된 `테이블`입니다. 이를 설정하면 모든 `키=값` 쌍과 일치하는 Kubernetes 노드에 파드를 생성하는 것이 제한됩니다. [노드 셀렉터 사용에 대해 자세히 알아보기](#specify-the-node-to-execute-builds). |
| `node_tolerations` | `string=string:string` 형식의 `"키=값" = "효과"`로 된 `테이블`입니다. 이를 설정하면 허용되는 노드의 모든 또는 일부에 일치하는 테인트(taints)가 있는 노드로 파드를 스케줄링할 수 있습니다. 환경 변수 구성을 통해 하나의 허용만 공급할 수 있습니다. `키`, `값`, `효과`는 각각 Kubernetes 팟 허용 구성의 해당 필드 이름과 일치합니다. |
| `pod_annotations` | 러너에 의해 생성된 각 빌드 파드에 추가될 주석 `key=value` 쌍의 `테이블`입니다. 이 값은 확장을 위해 환경 변수를 포함할 수 있습니다. 빌드마다 파드 주석을 덮어쓸 수 있습니다. |
| `pod_annotations_overwrite_allowed` | 파드 주석 덮어쓰기 환경 변수의 내용을 유효성 검사하기 위한 정규식입니다. 비어 있으면 파드 주석 덮어쓰기 기능이 비활성화됩니다. |
| `pod_labels` | 러너에 의해 생성된 각 빌드 파드에 추가될 라벨 `key=value` 쌍의 `테이블`입니다. 이 값은 확장을 위해 환경 변수를 포함할 수 있습니다. `pod_labels_overwrite_allowed`를 사용하여 빌드마다 파드 라벨을 덮어쓸 수 있습니다. |
| `pod_labels_overwrite_allowed` | 파드 라벨 덮어쓰기 환경 변수의 내용을 유효성 검사하기 위한 정규식입니다. 비어 있으면 파드 라벨 덮어쓰기 기능이 비활성화됩니다. |
| `pod_security_context` | 구성 파일을 통해 빌드 파드에 대한 pod 보안 컨텍스트를 설정합니다. [보안 컨텍스트에 대해 자세히 알아보기](#set-a-security-policy-for-the-pod). |
| `pod_termination_grace_period_seconds` | 파드가 정상적으로 종료되기까지 걸리는 시간(초)을 결정하는 파드 수준 설정입니다. 이 기간이 지나면 프로세스가 kill 시그널로 강제로 중지됩니다. `terminationGracePeriodSeconds`가 지정된 경우 무시됩니다. |
| `poll_interval` | 러너가 생성한 Kubernetes 파드의 상태를 확인하기 위해 대기하는 시간(초)입니다(기본값 = 3). |
| `poll_timeout` | 생성한 컨테이너에 연결을 시도하는 시간(초). 한 번에 처리할 수 있는 빌드를 추가로 대기시키는 데 유용합니다(기본값 = 180). |
| `cleanup_resources_timeout` | 작업이 완료된 후 Kubernetes 리소스를 정리하는 데 필요한 총 시간입니다. 지원되는 구문:`1h30m`, `300s`, `10m`. 기본값은 5분(`5m`)입니다. |
| `priority_class_name` | 파드에 설정할 Priority Class를 지정합니다. 설정되지 않으면 기본값이 사용됩니다. |
| `privileged` | 특권 플래그를 사용하여 컨테이너를 실행합니다. |
| `pull_policy` | 이미지 풀(policy) 정책을 지정합니다:`never`, `if-not-present`, `always`. 설정되지 않으면 클러스터의 이미지 [기본 풀(policy) 정책](https://kubernetes.io/docs/concepts/containers/images/#updating-images)이 사용됩니다. 여러 풀(policy) 정책을 설정하는 방법에 대한 자세한 내용과 지침은 [pull(policy) 정책 사용](#set-a-pull-policy)을 참조하세요. [`if-not-present`, `never` 보안 고려 사항](../../security/index.md#usage-of-private-docker-images-with-if-not-present-pull-policy) 및 [pull(policy) 정책 제한](#restrict-docker-pull-policies)도 참조하세요. |
| `resource_availability_check_max_attempts` | 포기하기 전에 리소스(서비스 계정 및/또는 풀 시크릿)가 사용 가능한지 확인하는 최대 시도 횟수입니다. 각 시도 사이에는 5초의 간격이 있습니다. GitLab 15.0에 [도입되었습니다](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27664). [준비 단계 중 자원 확인에 대해 자세히 알아보기](#resources-check-during-prepare-step). |
| `runtime_class_name` | 생성된 모든 파드에 사용할 런타임 클래스입니다. 클러스터에서 이 기능이 지원되지 않으면 작업이 종료되거나 실패합니다. |
| `service_container_security_context` | 서비스 컨테이너에 대한 컨테이너 보안 컨텍스트를 설정합니다. [보안 컨텍스트에 대해 자세히 알아보기](#set-a-security-policy-for-the-pod). |
| `scheduler_name` | 빌드 파드를 예약하는 데 사용할 스케줄러입니다. |
| `service_account` | Kubernetes API와 통신하는 데 사용되는 기본 서비스 계정 작업/실행기 파드입니다. |
| `service_account_overwrite_allowed` | 서비스 계정 덮어쓰기 기능을 비활성화하는 데 사용되는 환경 변수의 내용을 유효성 검사하기 위한 정규식입니다. 설정되지 않으면 서비스 계정 덮어쓰기 기능이 비활성화됩니다. |
| `services` | [sidecar pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/sidecar)을 사용하여 빌드 컨테이너에 연결된 [서비스](https://docs.gitlab.com/ee/ci/services/) 목록입니다. [서비스 사용에 대해 자세히 알아보기](#define-a-list-of-services). |
| `use_service_account_image_pull_secrets` | 활성화된 경우 실행기에 의해 생성된 파드에 `imagePullSecrets`가 없습니다. 이로 인해 설정된 경우 [`이미지 풀 시크릿`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-image-pull-secret-to-service-account)에서 파드가 생성됩니다. |
| `terminationGracePeriodSeconds` | 파드에서 실행 중인 프로세스에 종료 신호가 보내지고 프로세스가 kill 시그널로 중지될 때까지 걸리는 시간입니다. [deprecated](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28165)됨에 따라 `cleanup_grace_period_seconds` 및 `pod_termination_grace_period_seconds`를 사용합니다. |
| `volumes` | 빌드 컨테이너에 장착된 볼륨 목록을 설정합니다. [볼륨 사용에 대해 자세히 알아보기](#configure-volume-types). |
| `pod_spec` | 이 설정은 실험적인 기능입니다. 러너 매니저에 의해 생성된 파드 사양을 덮어쓴 다음 CI 작업을 실행하는 데 사용됩니다. 모든 속성은 설정할 수 있습니다. 자세한 내용은 [생성된 파드 사양 덮어쓰기 (실험)](#overwrite-generated-pod-specifications)를 참조하세요. |
| `retry_limit` | Kubernetes API와 통신하기 위한 최대 시도 횟수입니다. 각 시도 사이의 재시도 간격은 500 ms부터 시작하는 backoff 알고리즘을 기반으로 합니다. |
| `retry_limits` | 각 요청 오류의 재시도 횟수입니다. |
### 구성 예시
다음 예시는 Kubernetes Executor를 위한 `config.toml` 파일의 구성 예시를 보여줍니다.
```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
플래그를 사용할 수 있습니다.
포드 및 컨테이너
작업 실행 방식을 제어하기 위해 포드 및 컨테이너를 구성할 수 있습니다.
작업용 기본 주석
다음 주석은 기본적으로 작업을 실행하는 Pod에 추가됩니다:
Key | Description |
---|---|
job.runner.gitlab.com/id
| GitLab 인스턴스 전체에서 고유한 작업 ID입니다. |
job.runner.gitlab.com/url
| 작업 세부 정보에 대한 URL입니다. |
job.runner.gitlab.com/sha
| 프로젝트가 빌드된 커밋 수정입니다. |
job.runner.gitlab.com/before_sha
| 브랜치 또는 태그에서 이전 최신 커밋입니다. |
job.runner.gitlab.com/ref
| 프로젝트가 빌드된 브랜치 또는 태그 이름입니다. |
job.runner.gitlab.com/name
| 작업의 이름입니다. |
project.runner.gitlab.com/id
| 작업의 프로젝트 ID입니다. |
기본 주석을 덮어쓰려면 GitLab Runner 구성에서 pod_annotations
를 사용합니다.
또는 .gitlab-ci.yml
파일에서 각 CI/CD 작업의 주석을 덮어쓸 수 있습니다.
포드 라이프사이클
포드의 라이프사이클은 다음과 같이 영향을 받을 수 있습니다:
-
TOML
구성 파일에서pod_termination_grace_period_seconds
속성을 설정합니다. Pod에서 실행 중인 프로세스는TERM
시그널이 전송된 후 주어진 기간 동안 실행될 수 있습니다. 이 기간이 지난 후에도 Pod가 성공적으로 종료되지 않으면 종료 시그널이 전송됩니다. -
FF_USE_POD_ACTIVE_DEADLINE_SECONDS
기능 플래그를 활성화합니다. 활성화되면 작업 시간이 초과되면 CI/CD 작업을 실행 중인 Pod가 실패로 표시되고 관련된 모든 컨테이너가 종료됩니다. 먼저 GitLab에서 작업 시간 초과를 하려면,activeDeadlineSeconds
를구성된 시간 + 1 초
로 설정합니다.
참고:
FF_USE_POD_ACTIVE_DEADLINE_SECONDS
기능 플래그가 활성화되어 있고 pod_termination_grace_period_seconds
에 0이 아닌 값을 설정한 경우,
작업 시간이 초과되어도 CI 작업 Pod가 즉시 종료되지 않습니다.
Pod terminationGracePeriods
는 Pod가 만료될 때만 종료되도록 보장합니다.
포드 toleration 덮어쓰기
Kubernetes 포드 toleration을 덮어쓰려면:
-
config.toml
또는 Helmvalues.yaml
파일에서node_tolerations_overwrite_allowed
에 대한 정규 표현식을 정의하여 CI 작업 포드 toleration 덮어쓰기를 활성화합니다. 이 정규 표현식은KUBERNETES_NODE_TOLERATIONS_
로 시작하는 CI 변수 이름의 값을 유효성 검사합니다.runners: ... config: | [[runners]] [runners.kubernetes] node_tolerations_overwrite_allowed = ".*"
-
.gitlab-ci.yml
파일에서 하나 이상의 CI 변수를 정의하여 CI 작업 포드 toleration을 덮어쓸 수 있습니다.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: '' # 모든 taint을 허용
Pod 라벨 덮어쓰기
각 CI/CD 작업에 대해 Kubernetes 파드 라벨을 덮어쓰려면:
-
.config.yaml
파일에서pod_labels_overwrite_allowed
에 대한 정규 표현식을 정의하세요. -
.gitlab-ci.yml
파일에서KUBERNETES_POD_LABELS_*
변수를 설정하고key=value
값을 사용하세요. 파드 라벨은key=value
로 덮어쓰입니다. 여러 값을 적용할 수 있습니다:variables: KUBERNETES_POD_LABELS_1: "Key1=Val1" KUBERNETES_POD_LABELS_2: "Key2=Val2" KUBERNETES_POD_LABELS_3: "Key3=Val3"
Pod 주석 덮어쓰기
각 CI/CD 작업에 대해 Kubernetes 파드 주석을 덮어쓰려면:
-
.config.yaml
파일에서pod_annotations_overwrite_allowed
에 대한 정규 표현식을 정의하세요. -
.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"
생성된 파드 사양 덮어쓰기
세부정보: 상태: Beta
- 소개됨 : GitLab Runner 15.10에서.
이 기능은 Beta 상태입니다. 운영 클러스터에서 사용하기 전에 테스트 Kubernetes 클러스터에서 이 기능을 사용하는 것을 권장합니다. 이 기능을 사용하려면 FF_USE_ADVANCED_POD_SPEC_CONFIGURATION
기능 플래그를 활성화해야 합니다.
기능이 일반적으로 사용 가능해지기 전에 피드백을 추가하려면 이 이슈를 사용하세요.
런너 매니저에 의해 생성된 PodSpec
을 수정하려면 config.toml
파일의 pod_spec
설정을 사용하세요.
pod_spec
설정은 다음을 수행합니다:
- 생성된 파드 사양에 대한 필드를 덮어씁니다.
- GitLab Runner에 의해 생성된
PodSpec
객체에 설정된 구성 값을 덮어씁니다.
여러 pod_spec
설정을 구성할 수 있습니다.
설정 | 설명 |
---|---|
name
| 사용자 정의 pod_spec 에 지정된 이름.
|
patch_path
| 최종 PodSpec 객체에 적용되기 전에 변경을 정의하는 파일의 경로. 파일은 JSON 또는 YAML 파일이어야 합니다.
|
patch
| 최종 PodSpec 객체에 적용해야 하는 변경을 설명하는 JSON 또는 YAML 형식 문자열.
|
patch_type
| 러너가 GitLab Runner에 의해 생성된 PodSpec 객체에 지정된 변경을 적용하는 전략. 허용되는 값은 merge , json , strategic 입니다.
|
patch_path
및 patch
를 동일한 pod_spec
구성에 설정할 수 없습니다. 그렇지 않으면 오류가 발생합니다.
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
패치 전략은 기존 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
패치 전략은 JSON Patch 사양를 사용하여 PodSpec
개체 및 배열을 업데이트합니다. 이 전략은 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
컨테이너에 리소스 요청
이 설정됩니다.
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"
이 구성을 사용하면 리소스 요청
이 build
컨테이너에 설정됩니다.
최적의 사례
- 프로덕션 환경에 배포하기 전에 추가된
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"
각 빌드 작업을 위해 Pod Spec 수정하여 PVC 생성
각 빌드 작업을 위해 PersistentVolumeClaim를 만들려면 Pod Spec 기능을 활성화하는 방법을 확인하십시오.
Kubernetes는 Pod 수명주기에 첨부된 임시 PersistentVolumeClaim를 생성할 수 있도록 합니다. 이것은 각 PVC
가 새 Volume을 요청할 수 있는 경우에 작동합니다. Volume도 Pod의 수명주기에 묶입니다.
동적 프로비저닝이 활성화된 후, config.toml
은 다음과 같이 수정될 수 있습니다.
[[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: <The Storage Class that will dynamically provision a Volume>
accessModes: [ ReadWriteOnce ]
resources:
requests:
storage: 1Gi
'''
Pod를 위한 보안 정책 설정
빌드 Pod의 보안 정책을 설정하려면 security context를 config.toml
에 구성하세요.
다음 옵션을 사용하세요:
옵션 | 유형 | 필수 | 설명 |
---|---|---|---|
fs_group
| int
| No | Pod의 모든 컨테이너에 적용되는 특별 보충 그룹입니다. |
run_as_group
| int
| No | 컨테이너 프로세스의 GID를 실행할 GID입니다. |
run_as_non_root
| boolean | No | 컨테이너가 루트가 아닌 사용자로 실행해야 함을 나타냅니다. |
run_as_user
| int
| No | 컨테이너 프로세스의 UID를 실행할 UID입니다. |
supplemental_groups
|
int 목록
| No | 첫 번째 프로세스에 적용되는 추가 그룹 목록입니다. |
selinux_type
| string
| No | Pod의 모든 컨테이너에 적용되는 SELinux 타입 레이블입니다. |
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
이전 러너 파드 제거
- GitLab Runner 14.6에서 도입되었습니다.
가끔씩 이전 러너 파드가 지워지지 않을 수 있습니다. 이는 러너 매니저가 잘못되게 종료된 경우에 발생할 수 있습니다.
이 상황을 처리하기 위해, GitLab Runner Pod Cleanup 애플리케이션을 사용하여 이전 파드를 정리하는 스케줄을 예약할 수 있습니다. 더 많은 정보는 아래에서 확인하세요:
컨테이너에 보안 정책 설정
- GitLab Runner 14.5에서 도입되었습니다.
빌드, 헬퍼 또는 서비스 파드를 위한 컨테이너 보안 정책을 설정하기 위해 config.toml
실행자 내에서 컨테이너 보안 컨텍스트를 구성합니다.
다음 옵션을 사용하세요:
옵션 | 유형 | 필수 | 설명 |
---|---|---|---|
run_as_group
| int | 아니요 | 컨테이너 프로세스의 진입점을 실행할 GID. |
run_as_non_root
| 부울린 | 아니요 | 컨테이너가 반드시 루트가 아닌 사용자로 실행해야 함을 나타냅니다. |
run_as_user
| int | 아니요 | 컨테이너 프로세스의 진입점을 실행할 UID. |
capabilities.add
| 문자열 목록 | 아니요 | 컨테이너를 실행할 때 추가할 수 있는 기능. |
capabilities.drop
| 문자열 목록 | 아니요 | 컨테이너를 실행할 때 삭제할 수 있는 기능. |
selinux_type
| 문자열 | 아니요 | 컨테이너 프로세스와 연관된 SELinux 유형 라벨. |
다음 예제는 config.toml
내에서 보안 컨텍스트 구성을 보여줍니다:
- 파드 보안 컨텍스트를 설정합니다.
- 빌드 및 헬퍼 컨테이너를 위해
run_as_user
및run_as_group
를 재정의합니다. - 모든 서비스 컨테이너가 파드 보안 컨텍스트에서
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
풀 정책 설정
config.toml
파일 내의 pull_policy
매개변수를 사용하여 단일 또는 다중 풀 정책을 지정합니다. 이 정책은 이미지를 가져오고 업데이트하는 방법을 제어하며, 빌드 이미지, 헬퍼 이미지 및 모든 서비스에 적용됩니다.
어떤 정책을 사용할지 결정하려면 풀 정책에 대한 Kubernetes 문서를 참조하세요.
단일 풀 정책의 경우:
[runners.kubernetes]
pull_policy = "never"
다중 풀 정책의 경우:
[runners.kubernetes]
# 다중 풀 정책 사용
pull_policy = ["always", "if-not-present"]
여러 정책을 정의한 경우, 이미지가 성공적으로 얻어질 때까지 각 정책이 시도됩니다.
예를 들어, [ always, if-not-present ]
를 사용하면 임시 레지스트리 문제로 always
정책이 실패하면 if-not-present
정책이 사용됩니다.
실패한 풀을 재시도하려면:
[runners.kubernetes]
pull_policy = ["always", "always"]
GitLab의 네이밍 규칙은 Kubernetes와 다릅니다.
러너 풀 정책 | Kubernetes 풀 정책 | 설명 |
---|---|---|
빈칸 | 빈칸 | Kubernetes에서 지정된 기본 정책 사용. |
if-not-present
| IfNotPresent
| 이미지는 작업을 실행하는 노드에 이미 존재하지 않을 때에만 가져옵니다. 사용에 대한 고려해야 할 사항이 있습니다. |
always
| Always
| 이미지는 작업이 실행될 때마다 항상 가져옵니다. |
never
| Never
| 이미지는 가져오지 않으며, 노드에 이미 존재해야 합니다. |
컨테이너 기능 지정
컨테이너에서 사용할 Kubernetes 기능을 지정할 수 있습니다.
컨테이너 기능을 지정하려면 config.toml
의 cap_add
및 cap_drop
옵션을 사용합니다. 컨테이너 런타임은 또한 Docker나 container와 같이 기능의 기본 목록을 정의할 수 있습니다.
기본적으로 러너가 기본적으로 삭제하는 삭제된 기능 목록이 있습니다. cap_add
옵션에 나열된 기능은 삭제되지 않습니다.
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"]
# ...
기능을 지정할 때 다음 사항을 유의하세요:
-
사용자 정의
cap_drop
은 사용자 정의cap_add
보다 우선합니다. 두 설정에서 동일한 기능을 정의하면cap_drop
에서만 기능이 컨테이너로 전달됩니다. -
컨테이너 구성에 전달되는 기능 식별자에서
CAP_
접두사를 제거하세요. 예를 들어,CAP_SYS_TIME
기능을 추가하거나 제거하려면 설정 파일에서 문자열SYS_TIME
을 입력하세요. -
Kubernetes 클러스터의 소유자는 PodSecurityPolicy를 정의하여 특정 기능을 허용, 제한 또는 기본적으로 추가할 수 있습니다. 이러한 규칙은 사용자 정의 구성보다 우선합니다.
컨테이너 리소스 덮어쓰기
각 CI/CD 작업에 대해 Kubernetes CPU 및 메모리 할당을 덮어쓸 수 있습니다. 빌드, 헬퍼 및 서비스 컨테이너의 요청 및 제한 설정을 적용할 수 있습니다.
컨테이너 리소스를 덮어쓰려면 .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 기본 서비스 계정 덮어쓰기
.gitlab-ci.yml
파일에서 각 CI/CD 작업의 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에서.
각 작업 컨테이너에 RuntimeClass를 설정하려면 runtime_class_name
을 사용합니다.
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"]
노드 셀렉터 덮어쓰기
노드 셀렉터를 덮어쓰려면:
-
config.toml
또는 Helmvalues.yaml
파일에서 노드 셀렉터 덮어쓰기를 활성화합니다:runners: ... config: | [[runners]] [runners.kubernetes] node_selector_overwrite_allowed = ".*"
-
.gitlab-ci.yml
파일에서 노드 셀렉터를 덮어쓰기하기 위한 변수를 정의합니다:variables: KUBERNETES_NODE_SELECTOR_* = ''
다음 예시에서는 Kubernetes 노드 아키텍처를 덮어쓰기하기 위해 config.toml
및 .gitlab-ci.yml
에서 설정이 구성됩니다:
config.toml
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=.*" # <--- 아키텍처 덮어쓰기 허용
.gitlab-ci.yml
job:
image: IMAGE_NAME
variables:
KUBERNETES_NODE_SELECTOR_ARCH: 'kubernetes.io/arch=amd64' # <--- 올바른 아키텍처 선택
빌드를 실행할 노드 지정
node_selector
옵션을 사용하여 Kubernetes 클러스터의 특정 노드에서 빌드를 실행할 수 있도록 지정합니다.
이는 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가 리눅스 환경에서 동작하고 있는 경우, PowerShell이 Windows 노드를 대상으로 할 때 경로를 올바르게 해석하려면
# 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"
네트워킹
컨테이너 라이프사이클 후크 구성
컨테이너 라이프사이클 후크를 사용하여 해당 라이프사이클 후크를 실행할 때 구성된 코드를 실행합니다.
두 가지 유형의 후크를 구성할 수 있습니다: 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"
각 라이프사이클 후크를 구성하려면 다음 설정을 사용하십시오:
옵션 | 유형 | 필수 | 설명 |
---|---|---|---|
exec
| KubernetesLifecycleExecAction
| 아니오 |
Exec 는 수행할 작업을 지정합니다.
|
http_get
| KubernetesLifecycleHTTPGet
| 아니오 |
HTTPGet 은 수행할 HTTP 요청을 지정합니다.
|
tcp_socket
| KubernetesLifecycleTcpSocket
| 아니오 |
TCPsocket 은 TCP 포트와 관련된 작업을 지정합니다.
|
KubernetesLifecycleExecAction
옵션 | 유형 | 필수 | 설명 |
---|---|---|---|
command
|
문자열 목록
| 예 | 컨테이너 내부에서 실행할 명령어 라인입니다. |
KubernetesLifecycleHTTPGet
옵션 | 유형 | 필수 | 설명 |
---|---|---|---|
port
| int
| 예 | 컨테이너에서 액세스할 포트 번호입니다. |
host
| 문자열
| 아니오 | 연결할 호스트 이름으로, 기본값은 pod IP입니다(옵션). |
path
| 문자열
| 아니오 | HTTP 서버에서 액세스할 경로입니다(옵션). |
scheme
| 문자열
| 아니오 | 호스트에 연결하는 데 사용되는 체계입니다. 기본값은 HTTP입니다(옵션). |
http_headers
|
KubernetesLifecycleHTTPGetHeader 목록
| 아니오 | 요청에 설정할 사용자 정의 헤더입니다(옵션). |
KubernetesLifecycleHTTPGetHeader
옵션 | 타입 | 필수여부 | 설명 |
---|---|---|---|
name
| string | Yes | HTTP 헤더 이름. |
value
| string | Yes | HTTP 헤더 값. |
KubernetesLifecycleTcpSocket
옵션 | 타입 | 필수여부 | 설명 |
---|---|---|---|
port
| int
| Yes | 컨테이너에서 액세스할 포트 번호. |
host
| string | No | 연결할 호스트 이름, 기본값은 팟 IP(선택사항). |
팟 DNS 설정 구성
팟의 DNS 설정을 구성하는 데 다음 옵션을 사용합니다.
옵션 | 타입 | 필수여부 | 설명 |
---|---|---|---|
nameservers
|
string 목록
| No | 팟의 DNS 서버로 사용될 IP 주소 목록. |
options
| KubernetesDNSConfigOption
| No | 각 객체마다 이름 속성(필수)과 값을 속성(선택사항)을 갖는 객체의 선택사항 목록. |
searches
|
string 목록
| No | 팟 내에서 호스트명 조회를 위한 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
옵션 | 타입 | 필수여부 | 설명 |
---|---|---|---|
name
| string | Yes | 구성 옵션 이름. |
value
| *string
| No | 구성 옵션 값. |
기본 삭제된 능력(capabilities) 목록
GitLab Runner는 다음과 같은 능력(capabilities)을 기본적으로 삭제합니다.
사용자 정의 cap_add
가 기본적으로 삭제된 능력 목록보다 우선합니다.
기본적으로 삭제된 능력에 추가하려면 cap_add
에 추가하면 됩니다.
-
NET_RAW
추가 호스트 별칭 추가
이 기능은 Kubernetes 1.7 이상에서 사용할 수 있습니다.
컨테이너의 /etc/hosts
파일에 항목을 추가하도록 Kubernetes에 지시하는 호스트 별칭을 구성합니다.
다음 옵션을 사용합니다:
옵션 | 타입 | 필수여부 | 설명 |
---|---|---|---|
IP
| string | Yes | 호스트를 추가할 IP 주소. |
Hostnames
|
string 목록
| Yes | IP에 추가될 호스트명 별칭의 목록. |
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 실행기에서 캐시 사용하기
캐시가 Kubernetes 실행기와 함께 사용될 때, /cache
라는 볼륨이 팟에 장착됩니다. 작업 실행 중에 캐시된 데이터가 필요한 경우, Runner는 캐시된 데이터의 사용 가능 여부를 확인합니다. 캐시된 데이터는 캐시 볼륨에 압축 파일이 있는 경우 사용 가능합니다.
캐시 볼륨을 설정하려면 config.toml
파일의 cache_dir
설정을 사용합니다.
- 사용 가능한 경우, 압축 파일은 빌드 폴더로 추출되어 작업에서 사용할 수 있습니다.
- 사용 가능하지 않은 경우, 캐시된 데이터가 구성된 저장소에서 다운로드되어
cache dir
에 압축 파일로 저장됩니다. 그런 다음 압축 파일이build
폴더로 추출됩니다.
볼륨 유형 구성
다음과 같은 볼륨 유형을 마운트할 수 있습니다.
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
파일에서 다음 옵션을 사용하세요:
옵션 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name
| string | Yes | 볼륨의 이름. |
mount_path
| string | Yes | 볼륨이 마운트된 컨테이너 내부의 경로. |
sub_path
| string | No | 루트 대신 볼륨 내에서 서브 경로를 마운트합니다. |
host_path
| string | No | 볼륨으로 마운트할 호스트 경로. 지정하지 않으면 mount_path 와 동일한 경로로 설정됩니다.
|
read_only
| boolean | No | 볼륨을 읽기 전용 모드로 설정합니다 (기본값은 false). |
persistentVolumeClaim
볼륨
persistentVolumeClaim
볼륨을 구성하여 Kubernetes에게 Kubernetes 클러스터에서 정의된 persistentVolumeClaim
를 사용하고 컨테이너에 마운트하도록 지시합니다.
config.toml
파일에서 다음 옵션을 사용하세요:
옵션 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name
| string | Yes | 볼륨의 이름이자 사용해야 하는 PersistentVolumeClaim 의 이름입니다. 변수를 지원합니다. 자세한 내용은 Persistent per-concurrency build volumes를 참조하세요.
|
mount_path
| string | Yes | 볼륨이 마운트된 컨테이너 내의 경로. |
read_only
| boolean | No | 볼륨을 읽기 전용 모드로 설정합니다 (기본값은 false). |
sub_path
| string | No | 루트 대신 볼륨 내에서 서브 경로를 마운트합니다. |
configMap
볼륨
configMap
볼륨을 구성하여 Kubernetes에게 Kubernetes 클러스터에서 정의된 configMap
을 사용하고 컨테이너에 마운트하도록 지시합니다.
config.toml
에서 다음 옵션을 사용하세요:
옵션 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name
| string | Yes | 볼륨의 이름과 동시에 사용해야 하는 _configMap_의 이름입니다. |
mount_path
| string | Yes | 볼륨이 마운트된 컨테이너 내의 경로. |
read_only
| boolean | No | 볼륨을 읽기 전용 모드로 설정합니다 (기본값은 false). |
sub_path
| string | No | 루트 대신 볼륨 내에서 서브 경로를 마운트합니다. |
items
| map[string]string
| no | 사용해야 하는 _configMap_의 키에 대한 키-경로 매핑. |
configMap
의 각 키는 파일로 변경되어 마운트된 경로에 저장됩니다. 기본적으로:
- 모든 키가 포함됩니다.
-
configMap
키가 파일명으로 사용됩니다. - 값은 파일 내용에 저장됩니다.
기본 키 및 값 저장을 변경하려면 items
옵션을 사용하세요. items
옵션을 사용하면 지정된 키만 볼륨에 추가되고 다른 모든 키는 건너뜁니다.
참고: 존재하지 않는 키를 사용하면 pod를 생성하는 단계에서 작업이 실패합니다.
secret
볼륨
secret
볼륨을 구성하여 Kubernetes에게 Kubernetes 클러스터에서 정의된 secret
을 사용하도록 지시하고 컨테이너에 장착합니다.
config.toml
파일에서 다음 옵션을 사용하세요:
옵션 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
name
| 문자열 | 예 | 볼륨의 이름이자 사용해야 하는 _secret_의 이름입니다. |
mount_path
| 문자열 | 예 | 볼륨을 장착해야 하는 컨테이너 내부 경로입니다. |
read_only
| 부울 | 아니오 | 볼륨을 읽기 전용 모드로 설정합니다 (기본값은 false입니다). |
sub_path
| 문자열 | 아니오 | 루트 대신 볼륨 내의 하위 경로를 장착합니다. |
items
| map[string]string
| 아니오 | 사용해야 하는 _configMap_에서 키와 경로를 매핑합니다. |
선택한 secret
의 각 키는 선택한 장착 경로에 저장된 파일로 변경됩니다. 기본적으로:
- 모든 키가 포함됩니다.
-
configMap
키가 파일 이름으로 사용됩니다. - 값은 파일 내용에 저장됩니다.
기본 키 및 값 저장을 변경하려면 items
옵션을 사용하세요. items
옵션을 사용하면 지정된 키만 볼륨에 추가되고 다른 모든 키는 건너뜁니다.
참고: 존재하지 않는 키를 사용하면 해당 키가 없는 경우 pod 생성 단계에서 작업이 실패합니다.
emptyDir
볼륨
emptyDir
볼륨을 구성하여 Kubernetes에게 컨테이너 내에 빈 디렉터리를 장착하도록 지시합니다.
config.toml
파일에서 다음 옵션을 사용하세요:
옵션 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
name
| 문자열 | 예 | 볼륨의 이름입니다. |
mount_path
| 문자열 | 예 | 볼륨을 장착해야 하는 컨테이너 내부 경로입니다. |
sub_path
| 문자열 | 아니오 | 루트 대신 볼륨 내의 하위 경로를 장착합니다. |
medium
| 문자열 | 아니오 | “Memory”는 tmpfs 를 제공하며, 그렇지 않으면 노드 디스크 저장소(기본값은 ““)를 사용합니다.
|
size_limit
| 문자열 | 아니오 |
emptyDir 볼륨에 필요한 로컬 저장소의 총량입니다.
|
csi
볼륨
컨테이너 스토리지 인터페이스 (csi
) 볼륨을 구성하여 Kubernetes에게 사용자 정의 csi
드라이버를 사용하여 컨테이너에 임의의 저장 시스템을 장착하도록 지시합니다.
config.toml
에서 다음 옵션을 사용하세요:
옵션 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
name
| 문자열 | 예 | 볼륨의 이름입니다. |
mount_path
| 문자열 | 예 | 볼륨을 장착해야 하는 컨테이너 내부 경로입니다. |
driver
| 문자열 | 예 | 사용할 볼륨 드라이버의 이름을 지정하는 문자열 값입니다. |
fs_type
| 문자열 | 아니오 | 파일 시스템 유형의 이름을 지정하는 문자열 값(예: “ext4”, “xfs”, “ntfs”.)입니다. |
volume_attributes
| map[string]string
| 아니오 | CSI 볼륨의 속성에 대한 키-값 쌍 매핑입니다. |
sub_path
| 문자열 | 아니오 | 루트 대신 볼륨 내의 하위 경로를 장착합니다. |
read_only
| 부울 | 아니오 | 볼륨을 읽기 전용 모드로 설정합니다 (기본값은 false입니다). |
서비스 컨테이너에 볼륨 장착
빌드 컨테이너용으로 정의된 볼륨은 모든 서비스 컨테이너에 자동으로 장착됩니다. 이 기능을 사용하여 테스트 속도를 높이기 위해 RAM에 데이터베이스 저장소를 장착하는 것은 services_tmpfs
의 대안으로 사용할 수 있습니다(도커 실행자에만 사용 가능).
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
환경만 필요한 경우, GitLab Runner UBI
및 GitLab Runner Helper UBI
대신에 OpenShift (OCP) 이미지를 사용할 수 있습니다.
다음 예시는 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
이미지를 실행하는 경우, 컨테이너는 특권 모드로 실행되어야 합니다. 이는 잠재적인 리스크를 가질 수 있으며 추가적인 문제를 일으킬 수 있습니다.
도커 데몬은 서비스로 시작되기 때문에 기본적으로 팟 내에서 별도의 컨테이너로 실행됩니다. 팟 내의 컨테이너는 할당된 볼륨과 서로 통신하기 위해 사용하는 IP 주소만 공유하며 localhost
를 사용하여 서로 통신합니다. docker:dind
컨테이너는 /var/run/docker.sock
를 공유하지 않으며 docker
바이너리는 기본적으로 사용합니다.
클라이언트를 구성하기 위해 빌드 컨테이너의 환경 변수를 포함한 다른 컨테이너를 사용하여 도커 데몬에 접속하도록 설정하세요:
- 무 TLS 연결을 위해
DOCKER_HOST=tcp://<호스트명>:2375
. - TLS 연결을 위해
DOCKER_HOST=tcp://<호스트명>:2376
.
호스트명
으로 다음 값을 설정하세요:
- GitLab Runner 12.7 및 이전 버전, 그리고 Kubernetes 1.6 및 이전 버전에 대해
localhost
. - GitLab Runner 12.8 및 이후 버전, 그리고 Kubernetes 1.7 및 이후 버전에 대해
docker
.
Docker 19.03 및 이후 버전에서는 TLS가 기본적으로 활성화되어 있지만 클라이언트에 인증서를 매핑해야 합니다. DIND에 대해 무 TLS 연결을 활성화하거나 인증서를 마운트할 수 있습니다. 자세한 내용은 Docker executor로 Docker In Docker Workflow 사용를 참조하세요.
호스트 커널 노출 방지
만약 docker:dind
나 /var/run/docker.sock
을 사용할 경우, Docker 데몬은 호스트 머신의 기본 커널에 액세스합니다. 이는 파드에서 설정한 limits
가 Docker 이미지를 빌드할 때 작동하지 않음을 뜻합니다. Kubernetes에서 생성된 Docker 빌드 컨테이너에 부과된 제한에 관계없이 Docker 데몬은 노드의 전체 용량을 보고합니다.
만약 빌드 컨테이너를 관리 권한 모드에서 실행하거나 /var/run/docker.sock
이 노출된 경우, 호스트 커널은 빌드 컨테이너에 노출될 수 있습니다. 노출을 최소화하려면 node_selector
옵션에 레이블을 지정하세요. 이로써 컨테이너가 노드에 배포되기 전에 해당 노드가 레이블과 일치하는지 확인됩니다. 예를 들어, role=ci
레이블을 지정하면 빌드 컨테이너는 role=ci
로 레이블이 지정된 노드에서만 실행되며, 모든 다른 프로덕션 서비스는 다른 노드에서 실행됩니다.
또한 빌드 컨테이너를 더욱 분리하려면 노드 taints를 사용할 수 있습니다. Taints는 빌드 파드와 동일한 노드에 다른 파드가 예약되는 것을 방지하며, 다른 파드에 대한 추가 구성이 필요하지 않습니다.
Docker 이미지 빌드를 위한 kaniko 사용
Kaniko를 사용하여 Kubernetes 클러스터 내에서 Docker 이미지를 빌드할 수 있습니다.
Kaniko는 Docker 데몬없이 특권 액세스 없이 이미지를 빌드합니다.
더 많은 정보는 kaniko 및 GitLab CI/CD를 사용하여 이미지 빌드를 참조하세요.
Dockerfiles
의 _multi-stage_를 빌드하기 위해 kaniko를 사용하는 경우 알려진 이슈가 있습니다. 파이프라인 작업에 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가 Dockerfiles
를 빌드할 때 컨테이너의 WORKDIR
을 삭제하기 때문에 실패합니다. 이는 kubectl exec
(및 유사한 SDK API)가 컨테이너에 연결하는 것을 방지합니다.
이 문제에 대한 두 가지 해결책이 있습니다:
- kaniko 실행 호출에
--ignore-path /workspace
를 추가합니다. - 작업의
script
에 kaniko 실행 호출 이후에mkdir -p /workspace
를 추가합니다.
더 많은 정보는 issue 30769를 참조하세요.
Docker 이미지 및 서비스 제한
- GitLab Runner 14.2에서 Kubernetes executor를 위해 추가되었습니다.
작업을 실행하는 데 사용되는 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에서 기본적으로 첨부 사용 중.
기본적으로 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
exceeded quota
와 같이 완전히 다른 오류를 재시도하려면 20번 재시도하도록 설정하세요:
[[runners]]
name = "myRunner"
url = "https://gitlab.example.com/"
executor = "kubernetes"
[runners.kubernetes]
retry_limit = 5
[runners.kubernetes.retry_limits]
"exceeded quota" = 20
컨테이너 진입점 알려진 문제
참고:
GitLab 14.5부터 15.0까지 Kubernetes 실행기와 함께 사용될 때, GitLab Runner는 kube attach
와 함께 Docker 이미지에서 정의된 진입점을 사용합니다.
GitLab 15.1부터는 FF_KUBERNETES_HONOR_ENTRYPOINT
가 설정된 경우 Kubernetes 실행기와 함께 Docker 이미지에서 정의된 진입점이 사용됩니다.
진입점에는 다음과 같은 알려진 문제가 있습니다:
- 이미지의 Dockerfile에 진입점이 정의된 경우 올바른 셸을 열어야 합니다. 그렇지 않으면 작업이 멈춥니다.
- 파일 타입 CI/CD 변수는 진입점 실행 중에 디스크에 기록되지 않습니다. 해당 파일은 스크립트 실행 중에 작업에서만 액세스할 수 있습니다.
- 다음과 같은 CI/CD 변수는 진입점에서 액세스할 수 없습니다. 어떤 설정 변경을 하기 전에 스크립트 명령을 실행하려면
before_script
를 사용하세요:
작업 변수 액세스 제한
Kubernetes 실행자를 사용할 때 Kubernetes 클러스터에 액세스 권한이 있는 사용자는 작업에서 사용되는 변수를 읽을 수 있습니다. 기본적으로 작업 변수는 다음 위치에 저장됩니다.
- Pod의 환경 섹션
작업 변수 데이터에 대한 액세스를 제한하려면 GitLab 관리자만이 GitLab Runner에서 사용하는 네임스페이스에 액세스할 수 있도록 역할 기반 액세스 제어(RBAC)를 사용해야 합니다.
다른 사용자가 GitLab Runner 네임스페이스에 액세스해야 할 경우, GitLab Runner 네임스페이스에서 사용자가 가진 액세스 유형을 제한하기 위해 다음 verb
를 설정해야 합니다.
-
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"]
준비 단계 중에 자원 확인
전제 조건:
-
image_pull_secrets
또는service_account
가 설정되어 있어야 합니다. -
resource_availability_check_max_attempts
는 0보다 큰 숫자로 설정되어 있어야 합니다. -
get
및list
권한을 사용하는 KubernetesserviceAccount
가 있어야 합니다.
GitLab Runner는 각 시도 사이에 5초 간격으로 새 서비스 계정 또는 비밀을 확인합니다.
- GitLab 15.0 및 15.1에서는 이 기능을 비활성화할 수 없으며, 음수 값이 설정된 경우 기본적으로
5
로 설정됩니다. - GitLab 15.0.1, 15.1.1, 15.2 및 이후 버전에서는 이 기능이 기본적으로 비활성화됩니다. 이 기능을 활성화하려면
resource_availability_check_max_attempts
를0
이 아닌 다른 값으로 설정하세요. 설정한 값은 러너가 서비스 계정 또는 비밀을 확인하는 횟수를 정의합니다.
Kubernetes 네임스페이스 덮어쓰기
전제 조건:
- GitLab Runner Helm 차트의
values.yml
파일에서rbac.clusterWideAccess
가true
로 설정되어 있어야 합니다. - 러너가 코어 API 그룹에서 구성된 권한을 가져야 합니다.
CI 목적을 위해 네임스페이스를 지정하고 사용자 지정 팟 집합을 배포하기 위해 Kubernetes 네임스페이스를 덮어쓸 수 있습니다. 러너에 의해 생성된 팟은 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-.*"