• 구성 유효성 검사
• 글로벌 섹션
  • 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 통합 레지스트리 지원
    • Docker 인증 우선 순위 결정
• [runners.parallels] 섹션
• [runners.virtualbox] 섹션
• 기본 VM 이미지 재정의
• [runners.ssh] 섹션
• [runners.machine] 섹션
  • [[runners.machine.autoscaling]] 섹션들
  • 기간 구문
• [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으로 업로드 작동하는 방법
    • 서비스 계정 자원에 대한 IAM 역할 활성화
  • [runners.cache.gcs] 섹션
  • [runners.cache.azure] 섹션
    • Azure 워크로드 및 관리 신원
• [runners.kubernetes] 섹션
• 도우미 이미지
  • Kubernetes의 Arm용 도우미 이미지 구성
  • 이전 버전의 Alpine Linux를 사용하는 러너 이미지
  • Alpine pwsh 이미지
  • 도우미 이미지 레지스트리
  • 도우미 이미지 재정의
    • PowerShell Core 사용 시
• [runners.custom_build_dir] 섹션
  • 기본 빌드 디렉토리
• [runners.referees] 섹션
  • Metrics Runner referee 사용
  • GitLab Runner를 위한 Metrics Runner Referee 구성

고급 구성

GitLab Runner 및 개별 등록된 runner의 동작을 변경하려면 config.toml 파일을 수정하세요.

config.toml 파일은 다음 위치에 있습니다.

• 루트로 GitLab Runner가 실행될 때 *nix 시스템의 /etc/gitlab-runner/. 해당 디렉터리는 또한 서비스 구성의 경로입니다.
• *nix 시스템의 GitLab Runner가 루트로 실행될 때 ~/.gitlab-runner/.
• 다른 시스템의 경우 ./.

대부분의 옵션을 변경할 때 GitLab Runner를 다시 시작할 필요가 없습니다. 이에는 [[runners]] 섹션의 매개변수 및 글로벌 섹션의 대부분의 매개변수가 포함됩니다(단, listen_address는 제외). 이미 등록된 runner의 경우 다시 등록할 필요가 없습니다.

GitLab Runner는 구성 수정을 3초마다 확인하고 필요한 경우 다시로드합니다. 또한 SIGHUP 시그널에 응답하여 구성을 다시로드합니다.

구성 유효성 검사

• GitLab Runner 15.10에서 도입됨

구성 유효성 검사는 config.toml 파일의 구조를 확인하는 프로세스입니다. 구성 유효성 검사기의 출력은 info 레벨 메시지만 제공합니다.

구성 유효성 검사 프로세스는 정보 목적으로만 사용됩니다. 해당 출력을 사용하여 runner 구성의 잠재적 문제를 식별할 수 있습니다. 그러나 구성 유효성 검사는 모든 가능한 문제를 잡아내지 못할 수 있으며, 메시지가 없다고 해서 config.toml 파일에 결함이 없다는 것을 보장하지 않습니다.

글로벌 섹션

이러한 설정은 전역적으로 적용됩니다. 모든 runner에 적용됩니다.

다음은 구성 예제입니다:

# `config.toml` 예제 파일 

concurrent = 100 # 이 `config.toml` 파일에서 정의된 모든 runner 섹션에 적용되는 작업 병렬성을 위한 전역 설정
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

Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded                                builds=0
listen_address not defined, metrics & debug endpoints disabled  builds=0
[session_server].listen_address not defined, session endpoints disabled  builds=0

text

INFO[0000] Runtime platform                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...
INFO[0000]
INFO[0000] Configuration loaded                          builds=0
INFO[0000] listen_address not defined, metrics & debug endpoints disabled  builds=0
INFO[0000] [session_server].listen_address not defined, session endpoints disabled  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 Runner가 구성된 GitLab 인스턴스로 작업 요청을 지속적으로 스케줄링하는 루프가 포함되어 있습니다.

다음 예제에서는 check_interval이 10초이고 runner-1과 runner-2의 두 [[runners]] 섹션이 있습니다. GitLab Runner는 10초마다 요청을 보내고 5초간 일시 중단됩니다.

1. check_interval 값 구하기 (10초).
2. 러너 목록 가져오기 (runner-1, runner-2).
3. 일시 중단 간격 계산하기 (10초 / 2 = 5초).
4. 무한 루프 시작하기:
   1. runner-1의 작업 요청하기.
   2. 5초 동안 중단하기.
   3. runner-2의 작업 요청하기.
   4. 5초 동안 중단하기.
   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초마다 새로운 요청을 받습니다.

runner-1에 대한 첫 번째와 두 번째 요청 사이에는 두 개의 중단 기간이 있습니다. 각 기간은 5초이므로, runner-1에 대한 연속적인 요청 사이에는 약 10초가 소요됩니다. runner-2에도 동일한 원리가 적용됩니다.

만약 이보다 더 많은 러너를 정의한다면, 중단 간격은 더 짧아집니다. 그러나 러너에 대한 요청은 다른 러너의 모든 요청과 그들의 중단 기간이 호출된 후에 재반복됩니다.

[session_server] 섹션

[session_server] 섹션을 통해 사용자는 예를 들어 대화형 웹 터미널에서 작업할 수 있습니다.

[session_server] 섹션은 러너별로가 아닌 루트 레벨에서 지정해야 합니다.

# 세션 서버 구성이 포함된 `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 주소인지 확인하세요. 이는 런타임 중인 경우 GitLab에 러너가 브라우저로부터 로컬 요청을 허용하는 어플리케이션 설정 활성화가 사전에 활성화되었는지 확인하세요.

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

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

GitHub Runner 도커 이미지를 사용하는 경우, 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 작동 방법

러너가 사용할 수 없는 URL에서 GitLab 인스턴스가 사용 가능한 경우, clone_url을 구성할 수 있습니다.

예를 들어 방화벽이 러너가 URL에 도달하는 것을 막을 수 있습니다. 러너가 192.168.1.23의 노드에 접근할 수 있는 경우, clone_url을 http://192.168.1.23로 설정하세요.

clone_url이 설정되면, 러너는 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git 형식의 복제 URL을 구성합니다.

참고: 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 설정을 변경하십시오. 자세한 내용은 check_interval 동작 방식을 참조하십시오.

실행자들

다음 실행자들을 사용할 수 있습니다.

셸들

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

shell 옵션을 bash 또는 sh로 설정한 경우, Bash의 ANSI-C quoting이 작업 스크립트를 셸 이스케이핑하는 데 사용됩니다.

POSIX 준수 셸 사용

GitLab Runner 14.9 이상에서 기능 플래그를 활성화하여 FF_POSIXLY_CORRECT_ESCAPES로 설정하여 POSIX 준수 셸(dash와 같은)을 사용할 수 있습니다. 활성화된 경우, POSIX 준수 셸 이스케이핑 메커니즘이 사용됩니다.

[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: 데이터 볼륨 추가

데이터 볼륨은 유니언 파일 시스템을 우회하며 하나 이상의 컨테이너 내에서 특별히 지정된 디렉토리로, 컨테이너의 수명 주기와 독립적으로 데이터를 유지할 수 있도록 설계되었습니다.

[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"]

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

GitLab Runner 11.11부터는 정의된 [서비스](https://docs.gitlab.com/ee/ci/services/)에 대해 호스트 디렉토리를 마운트합니다.

사설 컨테이너 레지스트리 사용

작업에 사용할 이미지의 원본으로 사설 레지스트리를 사용하려면 CI/CD 변수 DOCKER_AUTH_CONFIG를 사용하여 권한을 구성하십시오. 다음 중 하나에 변수를 설정할 수 있습니다:

• 프로젝트의 CI/CD 설정에서 file 타입
• config.toml 파일

if-not-present 풀 정책으로 사설 레지스트리를 사용하는 것은 보안 문제를 도입할 수 있습니다. 풀 정책이 작동하는 방법에 대한 자세한 내용은 런너가 이미지를 끌어오는 방법 구성을 참조하십시오.

사설 컨테이너 레지스트리 사용에 대한 자세한 내용은 다음을 참조하십시오:

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

런너가 수행하는 단계는 다음과 같습니다:

1. 이미지 이름에서 레지스트리 이름을 찾습니다.
2. 값이 비어 있지 않으면 실행기는 해당 레지스트리에 대한 인증 구성을 검색합니다.
3. 마지막으로, 지정된 레지스트리에 해당하는 인증이 찾으면 후속 풀은 그것을 사용합니다.

GitLab 통합 레지스트리 지원

GitLab은 작업 데이터와 함께 통합 레지스트리용 자격 증명을 보냅니다. 이러한 자격 증명은 자동으로 레지스트리의 권한 부여 매개변수 목록에 추가됩니다.

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

작업에서 GitLab 통합 레지스트리에서는 이미지를 비공개 또는 보호된 이미지라도 사용할 수 있습니다. 작업이 액세스할 수 있는 이미지에 대한 자세한 내용은 CI/CD 작업 토큰 설명서를 참조하세요.

Docker 인증 우선 순위 결정

이전에 설명했듯이, GitLab Runner는 다양한 방법으로 Docker를 레지스트리에 대해 인증할 수 있습니다. 적절한 레지스트리를 찾기 위해 다음 우선 순위가 고려됩니다:

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

레지스트리를 위해 찾은 첫 번째 자격 증명이 사용됩니다. 예를 들어, DOCKER_AUTH_CONFIG 변수로 통합 레지스트리에 자격 증명을 추가하면 기본 자격 증명이 재정의됩니다.

[runners.parallels] 섹션

Parallels를 위한 다음 매개변수입니다.

예시:

[runners.parallels]
  base_name = "나의 Parallels 이미지"
  template_name = ""
  disable_snapshots = false

[runners.virtualbox] 섹션

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

예시:

[runners.virtualbox]
  base_name = "나의 VirtualBox 이미지"
  base_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 = "나의 프로덕션 서버"
  port = "22"
  user = "root"
  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 driver를 사용하여 추가적인 머신 옵션을 추가할 수 있습니다.
      # 호스트에 연결할 수 없음(예: "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 설정에는 cron 스타일 형식으로 표시된 시간 기간의 문자열 패턴 배열이 포함되어 있습니다. 이 줄에는 다음 필드가 포함되어 있습니다.

[초] [분] [시] [월의 날짜] [월] [주의 요일] [년]

표준 cron 구성 파일과 마찬가지로 필드에는 단일 값을, 범위를, 목록을, 그리고 별표를 포함시킬 수 있습니다. 구문의 자세한 설명은 구문 구현에 대한 자세한 설명을 참조하세요.

[runners.instance] 섹션

[runners.autoscaler] 섹션

• GitLab Runner v15.10.0에서 도입되었습니다.

다음 매개변수는 오토스케일러 기능을 구성합니다. 이러한 매개변수는 Instance와 Docker Autoscaler 실행기와 함께만 사용할 수 있습니다.

참고: 만약 instance_ready_command가 idle scale rules로 인해 자주 실패한다면, 인스턴스가 생성 및 제거되는 속도가 실행자가 작업을 수락하는 것보다 빠를 수 있습니다. 스케일 스로틀링을 지원하기 위해 지수 백오프가 GitLab 17.0에서 추가되었습니다.

참고: 오토스케일러 구성 옵션은 구성 변경으로 다시로드되지 않습니다. 그러나, 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에서 도입되었습니다.

상태 저장소가 비활성화된(default) 상태로 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 용량이 되며, scaler_factor_limit은 최대 idle 용량이 됩니다.

여러 정책을 정의할 수 있습니다. 가장 최근에 일치하는 정책이 사용됩니다.

다음 예에서 idle count 1은 월요일부터 금요일까지 08:00부터 15:59까지 사용됩니다. 그 외에는 idle count는 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 형식 문자열의 배열을 포함합니다.
크론 형식은 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.

이 크론 작업은 시간 범위를 나타내는 것을 명심할 가치가 있습니다. 예를 들어:

[runners.autoscaler.vm_isolation] 섹션

VM Isolation은 현재 MacOS에서만 지원되는 nesting을 사용합니다.

[runners.autoscaler.vm_isolation.connector_config] 섹션

[runners.autoscaler.vm_isolation.connector_config] 섹션의 매개변수는 [runners.autoscaler.connector_config] 섹션과 동일하지만, 오토스케일된 인스턴스가 아닌 nesting으로 프로비저닝된 가상 머신에 연결하는 데 사용됩니다.

[runners.custom] 섹션

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

[runners.cache] 섹션

다음 매개변수는 분산 캐시 기능을 정의합니다. 자세한 내용은 런너 오토스케일 문서를 참조하십시오.

캐시 메커니즘은 사전 서명된 URL을 사용하여 캐시를 업로드하고 다운로드합니다. URL은 GitLab 러너에 의해 자체 인스턴스에서 서명됩니다. 작업 스크립트(캐시 업로드/다운로드 스크립트 포함)가 로컬 또는 외부 기계에서 실행되는지는 중요하지 않습니다. 예를 들어 shell 또는 docker 실행기는 작업 스크립트를 GitLab 러너 프로세스가 실행 중인 동일한 기계에서 실행합니다. 동시에 virtualbox 또는 docker+machine은 스크립트를 실행하기 위해 별도의 VM에 연결합니다. 이 프로세스는 보안상의 이유로 캐시 어댑터 자격 증명이 유출될 가능성을 최소화하기 위한 것입니다.

S3 캐시 어댑터가 IAM 인스턴스 프로필을 사용하도록 구성된 경우 어댑터는 GitLab 러너 머신에 연결된 프로필을 사용합니다. 마찬가지로 GCS 캐시 어댑터도 CredentialsFile을 사용하도록 구성된 경우 파일은 GitLab 러너 머신에 있어야 합니다.

이 표는 register에 대한 config.toml, CLI 옵션 및 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가 사용됩니다.

GitLab Runner를 설치할 때 Helm 차트를 사용하고 values.yaml 파일에서 rbac.create가 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

ServerSideEncryption에서 KMS 유형을 사용하는 경우, 해당 역할에 대한 IAM 정책은 지정된 AWS KMS 키에 대해 다음 작업을 수행할 수 있는 권한을 가지고 있어야 합니다:

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

ServerSideEncryption에서 SSE-C 유형은 지원되지 않습니다. SSE-C는 사용자 제공 키를 포함하는 헤더를 다운로드 요청에 제공해야 하며, 또한 사전 서명된 URL에 대해 키를 제공해야 합니다. 이는 키 노출의 가능성을 가지고 있습니다. 이 문제에 대한 논의는 이 merge request에서 확인할 수 있습니다.

참고: 단일 파일의 AWS S3 캐시에 업로드할 수 있는 최대 크기는 5GB입니다. 이 동작에 대한 잠재적인 해결책에 대한 논의는 이 issue에서 확인할 수 있습니다.

러너 캐시를 위한 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 요청을 5GB로 제한합니다. 5GB보다 큰 파일의 경우 멀티파트 업로드 API를 사용해야합니다.

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

AWS에서 S3 멀티파트 업로드를 사용하려면 UploadRoleARN에 IAM 역할을 지정합니다. arn:aws:iam:::<ACCOUNT ID>:<YOUR ROLE NAME> 형식으로 역할을 지정합니다. 이 역할은 버킷의 특정 blob에 쓰기 권한이 제한된 일시적인 AWS 자격 증명을 생성합니다. 지정한 UploadRoleARN의 AssumeRole에 대한 원래 S3 자격 증명이 액세스 할 수 있는지 확인하십시오.

UploadRoleARN에 지정된 IAM 역할은 다음 권한을 가지고 있어야합니다:

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

예를 들어, my-instance-role이라는 IAM 역할이 arn:aws:iam::1234567890123:role/my-instance-role로 EC2 인스턴스에 연결되어 있는 경우

새 역할 arn:aws:iam::1234567890123:role/my-upload-role을 만들 수 있으며, s3:PutObject 권한만 BucketName에 부여합니다. my-instance-role에 대한 AWS 설정에서 Trust relationships는 다음과 유사한 모습을 가질 수 있습니다:

{
    "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 프로필에는 다음과 유사한 Trust relationships가 있을 수 있습니다:

{
    "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을 캐시 아카이버에 전달하여 파일을 업로드합니다.

서비스 계정 자원에 대한 IAM 역할 활성화

서비스 계정에 IAM 역할을 사용하려면 클러스터에 IAM OIDC 제공자가 연결되어 있어야합니다. IAM OIDC 제공자가 클러스터에 연결된 후, 러너의 서비스 계정에 연결할 IAM 역할을 만들 수 있습니다.

1. 역할 생성 창에서 신뢰할 수 있는 엔티티 유형 선택에서 웹 신원을 선택합니다.

2. 역할의 신뢰 관계 탭에서:

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

   • 조건 섹션은 rbac.serviceAccountName에 정의된 GitLab 러너 서비스 계정 또는 rbac.create가 true로 설정된 경우에 만들어진 기본 서비스 계정이어야합니다:

     조건	키	값
     StringEquals	` oidc.eks..amazonaws.com/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를 사용하면 일반적으로 기본 서비스 계정을 사용합니다. 그런 다음 인스턴스에 자격 증명을 제공할 필요가 없습니다.

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

ADC를 사용하는 경우 사용하는 서비스 계정에 iam.serviceAccounts.signBlob 권한이 있는지 확인하십시오. 일반적으로이는 서비스 계정에 서비스 계정 토큰 생성자 역할를 부여하여 수행됩니다.

[runners.cache.azure] 섹션

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

다음 매개변수는 Azure Blob Storage의 네이티브 지원을 정의합니다. 자세한 내용은 Azure Blob Storage 문서를 참조하십시오. S3 및 GCS는 개체 모음에 대해 ‘bucket’이라는 용어를 사용하는 반면 Azure는 ‘container’라는 용어를 사용하여 blob 모음을 나타냅니다.

예시:

[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 워크로드 및 관리 신원

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

Azure 워크로드 또는 관리 신원을 사용하려면 구성에서 AccountKey를 제외하십시오. AccountKey가 공백인 경우, 러너는 다음을 시도합니다:

1. DefaultAzureCredential를 통해 일시적인 자격 증명을 획들합니다.
2. 사용자 위임 키를 가져옵니다.
3. 해당 키로 Storage Account blob에 액세스하기 위해 SAS 토큰을 생성합니다.

인스턴스에 Storage Blob Data Contributor 역할이 할당되어 있는지 확인하십시오. 인스턴스가 위의 작업을 수행할 수 없는 경우, GitLab Runner에서 AuthorizationPermissionMismatch 오류가 보고됩니다.

[runners.kubernetes] 섹션

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

다음 표는 Kubernetes executor에 대한 구성 매개변수를 나열합니다. 추가 매개변수에 대해서는 Kubernetes executor 문서를 참조하십시오.

예시:

[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-helper 이진 파일이 포함되어 있으며, 이는 GitLab Runner 이진 파일의 특별한 컴파일입니다. 사용 가능한 명령어의 하위 집합뿐만 아니라 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 엔진에 없는 경우 자동으로 로드됩니다. docker 및 docker+machine 실행자는 이러한 방식으로 작동합니다.

alpine 버전의 경우 패키지에는 기본 alpine 버전 이미지만 포함되어 있습니다. 다른 모든 버전은 레지스트리에서 다운로드해야 합니다.

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

• 수동 설치의 경우 gitlab-runner-helper 이진 파일이 포함되어 있지 않습니다.
• kubernetes 실행자의 경우 Kubernetes API는 gitlab-runner-helper 이미지를 로컬 아카이브에서 로드할 수 없습니다.

두 경우 모두 GitLab Runner는 도우미 이미지를 다운로드합니다. GitLab Runner의 리비전 및 아키텍처는 다운로드할 태그를 정의합니다.

Kubernetes의 Arm용 도우미 이미지 구성

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 변형이 포함되어 있습니다. 유일한 예외는 도우미 이미지가 기반으로 하는 pwsh 도커 이미지들이 alpine:latest를 지원하지 않기 때문에 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 컨테이너 레지스트리에서 가져옵니다.

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

자체 관리형 인스턴스도 GitLab.com의 GitLab 컨테이너 레지스트리에서 도우미 이미지를 가져옵니다. GitLab 컨테이너 레지스트리의 상태를 확인하려면 GitLab 시스템 상태를 참조하세요.

도우미 이미지 재정의

경우에 따라 도우미 이미지를 재정의해야 할 수 있습니다. 이유는 여러 가지가 있습니다.

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

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

3. 인터넷 액세스 없는 빌드 환경: 인터넷 액세스가 없는 오프라인 환경에 Kubernetes 클러스터가 설치되어 있는 경우, CI/CD 작업에서 사용되는 이미지를 로컬 이미지 레지스트리나 패키지 리포지토리에서 가져올 수 있습니다.

4. 추가 소프트웨어: openssh와 같은 추가 소프트웨어를 도우미 이미지에 설치하려는 경우가 있을 수 있습니다. 이를 통해 git+http 대신 git+ssh로 접근 가능한 하위 모듈을 지원할 수 있습니다.

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

[[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는 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는 executor에게 버전 x86_64-v${CI_RUNNER_VERSION}의 이미지를 사용하도록 지시하며, 이는 컴파일 데이터에 기초합니다. 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 사용 시

Linux용 헬퍼 이미지의 추가 버전인 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’ executor에 대해 기본적으로 활성화됩니다. 다른 executor에 대해서는 기본적으로 비활성화됩니다.

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

기본적으로, 이 기능은 docker 및 kubernetes executor에만 사용 가능합니다. 이 기능은 명시적으로 다른 executor에 대해 활성화할 수 있지만, ‘concurrent > 1’인 executor와 함께 사용할 때 주의가 필요합니다.

예시:

[runners.custom_build_dir]
  enabled = true

기본 빌드 디렉토리

GitLab Runner는 리포지토리를 _빌드 디렉토리_로 알려진 기본 경로에 클론합니다. 이 기본 디렉토리의 기본 위치는 executor에 따라 다릅니다.

• Kubernetes, Docker 및 Docker Machine executor의 경우, 컨테이너 내의 /builds입니다.
• Instance의 경우, 타겟 머신에 대한 SSH 또는 WinRM 연결을 처리하는 사용자의 홈 디렉토리 내의 ~/builds입니다.
• Docker Autoscaler의 경우, 컨테이너 내의 /builds입니다.
• Shell executor의 경우, $PWD/builds입니다.
• SSH, VirtualBox 및 Parallels executor의 경우, 타겟 머신에 대한 SSH 연결을 처리하는 사용자의 홈 디렉토리 내의 ~/builds입니다.
• Custom executor의 경우, 기본값이 제공되지 않으며 명시적으로 구성해야 합니다.

사용자는 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 referees를 사용하여 추가 작업 모니터링 데이터를 GitLab에 전달합니다. Referee는 작업과 관련된 추가 데이터를 쿼리하고 수집하는 러너 관리자의 worker입니다. 결과는 작업 artifact로 GitLab에 업로드됩니다.

Metrics Runner referee 사용

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

현재 docker-machine executor만 referee를 지원합니다.

GitLab Runner를 위한 Metrics Runner Referee 구성

config.toml 파일의 [[runner]] 섹션 내에서 [runners.referees] 및 [runners.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 형식입니다. 쿼리 문자열은 실행 중에 대체되는 두 변수를 지원합니다: