도커 실행기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

GitLab Runner는 Docker 이미지를 사용하여 작업을 실행하기 위해 Docker 실행기를 사용합니다.

Docker 실행기를 사용하여 다음을 수행할 수 있습니다:

  • 각 작업에 대해 동일한 빌드 환경 유지
  • CI 서버에서 작업을 실행할 필요 없이 동일한 이미지를 사용하여 로컬에서 명령 테스트

Docker 실행기는 Docker Engine을 사용하여 각 작업을 별도의 격리된 컨테이너에서 실행합니다. Docker Engine에 연결하기 위해 실행기는 다음을 사용합니다:

필수 조건:

도커 실행기 워크플로우

Docker 실행기는 준비, 사전 작업 및 사후 작업 단계를 실행하는 도구를 포함하는 특수 Docker 이미지를 기반으로 하는 Alpine Linux를 사용합니다. 특수 Docker 이미지의 정의를 보려면 GitLab Runner 리포지토리를 참조하세요.

Docker 실행기는 작업을 여러 단계로 나눕니다:

  1. 준비: 서비스를 생성하고 시작합니다.
  2. 사전 작업: 이전 단계에서 캐시를 클론, 복원하고 아티팩트를 다운로드합니다. 특수 Docker 이미지에서 실행됩니다.
  3. 작업: 러너를 위해 구성한 Docker 이미지에서 빌드를 실행합니다.
  4. 사후 작업: 캐시를 생성하고 아티팩트를 GitLab에 업로드합니다. 특수 Docker 이미지에서 실행됩니다.

지원되는 구성

Docker 실행기는 다음 구성을 지원합니다.

Windows 구성의 알려진 문제 및 추가 요구 사항에 대한 내용은 Windows 컨테이너 사용을 참조하세요.

Runner가 설치된 위치: 실행기: 컨테이너가 실행되는 위치:
Windows docker-windows Windows
Windows docker Linux
Linux docker Linux

이 구성은 지원되지 않습니다:

Runner가 설치된 위치: 실행기: 컨테이너가 실행되는 위치:
Linux docker-windows Linux
Linux docker Windows
Linux docker-windows Windows
Windows docker Windows
Windows docker-windows Linux
note
GitLab Runner는 Docker Engine API
v1.25를 사용하여 Docker Engine과 통신합니다. 이는
Linux 서버에서 지원되는 Docker의
최소 지원 버전이 1.13.0임을 의미하며,
Windows Server에서는 최신 버전이어야 합니다.

Docker 실행기 사용

Docker 실행기를 사용하려면 config.toml에서 실행기로 Docker를 정의합니다.

다음 샘플은 Docker를 실행기로 정의하고 예제 구성을 보여줍니다. 이러한 값에 대한 자세한 내용은 고급 구성을 참조하세요.

concurrent = 4

[[runners]]
name = "myRunner"
url = "https://gitlab.com/ci"
token = "......"
executor = "docker"
[runners.docker]
  tls_verify = true
  image = "my.registry.tld:5000/alpine:latest"
  privileged = false
  disable_entrypoint_overwrite = false
  oom_kill_disable = false
  disable_cache = false
  volumes = [
    "/cache",
  ]
  shm_size = 0
  allowed_pull_policies = ["always", "if-not-present"]
  allowed_images = ["my.registry.tld:5000/*:*"]
  allowed_services = ["my.registry.tld:5000/*:*"]
  [runners.docker.volume_driver_ops]
    "size" = "50G"

이미지 및 서비스 구성

사전 요구 사항:

  • 작업이 실행되는 이미지에는 운영 체제 PATH에 작동하는 쉘이 있어야 합니다. 지원되는 쉘은 다음과 같습니다:

Docker executor를 구성하려면, .gitlab-ci.yml와 config.toml에서 Docker 이미지와 서비스를 정의합니다.

다음 키워드를 사용하세요:

  • image: 러너가 작업을 실행하는 데 사용하는 Docker 이미지의 이름입니다.
    • 로컬 Docker 엔진에서 이미지를 입력하거나 Docker Hub의 이미지를 사용할 수 있습니다. 자세한 내용은 Docker 문서를 참조하세요.
    • 이미지 버전을 정의하려면 콜론(:)을 사용하여 태그를 추가합니다. 태그를 지정하지 않으면 Docker는 latest를 버전으로 사용합니다.
  • services: 또 다른 컨테이너를 생성하고 image에 연결하는 추가 이미지입니다. 서비스 유형에 대한 자세한 내용은 Services를 참조하세요.

.gitlab-ci.yml에서 이미지 및 서비스 정의

러너가 모든 작업에 사용하는 이미지를 정의하고 빌드 시간 동안 사용할 서비스 목록을 정의합니다.

예시:

image: ruby:2.7

services:
  - postgres:9.3

before_script:
  - bundle install

test:
  script:
  - bundle exec rake spec

작별로 다른 이미지 및 서비스를 정의하려면:

before_script:
  - bundle install

test:2.6:
  image: ruby:2.6
  services:
  - postgres:9.3
  script:
  - bundle exec rake spec

test:2.7:
  image: ruby:2.7
  services:
  - postgres:9.4
  script:
  - bundle exec rake spec

.gitlab-ci.yml에서 image를 정의하지 않으면 러너는 config.toml에 정의된 image를 사용합니다.

