• 구성 검증
• 전역 섹션
  • log_format 예제 (단축)
    • runner
    • text
    • json
  • check_interval 작동 방식
• [session_server] 섹션
• [[runners]] 섹션
  • clone_url 작동 방식
    • Git LFS 엔드포인트 수정
  • unhealthy_requests_limit 및 unhealthy_interval 작동 방식
• 실행기
• 셸
  • POSIX 준수 셸 사용
• [runners.docker] 섹션
  • [[runners.docker.services]] 섹션
  • [runners.docker] 섹션의 볼륨
    • 예제 1: 데이터 볼륨 추가
    • 예제 2: 호스트 디렉토리를 데이터 볼륨으로 마운트
  • 개인 컨테이너 레지스트리 사용
    • GitLab 통합 레지스트리에 대한 지원
    • 도커 인증 우선 순위 해결
• [runners.parallels] 섹션
• [runners.virtualbox] 섹션
• 기본 VM 이미지 재정의
• [runners.ssh] 섹션
• [runners.machine] 섹션
  • [[runners.machine.autoscaling]] 섹션
  • Periods 구문
• [runners.instance] 섹션
• [runners.autoscaler] 섹션
• [runners.autoscaler.plugin_config] 섹션
• [runners.autoscaler.scale_throttle] 섹션
• [runners.autoscaler.connector_config] 섹션
• [runners.autoscaler.state_storage] 섹션
• [[runners.autoscaler.policy]] 섹션
  • 기간 구문
• [runners.autoscaler.vm_isolation] 섹션
• [runners.autoscaler.vm_isolation.connector_config] 섹션
• [runners.custom] 섹션
• [runners.cache] 섹션
  • [runners.cache.s3] 섹션
    • S3 버킷에서 러너 캐시를 위한 KMS 키 암호화 사용
    • UploadRoleARN으로 멀티파트 업로드 활성화
      • UploadRoleARN로 파일 업로드 하는 방법
    • Kubernetes ServiceAccount 리소스에 대한 IAM 역할 활성화
  • [runners.cache.gcs] 섹션
  • [runners.cache.azure] 섹션
    • Azure workload 및 관리되는 ID
• [runners.kubernetes] 섹션
• 헬퍼 이미지
  • Arm에서 Kubernetes 용 헬퍼 이미지 구성
  • 구버전의 Alpine Linux를 사용하는 러너 이미지
  • Alpine pwsh 이미지
  • 헬퍼 이미지 레지스트리
  • 헬퍼 이미지 재정의
    • PowerShell Core 사용 시
• [runners.custom_build_dir] 섹션
  • 기본 빌드 디렉터리
• [runners.referees] 섹션
  • 메트릭 러너 심판 사용하기
  • GitLab Runner를 위한 메트릭 러너 심판 구성하기

고급 구성

GitLab Runner의 동작을 변경하려면 config.toml 파일을 수정하세요.

config.toml 파일은 다음 위치에서 찾을 수 있습니다:

• GitLab Runner가 root로 실행될 때 *nix 시스템의 /etc/gitlab-runner/. 이 디렉토리는 서비스 구성의 경로이기도 합니다.

• GitLab Runner가 비-root로 실행될 때 *nix 시스템의 ~/.gitlab-runner/.

• 기타 시스템의 ./.

대부분의 옵션을 변경할 때 GitLab Runner는 재시작이 필요하지 않습니다. 이에는 [[runners]] 섹션의 매개변수와 전역 섹션의 대부분의 매개변수가 포함되지만 listen_address는 제외됩니다. 이미 등록된 러너는 다시 등록할 필요가 없습니다.

GitLab Runner는 3초마다 구성 변경 사항을 확인하고 필요한 경우 다시 로드합니다. GitLab Runner는 SIGHUP 신호에 응답하여 구성도 다시 로드합니다.

구성 검증

• GitLab Runner 15.10에서 도입됨

구성 검증은 config.toml 파일의 구조를 확인하는 과정입니다. 구성 검증기의 출력은 info 수준 메시지만 제공합니다.

구성 검증 과정은 정보 제공 목적으로만 사용됩니다. 출력 결과를 사용하여 러너 구성의 잠재적인 문제를 식별할 수 있습니다. 구성 검증이 모든 가능한 문제를 잡아내지 못할 수 있으며, 메시지가 없더라도 config.toml 파일이 완벽하다는 보장은 없습니다.

전역 섹션

이 설정은 전역적입니다. 모든 러너에 적용됩니다.

구성 예시는 다음과 같습니다:

# 예제 `config.toml` 파일  

concurrent = 100 # 이 `config.toml` 파일에서 정의된 모든 러너 섹션에 적용되는 작업 동시성의 전역 설정  
log_level = "warning"  
log_format = "info"  
check_interval = 3 # 초 단위의 값  

[[runners]]  
  name = "first"  
  url = "당신의 GitLab 인스턴스 URL (예: `https://gitlab.com`)"  
  executor = "shell"  
  (...)  

[[runners]]  
  name = "second"  
  url = "당신의 GitLab 인스턴스 URL (예: `https://gitlab.com`)"  
  executor = "docker"  
  (...)  

  [[runners]]  
  name = "third"  
  url = "당신의 GitLab 인스턴스 URL (예: `https://gitlab.com`)"  
  executor = "docker-autoscaler"  
  (...)  

log_format 예제 (단축)

runner

런타임 플랫폼                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
/multi-runner/config.toml...에서 다중 실행 시작...  builds=0
경고: 사용자 모드로 실행 중입니다.
경고: 시스템 모드의 경우 sudo를 사용하세요:
경고: $ sudo gitlab-runner...

구성 로드됨                                builds=0
listen_address가 정의되지 않음, 메트릭 및 디버그 엔드포인트 비활성화됨  builds=0
[session_server].listen_address가 정의되지 않음, 세션 엔드포인트 비활성화됨  builds=0

text

정보[0000] 런타임 플랫폼                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
정보[0000] /etc/gitlab-runner/config.toml...에서 다중 실행 시작...  builds=0
경고[0000] 사용자 모드로 실행 중입니다.
경고[0000] 시스템 모드의 경우 sudo를 사용하세요:
경고[0000] $ sudo gitlab-runner...
정보[0000]
정보[0000] 구성 로드됨                          builds=0
정보[0000] listen_address가 정의되지 않음, 메트릭 및 디버그 엔드포인트 비활성화됨  builds=0
정보[0000] [session_server].listen_address가 정의되지 않음, 세션 엔드포인트 비활성화됨  builds=0

json

{"arch":"amd64","level":"info","msg":"런타임 플랫폼","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"/etc/gitlab-runner/config.toml...에서 다중 실행 시작...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"사용자 모드로 실행 중입니다.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"시스템 모드의 경우 sudo를 사용하세요:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"구성 로드됨","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address가 정의되지 않음, 메트릭 및 디버그 엔드포인트 비활성화됨","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address가 정의되지 않음, 세션 엔드포인트 비활성화됨","time":"2020-06-05T15:57:35+02:00"}

check_interval 작동 방식

