Docker-in-Docker 사용
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
Docker-in-Docker(dind)는 등록된 러너가 Docker executor 또는 Kubernetes executor를 사용한다는 의미입니다. 이 Docker 이미지에는 모든 docker 도구가 포함되어 있으며, 권한 있는(privileged) 모드에서 이미지의 컨텍스트로 작업 스크립트를 실행할 수 있습니다.
Docker-in-Docker(dind)는 등록된 러너가 Docker executor 또는
Kubernetes executor를 사용한다는 의미입니다.
executor는 Docker가 제공하는 Docker 컨테이너 이미지를 사용해 CI/CD 작업을 실행합니다.
이 Docker 이미지에는 모든 docker 도구가 포함되어 있으며,
권한 있는(privileged) 모드에서 이미지의 컨텍스트로 작업 스크립트를 실행할 수 있습니다.
docker:24.0.5처럼 항상 이미지의 특정 버전을 고정합니다.
docker:latest 같은 태그를 사용하면 어떤 버전이 사용되는지 제어할 수 없습니다.
이 경우 새 버전이 출시될 때 호환성 문제가 발생할 수 있습니다.
Docker executor와 함께 사용#
Docker executor를 사용하면 Docker 컨테이너에서 작업을 실행할 수 있습니다.
Docker executor에서 TLS를 활성화한 Docker-in-Docker(권장)#
Docker 데몬은 TLS를 통한 연결을 지원합니다. 가능하면 TLS를 사용합니다. TLS는 Docker 19.03.12 이상에서 기본값이며 GitLab.com 인스턴스 러너에서 지원됩니다.
이 작업은 --docker-privileged를 활성화하며, 이는 컨테이너의 보안 메커니즘을 사실상 비활성화하고 호스트를 권한 상승에
노출합니다. 이 작업은 컨테이너 탈출(container breakout)을 일으킬 수 있습니다. 자세한 내용은
런타임 권한과 Linux capabilities를 참고합니다.
TLS를 활성화한 Docker-in-Docker를 사용하려면 다음을 수행합니다.
-
GitLab Runner를 설치합니다.
-
명령줄에서 GitLab Runner를 등록합니다.
docker와privileged모드를 사용합니다.sudo gitlab-runner register -n \ --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ --tag-list "tls-docker-runner" \ --docker-image "docker:24.0.5-cli" \ --docker-privileged \ --docker-volumes "/certs/client"- 이 명령은 (작업 수준에서 지정하지 않은 경우)
docker:24.0.5-cli이미지를 사용하도록 새 러너를 등록합니다. 빌드 및 서비스 컨테이너를 시작하기 위해privileged모드를 사용합니다. Docker-in-Docker를 사용하려면 Docker 컨테이너에서 항상privileged = true를 사용해야 합니다. - 이 명령은 서비스 및 빌드 컨테이너에
/certs/client를 마운트하며, Docker 클라이언트가 해당 디렉터리의 인증서를 사용하려면 이 마운트가 필요합니다. 자세한 내용은 Docker 이미지 문서를 참고합니다.
앞의 명령은 다음 예시와 비슷한
config.toml항목을 만듭니다.[[runners]] url = "https://gitlab.com/" token = TOKEN executor = "docker" [runners.docker] tls_verify = false image = "docker:24.0.5-cli" privileged = true disable_cache = false volumes = ["/certs/client", "/cache"] [runners.cache] [runners.cache.s3] [runners.cache.gcs] - 이 명령은 (작업 수준에서 지정하지 않은 경우)
-
이제 작업 스크립트에서
docker를 사용할 수 있습니다.docker:24.0.5-dind서비스를 포함합니다.default: image: docker:24.0.5-cli services: - docker:24.0.5-dind before_script: - docker info variables: # When you use the dind service, you must instruct Docker to talk with # the daemon started inside of the service. The daemon is available # with a network connection instead of the default # /var/run/docker.sock socket. Docker 19.03 does this automatically # by setting the DOCKER_HOST in # https://github.com/docker-library/docker/blob/d45051476babc297257df490d22cbd806f1b11e4/19.03/docker-entrypoint.sh#L23-L29 # # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ci/services/#accessing-the-services. # # Specify to Docker where to create the certificates. Docker # creates them automatically on boot, and creates # `/certs/client` to share between the service and job # container, thanks to volume mount from config.toml DOCKER_TLS_CERTDIR: "/certs" build: stage: build tags: - tls-docker-runner script: - docker build -t my-docker-image . - docker run my-docker-image /script/to/run/tests
Docker executor에서 TLS를 비활성화한 Docker-in-Docker#
TLS를 비활성화해야 하는 합당한 이유가 있는 경우가 있습니다. 예를 들어 사용 중인 GitLab Runner 구성을 제어할 수 없는 경우입니다.
-
명령줄에서 GitLab Runner를 등록합니다.
docker와privileged모드를 사용합니다.sudo gitlab-runner register -n \ --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ --tag-list "no-tls-docker-runner" \ --docker-image "docker:24.0.5-cli" \ --docker-privileged앞의 명령은 다음 예시와 비슷한
config.toml항목을 만듭니다.[[runners]] url = "https://gitlab.com/" token = TOKEN executor = "docker" [runners.docker] tls_verify = false image = "docker:24.0.5-cli" privileged = true disable_cache = false volumes = ["/cache"] [runners.cache] [runners.cache.s3] [runners.cache.gcs] -
작업 스크립트에
docker:24.0.5-dind서비스를 포함합니다.default: image: docker:24.0.5-cli services: - docker:24.0.5-dind before_script: - docker info variables: # When using dind service, you must instruct docker to talk with the # daemon started inside of the service. The daemon is available with # a network connection instead of the default /var/run/docker.sock socket. # # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ci/services/#accessing-the-services # DOCKER_HOST: tcp://docker:2375 # # This instructs Docker not to start over TLS. DOCKER_TLS_CERTDIR: "" build: stage: build tags: - no-tls-docker-runner script: - docker build -t my-docker-image . - docker run my-docker-image /script/to/run/tests
Docker-in-Docker와 빌드 컨테이너 사이의 공유 볼륨에서 Unix 소켓 사용#
Docker executor에서 TLS를 활성화한 Docker-in-Docker
방식에서 volumes = ["/certs/client", "/cache"]로 정의한 디렉터리는
빌드 간에 유지됩니다.
Docker executor 러너를 사용하는 여러 CI/CD 작업에서 Docker-in-Docker 서비스를 활성화하면 각 작업이
같은 디렉터리 경로에 씁니다. 이 방식은 충돌을 일으킬 수 있습니다.
이 충돌을 해결하려면 Docker-in-Docker 서비스와 빌드 컨테이너 사이에 공유되는 볼륨의 Unix 소켓을 사용합니다. 이 방식은 성능을 개선하고 서비스와 클라이언트 사이에 보안 연결을 구축합니다.
다음은 빌드 컨테이너와 서비스 컨테이너 사이에 공유되는 임시 볼륨을 사용하는 config.toml 예시입니다.
[[runners]]
url = "https://gitlab.com/"
token = TOKEN
executor = "docker"
[runners.docker]
image = "docker:24.0.5-cli"
privileged = true
volumes = ["/runner/services/docker"] # Temporary volume shared between build and service containers.
Docker-in-Docker 서비스가 docker.sock을 만듭니다. Docker 클라이언트는 Docker Unix 소켓 볼륨을 통해 docker.sock에 연결합니다.
job:
variables:
# This variable is shared by both the DinD service and Docker client.
# For the service, it will instruct DinD to create `docker.sock` here.
# For the client, it tells the Docker client which Docker Unix socket to connect to.
DOCKER_HOST: "unix:///runner/services/docker/docker.sock"
services:
- docker:24.0.5-dind
image: docker:24.0.5-cli
script:
- docker version
Docker executor에서 프록시를 활성화한 Docker-in-Docker#
docker push 명령을 사용하려면 프록시 설정을 구성해야 할 수 있습니다.
자세한 내용은 dind 서비스를 사용할 때의 프록시 설정을 참고합니다.
Kubernetes executor와 함께 사용#
Kubernetes executor를 사용하면 Docker 컨테이너에서 작업을 실행할 수 있습니다.
Kubernetes에서 TLS를 활성화한 Docker-in-Docker(권장)#
Kubernetes에서 TLS를 활성화한 Docker-in-Docker를 사용하려면 다음을 수행합니다.
-
Helm 차트를 사용해
values.yml파일을 업데이트하여 볼륨 마운트를 지정합니다.runners: tags: "tls-dind-kubernetes-runner" config: | [[runners]] [runners.kubernetes] image = "ubuntu:20.04" privileged = true [[runners.kubernetes.volumes.empty_dir]] name = "docker-certs" mount_path = "/certs/client" medium = "Memory" -
작업에
docker:24.0.5-dind서비스를 포함합니다.default: image: docker:24.0.5-cli services: - name: docker:24.0.5-dind variables: HEALTHCHECK_TCP_PORT: "2376" before_script: - docker info variables: # When using dind service, you must instruct Docker to talk with # the daemon started inside of the service. The daemon is available # with a network connection instead of the default # /var/run/docker.sock socket. DOCKER_HOST: tcp://docker:2376 # # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ci/services/#accessing-the-services. # # Specify to Docker where to create the certificates. Docker # creates them automatically on boot, and creates # `/certs/client` to share between the service and job # container, thanks to volume mount from config.toml DOCKER_TLS_CERTDIR: "/certs" # These are usually specified by the entrypoint, however the # Kubernetes executor doesn't run entrypoints # https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4125 DOCKER_TLS_VERIFY: 1 DOCKER_CERT_PATH: "$DOCKER_TLS_CERTDIR/client" build: stage: build tags: - tls-dind-kubernetes-runner script: - docker build -t my-docker-image . - docker run my-docker-image /script/to/run/tests
Kubernetes에서 TLS를 비활성화한 Docker-in-Docker#
Kubernetes에서 TLS를 비활성화한 Docker-in-Docker를 사용하려면 앞의 예시를 다음과 같이 수정해야 합니다.
values.yml파일에서[[runners.kubernetes.volumes.empty_dir]]섹션을 제거합니다.DOCKER_HOST: tcp://docker:2375로 포트를2376에서2375로 변경합니다.DOCKER_TLS_CERTDIR: ""로 Docker가 TLS를 비활성화한 상태로 시작하도록 지정합니다.
예를 들면 다음과 같습니다.
-
Helm 차트를 사용해
values.yml파일을 업데이트합니다.runners: tags: "no-tls-dind-kubernetes-runner" config: | [[runners]] [runners.kubernetes] image = "ubuntu:20.04" privileged = true -
이제 작업 스크립트에서
docker를 사용할 수 있습니다.docker:24.0.5-dind서비스를 포함합니다.default: image: docker:24.0.5-cli services: - name: docker:24.0.5-dind variables: HEALTHCHECK_TCP_PORT: "2375" before_script: - docker info variables: # When using dind service, you must instruct Docker to talk with # the daemon started inside of the service. The daemon is available # with a network connection instead of the default # /var/run/docker.sock socket. DOCKER_HOST: tcp://docker:2375 # # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ci/services/#accessing-the-services. # # This instructs Docker not to start over TLS. DOCKER_TLS_CERTDIR: "" build: stage: build tags: - no-tls-dind-kubernetes-runner script: - docker build -t my-docker-image . - docker run my-docker-image /script/to/run/tests
Docker-in-Docker의 알려진 문제#
Docker-in-Docker는 권장되는 구성이지만 다음 문제를 알아 두어야 합니다.
-
docker-compose명령: 이 구성에서는 기본적으로 이 명령을 사용할 수 없습니다. 작업 스크립트에서docker-compose를 사용하려면 Docker Compose 설치 지침을 따릅니다. -
캐시: 각 작업은 새 환경에서 실행됩니다. 모든 빌드가 Docker 엔진의 자체 인스턴스를 사용하므로 동시 작업이 충돌을 일으키지 않습니다. 하지만 레이어 캐시가 없어 작업이 더 느려질 수 있습니다. Docker 레이어 캐싱을 참고합니다.
-
스토리지 드라이버: 기본적으로 이전 버전의 Docker는 작업마다 파일 시스템을 복사하는
vfs스토리지 드라이버를 사용합니다. Docker 17.09 이상은 권장 스토리지 드라이버인--storage-driver overlay2를 사용합니다. 자세한 내용은 OverlayFS 드라이버 사용을 참고합니다. -
루트 파일 시스템:
docker:24.0.5-dind컨테이너와 러너 컨테이너는 루트 파일 시스템을 공유하지 않으므로 작업의 작업 디렉터리를 하위 컨테이너의 마운트 지점으로 사용할 수 있습니다. 예를 들어 하위 컨테이너와 공유하려는 파일이 있으면/builds/$CI_PROJECT_PATH아래에 하위 디렉터리를 만들어 마운트 지점으로 사용할 수 있습니다. 더 자세한 설명은 이슈 #41227을 참고합니다.variables: MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt script: - mkdir -p "$MOUNT_POINT" - docker run -v "$MOUNT_POINT:/mnt" my-docker-image