config.toml에서 이미지 및 서비스 정의

러너가 실행하는 모든 작업에 이미지를 추가하려면 config.toml의 [runners.docker]를 업데이트합니다.

.gitlab-ci.yml에서 image를 정의하지 않으면 러너는 config.toml에 정의된 이미지를 사용합니다.

예시:

[runners.docker]
  image = "ruby:2.7"

[[runners.docker.services]]
  name = "mysql:latest"
  alias = "db"

[[runners.docker.services]]
  name = "redis:latest"
  alias = "cache"

이 예시는 테이블 배열 구문을 사용합니다.

개인 레지스트리에서 이미지 정의

사전 요구 사항:

  • 개인 레지스트리의 이미지에 접근하려면 GitLab Runner 인증을 수행해야 합니다.

개인 레지스트리에서 이미지를 정의하려면 .gitlab-ci.yml에서 레지스트리 이름과 이미지를 제공합니다.

예시:

image: my.registry.tld:5000/namespace/image:tag

이 예시에서 GitLab Runner는 my.registry.tld:5000 레지스트리에서 이미지를 검색합니다 namespace/image:tag.

네트워크 구성

서비스를 CI/CD 작업에 연결하기 위해 네트워크를 구성해야 합니다.

네트워크를 구성하려면 다음 중 하나를 선택할 수 있습니다:

  • 권장합니다. 각 작업마다 네트워크를 생성하도록 러너를 구성합니다.
  • 컨테이너 링크를 정의합니다. 컨테이너 링크는 Docker의 레거시 기능입니다.

각 작업에 대한 네트워크 생성

각 작업마다 네트워크를 생성하도록 러너를 구성할 수 있습니다.

이 네트워킹 모드를 활성화하면 러너는 각 작업에 대해 사용자 정의 Docker 브리지 네트워크를 생성하고 사용합니다. Docker 환경 변수는 컨테이너 간에 공유되지 않습니다. 사용자 정의 브리지 네트워크에 대한 자세한 정보는 Docker 문서를 참조하세요.

이 네트워킹 모드를 사용하려면 config.toml에서 기능 플래그나 환경 변수에서 FF_NETWORK_PER_BUILD를 활성화하세요.

network_mode를 설정하지 마세요.

예제:

[[runners]]
  (...)
  executor = "docker"
  environment = ["FF_NETWORK_PER_BUILD=1"]

또는:

[[runners]]
  (...)
  executor = "docker"
  [runners.feature_flags]
    FF_NETWORK_PER_BUILD = true

기본 Docker 주소 풀을 설정하려면 dockerd에서 default-address-pool을 사용하세요. CIDR 범위가 이미 네트워크에서 사용 중인 경우, Docker 네트워크는 호스트의 다른 네트워크와 충돌할 수 있습니다. 여기에는 다른 Docker 네트워크도 포함됩니다.

이 기능은 Docker 데몬이 IPv6가 활성화된 상태로 구성된 경우에만 작동합니다. IPv6 지원을 활성화하려면 Docker 구성에서 enable_ipv6를 true로 설정하세요. 자세한 내용은 Docker 문서를 참조하세요.

러너는 작업 컨테이너를 해결하기 위해 build 별칭을 사용합니다.

러너가 각 작업에 대한 네트워크를 생성하는 방법

작업이 시작되면, 러너는:

  1. docker network create <network> 명령어와 유사한 브리지 네트워크를 생성합니다.
  2. 서비스 및 컨테이너를 브리지 네트워크에 연결합니다.
  3. 작업이 끝나면 네트워크를 제거합니다.

작업을 실행하는 컨테이너와 서비스를 실행하는 컨테이너는 서로의 호스트 이름과 별칭을 해결합니다. 이 기능은 Docker에 의해 제공됩니다.

컨테이너 링크로 네트워크 구성

Docker 레거시 컨테이너 링크와 기본 Docker bridge를 사용하여 작업 컨테이너와 서비스를 연결하는 네트워크 모드를 구성할 수 있습니다. 이 네트워크 모드는 FF_NETWORK_PER_BUILD가 활성화되지 않은 경우 기본값입니다.

네트워크를 구성하려면 config.toml 파일에서 네트워킹 모드를 지정하세요:

  • bridge: 브리지 네트워크를 사용합니다. 기본값입니다.
  • host: 컨테이너 내부에서 호스트의 네트워크 스택을 사용합니다.
  • none: 네트워킹 없음. 권장하지 않음.

예제:

[[runners]]
  (...)
  executor = "docker"
[runners.docker]
  network_mode = "bridge"

다른 network_mode 값을 사용하는 경우, 이는 이미 존재하는 Docker 네트워크의 이름으로 간주되며, 빌드 컨테이너가 연결됩니다.

이름 확인 중에 Docker는 서비스 컨테이너 호스트 이름과 별칭으로 /etc/hosts 파일을 업데이트합니다. 그러나 서비스 컨테이너는 컨테이너 이름을 해결할 수 없습니다. 컨테이너 이름을 해결하려면 각 작업에 대해 네트워크를 생성해야 합니다.

링크된 컨테이너는 환경 변수를 공유합니다.

생성된 네트워크의 MTU 재정의

OpenStack의 가상 머신과 같은 일부 환경에서는 사용자 정의 MTU가 필요합니다.