config.toml에 [[runners]] 섹션이 두 개 이상 있을 경우, GitLab Runner는 지속적으로 작업 요청을 GitLab 인스턴스에 예약하는 루프를 포함합니다.

다음 예제는 check_interval이 10초이고 두 개의 [[runners]] 섹션 (runner-1 및 runner-2)를 가지고 있습니다. GitLab Runner는 매 10초마다 요청을 보내고 5초 동안 대기합니다:

1. check_interval 값 가져오기 (10s).
2. 러너 목록 가져오기 (runner-1, runner-2).
3. 대기 간격 계산하기 (10s / 2 = 5s).
4. 무한 루프 시작:
   1. runner-1에 대한 작업 요청.
   2. 5s 동안 대기.
   3. runner-2에 대한 작업 요청.
   4. 5s 동안 대기.
   5. 반복.

다음은 check_interval 구성 예제입니다:

# 예제 `config.toml` 파일 

concurrent = 100 # 이 `config.toml` 파일에 정의된 모든 러너 섹션에 적용되는 작업 동시 처리에 대한 글로벌 설정입니다.
log_level = "warning"
log_format = "info"
check_interval = 10 # 초 단위 값

[[runners]]
  name = "runner-1"
  url = "귀하의 GitLab 인스턴스 URL (예: `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "runner-2"
  url = "귀하의 GitLab 인스턴스 URL (예: `https://gitlab.com`)"
  executor = "docker"
  (...)

이 예제에서 러너 프로세스에서의 작업 요청은 매 5초마다 이루어집니다.

runner-1 및 runner-2가 동일한 GitLab 인스턴스에 연결되어 있다면, 이 GitLab 인스턴스도 이 러너로부터 매 5초마다 새 요청을 받습니다.

첫 번째 요청과 두 번째 요청 사이에 두 개의 대기 기간이 발생합니다.

각 기간은 5초를 소요하므로, runner-1의 후속 요청은 대략적으로 10초가 걸립니다.

runner-2에도 동일하게 적용됩니다.

더 많은 러너를 정의하면 대기 간격이 더 작아집니다.

그러나 러너에 대한 요청은 다른 러너와 그 대기 기간에 대한 모든 요청이 호출된 후에 반복됩니다.

[session_server] 섹션

[session_server] 섹션은 사용자가 작업과 상호작용할 수 있게 해줍니다. 예를 들어, 인터랙티브 웹 터미널에서 가능합니다.

[session_server] 섹션은 루트 수준에서 지정해야 하며, 러너별로 지정하지 않아야 합니다. 이 섹션은 [[runners]] 섹션 외부에 정의해야 합니다.

# 세션 서버가 구성된 `config.toml` 파일의 예

concurrent = 100 # 이 `config.toml` 파일에 정의된 모든 러너 섹션에 적용되는 작업 동시 실행에 대한 전역 설정
log_level = "warning"
log_format = "info"
check_interval = 3 # 초 단위의 값

[session_server]
  listen_address = "[::]:8093" # 포트 `8093`에서 모든 사용 가능한 인터페이스에서 수신
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

[session_server] 섹션을 구성할 때:

• listen_address 및 advertise_address의 경우 host:port 형식을 사용하십시오. 여기서 host는 IP 주소(127.0.0.1:8093) 또는 도메인(my-runner.example.com:8093)입니다. 러너는 이 정보를 사용하여 보안 연결을 위한 TLS 인증서를 생성합니다.

• 웹 브라우저가 advertise_address에 연결할 수 있는지 확인하십시오. 라이브 세션은 웹 브라우저에 의해 시작됩니다.

• advertise_address가 공용 IP 주소인지 확인하십시오. 그렇지 않으면 애플리케이션 설정인 allow_local_requests_from_web_hooks_and_services를 활성화해야 합니다.

세션 서버 및 터미널 지원을 비활성화하려면 [session_server] 섹션을 삭제하십시오.

참고: 러너 인스턴스가 이미 실행 중인 경우, [session_server] 섹션의 변경 사항을 적용하려면 gitlab-runner restart를 실행해야 할 수 있습니다.

GitLab Runner Docker 이미지를 사용하는 경우, docker run 명령에 -p 8093:8093를 추가하여 포트 8093을 노출해야 합니다.

[[runners]] 섹션

각 [[runners]] 섹션은 하나의 러너를 정의합니다.

예시:

[[runners]]
  name = "ruby-3.3-docker"
  url = "https://CI/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  clone_url = "http://gitlab.example.local"

clone_url 작동 방식

GitLab 인스턴스가 러너가 사용할 수 없는 URL에서 이용 가능할 때,

clone_url을 구성할 수 있습니다.

예를 들어, 방화벽으로 인해 러너가 URL에 도달할 수 없을 수 있습니다.

러너가 192.168.1.23의 노드에 도달할 수 있는 경우, clone_url을 http://192.168.1.23로 설정하세요.

clone_url이 설정되면, 러너는 다음 형식의 클론 URL을 구성합니다.

http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git.

메모:

clone_url은 Git LFS 엔드포인트에 영향을 미치지 않습니다.

Git LFS 엔드포인트 수정

Git LFS 엔드포인트를 수정하려면 다음 파일 중 하나에서 pre_get_sources_script를 설정하세요:

• config.toml:

  pre_get_sources_script = "mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template; git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://<alternative-endpoint>"
  

• .gitlab-ci.yml:

  default:
    hooks:
      pre_get_sources_script:
        - mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template
        - git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://localhost
  

unhealthy_requests_limit 및 unhealthy_interval 작동 방식

GitLab 인스턴스가 오랜 시간 동안 이용 불가능할 때(예: 버전 업그레이드 중),

해당 인스턴스에 구성된 러너는 유휴 상태가 되고 GitLab 인스턴스가 다시 이용 가능해진 후

30-60분 동안 작업 처리를 재개하지 않습니다.

러너가 유휴 상태인 기간을 늘리거나 줄이려면 unhealthy_interval 설정을 변경하세요.

러너가 GitLab 서버에 연결을 시도하는 횟수와

유휴 상태가 되기 전에 받을 수 있는 불건전 대기 시간을 변경하려면

unhealthy_requests_limit 설정을 변경하세요.

자세한 내용은 How check_interval works를 참조하세요.

실행기

다음 실행기가 이용 가능합니다.

셸

CI/CD 작업은 셸 실행기를 사용하도록 구성되었을 때 호스트 머신에서 로컬로 실행됩니다. 지원되는 운영 체제 셸은 다음과 같습니다:

shell 옵션이 bash 또는 sh로 설정되면 Bash의 ANSI-C quoting이 작업 스크립트를 셸 이스케이프하는 데 사용됩니다.

POSIX 준수 셸 사용

GitLab Runner 14.9 이상에서는 FF_POSIXLY_CORRECT_ESCAPES라는 기능 플래그를 활성화하여 POSIX 준수 셸(예: dash)을 사용합니다. 활성화되면, POSIX 준수 셸 이스케이프 메커니즘인 “Double Quotes”가 사용됩니다.

[runners.docker] 섹션

