- 도커 실행자 작업 흐름
- 지원되는 구성
- 도커 실행자 사용
- 이미지 및 서비스 구성
- 네트워크 구성
- Docker 이미지와 서비스 제한
- 서비스 호스트명 액세스
- 서비스 구성
- Docker 드라이버 작업 사양 지정
- 컨테이너 빌드 및 캐시용 디렉터리 구성
- Docker 캐시 지우기
- Docker 빌드 이미지 지우기
- 지속적인 저장
- IPC 모드
- 특권 모드
- Docker ENTRYPOINT 구성
- Docker 명령 실행에 Podman 사용하기
- 작업을 실행하는 사용자 지정하기
- 러너가 이미지를 가져오는 방식 구성
- 실패한 풀 다시 시도하기
- Windows 컨테이너 사용하기
도커 실행자
GitLab Runner은 Docker 실행자를 사용하여 Docker 이미지에서 작업을 실행합니다.
도커 실행자를 사용하여 다음을 수행할 수 있습니다:
- 각 작업에 동일한 빌드 환경을 유지합니다.
- CI 서버에서 작업을 실행할 필요 없이 로컬에서 명령을 테스트할 동일한 이미지를 사용합니다.
도커 실행자는 Docker Engine를 사용하여 각 작업을 별도 및 격리된 컨테이너에서 실행합니다. 실행자는 Docker Engine에 연결하려면 다음을 사용합니다:
- 당신이
.gitlab-ci.yml
에서 정의한 이미지 및 서비스. - 당신이
config.toml
에서 정의한 구성.
도커 실행자 작업 흐름
도커 실행자는 Alpine Linux를 기반으로 한 특수 도커 이미지를 사용하여 준비, 작업 전, 작업 후 단계를 실행합니다. 특수 도커 이미지의 정의를 보려면 GitLab Runner 리포지터리를 참조하세요.
도커 실행자는 작업을 여러 단계로 나누어 실행합니다:
- 준비: services를 생성하고 시작합니다.
- 작업 전: 이전 단계에서 캐시를 복원하고 아티팩트를 다운로드하며 복제합니다. 특수 도커 이미지에서 실행됩니다.
- 작업: 당신이 실행자를 구성한 Docker 이미지에서 빌드를 실행합니다.
- 작업 후: 캐시를 생성하고 아티팩트를 GitLab에 업로드합니다. 특수 도커 이미지에서 실행됩니다.
지원되는 구성
도커 실행자는 다음 구성을 지원합니다.
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 |
1.13.0
이며,
Windows Server의 경우 더 최신 버전이 필요합니다.도커 실행자 사용
도커 실행자를 사용하려면 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
에 작동하는 셸이 있어야 합니다. 지원되는 셸은 다음과 같습니다:
도커 실행자를 구성하려면 .gitlab-ci.yml
및 config.toml
에서 Docker 이미지와 서비스를 정의합니다.
다음 키워드를 사용합니다:
-
image
: 실행자가 작업을 실행할 때 사용하는 Docker 이미지의 이름입니다.- 로컬 Docker Engine의 이미지 또는 Docker Hub의 이미지 중 하나를 입력합니다. 자세한 정보는 Docker 문서를 참조하세요.
- 이미지 버전을 정의하려면 콜론(
:
)을 사용하여 태그를 추가합니다. 태그를 지정하지 않으면 Docker는 버전을latest
로 사용합니다.
-
services
:image
에 링크되어 다른 컨테이너를 만드는 추가 이미지입니다. 서비스 유형에 대한 자세한 정보는 서비스를 참조하세요.
.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 러너에 대한 인증을 해야 합니다.
개인 레지스트리에서 이미지를 정의하려면, .gitlab-ci.yml
에서 레지스트리 이름과 이미지를 제공하세요.
예시:
image: my.registry.tld:5000/namespace/image:tag
이 예시에서 GitLab 러너는 레지스트리 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
별칭을 사용합니다.
러너가 각 작업에 대해 네트워크 생성하는 방법
작업이 시작되면, 러너는 다음 작업을 수행합니다:
-
docker network create <network>
명령어와 비슷한 브릿지 네트워크를 생성합니다. - 서비스와 컨테이너를 브릿지 네트워크에 연결합니다.
- 작업이 끝나면 네트워크를 제거합니다.
작업을 실행하는 컨테이너와 서비스를 실행하는 컨테이너는 서로의 호스트 이름과 별칭을 해결합니다. 이 기능은 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의 VM과 같은 환경에서는 사용자 정의 MTU가 필요할 수 있습니다. Docker 데몬은 docker.json
에서 MTU를 준수하지 않기 때문에, config.toml
에 있는 network_mtu
를 유효한 값으로 설정하여 Docker 데몬이 새로 생성된 네트워크에 올바른 MTU를 사용하도록 지시할 수 있습니다.
[runners.docker]
network_mtu = 1402
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에 디렉터리 마운트
디렉터리를 RAM에 마운트하려면 tmpfs
옵션을 사용할 수 있습니다. 이는 데이터베이스와 같이 많은 I/O 관련 작업을 테스트해야 하는 경우 시간을 단축시킵니다.
러너 구성에서 tmpfs
및 services_tmpfs
옵션을 사용하면 각각의 옵션을 가진 여러 경로를 지정할 수 있습니다. 더 많은 정보는 Docker 문서를 참조하세요.
예를 들어, RAM에 데이터 디렉터리를 마운트하려면 공식 MySQL 컨테이너의 config.toml
을 구성하세요:
[runners.docker]
# 메인 컨테이너에 대해
[runners.docker.tmpfs]
"/var/lib/mysql" = "rw,noexec"
# 서비스에 대해
[runners.docker.services_tmpfs]
"/var/lib/mysql" = "rw,noexec"
서비스 내 디렉터리 빌드
GitLab 러너는 /builds
디렉터리를 모든 공유 서비스에 마운트합니다.
다양한 서비스 사용에 대한 자세한 정보는 다음을 참조하세요:
GitLab 러너가 수행하는 서비스 상태 확인
- GitLab 16.0에서 여러 포트 확인이 도입되었습니다.
서비스가 시작된 후 GitLab 러너는 서비스가 응답할 때까지 대기합니다. Docker 실행자는 서비스 컨테이너의 노출된 서비스 포트와의 TCP 연결을 시도합니다.
- GitLab 15.11 및 이전 버전에서는 첫 번째 노출된 포트만 확인됩니다.
- GitLab 16.0 및 이후 버전에서는 처음 20개의 노출된 포트가 확인됩니다.
HEALTHCHECK_TCP_PORT
서비스 변수를 사용하여 특정 포트에서 상태 확인을 수행할 수 있습니다:
job:
services:
- name: mongo
variables:
HEALTHCHECK_TCP_PORT: "27017"
이를 구현한 방법은 Health Check 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 캐시 지우기
- GitLab Runner 13.9에서 도입됨, 생성된 모든 러너 자원 정리.
러너에 의해 생성된 사용되지 않는 컨테이너 및 볼륨을 제거하기 위해 clear-docker-cache
를 사용하세요.
옵션 디렉터리을 보려면 스크립트를 help
옵션과 함께 실행하세요:
clear-docker-cache help
기본 옵션은 모든 사용되지 않는 컨테이너(둔감하거나 참조되지 않음) 및 볼륨을 제거하는 prune-volumes
입니다.
효율적인 캐시 리포지터리 관리를 위해:
-
cron
을 사용하여clear-docker-cache
를 정기적으로 실행하세요 (예: 매주 한 번). - 디스크 공간을 회수하면서 성능을 유지하기 위해 최근의 일부 컨테이너를 유지하세요.
Docker 빌드 이미지 지우기
clear-docker-cache
스크립트는 Docker 이미지를 제거하지 않습니다. 이는 GitLab 러너에 의해 태그되지 않기 때문입니다.
Docker 빌드 이미지를 지우려면:
-
회수될 수 있는 디스크 공간을 확인하세요:
clear-docker-cache space Show docker disk usage ---------------------- 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
-
모든 사용되지 않는 컨테이너, 네트워크, 이미지(둔감하고 참조되지 않음) 및 태그되지 않은 볼륨을 제거하려면
docker system prune
을 실행하세요.
지속적인 저장
Docker 실행자는 컨테이너를 실행할 때 지속적인 저장을 제공합니다. volumes =
에서 정의된 모든 디렉터리는 빌드 간에 지속적입니다.
volumes
지시문은 다음 유형의 저장을 지원합니다:
- 동적 저장을 위해
<경로>
를 사용합니다.<경로>
는 해당 프로젝트의 동일한 동시 작업의 연속적인 실행 간에 지속됩니다. 데이터는 사용자 정의 캐시 볼륨에 첨부됩니다:runner-<short-token>-project-<id>-concurrent-<concurrency-id>-cache-<md5-of-path>
. - 호스트 바운드 저장을 위해
<호스트-경로>:<경로>[:<모드>]
를 사용합니다.<경로>
는 호스트 시스템의<호스트-경로>
에 바인딩됩니다. 선택 사항인<모드>
는 이 저장이 읽기 전용 또는 읽기/쓰기(기본값)임을 지정합니다.
빌드를 위한 지속적인 저장
만약 /builds
디렉터리를 호스트 바운드 저장으로 만든다면, 빌드는 다음 위치에 저장됩니다: /builds/<short-token>/<concurrent-id>/<namespace>/<project-name>
, 여기서:
-
<short-token>
은 실행자 토큰의 줄임말(첫 8글자)입니다. -
<concurrent-id>
는 프로젝트 문맥에서 특정 실행자의 로컬 작업 ID를 식별하는 고유한 숫자입니다.
IPC 모드
Docker 실행자는 컨테이너의 IPC 네임스페이스를 다른 위치와 공유하는 것을 지원합니다. 이것은 docker run --ipc
플래그에 매핑됩니다.
자세한 내용은 Docker 문서의 IPC 설정를 참조하세요.
특권 모드
Docker 실행자는 빌드 컨테이너를 세밀하게 조정하는 여러 옵션을 지원합니다. 이 중 하나는 privileged
모드입니다.
특권 모드로 Docker-in-Docker 사용
구성된 privileged
플래그는 빌드 컨테이너와 모든 서비스로 전달되어 Docker-in-Docker 접근 방식을 쉽게 사용할 수 있도록 합니다.
먼저, 실행자를 (config.toml
)에서 특권
모드로 실행하도록 구성하세요:
[[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-in-Docker의 TLS 구성 또는 TLS 비활성화가 필요할 수 있습니다.
tcp://docker:2375의 Docker 데몬에 연결할 수 없습니다. Docker 데몬이 실행 중인가요?
제한된 특권 모드로 rootless Docker-in-Docker 사용
이 버전에서, 특권 모드로 실행되는 서비스는 Docker-in-Docker rootless 이미지만 허용됩니다.
services_privileged
및 allowed_privileged_services
구성 매개변수는
특권 모드에서 실행되는 어떤 컨테이너가 허용되는지 제한합니다.
제한된 특권 모드로 rootless Docker-in-Docker을 사용하려면:
-
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"]
-
.gitlab-ci.yml
에서 빌드 스크립트를 편집하여 Docker-in-Docker rootless 컨테이너를 사용하도록 하세요:image: docker:git services: - docker:dind-rootless build: script: - docker build -t my-image . - docker push my-image
allowed_privileged_services
에 나열된 Docker-in-Docker rootless 이미지만 허용됩니다.
작업 및 서비스용 다른 모든 컨테이너는 비특권 모드로 실행됩니다.
루트레스로 실행되는 것들이므로, 특권 모드 이미지인 Docker-in-Docker rootless 또는 Buildkit rootless와 함께 사용해도 _거의 안전_합니다.
보안 문제에 대한 자세한 정보는 Docker 실행자의 보안 위험를 참조하세요.
Docker ENTRYPOINT 구성
기본적으로 Docker 실행자는 Docker 이미지의 ENTRYPOINT
를 재정의하지 않고 sh
또는 bash
를 COMMAND
로 전달하여 작업 스크립트를 실행하는 컨테이너를 시작합니다.
작업이 실행되려면 작업의 Docker 이미지는:
-
sh
또는bash
및grep
를 제공해야 합니다. -
ENTRYPOINT
를 정의하여sh
/bash
를 전달하면 셸을 시작하는 메커니즘을 지원해야 합니다.
Docker 실행자는 작업 컨테이너를 다음 명령어의 동등한 것으로 실행합니다:
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의 상호 작용 이해을 참조하세요.
작업 스크립트로의 ENTRYPOINT
ENTRYPOINT
를 사용하여 커스텀 환경이나 안전 모드에서 빌드 스크립트를 실행하는 도커 이미지를 만들 수 있습니다.
예를 들어, 빌드 스크립트를 실행하지 않고 미리 정의된 일련의 명령을 실행하는 ENTRYPOINT
를 사용하는 도커 이미지를 만들 수 있습니다. 빌드 컨테이너를 privileged mode에서 실행하고 러너의 빌드 환경을 안전하게 만듭니다.
-
새로운 Dockerfile을 만듭니다.
FROM docker:dind ADD / /entrypoint.sh ENTRYPOINT ["/bin/sh", "/entrypoint.sh"]
-
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"
-
이미지를 Docker 레지스트리에 푸시합니다.
-
Docker 실행자를
privileged
모드로 실행합니다.config.toml
에서 다음을 정의하세요.[[runners]] executor = "docker" [runners.docker] privileged = true
-
프로젝트에서 다음
.gitlab-ci.yml
을 사용합니다.variables: BUILD_IMAGE: my.image build: image: my/docker-build:image script: - 더미 스크립트
Docker 명령 실행에 Podman 사용하기
Linux에 GitLab Runner가 설치된 경우, 작업은 Docker 실행자에서 Docker를 대체하기 위해 Podman을 사용할 수 있습니다.
전제 조건:
- Podman v4.2.0 이상.
- Podman으로 services를 실행하려면
FF_NETWORK_PER_BUILD
feature flag를 활성화해야 합니다. Docker container links는 레거시이며 Podman에서는 지원되지 않습니다. 네트워크 별칭을 생성하는 서비스의 경우podman-plugins
패키지를 설치해야 합니다.
- Linux 호스트에서 GitLab Runner를 설치합니다. 시스템 패키지 관리자를 사용하여 GitLab Runner를 설치한 경우, 자동으로
gitlab-runner
사용자가 만들어집니다. - GitLab Runner를 실행할 사용자로 로그인합니다.
pam_systemd
를 우회하지 않는 방식으로 로그인해야 합니다. 올바른 사용자로 SSH를 사용할 수 있습니다. 이렇게 함으로써 이 사용자로systemctl
을 실행할 수 있습니다. - 시스템이 루트리스 Podman 설정 조건을 충족하는지 확인합니다. 특히 사용자가
/etc/subuid
및/etc/subgid
에 올바른 항목을 가지고 있는지 확인합니다. - Linux 호스트에서 Podman을 설치합니다.
-
Podman 소켓을 활성화하고 시작합니다.
systemctl --user --now enable podman.socket
-
Podman 소켓이 수신 대기 중인지 확인합니다.
systemctl status --user podman.socket
- Podman의 API에 액세스하는 데 사용되는
Listen
키의 소켓 문자열을 복사합니다. -
GitLab Runner 사용자가 로그아웃된 후에도 Podman 소켓을 유지할 수 있도록 합니다.
sudo loginctl enable-linger gitlab-runner
-
GitLab Runner
config.toml
파일을 수정하고[[runners.docker]]
섹션의 host 항목에 소켓 값을 추가합니다. 예시:[[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
Dockerfile을 사용하여 Podman으로 컨테이너 이미지 빌드하기
다음 예는 Podman을 사용하여 컨테이너 이미지를 빌드하고 해당 이미지를 GitLab 컨테이너 레지스트리에 푸시하는 방법을 보여줍니다.
Runner config.toml
의 기본 컨테이너 이미지는 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
에 pull policy
로 always
를 설정하세요:
[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
pull_policy = "always"
if-not-present
풀 정책 설정
풀 정책을 if-not-present
로 설정하면 러너는 먼저 로컬 이미지가 있는지 확인합니다. 로컬 이미지가 없는 경우 러너는 레지스트리에서 이미지를 가져옵니다.
다음과 같은 경우 if-not-present
정책을 사용하세요:
- 로컬 이미지를 사용하되, 로컬 이미지가 없는 경우에만 이미지를 가져오는 경우
- 러너가 무거운 이미지 및 드물게 업데이트되는 이미지의 이미지 레이어 차이를 분석하는 데 걸리는 시간을 줄이려는 경우. 이 경우, 정기적으로 로컬 Docker Engine 리포지터리에서 이미지를 매뉴얼으로 제거하여 이미지 업데이트를 강제해야 합니다.
다음의 경우 이 정책을 사용하지 마십시오:
- 러너를 사용하는 다른 사용자가 프라이빗 이미지에 액세스할 수 있는 공유 러너의 경우. 보안 문제에 대한 자세한 정보는 프라이빗 Docker 이미지의 if-not-present 풀 정책 사용을 참조하세요.
- 작업이 자주 업데이트되어 가장 최신 이미지 버전에서 실행되어야 하는 경우. 이 경우 로컬 이미지의 자주 삭제되는 가치를 상회하는 네트워크 부하 감소가 발생할 수 있습니다.
config.toml
에서 if-not-present
정책을 설정하세요:
[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
pull_policy = "if-not-present"
never
풀 정책 설정
전제 조건:
- 로컬 이미지에는 설치된 Docker Engine 및 사용된 이미지의 로컬 복사본이 있어야 합니다.
풀 정책을 never
로 설정하면 이미지 풀을 비활성화합니다. 사용자는 러너가 실행되는 Docker 호스트에서 매뉴얼으로 가져온 이미지만 사용할 수 있습니다.
다음과 같은 경우 never
풀 정책을 사용하세요:
- 러너 사용자가 사용하는 이미지를 제어해야 하는 경우
- 특정 레지스트리에 공개적으로 사용 가능하지 않은 특정 이미지만 사용할 수 있는 프로젝트에 전용으로 구성된 프라이빗 러너의 경우
다음의 경우 never
풀 정책을 사용하지 마십시오:
-
자동 스케일된 Docker executor에 대해
never
풀 정책을 설정하지 마십시오.never
풀 정책은 특정 클라우드 제공업체용 미리 정의된 클라우드 인스턴스 이미지를 사용할 때만 사용할 수 있습니다.
config.toml
에서 never
정책을 설정하세요:
[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
pull_policy = "never"
여러 풀 정책 설정
- GitLab Runner 13.8에서 도입.
만일 이미지 풀이 실패한 경우 실행할 여러 풀 정책을 디렉터리으로 나열할 수 있습니다. 러너는 디렉터리에 나열된 순서대로 풀 정책을 처리하며 풀 시도가 성공하거나 디렉터리이 고갈될 때까지 진행합니다. 예를 들어, 러너가 always
풀 정책을 사용하고 레지스트리에 액세스할 수 없는 경우 두 번째 풀 정책으로 if-not-present
를 추가하여 로컬에 캐시된 Docker 이미지를 사용할 수 있습니다.
이 풀 정책에 대한 보안적인 문제에 대한 자세한 정보는 프라이빗 Docker 이미지의 if-not-present 풀 정책 사용을 참조하세요.
여러 풀 정책을 config.toml
에 디렉터리으로 추가하세요:
[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
pull_policy = ["always", "if-not-present"]
Docker 풀 정책 허용
- GitLab 15.1에서 도입.
.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
파일에 있는 재시도 지시문과 유사하지만,
특별히 Docker 풀이 처음에 실패하는 경우에만 효과가 있습니다.
Windows 컨테이너 사용하기
- 소개됨 in GitLab Runner 11.11.
Docker Executor로 Windows 컨테이너를 사용하려면 제한 사항, 지원되는 Windows 버전 및 Windows Docker Executor 구성에 대한 다음 정보를 참고하세요.
Nanoserver 지원
Windows 보조 이미지에서 PowerShell Core 지원이 추가되어 이제 보조 이미지의 nanoserver
변형을 활용할 수 있습니다.
Windows에서 Docker Executor의 제한 사항
다음은 Docker Executor를 사용할 때 Windows 컨테이너의 일부 제한 사항입니다:
- Docker-in-Docker는 Docker 자체가 지원하지 않기 때문에 지원되지 않습니다.
- 대화식 Web 터미널은 지원되지 않습니다.
- 호스트 장치 장착은 지원되지 않습니다.
- 볼륨 디렉터리를 장착할 때 해당 디렉터리가 있어야 하며, 그렇지 않으면 Docker가 컨테이너를 시작하지 못합니다. 추가 세부 사항은 #3754를 참조하세요.
-
docker-windows
Executor는 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 버전에 대해서는 미래 버전 지원 정책을 갖고 있습니다.
GitLab Runner를 실행 중인 Windows와 동일한 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가 Windows Server 버전을 확인하기 위해 Docker를 사용하기 때문입니다.
GitLab Runner와 함께 작동하지 않는 알려진 Docker 버전은 Docker 17.06
입니다.
Docker가 Windows Server 버전을 식별하지 못하여 다음과 같은 오류가 발생합니다:
지원되지 않는 Windows 버전: Windows Server Datacenter
Windows Docker Executor 구성
아래는 Windows에서 실행되는 간단한 Docker Executor 구성의 예시입니다.
[[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 Executor의 다른 구성 옵션에 대한 자세한 정보는 고급 구성 섹션을 확인하세요.
서비스
GitLab Runner 12.9부터, 각 작업을 위한 네트워크를 생성하여 서비스를 사용할 수 있습니다.