# Building Docker images with GitLab CI/CD

> 原文：[https://docs.gitlab.com/ee/ci/docker/using_docker_build.html](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html)

*   [Runner Configuration](#runner-configuration)
    *   [Use shell executor](#use-shell-executor)
    *   [Use Docker-in-Docker workflow with Docker executor](#use-docker-in-docker-workflow-with-docker-executor)
        *   [TLS enabled](#tls-enabled)
        *   [TLS disabled](#tls-disabled)
    *   [Use Docker socket binding](#use-docker-socket-binding)
*   [Making Docker-in-Docker builds faster with Docker layer caching](#making-docker-in-docker-builds-faster-with-docker-layer-caching)
    *   [How Docker caching works](#how-docker-caching-works)
    *   [Using Docker caching](#using-docker-caching)
*   [Use the OverlayFS driver](#use-the-overlayfs-driver)
    *   [Requirements](#requirements)
    *   [Use the OverlayFS driver per project](#use-the-overlayfs-driver-per-project)
    *   [Use the OverlayFS driver for every project](#use-the-overlayfs-driver-for-every-project)
*   [Using the GitLab Container Registry](#using-the-gitlab-container-registry)
*   [Troubleshooting](#troubleshooting)
    *   [`docker: Cannot connect to the Docker daemon at tcp://docker:2375\. Is the docker daemon running?`](#docker-cannot-connect-to-the-docker-daemon-at-tcpdocker2375-is-the-docker-daemon-running)

# Building Docker images with GitLab CI/CD[](#building-docker-images-with-gitlab-cicd "Permalink")

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[](#runner-configuration "Permalink")

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

[使用 docker](using_kaniko.html) `docker build`的替代方法是[使用 kaniko](using_kaniko.html) . 这避免了必须在特权模式下执行 Runner.

**提示：**要了解如何在 GitLab.com 上为共享的 Runner 配置 Docker 和 Runner，请参阅[GitLab.com 的共享的 Runners](../../user/gitlab_com/index.html#shared-runners) .

### Use shell executor[](#use-shell-executor "Permalink")

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

1.  Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/#installation).

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 的更多信息，请查看[支持的安装](https://s0docs0docker0com.icopy.site/engine/installation/) .

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 认为是有害的](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful) .

### Use Docker-in-Docker workflow with Docker executor[](#use-docker-in-docker-workflow-with-docker-executor "Permalink")

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

**注意：** `docker-compose`不是 Docker-in-Docker（dind）的一部分. 要在 CI 构建中使用`docker-compose` ，请遵循`docker-compose` [安装说明](https://s0docs0docker0com.icopy.site/compose/install/) .**危险：**通过启用`--docker-privileged` ，可以有效地禁用容器的所有安全机制，并使主机暴露于特权升级之下，这可能导致容器突破. 有关更多信息，请查看有关[运行时特权和 Linux 功能](https://s0docs0docker0com.icopy.site/engine/reference/run/)的官方 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 驱动程序](#use-the-overlayfs-driver) .
*   由于`docker:19.03.12-dind`容器和 Runner 容器不共享其根文件系统，因此作业的工作目录可用作子容器的安装点. 例如，如果您有要与子容器共享的文件，则可以在`/builds/$CI_PROJECT_PATH`下创建一个子目录，并将其用作安装点（有关更详尽的解释，请[参见问题＃41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227) ）：

    ```
    variables:
      MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt

    script:
      - mkdir -p "$MOUNT_POINT"
      - docker run -v "$MOUNT_POINT:/mnt" my-docker-image 
    ```

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

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

#### TLS enabled[](#tls-enabled "Permalink")

**注意：**需要 GitLab Runner 11.11 或更高版本，但是如果使用[Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html)安装了 GitLab Runner，则不支持. 有关详细信息，请参见[相关问题](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) .

Docker 守护程序支持通过 TLS 的连接，默认情况下，对于 Docker 19.03.12 或更高版本，它已完成. 这是使用 Docker-in-Docker 服务的**建议**方法， [GitLab.com 共享运行程序](../../user/gitlab_com/index.html#shared-runners)支持此方法.

1.  Install [GitLab Runner](https://docs.gitlab.com/runner/install/).

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](https://www.docker.com/blog/docker-can-now-run-within-docker/)模式，则始终必须在 Docker 容器中使用`privileged = true` .

    这还将为服务安装`/certs/client`并构建容器，这是 Docker 客户端使用该目录内的证书所必需的. 有关更多信息，请参阅[https://hub.docker.com/_/docker/#tls](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-disabled "Permalink")

有时出于某些合理原因，您可能想要禁用 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[](#use-docker-socket-binding "Permalink")

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

**注意：**如果[在使用 GitLab Runner 11.11 或更高版本时](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261)绑定 Docker 套接字，则不能再将`docker:19.03.12-dind`用作服务，因为对服务也进行了卷绑定，从而使它们不兼容.

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

1.  Install [GitLab Runner](https://docs.gitlab.com/runner/install/).

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[](#making-docker-in-docker-builds-faster-with-docker-layer-caching "Permalink")

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

### How Docker caching works[](#how-docker-caching-works "Permalink")

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

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

### Using Docker caching[](#using-docker-caching "Permalink")

这是一个`.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[](#use-the-overlayfs-driver "Permalink")

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

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

### Requirements[](#requirements "Permalink")

1.  确保使用最新内核，最好`>= 4.2` .
2.  检查是否已加载`overlay`模块：

    ```
    sudo lsmod | grep overlay 
    ```

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

    ```
    sudo modprobe overlay 
    ```

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

    ```
    overlay 
    ```

### Use the OverlayFS driver per project[](#use-the-overlayfs-driver-per-project "Permalink")

您可以使用`.gitlab-ci.yml`的`DOCKER_DRIVER`环境[变量](../yaml/README.html#variables)分别为每个项目启用驱动程序：

```
variables:
  DOCKER_DRIVER: overlay2 
```

### Use the OverlayFS driver for every project[](#use-the-overlayfs-driver-for-every-project "Permalink")

如果使用自己的[GitLab Runners](https://docs.gitlab.com/runner/) ，则可以通过在[`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)的[`[[runners]]`部分中](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)设置`DOCKER_DRIVER`环境变量来为每个项目启用驱动程序：

```
environment = ["DOCKER_DRIVER=overlay2"] 
```

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

**注意：**阅读有关[Runner 配置](https://docs.gitlab.com/runner/configuration/)和[使用 OverlayFS 存储驱动程序的更多信息](https://s0docs0docker0com.icopy.site/engine/userguide/storagedriver/overlayfs-driver/) .

## Using the GitLab Container Registry[](#using-the-gitlab-container-registry "Permalink")

构建 Docker 映像后，可以将其推送到内置的[GitLab Container Registry 中](../../user/packages/container_registry/index.html#build-and-push-images-using-gitlab-cicd) .

## Troubleshooting[](#troubleshooting "Permalink")

### `docker: Cannot connect to the Docker daemon at tcp://docker:2375\. Is the docker daemon running?`[](#docker-cannot-connect-to-the-docker-daemon-at-tcpdocker2375-is-the-docker-daemon-running "Permalink")

[在 Docker](#use-docker-in-docker-workflow-with-docker-executor) v19.03 或更高版本中使用[Docker](#use-docker-in-docker-workflow-with-docker-executor)时，这是一个常见错误.

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

*   这是第一次设置，请[在 Docker 工作流程中使用 Docker](#use-docker-in-docker-workflow-with-docker-executor)仔细阅读.
*   您要从 v18.09 或更早版本[升级](https://about.gitlab.com/releases/2019/07/31/docker-in-docker-with-docker-19-dot-03/) ，请阅读我们的[升级指南](https://about.gitlab.com/releases/2019/07/31/docker-in-docker-with-docker-19-dot-03/) .