Building Docker images with GitLab CI/CD

原文：https://docs.gitlab.com/ee/ci/docker/using_docker_build.html

• Runner Configuration
  • Use shell executor
  • Use Docker-in-Docker workflow with Docker executor
    • TLS enabled
    • TLS disabled
  • Use Docker socket binding
• Making Docker-in-Docker builds faster with Docker layer caching
  • How Docker caching works
  • Using Docker caching
• Use the OverlayFS driver
  • Requirements
  • Use the OverlayFS driver per project
  • Use the OverlayFS driver for every project
• Using the GitLab Container Registry
• Troubleshooting
  • docker: Cannot connect to the Docker daemon at tcp://docker:2375\. Is the docker daemon running?

Building Docker images with GitLab CI/CD

GitLab CI / CD 允许您使用 Docker Engine 来构建和测试基于 Docker 的项目.

持续集成/部署中的新趋势之一是：

1. Create an application image.
2. 针对创建的图像运行测试.
3. 将映像推送到远程注册表.
4. 从推送的映像部署到服务器.

当您的应用程序已经具有可用于创建和测试映像的Dockerfile ，它也很有用：

docker build -t my-image dockerfiles/
docker run my-image /script/to/run/tests
docker tag my-image my-registry:5000/my-image
docker push my-registry:5000/my-image

这需要对 GitLab Runner 进行特殊配置才能在作业期间启用docker支持.

Runner Configuration

有三种方法可在作业期间启用docker build和docker run的使用： 每个都有自己的权衡.

使用 docker docker build的替代方法是使用 kaniko . 这避免了必须在特权模式下执行 Runner.

提示：要了解如何在 GitLab.com 上为共享的 Runner 配置 Docker 和 Runner，请参阅GitLab.com 的共享的 Runners .

Use shell executor

最简单的方法是在shell执行模式下安装 GitLab Runner. 然后，GitLab Runner 以gitlab-runner用户身份执行作业脚本.

1. Install GitLab Runner.

2. 在 GitLab Runner 安装过程中，选择shell作为执行作业脚本的方法或使用命令：

   sudo gitlab-runner register -n \
     --url https://gitlab.com/ \
     --registration-token REGISTRATION_TOKEN \
     --executor shell \
     --description "My Runner"

3. 在服务器上安装 Docker Engine.

   有关如何在不同系统上安装 Docker Engine 的更多信息，请查看支持的安装 .

4. Add gitlab-runner user to docker group:

   sudo usermod -aG docker gitlab-runner

5. 确认gitlab-runner有权访问 Docker：

   sudo -u gitlab-runner -H docker info

   现在，您可以通过将.gitlab-ci.yml docker info添加到.gitlab-ci.yml来验证一切正常：

   before_script:
     - docker info
   build_image:
     script:
       - docker build -t my-docker-image .
       - docker run my-docker-image /script/to/run/tests

6. 您现在可以使用docker命令（并在需要时安装 docker-compose ）.

注：通过添加gitlab-runner的docker您可以有效地授予组gitlab-runner完整的 root 权限. 有关更多信息，请阅读关于 Docker 安全性： docker group 认为是有害的 .

Use Docker-in-Docker workflow with Docker executor

第二种方法是使用特殊泊坞窗功能于泊坞（DIND） 泊坞窗图像安装（所有工具docker ），并在特权模式图像的上下文中运行作业脚本.

注意： docker-compose不是 Docker-in-Docker（dind）的一部分. 要在 CI 构建中使用docker-compose ，请遵循docker-compose 安装说明 .危险：通过启用--docker-privileged ，可以有效地禁用容器的所有安全机制，并使主机暴露于特权升级之下，这可能导致容器突破. 有关更多信息，请查看有关运行时特权和 Linux 功能的官方 Docker 文档.

Docker-in-Docker 运作良好，是推荐的配置，但并非没有挑战：

• When using Docker-in-Docker, each job is in a clean environment without the past history. Concurrent jobs work fine because every build gets its own instance of Docker engine so they won’t conflict with each other. But this also means that jobs can be slower because there’s no caching of layers.
• 默认情况下，Docker 17.09 及更高版本使用--storage-driver overlay2 ，这是推荐的存储驱动程序. 有关详细信息，请参见使用 overlayfs 驱动程序 .

• 由于docker:19.03.12-dind容器和 Runner 容器不共享其根文件系统，因此作业的工作目录可用作子容器的安装点. 例如，如果您有要与子容器共享的文件，则可以在/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

可在以下位置找到使用此方法的示例项目： https : //gitlab.com/gitlab-examples/docker .

在以下示例中，我们使用 Docker images 标签指定特定版本，例如docker:19.03.12 . 如果使用了诸如docker:stable类的标签，则您将无法控制要使用的版本，这可能导致无法预测的行为，尤其是在发布新版本时.

TLS enabled