Docker 데몬은 docker.json의 MTU를 존중하지 않습니다(자세한 내용은 Moby issue 34981 참조).

config.toml에서 유효한 값으로 network_mtu를 설정하여 Docker 데몬이 새로 생성된 네트워크에 대한 올바른 MTU를 사용할 수 있도록 해야 합니다.

재정의가 적용되려면 FF_NETWORK_PER_BUILD를 활성화해야 합니다.

다음 구성은 각 작업에 대해 생성된 네트워크의 MTU를 1402로 설정합니다.

환경 요구 사항에 맞게 값을 조정하십시오.

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    network_mtu = 1402
    [runners.feature_flags]
      FF_NETWORK_PER_BUILD = true

Docker 이미지 및 서비스 제한

Docker 이미지 및 서비스를 제한하려면 allowed_images 및 allowed_services 매개변수에 와일드카드 패턴을 지정하세요.

예를 들어, 개인 Docker 레지스트리에서만 이미지를 허용하려면 다음과 같이 합니다:

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

개인 Docker 레지스트리에서 이미지 목록으로 제한하려면 다음과 같이 합니다:

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

서비스 호스트명 접근

서비스 호스트명에 접근하려면 .gitlab-ci.yml의 services에 서비스를 추가하세요.

예를 들어, 애플리케이션과의 API 통합 테스트를 위해 Wordpress 인스턴스를 사용하려면, tutum/wordpress를 서비스 이미지로 사용하세요:

services:
- tutum/wordpress:latest

작업이 실행될 때 tutum/wordpress 서비스가 시작됩니다.

빌드 컨테이너에서 tutum__wordpress 및 tutum-wordpress라는 호스트명으로 접근할 수 있습니다.

지정된 서비스 별칭 외에, 러너는 서비스 이미지의 이름을 별칭으로 서비스 컨테이너에 할당합니다.

이러한 별칭 중 아무거나 사용할 수 있습니다.

러너는 이미지 이름을 기준으로 다음 규칙을 사용하여 별칭을 생성합니다:

  • : 이후의 모든 부분이 제거됩니다.
  • 첫 번째 별칭에 대해 슬래시 (/)는 두 개의 언더스코어 (__)로 대체됩니다.
  • 두 번째 별칭에 대해 슬래시 (/)는 하이픈 (-)으로 대체됩니다.

개인 서비스 이미지를 사용하는 경우, 러너는 지정된 포트를 제거하고 규칙을 적용합니다.

서비스 registry.gitlab-wp.com:4999/tutum/wordpress는 호스트명 registry.gitlab-wp.com__tutum__wordpress 및 registry.gitlab-wp.com-tutum-wordpress로 결과가 나옵니다.

서비스 구성

데이터베이스 이름을 변경하거나 계정 이름을 설정하려면 서비스에 대한 환경 변수를 정의할 수 있습니다.

러너가 변수를 전달할 때:

  • 변수는 모든 컨테이너에 전달됩니다. 러너는 특정 컨테이너에 변수 전달할 수 없습니다.
  • 보안 변수는 빌드 컨테이너에 전달됩니다.

구성 변수에 대한 자세한 정보는 각 이미지의 해당 Docker Hub 페이지에서 제공되는 문서를 참조하세요.

RAM에 디렉터리 마운트

tmpfs 옵션을 사용하여 RAM에 디렉터리를 마운트할 수 있습니다. 이는 데이터베이스와 같이 I/O 관련 작업이 많은 경우 테스트 시간을 단축시킵니다.

러너 구성에서 tmpfs 및 services_tmpfs 옵션을 사용하면 각기 다른 옵션을 가진 여러 경로를 지정할 수 있습니다. 자세한 내용은 Docker 문서를 참조하세요.

예를 들어, 공식 MySQL 컨테이너의 데이터 디렉터리를 RAM에 마운트하기 위해 config.toml을 구성합니다:

[runners.docker]
  # 메인 컨테이너용
  [runners.docker.tmpfs]
      "/var/lib/mysql" = "rw,noexec"

  # 서비스용
  [runners.docker.services_tmpfs]
      "/var/lib/mysql" = "rw,noexec"

서비스에서 디렉터리 빌드

GitLab Runner는 모든 공유 서비스에 /builds 디렉터리를 마운트합니다.

다양한 서비스 사용에 대한 자세한 내용은 다음을 참조하세요:

GitLab Runner가 서비스 상태 검사를 수행하는 방법

  • GitLab 16.0에서 여러 포트 검사가 도입됨.

서비스가 시작된 후, GitLab Runner는 서비스가 응답할 때까지 대기합니다. Docker 실행자는 서비스 컨테이너의 노출된 서비스 포트에 TCP 연결을 시도합니다.

  • GitLab 15.11 및 이전 버전에서는 첫 번째 노출된 포드만 확인됩니다.
  • GitLab 16.0 및 이후 버전에서는 처음 20개의 노출된 포드가 확인됩니다.

HEALTHCHECK_TCP_PORT 서비스 변수를 사용하여 특정 포트에서 상태 검사를 수행할 수 있습니다:

job:
  services:
    - name: mongo
      variables:
        HEALTHCHECK_TCP_PORT: "27017"

이를 구현하는 방법을 보려면 상태 검사 Go 명령어를 사용하세요.

