diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-03-16 18:18:33 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-03-16 18:18:33 +0000 |
commit | f64a639bcfa1fc2bc89ca7db268f594306edfd7c (patch) | |
tree | a2c3c2ebcc3b45e596949db485d6ed18ffaacfa1 /doc/ci/docker | |
parent | bfbc3e0d6583ea1a91f627528bedc3d65ba4b10f (diff) | |
download | gitlab-ce-f64a639bcfa1fc2bc89ca7db268f594306edfd7c.tar.gz |
Add latest changes from gitlab-org/gitlab@13-10-stable-eev13.10.0-rc40
Diffstat (limited to 'doc/ci/docker')
-rw-r--r-- | doc/ci/docker/index.md | 19 | ||||
-rw-r--r-- | doc/ci/docker/using_docker_build.md | 101 | ||||
-rw-r--r-- | doc/ci/docker/using_docker_images.md | 30 | ||||
-rw-r--r-- | doc/ci/docker/using_kaniko.md | 2 |
4 files changed, 67 insertions, 85 deletions
diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 18a9d63b694..0897bb183e5 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -8,11 +8,18 @@ type: index # Docker integration -GitLab CI/CD can be combined with [Docker](https://www.docker.com) to enable -integration between the two. +There are two primary ways to incorporate [Docker](https://www.docker.com) in your CI/CD workflow. -The following documentation is available for using GitLab CI/CD with Docker: +- **[Run your CI/CD jobs](using_docker_images.md) in Docker containers.** -- [Building Docker images with GitLab CI/CD](using_docker_build.md). -- [Using Docker images](using_docker_images.md). -- [Building images with kaniko and GitLab CI/CD](using_kaniko.md). + You can create CI/CD jobs to do things like test, build, or publish + an application. These jobs can run in Docker containers. + + For example, you can tell GitLab CI/CD to use a Node image that's hosted on Docker Hub + or in the GitLab Container Registry. Your job then runs in a container that's based on the image. + The container has all the Node dependencies you need to build your app. + +- **Use [Docker](using_docker_build.md) or [kaniko](using_kaniko.md) to build Docker images.** + + You can create CI/CD jobs to build Docker images and publish + them to a container registry. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 46ced9b4d6d..2091a80bdf2 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -5,34 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Building Docker images with GitLab CI/CD +# Use Docker to build Docker images -You can use GitLab CI/CD with Docker Engine to build and test Docker-based projects. - -For example, you might want to: - -1. Create an application image. -1. Run tests against the created image. -1. Push image to a remote registry. -1. Deploy to a server from the pushed image. - -Or, if your application already has a `Dockerfile`, you can -use it to create and test an image: - -```shell -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 -``` +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. To run Docker commands in your CI/CD jobs, you must configure -GitLab Runner to enable `docker` support. +GitLab Runner to support `docker` commands. ## Enable Docker commands in your CI/CD jobs -There are three ways to enable the use of `docker build` and `docker run` -during jobs, each with their own tradeoffs. You can use: +To enable Docker commands for your CI/CD jobs, you can use: - [The shell executor](#use-the-shell-executor) - [The Docker executor with the Docker image (Docker-in-Docker)](#use-the-docker-executor-with-the-docker-image-docker-in-docker) @@ -47,12 +31,9 @@ to learn more about how these runners are configured. ### Use the shell executor -One way to configure GitLab Runner for `docker` support is to use the -`shell` executor. - -After you register a runner and select the `shell` executor, -your job scripts are executed as the `gitlab-runner` user. -This user needs permission to run Docker commands. +You can include Docker commands in your CI/CD jobs if your runner is configured to +use the `shell` executor. The `gitlab-runner` user runs the Docker commands, but +needs permission to run them. 1. [Install](https://gitlab.com/gitlab-org/gitlab-runner/#installation) GitLab Runner. 1. [Register](https://docs.gitlab.com/runner/register/) a runner. @@ -100,9 +81,11 @@ Learn more about the [security of the `docker` group](https://blog.zopyx.com/on- ### Use the Docker executor with the Docker image (Docker-in-Docker) -Another way to configure GitLab Runner for `docker` support is to -register a runner with the Docker executor and use the [Docker image](https://hub.docker.com/_/docker/) -to run your job scripts. This configuration is referred to as "Docker-in-Docker." +You can use "Docker-in-Docker" to run commands in your CI/CD jobs: + +- Register a runner that uses the Docker executor. +- Use the [Docker image](https://hub.docker.com/_/docker/) provided by Docker to + run the jobs that need Docker commands. The Docker image has all of the `docker` tools installed and can run the job script in context of the image in privileged mode. @@ -111,14 +94,18 @@ The `docker-compose` command is not available in this configuration by default. To use `docker-compose` in your job scripts, follow the `docker-compose` [installation instructions](https://docs.docker.com/compose/install/). +An example project that uses this approach can be found here: <https://gitlab.com/gitlab-examples/docker>. + WARNING: When you enable `--docker-privileged`, you are effectively disabling all of the security mechanisms of containers and exposing your host to privilege -escalation which can lead to container breakout. For more information, check +escalation. Doing this can lead to container breakout. For more information, check out the official Docker documentation on [runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). -Docker-in-Docker works well, and is the recommended configuration, but it is +#### Limitations of Docker-in-Docker + +Docker-in-Docker is the recommended configuration, but it is not without its own challenges: - When using Docker-in-Docker, each job is in a clean environment without the past @@ -144,8 +131,6 @@ not without its own challenges: - docker run -v "$MOUNT_POINT:/mnt" my-docker-image ``` -An example project using this approach can be found here: <https://gitlab.com/gitlab-examples/docker>. - In the examples below, we are using Docker images tags to specify a specific version, such as `docker:19.03.12`. If tags like `docker:stable` are used, you have no control over what version is used. This can lead to @@ -373,9 +358,8 @@ build: ### Use Docker socket binding -Another way to configure GitLab Runner for `docker` support is to -bind-mount `/var/run/docker.sock` into the -container so that Docker is available in the context of the image. +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. NOTE: If you bind the Docker socket and you are @@ -478,13 +462,10 @@ services: > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173) in GitLab Runner 13.6. -If you are an administrator of GitLab Runner and you have the `dind` -service defined for the [Docker -executor](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdockerservices-section), -or the [Kubernetes -executor](https://docs.gitlab.com/runner/executors/kubernetes.html#using-services) -you can specify the `command` to configure the registry mirror for the -Docker daemon. +If you are a GitLab Runner administrator, you can specify the `command` to configure the registry mirror +for the Docker daemon. The `dind` service must be defined for the +[Docker](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdockerservices-section) +or [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html#using-services). Docker: @@ -516,11 +497,10 @@ Kubernetes: ##### Docker executor inside GitLab Runner configuration -If you are an administrator of GitLab Runner and you want to use -the mirror for every `dind` service, update the +If you are a GitLab Runner administrator, you can use +the mirror for every `dind` service. Update the [configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) -to specify a [volume -mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). +to specify a [volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). For example, if you have a `/opt/docker/daemon.json` file with the following content: @@ -552,11 +532,10 @@ picked up by the `dind` service. > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3223) in GitLab Runner 13.6. -If you are an administrator of GitLab Runner and you want to use -the mirror for every `dind` service, update the +If you are a GitLab Runner administrator, you can use +the mirror for every `dind` service. Update the [configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) -to specify a [ConfigMap volume -mount](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes). +to specify a [ConfigMap volume mount](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes). For example, if you have a `/tmp/daemon.json` file with the following content: @@ -602,7 +581,7 @@ The configuration is picked up by the `dind` service. When you use Docker-in-Docker, the [normal authentication methods](using_docker_images.html#define-an-image-from-a-private-container-registry) -won't work because a fresh Docker daemon is started with the service. +don't work because a fresh Docker daemon is started with the service. ### Option 1: Run `docker login` @@ -634,14 +613,14 @@ empty or remove it. 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 will be authenticated already. If you +Then every job that the runner picks up is authenticated already. If you are using the official `docker:19.03.13` image, the home directory is under `/root`. If you mount the configuration file, any `docker` command that modifies the `~/.docker/config.json` (for example, `docker login`) fails, because the file is mounted as read-only. Do not change it from -read-only, because other problems will occur. +read-only, because problems occur. Here is an example of `/opt/.docker/config.json` that follows the [`DOCKER_AUTH_CONFIG`](using_docker_images.md#determining-your-docker_auth_config-data) @@ -743,8 +722,8 @@ build: 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 above) can -use a pre-existing image as a cache during the `docker build` step, considerably -speeding up the build process. +use a pre-existing image as a cache during the `docker build` step. This considerably +speeds up the build process. ### How Docker caching works @@ -754,8 +733,8 @@ 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. Keep in mind that -any image that's used with the `--cache-from` argument must first be pulled +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. ### Using Docker caching @@ -872,4 +851,4 @@ If: - This is the first time setting it up, carefully read [using Docker in Docker workflow](#use-the-docker-executor-with-the-docker-image-docker-in-docker). - You are upgrading from v18.09 or earlier, read our - [upgrade guide](https://about.gitlab.com/releases/2019/07/31/docker-in-docker-with-docker-19-dot-03/). + [upgrade guide](https://about.gitlab.com/blog/2019/07/31/docker-in-docker-with-docker-19-dot-03/). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 67450d442a9..e8028a862c4 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -5,29 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Using Docker images +# Run your CI/CD jobs in Docker containers -GitLab CI/CD in conjunction with [GitLab Runner](../runners/README.md) can use -[Docker Engine](https://www.docker.com/) to test and build any application. +You can run your CI/CD jobs in separate, isolated Docker containers. -Docker is an open-source project that has predefined images you can use to -run applications in independent "containers." These containers run in a single Linux -instance. [Docker Hub](https://hub.docker.com/) is a database of pre-built images you can -use to test and build your applications. +When you run a Docker container on your local machine, it acts as a reproducible build environment. +You can run tests in the container, instead of testing on a dedicated CI/CD server. -When you use Docker with GitLab CI/CD, Docker runs each job in a separate and isolated -container. You specify the container image in the project's -[`.gitlab-ci.yml`](../yaml/README.md) file. +To run CI/CD jobs in a Docker container, you need to: -Docker containers provide a reproducible build environment that -can run on your workstation. When a Docker container is running, you can test -commands from your shell, rather than having to -test them on a dedicated CI server. +- Register a runner that uses the Docker executor. Then all jobs run in a Docker container. +- Specify an image in your `.gitlab-ci.yml` file. The runner creates a container from this image + and runs the jobs in it. +- Optional. Specify other images in your `.gitlab-ci.yml` file. These containers are known as + ["services"](#what-is-a-service) and you can use them to run services like MySQL separately. -## Register Docker Runner +## Register a runner that uses the Docker executor -To use GitLab Runner with Docker you need to [register a new runner](https://docs.gitlab.com/runner/register/) -to use the `docker` executor. +To use GitLab Runner with Docker you need to [register a runner](https://docs.gitlab.com/runner/register/) +that uses the Docker executor. In this example, we first set up a temporary template to supply the services: diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 2122cf2bf16..0344e736dd4 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Building images with kaniko and GitLab CI/CD +# Use kaniko to build Docker images > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45512) in GitLab 11.2. Requires GitLab Runner 11.2 and above. |