注意：需要 GitLab Runner 11.11 或更高版本，但是如果使用Helm chart安装了 GitLab Runner，则不支持. 有关详细信息，请参见相关问题 .

Docker 守护程序支持通过 TLS 的连接，默认情况下，对于 Docker 19.03.12 或更高版本，它已完成. 这是使用 Docker-in-Docker 服务的建议方法， GitLab.com 共享运行程序支持此方法.

1. Install GitLab Runner.

2. 从命令行注册 GitLab Runner 以使用docker和privileged模式：

   sudo gitlab-runner register -n \
     --url https://gitlab.com/ \
     --registration-token REGISTRATION_TOKEN \
     --executor docker \
     --description "My Docker Runner" \
     --docker-image "docker:19.03.12" \
     --docker-privileged \
     --docker-volumes "/certs/client"

   上面的命令将注册一个新的 Runner 以使用由 Docker 提供的特殊docker:19.03.12映像. 注意，它使用privileged模式来启动构建和服务容器. 如果要使用Docker-in-Docker模式，则始终必须在 Docker 容器中使用privileged = true .

   这还将为服务安装/certs/client并构建容器，这是 Docker 客户端使用该目录内的证书所必需的. 有关更多信息，请参阅https://hub.docker.com/_/docker/#tls .

   上面的命令将创建一个类似于以下内容的config.toml条目：

   [[runners]]
     url = "https://gitlab.com/"
     token = TOKEN
     executor = "docker"
     [runners.docker]
       tls_verify = false
       image = "docker:19.03.12"
       privileged = true
       disable_cache = false
       volumes = ["/certs/client", "/cache"]
     [runners.cache]
       [runners.cache.s3]
       [runners.cache.gcs]

3. 您现在可以使用docker在构建脚本（注意列入docker:19.03.12-dind服务）：

   image: docker:19.03.12
   variables:
     # When using dind service, we need to 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/ee/ci/docker/using_docker_images.html#accessing-the-services.
     #
     # Note that if you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier,
     # the variable must be set to tcp://localhost:2376 because of how the
     # Kubernetes executor connects services to the job container
     # DOCKER_HOST: tcp://localhost:2376
     #
     # Specify to Docker where to create the certificates, Docker will
     # create them automatically on boot, and will create
     # `/certs/client` that will be shared between the service and job
     # container, thanks to volume mount from config.toml
     DOCKER_TLS_CERTDIR: "/certs"
   services:
     - docker:19.03.12-dind
   before_script:
     - docker info
   build:
     stage: build
     script:
       - docker build -t my-docker-image .
       - docker run my-docker-image /script/to/run/tests

TLS disabled

有时出于某些合理原因，您可能想要禁用 TLS. 例如，您无法控制所使用的 GitLab Runner 配置.

假设 Runner config.toml类似于：

[[runners]]
  url = "https://gitlab.com/"
  token = TOKEN
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "docker:19.03.12"
    privileged = true
    disable_cache = false
    volumes = ["/cache"]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

您现在可以使用docker在构建脚本（注意列入docker:19.03.12-dind服务）：

image: docker:19.03.12
variables:
  # When using dind service we need to 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/ee/ci/docker/using_docker_images.html#accessing-the-services
  #
  # Note that if you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier,
  # the variable must be set to tcp://localhost:2375 because of how the
  # Kubernetes executor connects services to the job container
  # DOCKER_HOST: tcp://localhost:2375
  #
  DOCKER_HOST: tcp://docker:2375
  #
  # This will instruct Docker not to start over TLS.
  DOCKER_TLS_CERTDIR: ""
services:
  - docker:19.03.12-dind
before_script:
  - docker info
build:
  stage: build
  script:
    - docker build -t my-docker-image .
    - docker run my-docker-image /script/to/run/tests

Use Docker socket binding

第三种方法是将/var/run/docker.sock绑定安装到容器中，以便 Docker 在该映像的上下文中可用.

注意：如果在使用 GitLab Runner 11.11 或更高版本时绑定 Docker 套接字，则不能再将docker:19.03.12-dind用作服务，因为对服务也进行了卷绑定，从而使它们不兼容.

为此，请按照下列步骤操作：

1. Install GitLab Runner.

2. 从命令行注册 GitLab Runner 以使用docker并共享/var/run/docker.sock ：

   sudo gitlab-runner register -n \
     --url https://gitlab.com/ \
     --registration-token REGISTRATION_TOKEN \
     --executor docker \
     --description "My Docker Runner" \
     --docker-image "docker:19.03.12" \
     --docker-volumes /var/run/docker.sock:/var/run/docker.sock

   上面的命令将注册一个新的 Runner 以使用由 Docker 提供的特殊docker:19.03.12映像. 请注意，它使用的是 Runner 本身的 Docker 守护进程，并且 Docker 命令产生的任何容器都将是 Runner 的兄弟，而不是 Runner 的子代. 这可能会带来一些不适合您的工作流程的复杂性和局限性.

   上面的命令将创建一个类似于以下内容的config.toml条目：

   [[runners]]
     url = "https://gitlab.com/"
     token = REGISTRATION_TOKEN
     executor = "docker"
     [runners.docker]
       tls_verify = false
       image = "docker:19.03.12"
       privileged = false
       disable_cache = false
       volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
     [runners.cache]
       Insecure = false