다음 설정은 Docker 컨테이너 매개변수를 정의합니다. 이는 러너가 Docker 실행기를 사용하도록 구성된 경우에 적용됩니다.

Docker-in-Docker 서비스 또는 작업 내에서 구성된 다른 컨테이너 런타임은 이러한 매개변수를 상속하지 않습니다.

[[runners.docker.services]] 섹션

작업과 함께 실행할 추가 서비스를 지정합니다. 사용 가능한 이미지 목록은 Docker Registry를 참조하세요.

각 서비스는 별도의 컨테이너에서 실행되며 작업에 연결됩니다.

예시:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "0,1"
  cpuset_mems = "0,1"
  cpus = "2"
  dns = ["8.8.8.8"]
  dns_search = [""]
  service_memory = "128m"
  service_memory_swap = "256m"
  service_memory_reservation = "64m"
  service_cpuset_cpus = "0,1"
  service_cpus = "2"
  services_limit = 5
  privileged = false
  group_add = ["docker"]
  userns_mode = "host"
  cap_add = ["NET_ADMIN"]
  cap_drop = ["DAC_OVERRIDE"]
  devices = ["/dev/net/tun"]
  disable_cache = false
  wait_for_services_timeout = 30
  cache_dir = ""
  volumes = ["/data", "/home/project/cache"]
  extra_hosts = ["other-host:127.0.0.1"]
  shm_size = 300000
  volumes_from = ["storage_container:ro"]
  links = ["mysql_container:mysql"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9", "redis:*", "mysql:*"]
  [runners.docker.ulimit]
    "rtprio" = "99"
  [[runners.docker.services]]
    name = "registry.example.com/svc1"
    alias = "svc1"
    entrypoint = ["entrypoint.sh"]
    command = ["executable","param1","param2"]
    environment = ["ENV1=value1", "ENV2=value2"]
  [[runners.docker.services]]
    name = "redis:2.8"
    alias = "cache"
  [[runners.docker.services]]
    name = "postgres:9"
    alias = "postgres-db"
  [runners.docker.sysctls]
    "net.ipv4.ip_forward" = "1"

[runners.docker] 섹션의 볼륨

볼륨에 대한 자세한 정보는 Docker 문서에서 확인하세요.

다음 예제는 [runners.docker] 섹션에서 볼륨을 지정하는 방법을 보여줍니다.

예제 1: 데이터 볼륨 추가

데이터 볼륨은 하나 이상의 컨테이너에서 Union File System을 우회하는 특별히 지정된 디렉토리입니다. 데이터 볼륨은 컨테이너의 수명 주기와 독립적으로 데이터를 지속하도록 설계되었습니다.

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]

이 예제는 컨테이너의 /path/to/volume/in/container에 새로운 볼륨을 생성합니다.

예제 2: 호스트 디렉토리를 데이터 볼륨으로 마운트

컨테이너 외부에 디렉토리를 저장하려는 경우 Docker 데몬의 호스트에서 컨테이너로 디렉토리를 마운트할 수 있습니다:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

이 예제는 CI/CD 호스트의 /path/to/bind/from/host를 컨테이너의 /path/to/bind/in/container에 사용합니다.

GitLab Runner 11.11 이상에서는 정의된 서비스에 대해 호스트 디렉토리를 마운트합니다.

개인 컨테이너 레지스트리 사용

작업에 대한 이미지 소스로 개인 레지스트리를 사용하려면 CI/CD 변수 DOCKER_AUTH_CONFIG로 인증을 구성하세요. 다음 방법 중 하나로 변수를 설정할 수 있습니다:

• file 형식으로 프로젝트의 CI/CD 설정
• config.toml 파일

if-not-present 풀 정책으로 개인 레지스트리를 사용하면 보안 문제를 초래할 수 있습니다. 풀 정책이 작동하는 방식에 대한 자세한 정보는 러너가 이미지를 끌어오는 방법 구성하기를 참조하세요.

개인 컨테이너 레지스트리 사용에 대한 더 많은 정보는 다음을 참조하세요:

• 개인 컨테이너 레지스트리에서 이미지에 액세스
• .gitlab-ci.yml 키워드 참조

러너가 수행하는 단계를 요약하면 다음과 같습니다:

1. 레지스트리 이름은 이미지 이름에서 찾아집니다.

2. 값이 비어 있지 않으면 실행기는 이 레지스트리에 대한 인증 구성을 검색합니다.

3. 마지막으로 지정된 레지스트리에 해당하는 인증이 발견되면, 이후의 풀에서 이를 사용합니다.

GitLab 통합 레지스트리에 대한 지원

GitLab은 작업 데이터를 함께 통합 레지스트리에 대한 자격 증명을 전송합니다. 이러한 자격 증명은 자동으로 레지스트리의 인증 매개변수 목록에 추가됩니다.

이 단계 이후 레지스트리에 대한 인증은 DOCKER_AUTH_CONFIG 변수로 추가된 구성고 유사하게 진행됩니다.

작업에서는 GitLab 통합 레지스트리의 모든 이미지를 사용할 수 있으며, 이미지가 비공개이거나 보호되어 있어도 사용할 수 있습니다. 작업이 액세스할 수 있는 이미지에 대한 정보는 CI/CD 작업 토큰 문서를 참조하세요.

도커 인증 우선 순위 해결

앞서 설명한 바와 같이, GitLab Runner는 다양한 방법으로 전송된 자격 증명을 사용하여 도커를 레지스트리에 대해 인증할 수 있습니다. 적절한 레지스트리를 찾기 위해 다음의 우선 순위를 고려합니다:

1. DOCKER_AUTH_CONFIG로 구성된 자격 증명.
2. GitLab Runner 호스트의 로컬에 ~/.docker/config.json 또는 ~/.dockercfg 파일로 구성된 자격 증명 (예: 호스트에서 docker login을 실행하여).
3. 작업의 페이로드와 함께 기본적으로 전송된 자격 증명 (예: 앞서 설명한 통합 레지스트리에 대한 자격 증명).

레지스트리를 위해 처음 발견된 자격 증명이 사용됩니다. 예를 들어, 통합 레지스트리에 대해 DOCKER_AUTH_CONFIG 변수를 사용하여 자격 증명을 추가하면 기본 자격 증명이 덮어씌워집니다.

[runners.parallels] 섹션

다음 매개변수는 Parallels에 해당합니다.

예시:

[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false

[runners.virtualbox] 섹션

다음 매개변수는 VirtualBox에 해당합니다. 이 실행기는 VirtualBox 머신을 제어하기 위해 vboxmanage 실행 파일에 의존하므로, Windows 호스트에서 PATH 환경 변수를 조정해야 합니다: PATH=%PATH%;C:\Program Files\Oracle\VirtualBox.

예시:

[runners.virtualbox]
  base_name = "my-virtualbox-image"
  base_snapshot = "my-image-snapshot"
  disable_snapshots = false
  start_type = "headless"

start_type 매개변수는 가상 이미지를 시작할 때 사용되는 그래픽 프론트 엔드를 결정합니다. 유효한 값은 호스트와 게스트 조합으로 지원되는 headless (기본), gui 또는 separate입니다.

기본 VM 이미지 재정의

• GitLab Runner 14.2에서 도입됨.

Parallels 및 VirtualBox 실행기 모두에서 base_name으로 지정된 기본 VM 이름을 재정의할 수 있습니다.
이를 위해 .gitlab-ci.yml 파일에서 image 매개변수를 사용하세요.

후방 호환성을 위해 기본적으로 이 값을 재정의할 수 없습니다. base_name으로 지정된 이미지만 허용됩니다.

사용자가 .gitlab-ci.yml image 매개변수를 사용하여 VM 이미지를 선택할 수 있도록 하려면:

[runners.virtualbox]
  ...
  allowed_images = [".*"]

예제에서는 기존의 모든 VM 이미지를 사용할 수 있습니다.

allowed_images 매개변수는 정규 표현식 목록입니다. 구성이 필요에 따라 정밀할 수 있습니다.
예를 들어 특정 VM 이미지만 허용하고 싶다면 다음과 같은 정규 표현식을 사용할 수 있습니다:

[runners.virtualbox]
  ...
  allowed_images = ["^allowed_vm[1-2]$"]

이 예에서는 allowed_vm1 및 allowed_vm2만 허용됩니다. 다른 모든 시도는 오류가 발생합니다.

[runners.ssh] 섹션

다음 매개변수는 SSH 연결을 정의합니다.

예제:

[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
  identity_file = ""

[runners.machine] 섹션

다음 매개변수는 Docker Machine 기반 자동 확장 기능을 정의합니다. 자세한 내용은 Docker Machine Executor autoscale configuration을 참조하세요.

[[runners.machine.autoscaling]] 섹션

다음 매개변수는 Instance 또는 Docker Autoscaler 실행기를 사용할 때 사용 가능한 구성을 정의합니다.

예시:

[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # 인증 방법에 대한 자세한 내용은 Docker Machine 문서를 참조하세요: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Google Compute Engine 드라이버를 사용하여 추가 머신 옵션을 추가할 수 있습니다.
      # 호스트에 접근할 수 없는 경우(ex. "Waiting for SSH") 문제를 겪으면,
      # 디버깅을 돕기 위해 선택적 매개변수를 제거해야 합니다.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # 예: 'us-central1-a', 전체 목록은 https://cloud.google.com/compute/docs/regions-zones/에서 확인 가능
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # 현재 Idle 머신 수가 1.5*사용 중인 머신 수가 됨을 의미합니다,
                          # 50(IdleCount의 값)보다 많지 않도록 하고 5(IdleCountMin의 값)보다 적지 않도록 합니다.
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

Periods 구문

Periods 설정은 cron 스타일 형식으로 표현된 시간 기간의 문자열 패턴 배열을 포함합니다. 이 줄은 다음 필드를 포함합니다:

[초] [분] [시간] [월의 일] [월] [주일] [년도]

표준 cron 구성 파일과 마찬가지로 필드는 단일 값, 범위, 목록 및 별표(*)를 포함할 수 있습니다. 구문에 대한 자세한 설명을 확인하세요.

[runners.instance] 섹션

[runners.autoscaler] 섹션

• GitLab Runner v15.10.0에 도입됨.

다음 매개변수는 autoscaler 기능을 구성합니다. 이 매개변수는 Instance와 Docker Autoscaler 실행기에만 사용할 수 있습니다.

참고: instance_ready_command가 유휴 스케일 규칙으로 인해 자주 실패하는 경우, 인스턴스가 작업을 수락하는 것보다 더 빠르게 제거되고 생성될 수 있습니다. 스케일 스로틀링을 지원하기 위해, GitLab 17.0에서 지수 백오프가 추가되었습니다.

참고: Autoscaler 구성 옵션은 구성 변경 시 다시 로드되지 않습니다. 그러나 GitLab 17.5.0 이상에서는 [[runners.autoscaler.policy]] 항목이 구성 변경 시 다시 로드됩니다.

[runners.autoscaler.plugin_config] 섹션

이 해시 테이블은 JSON으로 재인코딩되어 구성된 플러그인에 직접 전달됩니다.

fleeting 플러그인은 일반적으로 지원되는 구성에 대한 문서가 함께 제공됩니다.

[runners.autoscaler.scale_throttle] 섹션

• GitLab Runner v17.0.0에 도입되었습니다.

[runners.autoscaler.connector_config] 섹션

fleeting 플러그인은 일반적으로 지원되는 연결 옵션에 대한 동반 문서가 있습니다.

플러그인은 자동으로 커넥터 구성을 업데이트합니다. [runners.autoscaler.connector_config]를 사용하여 커넥터 구성의 자동 업데이트를 재정의하거나 플러그인이 결정할 수 없는 빈 값을 채울 수 있습니다.

[runners.autoscaler.state_storage] 섹션

• GitLab Runner 17.5.0에 도입되었습니다.

상태 저장소가 비활성화된 상태에서 GitLab Runner가 시작되면(기본값), 기존의 fleeting 인스턴스는 안전상의 이유로 즉시 제거됩니다. max_use_count: 1과 같은 구성에서는 그 사용 상태를 알지 못할 경우 이미 사용된 인스턴스에 작업이 할당되는 것을 방지할 수 있습니다.

상태 저장소 기능을 활성화하면 인스턴스의 상태가 로컬 디스크에 지속됩니다. 이 경우, GitLab Runner가 시작할 때 인스턴스가 존재하면 삭제되지 않습니다. 캐시된 연결 세부 정보, 사용 횟수 및 기타 구성은 복원됩니다.

상태 저장소 기능을 활성화할 때 다음 정보를 고려하세요:

• 인스턴스의 인증 세부 정보(사용자 이름, 비밀번호, 키)는 디스크에 남아 있습니다.
• 인스턴스가 작업을 실행 중일 때 복원되면, GitLab Runner는 기본적으로 이를 제거합니다. 이 동작은 안전성을 보장합니다. GitLab Runner는 작업을 재개할 수 없기 때문입니다. 인스턴스를 유지하려면 keep_instance_with_acquisitions를 true로 설정하세요.

keep_instance_with_acquisitions를 true로 설정하는 것은 인스턴스에서 진행 중인 작업에 대해 걱정하지 않을 때 유용합니다. 환경을 정리하는 데에도 유용합니다. 예를 들어, instance_ready_command 구성 옵션을 사용하여 환경을 정리하여 인스턴스를 유지할 수 있습니다. 이는 모든 실행 중인 명령을 중단하거나 Docker 컨테이너를 강제로 제거하는 것과 관련이 있을 수 있습니다.

[[runners.autoscaler.policy]] 섹션

노트 - 이 맥락에서 idle_count는 레거시 오토스케일링 방법에서의 오토스케일된 머신 수가 아닌 작업 수를 나타냅니다.

scale_factor가 설정되면, idle_count는 최소 idle 용량이 되고 scale_factor_limit는 최대 idle 용량이 됩니다.

여러 정책을 정의할 수 있습니다. 마지막으로 일치하는 정책이 사용됩니다.

다음 예제에서는 월요일부터 금요일까지 08:00에서 15:59 사이에 유휴 수 1이 사용됩니다. 그렇지 않으면 유휴 수는 0입니다.

[[runners.autoscaler.policy]]
  idle_count        = 0
  idle_time         = "0s"
  periods           = ["* * * * *"]

[[runners.autoscaler.policy]]
  idle_count        = 1
  idle_time         = "30m0s"
  periods           = ["* 8-15 * * mon-fri"]

기간 구문

periods 설정은 정책이 활성화되는 기간을 나타내는 unix-cron 형식 문자열의 배열을 포함합니다. cron 형식은 5개의 필드로 구성됩니다:

 ┌────────── 분 (0 - 59)
 │ ┌──────── 시간 (0 - 23)
 │ │ ┌────── 월의 날짜 (1 - 31)
 │ │ │ ┌──── 월 (1 - 12)
 │ │ │ │ ┌── 주의 날짜 (1 - 7 또는 MON-SUN, 0은 일요일의 별칭)
 * * * * *

• 두 숫자 사이에 -를 사용하여 범위를 지정할 수 있습니다.
• *는 해당 필드의 유효한 값의 전체 범위를 나타내는 데 사용할 수 있습니다.
• 숫자 뒤에 /를 사용하거나 범위 뒤에 사용하여 그 범위를 건너뛰는 데 사용할 수 있습니다. 예를 들어, 시간 필드의 경우 0-12/2는 00:00과 00:12 사이의 2시간마다 주기를 활성화합니다.
• ,를 사용하여 필드의 유효한 숫자 또는 범위 목록을 구분할 수 있습니다. 예를 들어, 1,2,6-9와 같습니다.

이 cron 작업은 시간의 범위를 나타낸다는 점을 염두에 두는 것이 중요합니다. 예를 들어:

[runners.autoscaler.vm_isolation] 섹션

VM Isolation은 nesting을 사용하며, 현재 MacOS에서만 지원됩니다.

[runners.autoscaler.vm_isolation.connector_config] 섹션

[runners.autoscaler.vm_isolation.connector_config] 섹션의 매개변수는 [runners.autoscaler.connector_config] 섹션과 동일하지만, 자동 확장된 인스턴스가 아닌 nesting으로 제공된 가상 머신에 연결하는 데 사용됩니다.

[runners.custom] 섹션

다음 매개변수는 커스텀 실행기에 대한 구성을 정의합니다.

[runners.cache] 섹션

다음 매개변수는 분산 캐시 기능을 정의합니다. 자세한 내용은 러너 자동 스케일 문서에서 확인하세요.

캐시 메커니즘은 캐시를 업로드하고 다운로드하기 위해 미리 서명된 URL을 사용합니다. URL은 GitLab Runner의 자체 인스턴스에서 서명됩니다.

작업의 스크립트(캐시 업로드/다운로드 스크립트 포함)가 로컬 또는 외부 머신에서 실행되는 것은 중요하지 않습니다.

예를 들어, shell 또는 docker 실행자는 GitLab Runner 프로세스가 실행되는 동일한 머신에서 스크립트를 실행합니다.

동시에, virtualbox 또는 docker+machine은 별도의 VM에 연결하여 스크립트를 실행합니다. 이 프로세스는 보안상의 이유로 캐시 어댑터의 자격 증명 유출 가능성을 최소화합니다.

S3 캐시 어댑터가 IAM 인스턴스 프로파일을 사용하도록 구성된 경우 어댑터는 GitLab Runner 머신에 연결된 프로파일을 사용합니다.

유사하게 GCS 캐시 어댑터도 CredentialsFile을 사용하도록 구성된 경우 GitLab Runner 머신에 해당 파일이 존재해야 합니다.

이 표는 config.toml, CLI 옵션 및 register용 ENV 변수를 나열합니다.

[runners.cache.s3] 섹션

다음 매개변수는 캐시를 위한 S3 스토리지를 정의합니다.

예:

[runners.cache]
  Type = "s3"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "AWS_S3_ACCESS_KEY"
    SecretKey = "AWS_S3_SECRET_KEY"
    BucketName = "runners-cache"
    BucketLocation = "eu-west-1"
    Insecure = false
    ServerSideEncryption = "KMS"
    ServerSideEncryptionKeyID = "alias/my-key"

ServerAddress, AccessKey 또는 SecretKey가 지정되지 않고 AuthenticationType이 제공되지 않으면 S3 클라이언트는 gitlab-runner 인스턴스에 사용 가능한 IAM 인스턴스 프로필을 사용합니다. autoscale 구성에서는 작업이 실행되는 온디맨드 머신이 아닙니다. ServerAddress, AccessKey, SecretKey가 모두 지정되지만 AuthenticationType이 제공되지 않으면 access-key가 인증 유형으로 사용됩니다.

Helm 차트를 사용하여 GitLab Runner를 설치할 때 rbac.create가 values.yaml 파일에서 true로 설정되면 ServiceAccount가 생성됩니다. 이 ServiceAccount의 주석은 rbac.serviceAccountAnnotations 섹션에서 가져옵니다.

Amazon EKS에서 실행되는 러너의 경우 서비스 계정에 할당할 IAM 역할을 지정할 수 있습니다. 필요한 특정 주석은 다음과 같습니다: eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>.

이 역할에 대한 IAM 정책은 지정된 버킷에 대해 다음 작업을 수행할 수 있는 권한을 가져야 합니다:

• s3:PutObject
• s3:GetObjectVersion
• s3:GetObject
• s3:DeleteObject

KMS 유형의 ServerSideEncryption을 사용하는 경우 이 역할은 또한 지정된 AWS KMS 키에 대해 다음 작업을 수행할 수 있는 권한이 있어야 합니다:

• kms:Encrypt
• kms:Decrypt
• kms:ReEncrypt*
• kms:GenerateDataKey*
• kms:DescribeKey

SSE-C 유형의 ServerSideEncryption은 지원되지 않습니다.
SSE-C는 다운로드 요청에 대해 사용자 제공 키가 포함된 헤더가 필요하며, 이와 함께 사전 서명된 URL이 필요합니다. 이는 작업에 키 자재를 전달해야 하며, 키를 안전하게 유지할 수 없습니다. 이는 복호화 키가 유출될 가능성이 있습니다. 이 문제에 대한 논의는 이 머지 요청에 있습니다.

주목: AWS S3 캐시에 업로드할 수 있는 단일 파일의 최대 크기는 5GB입니다.
이 동작에 대한 잠재적인 우회 방법에 대한 논의는 이 문제에 있습니다.

S3 버킷에서 러너 캐시를 위한 KMS 키 암호화 사용

GenerateDataKey API는 KMS 대칭 키를 사용하여 클라이언트 측 암호화를 위한 데이터 키를 생성합니다. (https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) KMS 키 구성은 다음과 같아야 합니다:

rbac.serviceAccountName에 정의된 ServiceAccount에 할당된 역할의 IAM 정책은 KMS 키에 대해 다음 작업을 수행할 수 있는 권한이 있어야 합니다:

• kms:GetPublicKey
• kms:Decrypt
• kms:Encrypt
• kms:DescribeKey
• kms:GenerateDataKey

UploadRoleARN으로 멀티파트 업로드 활성화

캐시에 대한 접근을 제한하기 위해, 러너 관리자는 취소된 시간의 프리사인 URL을 생성하여 작업이 캐시에서 다운로드하고 업로드할 수 있도록 합니다. 그러나 AWS S3는 단일 PUT 요청을 5 GB로 제한합니다. 5 GB보다 큰 파일의 경우, 멀티파트 업로드 API를 사용해야 합니다.

멀티파트 업로드는 AWS S3에서만 지원되며 다른 S3 제공업체에서는 지원되지 않습니다. 러너 관리자가 여러 프로젝트의 작업을 처리하기 때문에, 러너 관리자는 버킷 전체 권한이 있는 S3 자격 증명을 전달할 수 없습니다. 대신, 러너 관리자는 시간 제한 프리사인 URL과 제한된 범위의 자격 증명을 사용하여 특정 객체에 대한 액세스를 제한합니다.

AWS와 함께 S3 멀티파트 업로드를 사용하려면, UploadRoleARN에 arn:aws:iam:::<ACCOUNT ID>:<YOUR ROLE NAME> 형식으로 IAM 역할을 지정하세요. 이 역할은 특정 블롭에 쓰기 위해 좁게 범위가 지정된 시간 제한 AWS 자격 증명을 생성합니다. 원래 S3 자격 증명이 지정된 UploadRoleARN에 대한 AssumeRole에 액세스할 수 있는지 확인하세요.

UploadRoleARN에 지정된 IAM 역할은 다음과 같은 권한을 가져야 합니다:

• BucketName에 지정된 버킷에 대한 s3:PutObject 액세스.
• KMS 또는 DSSE-KMS를 사용하는 서버 측 암호화가 활성화된 경우 kms:Decrypt 및 kms:GenerateDataKey.

예를 들어, my-instance-role이라는 IAM 역할이 arn:aws:iam::1234567890123:role/my-instance-role ARN을 가진 EC2 인스턴스에 연결되어 있다고 가정해 보세요.

BucketName에 대한 s3:PutObject 권한만 있는 새 역할 arn:aws:iam::1234567890123:role/my-upload-role을 생성할 수 있습니다. my-instance-role에 대한 AWS 설정에서 신뢰 관계는 다음과 유사할 수 있습니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::1234567890123:role/my-upload-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

새 역할을 생성하지 않고 my-instance-role을 UploadRoleARN으로 재사용할 수도 있습니다. my-instance-role이 AssumeRole 권한을 갖고 있는지 확인하세요. 예를 들어, EC2 인스턴스와 연결된 IAM 프로필의 신뢰 관계는 다음과 같을 수 있습니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com",
                "AWS": "arn:aws:iam::1234567890123:role/my-instance-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

AWS 명령줄 인터페이스를 사용하여 인스턴스가 AssumeRole 권한을 갖고 있는지 확인할 수 있습니다. 예를 들어:

aws sts assume-role --role-arn arn:aws:iam::1234567890123:role/my-upload-role --role-session-name gitlab-runner-test1

UploadRoleARN로 파일 업로드 하는 방법

UploadRoleARN이 존재하면, 러너가 캐시에 업로드할 때마다:

1. 러너 관리자는 원래의 S3 자격 증명( AuthenticationType, AccessKey, SecretKey를 통해 지정됨)을 검색합니다.

2. S3 자격 증명으로, 러너 관리자는 UploadRoleARN과 함께 Amazon Security Token Service (STS)에 AssumeRole 요청을 보냅니다.
   정책 요청은 다음과 유사하게 보입니다:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": ["s3:PutObject"],
                "Resource": "arn:aws:s3:::<YOUR-BUCKET-NAME>/<CACHE-FILENAME>"
            }
        ]
    }
   

3. 요청이 성공하면, 러너 관리자는 제한된 세션을 가진 임시 AWS 자격 증명을 얻습니다.

4. 러너 관리자는 이러한 자격 증명과 s3://<bucket name>/<filename> 형식의 URL을 캐시 아카이버에 전달하여 파일을 업로드합니다.

Kubernetes ServiceAccount 리소스에 대한 IAM 역할 활성화

서비스 계정에 대한 IAM 역할을 사용하려면, 클러스터에 대한 IAM OIDC 공급자가 존재해야 합니다. IAM OIDC 공급자가 클러스터와 연결되면, 러너의 서비스 계정과 연결할 IAM 역할을 생성할 수 있습니다.

1. Create Role 창에서 Select type of trusted entity에서 Web Identity를 선택합니다.

2. 역할의 Trusted Relationships tab에서:

   • Trusted entities 섹션은 다음 형식을 가져야 합니다:
     arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>.
     OIDC ID는 EKS 클러스터의 Configuration 탭에서 찾을 수 있습니다.

   • Condition 섹션은 rbac.serviceAccountName에 정의된 GitLab Runner 서비스 계정을 가지고 있어야 하며, rbac.create가 true로 설정되면 생성된 기본 서비스 계정이 사용됩니다:

     Condition	Key	Value
     StringEquals	oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub	system:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>