Docker 드라이버 작업 지정

빌드 용량을 생성할 때 Docker 볼륨 드라이버에 전달할 인수를 지정합니다.

예를 들어, 다른 드라이버 특정 옵션 외에도 각 빌드를 실행하는 공간을 제한하는 데 이러한 인수를 사용할 수 있습니다.

각 빌드에서 소비할 수 있는 한도가 50GB로 설정된 config.toml의 예는 다음과 같습니다.

[runners.docker]
  [runners.docker.volume_driver_ops]
      "size" = "50G"

컨테이너 빌드 및 캐시를 위한 디렉터리 구성

컨테이너 내에서 데이터가 저장되는 위치를 정의하려면 config.toml의 [[runners]] 섹션에서 /builds 및 /cache 디렉터리를 구성합니다.

/cache 저장 경로를 수정하는 경우, 경로를 지속적으로 표시하려면 config.toml의 [runners.docker] 섹션에서 volumes = ["/my/cache/"]로 정의해야 합니다.

기본적으로 Docker 실행자는 다음 디렉터리에 빌드 및 캐시를 저장합니다:

  • /builds/<namespace>/<project-name>의 빌드
  • 컨테이너 내의 /cache의 캐시

Docker 캐시 지우기

사용하지 않는 컨테이너와 러너가 생성한 볼륨을 제거하려면 clear-docker-cache를 사용하세요.

옵션 목록을 보려면 스크립트를 help 옵션으로 실행하세요:

clear-docker-cache help

기본 옵션은 prune-volumes로, 사용하지 않는 모든 컨테이너(대기 및 참조되지 않은)와 볼륨을 제거합니다.

캐시 저장소를 효율적으로 관리하려면:

  • 매주 한 번 cron으로 clear-docker-cache를 정기적으로 실행하세요.
  • 디스크 공간을 회수하는 동안 성능 향상을 위해 캐시에서 최근 컨테이너를 유지하세요.

Docker 빌드 이미지 지우기

clear-docker-cache 스크립트는 GitLab Runner에 의해 태그가 지정되지 않은 Docker 이미지를 제거하지 않습니다.

Docker 빌드 이미지를 지우려면:

  1. 회수할 수 있는 디스크 공간을 확인합니다:

    clear-docker-cache space

Docker 디스크 사용량 표시
----------------------

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          14        9         1.306GB   545.8MB (41%)
Containers      19        18        115kB     0B (0%)
Local Volumes   0         0         0B        0B
Build Cache     0         0         0B        0B

  2. 사용하지 않는 모든 컨테이너, 네트워크, 이미지(담기 및 참조되지 않은) 및 태그가 없는 볼륨을 제거하려면 docker system prune 명령을 실행합니다.

영구 저장소

Docker 실행자는 컨테이너를 실행할 때 영구 저장소를 제공합니다.

volumes = 에 정의된 모든 디렉터리는 빌드 간에 지속적입니다.

volumes 지시어는 다음 유형의 저장소를 지원합니다:

  • 동적 저장소의 경우 <path>를 사용합니다. <path>는 해당 프로젝트의 동일한 동시 작업의 후속 실행 간에 지속적입니다. 데이터는 사용자 정의 캐시 볼륨에 연결됩니다: runner-<short-token>-project-<id>-concurrent-<concurrency-id>-cache-<md5-of-path>.
  • 호스트 바인딩 저장소의 경우 <host-path>:<path>[:<mode>]를 사용합니다. <path>는 호스트 시스템의 <host-path>에 바인딩됩니다. 선택적 <mode>는 이 저장소가 읽기 전용인지 읽기-쓰기인지(기본값) 지정합니다.

빌드를 위한 영구 저장소

/builds 디렉토리를 호스트 바인딩 저장소로 만들면 빌드는 다음에 저장됩니다: /builds/<short-token>/<concurrent-id>/<namespace>/<project-name>, 여기서:

  • <short-token>는 Runner의 토큰을 간략화한 버전입니다(첫 8자리).
  • <concurrent-id>는 특정 러너의 로컬 작업 ID를 식별하는 고유한 번호입니다.

IPC 모드

Docker 실행자는 컨테이너의 IPC 네임스페이스를 다른 위치와 공유하는 것을 지원합니다. 이는 docker run --ipc 플래그와 일치합니다.

Docker 문서에서 IPC 설정에 대한 자세한 내용 확인하세요.

권한 모드

Docker 실행자는 빌드 컨테이너의 미세 조정을 가능하게 하는 여러 옵션을 지원합니다. 이러한 옵션 중 하나가 privileged 모드입니다.

권한 모드에서 Docker-in-Docker 사용

구성된 privileged 플래그는 빌드 컨테이너와 모든 서비스에 전달되어 Docker-in-Docker 접근 방식을 쉽게 사용할 수 있도록 합니다.

먼저, 러너(config.toml)를 privileged 모드에서 실행되도록 구성합니다:

[[runners]]
  executor = "docker"
  [runners.docker]
    privileged = true

그런 다음, 빌드 스크립트(.gitlab-ci.yml)를 Docker-in-Docker 컨테이너를 사용하도록 만듭니다:

image: docker:git
services:
- docker:dind

build:
  script:
  - docker build -t my-image .
  - docker push my-image

경고: 권한 모드에서 실행되는 컨테이너는 보안 위험이 있습니다.

컨테이너가 권한 모드로 실행될 때 컨테이너 보안 메커니즘이 비활성화되어 호스트가 권한 상승에 노출됩니다.

권한 모드에서 컨테이너를 실행하면 컨테이너 탈출로 이어질 수 있습니다. 더 많은 정보는 Docker 문서에서 런타임 권한 및 Linux 기능에 대해 참고하세요.

당신은 다음과 같은 오류를 피하기 위해 Docker-in-Docker에서 TLS를 구성하거나 TLS를 비활성화해야 할 수 있습니다:

Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running?

루트리스 Docker-in-Docker와 제한된 특권 모드 사용

이 버전에서는 루트리스 Docker-in-Docker 이미지만 특권 모드에서 서비스로 실행할 수 있습니다.

services_privileged 및 allowed_privileged_services 구성 매개변수는 어떤 컨테이너가 특권 모드에서 실행될 수 있는지를 제한합니다.

루트리스 Docker-in-Docker를 제한된 특권 모드에서 사용하려면:

  1. config.toml에서 실행기를 services_privileged 및 allowed_privileged_services를 사용하도록 구성합니다:

    [[runners]]
  executor = "docker"
  [runners.docker]
    services_privileged = true
    allowed_privileged_services = ["docker.io/library/docker:*-dind-rootless", "docker.io/library/docker:dind-rootless", "docker:*-dind-rootless", "docker:dind-rootless"]

  2. .gitlab-ci.yml에서 빌드 스크립트를 수정하여 루트리스 Docker-in-Docker 컨테이너를 사용합니다:

    image: docker:git
services:
- docker:dind-rootless

build:
  script:
  - docker build -t my-image .
  - docker push my-image

allowed_privileged_services에 나열한 루트리스 Docker-in-Docker 이미지만 특권 모드에서 실행될 수 있습니다.
다른 모든 컨테이너는 비특권 모드에서 작업과 서비스가 실행됩니다.

비루트 모드로 실행되기 때문에, 루트리스 Docker-in-Docker 또는 루트리스 Buildkit과 같은 특권 모드 이미지와 함께 사용하는 것이 _거의 안전_합니다.

보안 문제에 대한 자세한 내용은
Docker 실행기의 보안 위험을 참조하십시오.

Docker ENTRYPOINT 구성

기본적으로 Docker 실행기는 Docker 이미지의 ENTRYPOINT를 재정의하지 않으며, 작업 스크립트를 실행하는 컨테이너를 시작하기 위해 sh 또는 bash를 COMMAND로 전달합니다.

작업이 실행될 수 있도록 하려면, 해당 Docker 이미지는 다음을 제공해야 합니다:

  • sh 또는 bash와 grep
  • sh/bash를 인자로 받아 쉘을 시작하는 ENTRYPOINT 정의

Docker Executor는 작업의 컨테이너를 다음 명령어와 동등한 것으로 실행합니다:

docker run <image> sh -c "echo 'It works!'" # 또는 bash

Docker 이미지가 이 메커니즘을 지원하지 않는 경우, 이미지의 ENTRYPOINT를 재정의할 수 있습니다.

# 등가
# docker run --entrypoint "" <image> sh -c "echo 'It works!'"
image:
  name: my-image
  entrypoint: [""]

자세한 내용은 이미지의 Entrypoint 재정의하기 및 Docker에서 CMD와 ENTRYPOINT가 상호 작용하는 방법을 참조하십시오.

JOB 스크립트 as ENTRYPOINT

ENTRYPOINT를 사용하여 빌드 스크립트를 사용자 정의 환경이나 보안 모드에서 실행하는 Docker 이미지를 만들 수 있습니다.

예를 들어, 빌드 스크립트를 실행하지 않는 ENTRYPOINT를 사용하는 Docker 이미지를 만들 수 있습니다. 대신에, Docker 이미지는 디렉토리에서 Docker 이미지를 빌드하기 위해 미리 정의된 명령 집합을 실행합니다.
빌드 컨테이너를 특권 모드에서 실행하고 러너의 빌드 환경을 안전하게 유지합니다.

  1. 새로운 Dockerfile을 생성합니다:

    FROM docker:dind
ADD / /entrypoint.sh
ENTRYPOINT ["/bin/sh", "/entrypoint.sh"]

  2. ENTRYPOINT로 사용되는 bash 스크립트(entrypoint.sh)를 생성합니다:

    #!/bin/sh

dind docker daemon
    --host=unix:///var/run/docker.sock \
    --host=tcp://0.0.0.0:2375 \
    --storage-driver=vf &

docker build -t "$BUILD_IMAGE" .
docker push "$BUILD_IMAGE"

  3. 이미지를 Docker 레지스트리에 푸시합니다.

  4. privileged 모드에서 Docker 실행기를 실행합니다. config.toml에서 다음과 같이 정의합니다:

    [[runners]]
  executor = "docker"
  [runners.docker]
    privileged = true

  5. 프로젝트에서 다음 .gitlab-ci.yml을 사용합니다:

    variables:
  BUILD_IMAGE: my.image
build:
  image: my/docker-build:image
  script:
  - Dummy Script

Podman을 사용하여 Docker 명령 실행

Linux에 GitLab Runner가 설치되어 있으면, 작업에서 Podman을 사용하여 Docker 실행기에서 컨테이너 런타임으로 Docker를 대체할 수 있습니다.

사전 요구사항:

  1. Linux 호스트에서 GitLab Runner를 설치합니다. 시스템의 패키지 관리자를 사용하여 GitLab Runner를 설치한 경우, 자동으로 gitlab-runner 사용자가 생성됩니다.

  2. GitLab Runner를 실행할 사용자로 로그인하세요. 이는 pam_systemd를 우회하지 않는 방식으로 해야 합니다. 올바른 사용자로 SSH를 사용할 수 있습니다. 이렇게 하면 이 사용자로 systemctl을 실행할 수 있습니다.

  3. 시스템이 rootless Podman 설정의 사전 요구사항을 충족하는지 확인하세요. 특히, 사용자가 /etc/subuid 및 /etc/subgid 파일에 올바른 항목을 가지고 있는지 확인합니다.

  4. Linux 호스트에서 Podman을 설치합니다.

  5. Podman 소켓을 활성화하고 시작합니다:

    systemctl --user --now enable podman.socket

  6. Podman 소켓이 수신 대기 중인지 확인합니다:

    systemctl status --user podman.socket

  7. Podman의 API에 접근하는 Listen 키의 소켓 문자열을 복사합니다.

  8. GitLab Runner 사용자가 로그아웃한 후에도 Podman 소켓이 사용 가능하도록 합니다:

    sudo loginctl enable-linger gitlab-runner

  9. GitLab Runner의 config.toml 파일을 편집하고 [runners.docker] 섹션의 호스트 항목에 소켓 값을 추가합니다. 예를 들어:

    [[runners]]
  name = "podman-test-runner-2022-06-07"
  url = "https://gitlab.com"
  token = "x-XxXXXXX-xxXxXxxxxx"
  executor = "docker"
  [runners.docker]
    host = "unix:///run/user/1012/podman/podman.sock"
    tls_verify = false
    image = "quay.io/podman/stable"
    privileged = true

Podman을 사용하여 Dockerfile에서 컨테이너 이미지 빌드

다음 예제는 Podman을 사용하여 컨테이너 이미지를 빌드하고 이미지를 GitLab Container 레지스트리에 푸시합니다.

Runner의 config.toml에서 기본 컨테이너 이미지는 quay.io/podman/stable로 설정되어 있어, CI 작업이 포함된 명령을 실행하기 위해 해당 이미지를 사용합니다.

variables:
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG

before_script:
  - podman login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

oci-container-build:
  stage: build
  script:
    - podman build -t $IMAGE_TAG .
    - podman push $IMAGE_TAG
  when: manual

Buildah를 사용하여 Dockerfile에서 컨테이너 이미지를 빌드하기

다음 예제는 Buildah를 사용하여 컨테이너 이미지를 빌드하고 GitLab 컨테이너 레지스트리에 이미지를 푸시하는 방법을 보여줍니다.

image: quay.io/buildah/stable

variables:
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG

before_script:
  - buildah login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

oci-container-build:
  stage: build
  script:
    - buildah bud -t $IMAGE_TAG .
    - buildah push $IMAGE_TAG
  when: manual

작업을 실행하는 사용자 지정

기본적으로 러너는 컨테이너 내에서 root 사용자로 작업을 실행합니다. 작업을 실행할 다른 비 루트 사용자 지정하려면 Docker 이미지의 Dockerfile에 USER 지시어를 사용하세요.

FROM amazonlinux
RUN ["yum", "install", "-y", "nginx"]
RUN ["useradd", "www"]
USER "www"
CMD ["/bin/bash"]

해당 Docker 이미지를 사용하여 작업을 실행하면 지정된 사용자로 실행됩니다:

build:
  image: my/docker-build:image
  script:
  - whoami   # www

러너가 이미지를 가져오는 방법 구성

config.toml에서 풀 정책을 구성하여 러너가 레지스트리에서 Docker 이미지를 끌어오는 방법을 정의할 수 있습니다. 단일 정책, 여러 정책 목록 또는 특정 풀 정책 허용을 설정할 수 있습니다.

다음 값을 pull_policy에 사용하세요:

  • always: 로컬 이미지가 존재하더라도 이미지를 가져옵니다. 기본값.
  • if-not-present: 로컬 버전이 존재하지 않을 때만 이미지를 가져옵니다.
  • never: 이미지를 가져오지 않고 로컬 이미지만 사용합니다.
[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    pull_policy = "always" # 사용 가능한: always, if-not-present, never

always 풀 정책 설정

기본적으로 활성화되어 있는 always 옵션은 컨테이너를 생성하기 전에 항상 이미지를 가져옵니다. 이 옵션은 이미지가 최신 상태인지 확인하고, 로컬 이미지가 존재하더라도 구식 이미지를 사용하지 않도록 방지합니다.

다음과 같은 경우 이 풀 정책을 사용하세요:

  • 러너는 항상 최신 이미지를 가져와야 합니다.
  • 러너는 공개적으로 이용 가능하며 자동 스케일링 또는 GitLab 인스턴스의 공유 러너로 구성되어 있습니다.

이 정책을 사용하지 마세요: 러너가 로컬 저장 이미지만 사용해야 하는 경우.

config.toml에서 always를 pull policy로 설정하세요:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    pull_policy = "always"

if-not-present 풀 정책 설정

풀 정책을 if-not-present로 설정하면 러너는 먼저 로컬 이미지가 존재하는지 확인합니다. 로컬 이미지가 없으면 러너가 레지스트리에서 이미지를 가져옵니다.

if-not-present 정책을 사용하여:

  • 로컬 이미지를 사용하지만 로컬 이미지가 존재하지 않을 경우 이미지를 가져옵니다.
  • 러너가 무거운 이미지 레이어의 차이를 분석하는 시간을 줄이기 위해 이미지를 드물게 업데이트해야 하는 경우. 이 경우, 이미지를 강제로 업데이트하려면 로컬 Docker Engine 저장소에서 이미지를 정기적으로 수동으로 제거해야 합니다.

이 정책을 사용하지 마세요:

  • 서로 다른 사용자가 사용할 수 있는 공유 러너의 경우, 그 사용자가 개인 이미지에 접근할 수 있습니다. 보안 문제에 대한 자세한 내용은 if-not-present 풀 정책과 함께 개인 Docker 이미지 사용을 참조하세요.
  • 작업이 자주 업데이트되며 최신 이미지 버전에서 실행되어야 하는 경우. 이로 인해 네트워크 부하 감소는 로컬 이미지를 자주 삭제하는 것의 가치를 초과할 수 있습니다.

config.toml에서 if-not-present 정책을 설정하세요:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    pull_policy = "if-not-present"

never 풀 정책 설정

선행 조건:

  • 로컬 이미지는 설치된 Docker Engine과 사용 중인 이미지의 로컬 복사본을 포함해야 합니다.

never로 풀 정책을 설정하면 이미지 풀링이 비활성화됩니다. 사용자는 러너가 실행되는 Docker 호스트에서 수동으로 풀링된 이미지만 사용할 수 있습니다.

never 풀 정책을 사용하십시오:

  • 러너 사용자가 사용하는 이미지를 제어하기 위해.
  • 특정 이미지만 사용할 수 있고 공용 레지스트리에 없는 프로젝트 전용 개인 러너를 위해.

사용하지 마십시오 never 풀 정책은 자동 확장 Docker 실행기에서. never 풀 정책은 선택한 클라우드 제공자에 대한 미리 정의된 클라우드 인스턴스 이미지를 사용할 때만 사용 가능합니다.

config.toml에서 never 정책을 설정하십시오:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    pull_policy = "never"

여러 개의 풀 정책 설정

풀링이 실패할 경우 실행할 여러 풀 정책을 나열할 수 있습니다. 러너는 풀 시도가 성공할 때까지 나열된 순서대로 풀 정책을 처리합니다. 예를 들어, 러너가 always 풀 정책을 사용하고 레지스트리가 사용할 수 없는 경우 if-not-present를 두 번째 풀 정책으로 추가하여 로컬에서 캐시된 Docker 이미지를 사용할 수 있습니다.

이 풀 정책의 보안 영향을 포함한 정보는 if-not-present 풀 정책으로 개인 Docker 이미지의 사용을 참조하십시오.

여러 풀 정책을 설정하려면 config.toml에서 목록으로 추가하십시오:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    pull_policy = ["always", "if-not-present"]

Docker 풀 정책 허용

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

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

예를 들어, always 및 if-not-present 풀 정책만 허용하려면 config.toml에 추가하십시오:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    allowed_pull_policies = ["always", "if-not-present"]
  • allowed_pull_policies를 지정하지 않으면 목록은 pull_policy 키워드에 지정된 값과 일치합니다.
  • pull_policy를 지정하지 않으면 기본값은 always입니다.
  • 기존 pull_policy 키워드는 allowed_pull_policies에 지정되지 않은 풀 정책을 포함해서는 안됩니다. 만약 포함된다면, 작업은 오류를 반환합니다.

이미지 풀 오류 메시지

오류 메시지 설명
Pulling docker image registry.tld/my/image:latest ... ERROR: Build failed: Error: image registry.tld/my/image:latest not found 러너가 이미지를 찾을 수 없습니다. always 풀 정책이 설정되었을 때 표시됩니다.
Pulling docker image local_image:latest ... ERROR: Build failed: Error: image local_image:latest not found 이미지는 로컬에서 빌드되었으며 공용 또는 기본 Docker 레지스트리에 존재하지 않습니다. always 풀 정책이 설정되었을 때 표시됩니다.
Pulling docker image registry.tld/my/image:latest ... WARNING:Cannot pull the latest version of image registry.tld/my/image:latest : Error: image registry.tld/my/image:latest not found WARNING:Locally found image will be used instead. 러너가 이미지를 당겨오는 대신 로컬 이미지를 사용했습니다. always 풀 정책이 설정된 경우에만 GitLab Runner 1.8 및 이전 버전에서 표시됩니다.
Pulling docker image local_image:latest ... ERROR: Build failed: Error: image local_image:latest not found 이미지를 로컬에서 찾을 수 없습니다. never 풀 정책이 설정되었을 때 표시됩니다.
WARNING:Failed to pull image with policy "always": Error response from daemon: received unexpected HTTP status: 502 Bad Gateway (docker.go:143:0s) Attempt #2: Trying "if-not-present" pull policy Using locally found image version due to "if-not-present" pull policy 러너가 이미지를 풀링하지 못하고 다음 목록에 나열된 풀 정책을 사용하여 이미지를 풀링하려고 합니다. 여러 개의 풀 정책이 설정되었을 때 표시됩니다.

실패한 풀 재시도

실패한 이미지 풀을 재시도하도록 러너를 구성하려면, config.toml에서 동일한 정책을 여러 번 지정하십시오.

예를 들어, 이 설정은 풀을 한 번 재시도합니다:

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

이 설정은 개별 프로젝트의 .gitlab-ci.yml 파일에 있는 retry 지시문과 유사하지만, Docker 풀의 초기 실패 시에만 적용됩니다.

Windows 컨테이너 사용

Docker 실행기와 함께 Windows 컨테이너를 사용하려면, 다음의 제한 사항, 지원되는 Windows 버전 및 Windows Docker 실행기 구성에 대한 정보를 참고하세요.

Nanoserver 지원

Windows 헬퍼 이미지에서 PowerShell Core 지원이 도입됨에 따라, 헬퍼 이미지의 nanoserver 변형을 활용할 수 있게 되었습니다.

Windows에서의 Docker 실행기 제한 사항

다음은 Docker 실행기와 함께 Windows 컨테이너를 사용할 때 몇 가지 제한 사항입니다:

  • Docker-in-Docker는 지원되지 않습니다. 이는 Docker 자체에서 지원되지 않기 때문입니다.
  • 상호작용 웹 터미널은 지원되지 않습니다.
  • 호스트 장치 마운팅은 지원되지 않습니다.
  • 볼륨 디렉토리를 마운트하려면 해당 디렉토리가 존재해야 하며, 그렇지 않으면 Docker가 컨테이너를 시작하지 못하게 되며, 이와 관련된 추가 세부 정보는 #3754를 참조하십시오.
  • docker-windows 실행기는 Windows에서 실행 중인 GitLab Runner에서만 실행할 수 있습니다.
  • Windows에서의 Linux 컨테이너는 여전히 실험적이기 때문에 지원되지 않습니다. 더 많은 세부사항은 관련 이슈를 읽어보십시오.

  • Docker의 제한 사항으로 인해, 대상 경로 드라이브 문자가 c:가 아닐 경우, 다음 경로는 지원되지 않습니다:

    즉, f:\\cache_dir와 같은 값은 지원되지 않지만, f:는 지원됩니다.

    그러나 대상 경로가 c: 드라이브에 있는 경우, 경로도 지원됩니다 (예: c:\\cache_dir).

    Docker 데몬이 이미지를 저장하고 컨테이너를 유지하는 위치를 설정하려면, Docker 데몬의 daemon.json 파일에서 data-root 매개변수를 업데이트하십시오.

    추가 정보는 구성 파일로 Docker 구성을 참조하십시오.

지원되는 Windows 버전

GitLab Runner는 다음 Windows 버전만 지원하며, 이는 우리의 Windows 지원 수명 주기를 따릅니다:

  • Windows Server 2022 LTSC (21H2)
  • Windows Server 2019 LTSC (1809)

향후 Windows Server 버전의 경우, 향후 버전 지원 정책이 있습니다.

Docker 데몬이 실행되는 동일한 OS 버전을 기반으로 하는 컨테이너만 실행할 수 있습니다. 예를 들어, 다음의 Windows Server Core 이미지를 사용할 수 있습니다:

  • mcr.microsoft.com/windows/servercore:ltsc2022
  • mcr.microsoft.com/windows/servercore:ltsc2022-amd64
  • mcr.microsoft.com/windows/servercore:1809
  • mcr.microsoft.com/windows/servercore:1809-amd64
  • mcr.microsoft.com/windows/servercore:ltsc2019

지원되는 Docker 버전

GitLab Runner가 실행되는 Windows Server는 최신 버전의 Docker를 실행해야 합니다.

왜냐하면 GitLab Runner는 Docker를 사용하여 어떤 버전의 Windows Server가 실행 중인지 감지하기 때문입니다.

GitLab Runner와 작동하지 않는 Docker의 알려진 버전은 Docker 17.06입니다.

왜냐하면 Docker가 Windows Server 버전을 식별하지 못해

다음과 같은 오류가 발생합니다:

지원되지 않는 Windows 버전: Windows Server Datacenter

이와 관련된 문제 해결 방법을 더 읽어보세요.

Windows Docker 실행기 구성

note
런너가 --docker-volumes 또는 DOCKER_VOLUMES 환경 변수를 전달할 때 소스 디렉토리로 c:\\cache로 등록된 경우, 알려진 문제가 발생합니다.

아래는 Windows에서 실행되는 간단한 Docker 실행기에 대한 구성 예시입니다.

[[runners]]
  name = "windows-docker-2019"
  url = "https://gitlab.com/"
  token = "xxxxxxx"
  executor = "docker-windows"
  [runners.docker]
    image = "mcr.microsoft.com/windows/servercore:1809_amd64"
    volumes = ["c:\\cache"]

Docker 실행기에 대한 다른 구성 옵션은

고급 구성 섹션을 참조하세요.

서비스

GitLab Runner 12.9 및 이후 버전에서는

서비스를 사용할 수 있습니다.

각 작업에 대한 네트워크를 활성화하여 사용할 수 있습니다.