3. 您现在可以使用docker在构建脚本（请注意，您不需要包括docker:19.03.12-dind服务泊坞执行使用泊坞时）：

   image: docker:19.03.12
   before_script:
     - docker info
   build:
     stage: build
     script:
       - docker build -t my-docker-image .
       - docker run my-docker-image /script/to/run/tests

尽管上述方法避免在特权模式下使用 Docker，但您应注意以下含义：

• 通过共享 Docker 守护程序，您可以有效地禁用容器的所有安全机制，并使主机暴露于特权升级之下，这可能导致容器突破. 例如，如果一个项目运行docker rm -f $(docker ps -a -q) ，它将删除 GitLab Runner 容器.
• 并发工作可能无法正常工作； 如果您的测试创建了具有特定名称的容器，则它们可能会相互冲突.

• 将源仓库中的文件和目录共享到容器中可能无法正常工作，因为卷安装是在主机而不是构建容器的上下文中完成的. 例如：

   docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests

Making Docker-in-Docker builds faster with Docker layer caching

在使用 Docker-in-Docker 时，每次创建构建时 Docker 都会下载映像的所有层. 最新版本的 Docker（Docker 1.13 及更高版本）可以在 Docker docker build步骤中使用预先存在的映像作为缓存，从而大大加快了构建过程.

How Docker caching works

运行Dockerfile docker build ， Dockerfile中的每个命令Dockerfile一个图层. 这些层保留为高速缓存，如果没有任何更改，可以重复使用. 一层中的更改将导致重新创建所有后续层.

您可以使用--cache-from参数指定标记的图像用作--cache-from docker build命令的缓存源. 可以使用多个--cache-from参数将多个图像指定为缓存源. 请记住，与--cache-from参数一起使用的任何映像都必须先被拉出（使用docker pull ），然后才能用作缓存源.

Using Docker caching

这是一个.gitlab-ci.yml文件，显示了如何使用 Docker 缓存：

image: docker:19.03.12
services:
  - docker:19.03.12-dind
variables:
  # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: "/certs"
before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
build:
  stage: build
  script:
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

build阶段的script部分中的步骤可以总结为：

1. 第一个命令尝试从注册表中提取映像，以便将其用作docker build命令的缓存.
2. 第二个命令使用拉取的映像作为缓存来构建 Docker 映像（请注意--cache-from $CI_REGISTRY_IMAGE:latest参数），并对其进行标记.
3. 最后两个命令将标记的 Docker 映像推送到容器注册表，以便它们也可用作后续构建的缓存.

Use the OverlayFS driver

注意：默认情况下，GitLab.com 上的共享 Runners 使用overlay2驱动程序.

默认情况下，使用docker:dind ，Docker 使用vfs存储驱动程序，该驱动程序会在每次运行时复制文件系统. 这是磁盘密集型操作，如果使用其他驱动程序（例如overlay2 ，则可以避免.

Requirements

1. 确保使用最新内核，最好>= 4.2 .

2. 检查是否已加载overlay模块：

   sudo lsmod | grep overlay

   如果看不到任何结果，则说明未加载. 要加载它，请使用：

   sudo modprobe overlay

   如果一切正常，则需要确保模块在重新启动时已加载. 在 Ubuntu 系统上，这是通过编辑/etc/modules . 只需将以下行添加到其中：

   overlay

Use the OverlayFS driver per project

您可以使用.gitlab-ci.yml的DOCKER_DRIVER环境变量分别为每个项目启用驱动程序：

variables:
  DOCKER_DRIVER: overlay2

Use the OverlayFS driver for every project

如果使用自己的GitLab Runners ，则可以通过在config.toml的[[runners]]部分中设置DOCKER_DRIVER环境变量来为每个项目启用驱动程序：

environment = ["DOCKER_DRIVER=overlay2"]

如果您正在运行多个运行程序，则必须修改所有配置文件.

注意：阅读有关Runner 配置和使用 OverlayFS 存储驱动程序的更多信息 .

Using the GitLab Container Registry

构建 Docker 映像后，可以将其推送到内置的GitLab Container Registry 中 .

Troubleshooting

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

在 Docker v19.03 或更高版本中使用Docker时，这是一个常见错误.

发生这种情况是因为 Docker 自动在 TLS 上启动，因此您需要进行一些设置. 如果：

• 这是第一次设置，请在 Docker 工作流程中使用 Docker仔细阅读.
• 您要从 v18.09 或更早版本升级 ，请阅读我们的升级指南 .