[runners.cache.gcs] 섹션

다음 매개 변수는 Google Cloud Storage에 대한 기본 지원을 정의합니다. 이러한 값들에 대한 자세한 내용은 Google Cloud Storage (GCS) 인증 문서를 참조하세요.

예시:

config.toml 파일에 직접 구성된 자격 증명:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com"
    PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n"
    BucketName = "runners-cache"

GCP에서 다운로드한 JSON 파일의 자격 증명:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"

GCP의 메타데이터 서버에서의 애플리케이션 기본 자격 증명(ADC):

Google Cloud ADC와 함께 GitLab Runner를 사용할 때, 일반적으로 기본 서비스 계정을 사용합니다. 따라서 인스턴스에 대한 자격 증명을 제공할 필요가 없습니다:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"

ADC를 사용하는 경우, 사용 중인 서비스 계정이 iam.serviceAccounts.signBlob 권한을 가지고 있는지 확인하세요. 일반적으로 이는 Service Account Token Creator 역할을 서비스 계정에 부여함으로써 수행됩니다.

[runners.cache.azure] 섹션

• GitLab Runner 13.4.0에서 도입됨.

다음 매개변수는 Azure Blob Storage에 대한 기본 지원을 정의합니다. 자세한 내용은 Azure Blob Storage 문서를 참조하세요.

S3 및 GCS는 객체 모음에 대해 bucket이라는 단어를 사용하지만, Azure는 blob의 모음을 나타내기 위해 container라는 단어를 사용합니다.

예시:

[runners.cache]
  Type = "azure"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.azure]
    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

Azure workload 및 관리되는 ID

• GitLab Runner v17.5.0에서 도입됨.

Azure workload 또는 관리되는 ID를 사용하려면 구성에서 AccountKey를 생략하세요.

AccountKey가 비어 있으면 러너는 다음을 시도합니다:

