diff options
Diffstat (limited to 'doc/ci/docker')
-rw-r--r-- | doc/ci/docker/authenticate_registry.md | 144 | ||||
-rw-r--r-- | doc/ci/docker/docker_layer_caching.md | 61 | ||||
-rw-r--r-- | doc/ci/docker/index.md | 1 | ||||
-rw-r--r-- | doc/ci/docker/using_docker_build.md | 361 | ||||
-rw-r--r-- | doc/ci/docker/using_kaniko.md | 4 |
5 files changed, 292 insertions, 279 deletions
diff --git a/doc/ci/docker/authenticate_registry.md b/doc/ci/docker/authenticate_registry.md new file mode 100644 index 00000000000..224d0cdf7aa --- /dev/null +++ b/doc/ci/docker/authenticate_registry.md @@ -0,0 +1,144 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: concepts, howto +--- + +# Authenticate with registry in Docker-in-Docker + +When you use Docker-in-Docker, the +[standard authentication methods](using_docker_images.md#access-an-image-from-a-private-container-registry) +do not work, because a fresh Docker daemon is started with the service. + +## Option 1: Run `docker login` + +In [`before_script`](../yaml/index.md#before_script), run `docker +login`: + +```yaml +image: docker:20.10.16 + +variables: + DOCKER_TLS_CERTDIR: "/certs" + +services: + - docker:20.10.16-dind + +build: + stage: build + before_script: + - echo "$DOCKER_REGISTRY_PASS" | docker login $DOCKER_REGISTRY --username $DOCKER_REGISTRY_USER --password-stdin + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +To sign in to Docker Hub, leave `$DOCKER_REGISTRY` +empty or remove it. + +## Option 2: Mount `~/.docker/config.json` on each job + +If you are an administrator for GitLab Runner, you can mount a file +with the authentication configuration to `~/.docker/config.json`. +Then every job that the runner picks up is already authenticated. If you +are using the official `docker:20.10.16` image, the home directory is +under `/root`. + +If you mount the configuration file, any `docker` command +that modifies the `~/.docker/config.json` fails. For example, `docker login` +fails, because the file is mounted as read-only. Do not change it from +read-only, because this causes problems. + +Here is an example of `/opt/.docker/config.json` that follows the +[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determine-your-docker_auth_config-data) +documentation: + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } +} +``` + +### Docker + +Update the +[volume mounts](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section) +to include the file. + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/opt/.docker/config.json:/root/.docker/config.json:ro"] +``` + +### Kubernetes + +Create a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with the content +of this file. You can do this with a command like: + +```shell +kubectl create configmap docker-client-config --namespace gitlab-runner --from-file /opt/.docker/config.json +``` + +Update the [volume mounts](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes) +to include the file. + +```toml +[[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "docker-client-config" + mount_path = "/root/.docker/config.json" + # If you are running GitLab Runner 13.5 + # or lower you can remove this + sub_path = "config.json" +``` + +## Option 3: Use `DOCKER_AUTH_CONFIG` + +If you already have +[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determine-your-docker_auth_config-data) +defined, you can use the variable and save it in +`~/.docker/config.json`. + +You can define this authentication in several ways: + +- In [`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) + in the runner configuration file. +- In [`before_script`](../yaml/index.md#before_script). +- In [`script`](../yaml/index.md#script). + +The following example shows [`before_script`](../yaml/index.md#before_script). +The same commands apply for any solution you implement. + +```yaml +image: docker:20.10.16 + +variables: + DOCKER_TLS_CERTDIR: "/certs" + +services: + - docker:20.10.16-dind + +build: + stage: build + before_script: + - mkdir -p $HOME/.docker + - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` diff --git a/doc/ci/docker/docker_layer_caching.md b/doc/ci/docker/docker_layer_caching.md new file mode 100644 index 00000000000..145ead9a212 --- /dev/null +++ b/doc/ci/docker/docker_layer_caching.md @@ -0,0 +1,61 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: concepts, howto +--- + +# Make Docker-in-Docker builds faster with Docker layer caching + +When using Docker-in-Docker, Docker downloads all layers of your image every +time you create a build. Recent versions of Docker (Docker 1.13 and later) can +use a pre-existing image as a cache during the `docker build` step. This significantly +accelerates the build process. + +## How Docker caching works + +When running `docker build`, each command in `Dockerfile` creates a layer. +These layers are retained as a cache and can be reused if there have been no changes. Change in one layer causes the recreation of all subsequent layers. + +To specify a tagged image to be used as a cache source for the `docker build` +command, use the `--cache-from` argument. Multiple images can be specified +as a cache source by using multiple `--cache-from` arguments. Any image that's used +with the `--cache-from` argument must be pulled +(using `docker pull`) before it can be used as a cache source. + +## Docker caching example + +This example `.gitlab-ci.yml` file shows how to use Docker caching: + +```yaml +image: docker:20.10.16 + +services: + - docker:20.10.16-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 +``` + +In the `script` section for the `build` stage: + +1. The first command tries to pull the image from the registry so that it can be + used as a cache for the `docker build` command. +1. The second command builds a Docker image by using the pulled image as a + cache (see the `--cache-from $CI_REGISTRY_IMAGE:latest` argument) if + available, and tags it. +1. The last two commands push the tagged Docker images to the container registry + so that they can also be used as cache for subsequent builds. diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index e976700c160..162d67286ad 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -comments: false type: index --- diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index a8c192dc944..fe57b451146 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -9,12 +9,12 @@ type: concepts, howto You can use GitLab CI/CD with Docker to create Docker images. For example, you can create a Docker image of your application, -test it, and publish it to a container registry. +test it, and push it to a container registry. To run Docker commands in your CI/CD jobs, you must configure -GitLab Runner to support `docker` commands. +GitLab Runner to support `docker` commands. This method requires `privileged` mode. -If you want to build Docker images without enabling privileged mode on the runner, +If you want to build Docker images without enabling `privileged` mode on the runner, you can use a [Docker alternative](#docker-alternatives). ## Enable Docker commands in your CI/CD jobs @@ -23,7 +23,7 @@ To enable Docker commands for your CI/CD jobs, you can use: - [The shell executor](#use-the-shell-executor) - [Docker-in-Docker](#use-docker-in-docker) -- [Docker socket binding](#use-docker-socket-binding) +- [Docker socket binding](#use-the-docker-executor-with-docker-socket-binding) ### Use the shell executor @@ -58,7 +58,7 @@ the Docker commands, but needs permission to do so. sudo -u gitlab-runner -H docker info ``` -1. In GitLab, to verify that everything works, add `docker info` to `.gitlab-ci.yml`: +1. In GitLab, add `docker info` to `.gitlab-ci.yml` to verify that Docker is working: ```yaml before_script: @@ -70,10 +70,10 @@ the Docker commands, but needs permission to do so. - docker run my-docker-image /script/to/run/tests ``` -You can now use `docker` commands (and install `docker-compose` if needed). +You can now use `docker` commands (and install Docker Compose if needed). -When you add `gitlab-runner` to the `docker` group, you are effectively granting `gitlab-runner` full root permissions. -For more information, see the [security of the `docker` group](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). +When you add `gitlab-runner` to the `docker` group, you effectively grant `gitlab-runner` full root permissions. +For more information, see [security of the `docker` group](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). ### Use Docker-in-Docker @@ -83,15 +83,15 @@ For more information, see the [security of the `docker` group](https://blog.zopy - The executor uses a [container image of Docker](https://hub.docker.com/_/docker/), provided by Docker, to run your CI/CD jobs. -The Docker image has all of the `docker` tools installed and can run +The Docker image includes all of the `docker` tools and can run the job script in context of the image in privileged mode. -We recommend you use Docker-in-Docker with TLS enabled, +You should use Docker-in-Docker with TLS enabled, which is supported by [GitLab.com shared runners](../runners/index.md). -You should always specify a specific version of the image, like `docker:20.10.16`. +You should always pin a specific version of the image, like `docker:20.10.16`. If you use a tag like `docker:stable`, you have no control over which version is used. -Unpredictable behavior can result, especially when new versions are released. +This can cause incompatibility problems when new versions are released. #### Use the Docker executor with Docker-in-Docker @@ -101,14 +101,11 @@ You can use the Docker executor to run jobs in a Docker container. > Introduced in GitLab Runner 11.11. -The Docker daemon supports connections over TLS. In Docker 19.03.12 and later, -TLS is the default. +The Docker daemon supports connections over TLS. TLS is the default in Docker 19.03.12 and later. WARNING: -This task enables `--docker-privileged`. When you do this, you are effectively disabling all of -the security mechanisms of containers and exposing your host to privilege -escalation. Doing this can lead to container breakout. For more information, -see the official Docker documentation about +This task enables `--docker-privileged`, which effectively disables the container's security mechanisms and exposes your host to privilege +escalation. This action can cause container breakout. For more information, see [runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). To use Docker-in-Docker with TLS enabled: @@ -134,10 +131,9 @@ To use Docker-in-Docker with TLS enabled: you must always use `privileged = true` in your Docker containers. - This command mounts `/certs/client` for the service and build container, which is needed for the Docker client to use the - certificates in that directory. For more information on how - Docker with TLS works, see <https://hub.docker.com/_/docker/#tls>. + certificates in that directory. For more information, see [the Docker image documentation](https://hub.docker.com/_/docker/). - The previous command creates a `config.toml` entry similar to this: + The previous command creates a `config.toml` entry similar to the following example: ```toml [[runners]] @@ -155,7 +151,7 @@ To use Docker-in-Docker with TLS enabled: [runners.cache.gcs] ``` -1. You can now use `docker` in the job script. Note the inclusion of the +1. You can now use `docker` in the job script. You should include the `docker:20.10.16-dind` service: ```yaml @@ -193,7 +189,7 @@ To use Docker-in-Docker with TLS enabled: ##### Docker-in-Docker with TLS disabled in the Docker executor -Sometimes you might have legitimate reasons to disable TLS. +Sometimes there are legitimate reasons to disable TLS. For example, you have no control over the GitLab Runner configuration that you are using. @@ -215,7 +211,7 @@ Assuming that the runner's `config.toml` is similar to: [runners.cache.gcs] ``` -You can now use `docker` in the job script. Note the inclusion of the +You can now use `docker` in the job script. You should include the `docker:20.10.16-dind` service: ```yaml @@ -254,7 +250,7 @@ build: #### Use the Kubernetes executor with Docker-in-Docker -You can use the Kubernetes executor to run jobs in a Docker container. +You can use the [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html) to run jobs in a Docker container. ##### Docker-in-Docker with TLS enabled in Kubernetes @@ -280,7 +276,7 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: medium = "Memory" ``` -1. You can now use `docker` in the job script. Note the inclusion of the +1. You can now use `docker` in the job script. You should include the `docker:20.10.16-dind` service: ```yaml @@ -324,25 +320,23 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: - docker run my-docker-image /script/to/run/tests ``` -#### Limitations of Docker-in-Docker +#### Known issues with Docker-in-Docker -Docker-in-Docker is the recommended configuration, but is -not without its own challenges: +Docker-in-Docker is the recommended configuration, but you should be aware of the following issues: - **The `docker-compose` command**: This command is not available in this configuration by default. - To use `docker-compose` in your job scripts, follow the `docker-compose` + To use `docker-compose` in your job scripts, follow the Docker Compose [installation instructions](https://docs.docker.com/compose/install/). -- **Cache**: Each job runs in a new environment. Concurrent jobs work fine, - because every build gets its own instance of Docker engine and they don't conflict with each other. - However, jobs can be slower because there's no caching of layers. +- **Cache**: Each job runs in a new environment. Because every build gets its own instance of the Docker engine, concurrent jobs do not cause conflicts. + However, jobs can be slower because there's no caching of layers. See [Docker layer caching](#make-docker-in-docker-builds-faster-with-docker-layer-caching). - **Storage drivers**: By default, earlier versions of Docker use the `vfs` storage driver, which copies the file system for each job. Docker 17.09 and later use `--storage-driver overlay2`, which is the recommended storage driver. See [Using the OverlayFS driver](#use-the-overlayfs-driver) for details. -- **Root file system**: Because the `docker:20.10.16-dind` container and the runner container don't share their +- **Root file system**: Because the `docker:20.10.16-dind` container and the runner container do not share their root file system, you can use the job's working directory as a mount point for child containers. For example, if you have files you want to share with a - child container, you might create a subdirectory under `/builds/$CI_PROJECT_PATH` - and use it as your mount point. For a more detailed explanation, view + child container, you could create a subdirectory under `/builds/$CI_PROJECT_PATH` + and use it as your mount point. For a more detailed explanation, see [issue #41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227). ```yaml @@ -353,7 +347,7 @@ not without its own challenges: - docker run -v "$MOUNT_POINT:/mnt" my-docker-image ``` -### Use Docker socket binding +### Use the Docker executor with Docker socket binding To use Docker commands in your CI/CD jobs, you can bind-mount `/var/run/docker.sock` into the container. Docker is then available in the context of the image. @@ -362,16 +356,14 @@ NOTE: If you bind the Docker socket and you are [using GitLab Runner 11.11 or later](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261), you can no longer use `docker:20.10.16-dind` as a service. Volume bindings -are done to the services as well, making these incompatible. - -#### Use the Docker executor with Docker socket binding +also affect services, making them incompatible. To make Docker available in the context of the image, you need to mount `/var/run/docker.sock` into the launched containers. To do this with the Docker -executor, you need to add `"/var/run/docker.sock:/var/run/docker.sock"` to the +executor, add `"/var/run/docker.sock:/var/run/docker.sock"` to the [Volumes in the `[runners.docker]` section](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). -Your configuration should look something like this: +Your configuration should look similar to this example: ```toml [[runners]] @@ -388,7 +380,7 @@ Your configuration should look something like this: Insecure = false ``` -You can also do this while registering your runner by providing the following options: +To mount `/var/run/docker.sock` while registering your runner, include the following options: ```shell sudo gitlab-runner register -n \ @@ -400,14 +392,14 @@ sudo gitlab-runner register -n \ --docker-volumes /var/run/docker.sock:/var/run/docker.sock ``` -##### Enable registry mirror for `docker:dind` service +#### Enable registry mirror for `docker:dind` service -When the Docker daemon starts inside of the service container, it uses -the default configuration. You may want to configure a +When the Docker daemon starts inside the service container, it uses +the default configuration. You might want to configure a [registry mirror](https://docs.docker.com/registry/recipes/mirror/) for -performance improvements and to ensure you don't reach Docker Hub rate limits. +performance improvements and to ensure you do not exceed Docker Hub rate limits. -###### The service in the `.gitlab-ci.yml` file +##### The service in the `.gitlab-ci.yml` file You can append extra CLI flags to the `dind` service to set the registry mirror: @@ -418,7 +410,7 @@ services: command: ["--registry-mirror", "https://registry-mirror.example.com"] # Specify the registry mirror to use ``` -###### The service in the GitLab Runner configuration file +##### The service in the GitLab Runner configuration file > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173) in GitLab Runner 13.6. @@ -455,7 +447,7 @@ Kubernetes: command = ["--registry-mirror", "https://registry-mirror.example.com"] ``` -###### The Docker executor in the GitLab Runner configuration file +##### The Docker executor in the GitLab Runner configuration file If you are a GitLab Runner administrator, you can use the mirror for every `dind` service. Update the @@ -474,9 +466,9 @@ content: ``` Update the `config.toml` file to mount the file to -`/etc/docker/daemon.json`. This would mount the file for **every** -container that is created by GitLab Runner. The configuration is -picked up by the `dind` service. +`/etc/docker/daemon.json`. This mounts the file for **every** +container created by GitLab Runner. The configuration is +detected by the `dind` service. ```toml [[runners]] @@ -488,7 +480,7 @@ picked up by the `dind` service. volumes = ["/opt/docker/daemon.json:/etc/docker/daemon.json:ro"] ``` -###### The Kubernetes executor in the GitLab Runner configuration file +##### The Kubernetes executor in the GitLab Runner configuration file > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3223) in GitLab Runner 13.6. @@ -516,13 +508,12 @@ kubectl create configmap docker-daemon --namespace gitlab-runner --from-file /tm ``` NOTE: -Make sure to use the namespace that the Kubernetes executor for GitLab Runner uses -to create job pods in. +You must use the namespace that the Kubernetes executor for GitLab Runner uses to create job pods. After the ConfigMap is created, you can update the `config.toml` file to mount the file to `/etc/docker/daemon.json`. This update -mounts the file for **every** container that is created by GitLab Runner. -The configuration is picked up by the `dind` service. +mounts the file for **every** container created by GitLab Runner. +The `dind` service detects this configuration. ```toml [[runners]] @@ -537,22 +528,21 @@ The configuration is picked up by the `dind` service. sub_path = "daemon.json" ``` -##### Limitations of Docker socket binding +#### Known issues with Docker socket binding When you use Docker socket binding, you avoid running Docker in privileged mode. However, the implications of this method are: -- By sharing the Docker daemon, you are effectively disabling all - the security mechanisms of containers and exposing your host to privilege - escalation, which can lead to container breakout. For example, if a project - ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner +- By sharing the Docker daemon, you effectively disable all + the container's security mechanisms and expose your host to privilege + escalation. This can cause container breakout. For example, if a project + ran `docker rm -f $(docker ps -a -q)`, it would remove the GitLab Runner containers. -- Concurrent jobs may not work; if your tests - create containers with specific names, they may conflict with each other. -- Any containers spawned by Docker commands are siblings of the runner rather - than children of the runner. This may have complications and limitations that - are unsuitable for your workflow. -- Sharing files and directories from the source repository into containers may not +- Concurrent jobs might not work. If your tests + create containers with specific names, they might conflict with each other. +- Any containers created by Docker commands are siblings of the runner, rather + than children of the runner. This might cause complications for your workflow. +- Sharing files and directories from the source repository into containers might not work as expected. Volume mounting is done in the context of the host machine, not the build container. For example: @@ -560,8 +550,8 @@ the implications of this method are: docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests ``` -You don't need to include the `docker:20.10.16-dind` service, like you do when -you're using the Docker-in-Docker executor: +You do not need to include the `docker:20.10.16-dind` service, like you do when +you use the Docker-in-Docker executor: ```yaml image: docker:20.10.16 @@ -578,225 +568,37 @@ build: ## Authenticate with registry in Docker-in-Docker -When you use Docker-in-Docker, the -[standard authentication methods](using_docker_images.md#access-an-image-from-a-private-container-registry) -don't work because a fresh Docker daemon is started with the service. - -### Option 1: Run `docker login` - -In [`before_script`](../yaml/index.md#before_script), run `docker -login`: - -```yaml -image: docker:20.10.16 - -variables: - DOCKER_TLS_CERTDIR: "/certs" - -services: - - docker:20.10.16-dind - -build: - stage: build - before_script: - - echo "$DOCKER_REGISTRY_PASS" | docker login $DOCKER_REGISTRY --username $DOCKER_REGISTRY_USER --password-stdin - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` - -To sign in to Docker Hub, leave `$DOCKER_REGISTRY` -empty or remove it. - -### Option 2: Mount `~/.docker/config.json` on each job - -If you are an administrator for GitLab Runner, you can mount a file -with the authentication configuration to `~/.docker/config.json`. -Then every job that the runner picks up is authenticated already. If you -are using the official `docker:20.10.16` image, the home directory is -under `/root`. - -If you mount the configuration file, any `docker` command -that modifies the `~/.docker/config.json` fails. For example, `docker login` -fails, because the file is mounted as read-only. Do not change it from -read-only, because problems occur. - -Here is an example of `/opt/.docker/config.json` that follows the -[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determine-your-docker_auth_config-data) -documentation: - -```json -{ - "auths": { - "https://index.docker.io/v1/": { - "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" - } - } -} -``` - -#### Docker - -Update the -[volume mounts](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section) -to include the file. - -```toml -[[runners]] - ... - executor = "docker" - [runners.docker] - ... - privileged = true - volumes = ["/opt/.docker/config.json:/root/.docker/config.json:ro"] -``` - -#### Kubernetes - -Create a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with the content -of this file. You can do this with a command like: - -```shell -kubectl create configmap docker-client-config --namespace gitlab-runner --from-file /opt/.docker/config.json -``` - -Update the [volume mounts](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes) -to include the file. - -```toml -[[runners]] - ... - executor = "kubernetes" - [runners.kubernetes] - image = "alpine:3.12" - privileged = true - [[runners.kubernetes.volumes.config_map]] - name = "docker-client-config" - mount_path = "/root/.docker/config.json" - # If you are running GitLab Runner 13.5 - # or lower you can remove this - sub_path = "config.json" -``` - -### Option 3: Use `DOCKER_AUTH_CONFIG` - -If you already have -[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determine-your-docker_auth_config-data) -defined, you can use the variable and save it in -`~/.docker/config.json`. - -There are multiple ways to define this authentication: - -- In [`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) - in the runner configuration file. -- In [`before_script`](../yaml/index.md#before_script). -- In [`script`](../yaml/index.md#script). - -The following example shows [`before_script`](../yaml/index.md#before_script). -The same commands apply for any solution you implement. - -```yaml -image: docker:20.10.16 - -variables: - DOCKER_TLS_CERTDIR: "/certs" - -services: - - docker:20.10.16-dind - -build: - stage: build - before_script: - - mkdir -p $HOME/.docker - - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` +When you use Docker-in-Docker, the [standard authentication methods](using_docker_images.md#access-an-image-from-a-private-container-registry) do not work, because a fresh Docker daemon is started with the service. You should [authenticate with registry](authenticate_registry.md). ## Make Docker-in-Docker builds faster with Docker layer caching -When using Docker-in-Docker, Docker downloads all layers of your image every -time you create a build. Recent versions of Docker (Docker 1.13 and later) can -use a pre-existing image as a cache during the `docker build` step. This considerably -speeds up the build process. - -### How Docker caching works - -When running `docker build`, each command in `Dockerfile` results in a layer. -These layers are kept around as a cache and can be reused if there haven't been -any changes. Change in one layer causes all subsequent layers to be recreated. - -You can specify a tagged image to be used as a cache source for the `docker build` -command by using the `--cache-from` argument. Multiple images can be specified -as a cache source by using multiple `--cache-from` arguments. Any image that's used -with the `--cache-from` argument must first be pulled -(using `docker pull`) before it can be used as a cache source. - -### Docker caching example - -Here's a `.gitlab-ci.yml` file that shows how to use Docker caching: - -```yaml -image: docker:20.10.16 - -services: - - docker:20.10.16-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 -``` - -In the `script` section for the `build` stage: - -1. The first command tries to pull the image from the registry so that it can be - used as a cache for the `docker build` command. -1. The second command builds a Docker image by using the pulled image as a - cache (see the `--cache-from $CI_REGISTRY_IMAGE:latest` argument) if - available, and tags it. -1. The last two commands push the tagged Docker images to the container registry - so that they may also be used as cache for subsequent builds. +When using Docker-in-Docker, Docker downloads all layers of your image every time you create a build. You can [make your builds faster with Docker layer caching](docker_layer_caching.md). ## Use the OverlayFS driver NOTE: The shared runners on GitLab.com use the `overlay2` driver by default. -By default, when using `docker:dind`, Docker uses the `vfs` storage driver which -copies the file system on every run. This is a disk-intensive operation -which can be avoided if a different driver is used, for example `overlay2`. +By default, when using `docker:dind`, Docker uses the `vfs` storage driver, which +copies the file system on every run. You can avoid this disk-intensive operation by using a different driver, for example `overlay2`. ### Requirements -1. Make sure a recent kernel is used, preferably `>= 4.2`. +1. Ensure a recent kernel is used, preferably `>= 4.2`. 1. Check whether the `overlay` module is loaded: ```shell sudo lsmod | grep overlay ``` - If you see no result, then it isn't loaded. To load it use: + If you see no result, then the module is not loaded. To load the module, use: ```shell sudo modprobe overlay ``` - If everything went fine, you need to make sure module is loaded on reboot. - On Ubuntu systems, this is done by editing `/etc/modules`. Just add the - following line into it: + If the module loaded, you must make sure the module loads on reboot. + On Ubuntu systems, do this by adding the following line to `/etc/modules`: ```plaintext overlay @@ -823,7 +625,7 @@ environment variable in the environment = ["DOCKER_DRIVER=overlay2"] ``` -If you're running multiple runners, you have to modify all configuration files. +If you're running multiple runners, you must modify all configuration files. Read more about the [runner configuration](https://docs.gitlab.com/runner/configuration/) and [using the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/). @@ -833,8 +635,8 @@ and [using the OverlayFS storage driver](https://docs.docker.com/storage/storage To build Docker images without enabling privileged mode on the runner, you can use one of these alternatives: -- [`kaniko`](using_kaniko.md). -- [`buildah`](https://github.com/containers/buildah). +- [`kaniko`](using_kaniko.md) +- [`buildah`](https://github.com/containers/buildah) For example, with `buildah`: @@ -868,7 +670,7 @@ build: ## Use the GitLab Container Registry -After you've built a Docker image, you can push it up to the built-in +After you've built a Docker image, you can push it to the [GitLab Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). ## Troubleshooting @@ -879,18 +681,18 @@ This is a common error when you are using [Docker-in-Docker](#use-docker-in-docker) v19.03 or later. -This issue occurs because Docker starts on TLS automatically. +This error occurs because Docker starts on TLS automatically. -- If this is your first time setting it up, read +- If this is your first time setting it up, see [use the Docker executor with the Docker image](#use-docker-in-docker). -- If you are upgrading from v18.09 or earlier, read our +- If you are upgrading from v18.09 or earlier, see the [upgrade guide](https://about.gitlab.com/blog/2019/07/31/docker-in-docker-with-docker-19-dot-03/). -This error can also occur with the [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind) when attempts are made to access the Docker-in-Docker service before it has had time to fully start up. For a more detailed explanation, see [this issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27215). +This error can also occur with the [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind) when attempts are made to access the Docker-in-Docker service before it has fully started up. For a more detailed explanation, see [issue 27215](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27215). ### Docker `no such host` error -You may get an error that says +You might get an error that says `docker: error during connect: Post https://docker:2376/v1.40/containers/create: dial tcp: lookup docker on x.x.x.x:53: no such host`. This issue can occur when the service's image name @@ -914,3 +716,10 @@ services: - name: registry.hub.docker.com/library/docker:20.10.16-dind alias: docker ``` + +### Error response from daemon: Get "https://registry-1.docker.io/v2/": unauthorized: incorrect username or password + +This error appears when you use the deprecated variable, `CI_BUILD_TOKEN`. To prevent users from receiving this error, you should: + +- Use [CI_JOB_TOKEN](../jobs/ci_job_token.md) instead. +- Change from `gitlab-ci-token/CI_BUILD_TOKEN` to `$CI_REGISTRY_USER/$CI_REGISTRY_PASSWORD`. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index b19e65ee396..32f95052980 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -20,7 +20,7 @@ method: to function, which is a significant security concern. - Docker-in-Docker generally incurs a performance penalty and can be quite slow. -## Requirements +## Prerequisites To use kaniko with GitLab, [a runner](https://docs.gitlab.com/runner/) with one of the following executors is required: @@ -113,7 +113,7 @@ build: You can build [multi-arch images](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/) inside a container by using [`manifest-tool`](https://github.com/estesp/manifest-tool). -For a detailed guide on how to build a multi-arch image, read [Building a multi-arch container image in unprivileged containers](https://ingenuity.siemens.com/2022/07/building-a-multi-arch-container-image-in-unprivileged-containers/). +For a detailed guide on how to build a multi-arch image, read [Building a multi-arch container image in unprivileged containers](https://blog.siemens.com/2022/07/building-a-multi-arch-container-image-in-unprivileged-containers/). ## Using a registry with a custom certificate |