1. DefaultAzureCredential를 통해 임시 자격 증명을 얻습니다.

2. 사용자 위임 키를 얻습니다.

3. 해당 키로 SAS 토큰을 생성하여 스토리지 계정 blob에 접근합니다.

해당 인스턴스에 Storage Blob Data Contributor 역할이 할당되어 있는지 확인하세요.

해당 인스턴스가 위의 작업을 수행할 수 있는 접근 권한이 없으면 GitLab Runner는 AuthorizationPermissionMismatch 오류를 보고합니다.

[runners.kubernetes] 섹션

• GitLab Runner v1.6.0에서 도입됨.

다음 표는 Kubernetes 실행자에 대한 구성 매개변수를 나열합니다.

더 많은 매개변수는 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"
  image = "golang:1.8"
  privileged = true
  allow_privilege_escalation = true
  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9.4", "postgres:latest"]
  logs_base_dir = "/tmp"
  scripts_base_dir = "/tmp"
  [runners.kubernetes.node_selector]
    gitlab = "true"

헬퍼 이미지

docker, docker+machine 또는 kubernetes 실행기를 사용할 때, GitLab Runner는 특정 컨테이너를 사용하여 Git, 아티팩트 및 캐시 작업을 처리합니다. 이 컨테이너는 헬퍼 이미지라는 이름의 이미지에서 생성됩니다.

헬퍼 이미지는 amd64, arm, arm64, s390x 및 ppc64le 아키텍처에서 사용할 수 있습니다. 이 이미지는 GitLab Runner 바이너리의 특별한 컴파일인 gitlab-runner-helper 바이너리를 포함하고 있습니다. 사용 가능한 명령어의 하위 집합과 Git, Git LFS 및 SSL 인증서 저장소만 포함되어 있습니다.

헬퍼 이미지는 몇 가지 종류가 있습니다: alpine, alpine3.17, alpine3.18, alpine3.19, alpine-latest, ubi-fips 및 ubuntu. 현재 alpine 이미지는 작은 크기 때문에 기본값으로 설정되어 있지만, 일부 환경에서 DNS 문제가 있을 수 있습니다. helper_image_flavor = "ubuntu"를 사용하면 헬퍼 이미지의 ubuntu 종류가 선택됩니다.

GitLab Runner 16.1에서 17.1까지 alpine 종류는 alpine3.18의 별칭입니다. GitLab Runner 17.2 및 이후 버전에서는 alpine3.19의 별칭입니다.

alpine-latest 종류는 alpine:latest를 기본 이미지로 사용하며, 이는 잠재적으로 더 불안정할 수 있습니다.

GitLab Runner가 DEB/RPM 패키지를 통해 설치될 때, 지원되는 아키텍처의 이미지가 호스트에 설치됩니다.

러너가 작업을 실행하기 위해 준비할 때, 지정된 버전(러너의 Git 수정 기준)에서 이미지가 Docker Engine에서 발견되지 않으면 자동으로 로드됩니다. docker와 docker+machine 실행기는 모두 이러한 방식으로 작동합니다.

alpine 종류의 경우, 기본 alpine 종류 이미지만 패키지에 포함되어 있습니다. 나머지 모든 종류는 레지스트리에서 다운로드됩니다.

kubernetes 실행기와 GitLab Runner의 수동 설치는 다르게 작동합니다.

• 수동 설치의 경우 gitlab-runner-helper 바이너리가 포함되지 않습니다.
• kubernetes 실행기의 경우, Kubernetes API는 gitlab-runner-helper 이미지를 로컬 아카이브에서 로드하는 것을 허용하지 않습니다.

두 경우 모두 GitLab Runner는 헬퍼 이미지를 다운로드합니다.

GitLab Runner의 수정 및 아키텍처는 다운로드할 태그를 정의합니다.

Arm에서 Kubernetes 용 헬퍼 이미지 구성

arm64 Kubernetes 클러스터에서 arm64 헬퍼 이미지를 사용하려면, 구성 파일에서 다음 값을 설정하십시오.

[runners.kubernetes]
        helper_image = "registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:arm64-latest"

구버전의 Alpine Linux를 사용하는 러너 이미지

• GitLab Runner 14.5에서 도입됨.

이미지는 여러 버전의 Alpine Linux로 빌드되므로 더 최신 버전의 Alpine을 사용할 수 있지만 동시에 이전 버전도 사용할 수 있습니다.

헬퍼 이미지의 경우 helper_image_flavor를 변경하거나 헬퍼 이미지 섹션을 읽으십시오.

GitLab Runner 이미지의 경우, 동일한 논리를 따르며, alpine, alpine3.16, alpine3.17, alpine3.18, alpine3.19 또는 alpine-latest가 이미지 내 버전 이전에 접두사로 사용됩니다.

docker pull gitlab/gitlab-runner:alpine3.19-v16.1.0

Alpine pwsh 이미지

GitLab Runner 16.1 버전 이후 모든 alpine 헬퍼 이미지에 pwsh 변형이 있습니다. 유일한 예외는 alpine-latest로, pwsh Docker 이미지를 기반으로 하는 GitLab Runner 헬퍼 이미지가 alpine:latest를 지원하지 않기 때문입니다.

예시:

docker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:alpine3.18-x86_64-v16.1.0-pwsh

헬퍼 이미지 레지스트리

GitLab 15.0 및 이전 버전에서는 헬퍼 이미지를 Docker Hub에서 가져오도록 구성할 수 있습니다.

GitLab 15.1 이후 버전에서는 헬퍼 이미지가 GitLab Container Registry에서 가져옵니다.

GitLab 레지스트리에서 기본 gitlab-runner-helper 이미지를 가져오려면 helper-image 값을 사용하세요: registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}.

자체 관리 인스턴스도 GitLab.com의 GitLab Container Registry에서 헬퍼 이미지를 가져옵니다. GitLab Container Registry의 상태를 확인하려면 GitLab 시스템 상태를 참조하세요.

헬퍼 이미지 재정의

경우에 따라 헬퍼 이미지를 재정의해야 할 수도 있습니다. 그렇게 하는 이유는 여러 가지가 있습니다:

1. 작업 실행 속도 향상: 인터넷 연결이 느린 환경에서는 같은 이미지를 여러 번 다운로드하는 것이 작업 실행 시간을 늘릴 수 있습니다. registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ의 정확한 복사본이 저장된 로컬 레지스트리에서 헬퍼 이미지를 다운로드하면 속도를 높일 수 있습니다.

2. 보안 문제: 이전에 확인하지 않은 외부 의존성을 다운로드하고 싶지 않을 수 있습니다. 검토되고 로컬 리포지토리에 저장된 의존성만 사용하라는 비즈니스 규칙이 있을 수 있습니다.

3. 인터넷에 접근할 수 없는 빌드 환경: 오프라인 환경에서 Kubernetes 클러스터를 설치한 경우, CI/CD 작업에 사용되는 이미지를 가져오기 위해 로컬 이미지 레지스트리나 패키지 저장소를 사용할 수 있습니다.

4. 추가 소프트웨어: git+http 대신 git+ssh로 접근 가능한 서브모듈을 지원하기 위해 헬퍼 이미지에 openssh와 같은 추가 소프트웨어를 설치하고 싶을 수 있습니다.

이러한 경우, docker, docker+machine, 및 kubernetes 실행기에 대해 사용할 수 있는 helper_image 구성 필드를 사용하여 사용자 정의 이미지를 구성할 수 있습니다:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

헬퍼 이미지의 버전은 GitLab Runner 버전과 엄격히 연결되어 있어야 합니다. 이 이미지를 제공하는 주요 이유 중 하나는 GitLab Runner가 gitlab-runner-helper 바이너리를 사용하고 있다는 것입니다. 이 바이너리는 GitLab Runner 소스의 일부에서 컴파일됩니다. 이 바이너리는 두 바이너리에서 동일할 것으로 예상되는 내부 API를 사용합니다.

기본적으로, GitLab Runner는 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 이미지를 참조합니다. 여기서 XYZ는 GitLab Runner 아키텍처와 Git 수정에 따라 다릅니다. GitLab Runner 11.3 이상에서는 다음의 버전 변수를 사용하여 이미지 버전을 정의할 수 있습니다:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

이 구성을 사용하면 GitLab Runner는 실행기에게 x86_64-v${CI_RUNNER_VERSION} 버전의 이미지를 사용하도록 지시합니다. 이는 컴파일 데이터에 기반합니다. GitLab Runner를 새 버전으로 업데이트한 후, GitLab Runner는 적절한 이미지를 다운로드하려고 시도합니다. 이미지는 GitLab Runner를 업그레이드하기 전에 레지스트리에 업로드되어야 하며, 그렇지 않으면 작업이 “No such image” 오류와 함께 실패합니다.

GitLab Runner 13.2 이후 버전에서는 헬퍼 이미지가 $CI_RUNNER_VERSION뿐만 아니라 $CI_RUNNER_REVISION으로 태그가 지정됩니다. 두 태그는 유효하며 동일한 이미지를 가리킵니다.

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

PowerShell Core 사용 시

PowerShell Core를 포함하는 헬퍼 이미지의 추가 버전이 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ-pwsh 태그와 함께 게시됩니다.

[runners.custom_build_dir] 섹션

• GitLab Runner 11.10에서 소개됨.

이 섹션은 사용자 정의 빌드 디렉터리 매개변수를 정의합니다.

이 기능은 명시적으로 구성되지 않는 한 기본적으로 kubernetes, docker, docker+machine, docker autoscaler 및 instance 실행자에 대해 활성화됩니다. 다른 모든 실행자는 기본적으로 비활성화됩니다.

이 기능은 GIT_CLONE_PATH가 runners.builds_dir에 정의된 경로에 있어야 합니다. builds_dir를 사용하려면 $CI_BUILDS_DIR 변수를 사용하십시오.

기본적으로 이 기능은 docker 및 kubernetes 실행자에 대해서만 활성화됩니다.

이들은 자원을 분리하는 좋은 방법을 제공하기 때문입니다. 이 기능은 모든 실행자에 대해 명시적으로 활성화할 수 있지만, builds_dir를 공유하고 concurrent > 1인 실행자와 함께 사용할 때는 주의가 필요합니다.

예시:

[runners.custom_build_dir]
  enabled = true

기본 빌드 디렉터리

GitLab Runner는 리포지토리를 _빌드 디렉터리_라고 잘 알려진 기본 경로 아래에 존재하는 경로로 복제합니다. 이 기본 디렉터리의 기본 위치는 실행자에 따라 다릅니다. 예를 들어:

• Kubernetes, Docker 및 Docker Machine 실행자에 대해 /builds는 컨테이너 내에 있습니다.

• Instance에 대해 ~/builds는 SSH 또는 WinRM 연결을 처리하도록 구성된 사용자의 홈 디렉터리에 있습니다.

• Docker Autoscaler에 대해 /builds는 컨테이너 내에 있습니다.

• Shell 실행자에 대해 $PWD/builds입니다.

• SSH, VirtualBox 및 Parallels 실행자에 대해 ~/builds는 SSH 연결을 처리하도록 구성된 사용자의 홈 디렉터리에 있습니다.

• Custom 실행자에 대해서는 기본값이 제공되지 않으며 명시적으로 구성되어야 하며, 그렇지 않으면 작업이 실패합니다.

사용된 _빌드 디렉터리_는 사용자가 builds_dir 설정을 통해 명시적으로 정의할 수 있습니다.

참고:

사용자가 커스텀 디렉터리에 복제하고 싶을 경우 GIT_CLONE_PATH도 지정할 수 있으며, 아래 가이드는 적용되지 않습니다.

GitLab Runner는 실행하는 모든 작업에 대해 _빌드 디렉터리_를 사용하지만, 특정 패턴을 사용하여 중첩합니다 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAME.

예: /builds/2mn-ncv-/0/user/playground.

GitLab Runner는 빌드 디렉터리 내에 항목을 저장하는 것을 막지 않습니다. 예를 들어, CI 실행 중에 사용할 수 있는 /builds/tools 내에 도구를 저장할 수 있습니다. 우리는 강력히 이를 반대하며, 빌드 디렉터리 내에 어떤 것도 저장해서는 안 됩니다. GitLab Runner는 이를 완전히 제어해야 하며 이러한 경우에는 안정성을 제공하지 않습니다. CI에 필요한 의존성이 있는 경우, 다른 곳에 설치하는 것을 권장합니다.

[runners.referees] 섹션

GitLab Runner 심판을 사용하여 추가 작업 모니터링 데이터를 GitLab에 전달하십시오. 심판은 작업과 관련된 추가 데이터를 쿼리하고 수집하는 러너 관리자 내의 작업자입니다. 결과는 작업 아티팩트로서 GitLab에 업로드됩니다.

메트릭 러너 심판 사용하기

작업을 실행하는 머신 또는 컨테이너가 Prometheus 메트릭을 노출하는 경우, GitLab Runner는 작업 전체 기간 동안 Prometheus 서버를 쿼리할 수 있습니다. 메트릭을 수신한 후, 이들은 나중에 분석에 사용할 수 있는 작업 아티팩트로 업로드됩니다.

오직 docker-machine executor만이 심판을 지원합니다.

GitLab Runner를 위한 메트릭 러너 심판 구성하기

config.toml 파일 내의 [[runner]] 섹션에 [runner.referees] 및 [runner.referees.metrics]를 정의하고 다음 필드를 추가하십시오:

다음은 node_exporter 메트릭에 대한 전체 구성 예입니다:

[[runners]]
  [runners.referees]
    [runners.referees.metrics]
      prometheus_address = "http://localhost:9090"
      query_interval = 10
      metric_queries = [
        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
      ]

메트릭 쿼리는 canonical_name:query_string 형식입니다. 쿼리 문자열은 실행 중에 대체되는 두 개의 변수를 지원합니다:

예를 들어, docker-machine executor를 사용하는 공유 GitLab Runner 환경에서는 {selector}가 node=shared-runner-123와 유사할 것입니다.