diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 04:45:44 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 04:45:44 +0300 |
commit | 85dc423f7090da0a52c73eb66faf22ddb20efff9 (patch) | |
tree | 9160f299afd8c80c038f08e1545be119f5e3f1e1 /doc/ci/docker | |
parent | 15c2c8c66dbe422588e5411eee7e68f1fa440bb8 (diff) |
Add latest changes from gitlab-org/gitlab@13-4-stable-ee
Diffstat (limited to 'doc/ci/docker')
-rw-r--r-- | doc/ci/docker/using_docker_build.md | 28 | ||||
-rw-r--r-- | doc/ci/docker/using_docker_images.md | 48 | ||||
-rw-r--r-- | doc/ci/docker/using_kaniko.md | 22 |
3 files changed, 49 insertions, 49 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 88d6dc3aae4..045fcd39c4d 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -35,12 +35,12 @@ There are three methods to enable the use of `docker build` and `docker run` during jobs, each with their own tradeoffs. An alternative to using `docker build` is to [use kaniko](using_kaniko.md). -This avoids having to execute Runner in privileged mode. +This avoids having to execute a runner in privileged mode. TIP: **Tip:** -To see how Docker and Runner are configured for shared Runners on -GitLab.com, see [GitLab.com Shared -Runners](../../user/gitlab_com/index.md#shared-runners). +To see how Docker and GitLab Runner are configured for shared runners on +GitLab.com, see [GitLab.com shared +runners](../../user/gitlab_com/index.md#shared-runners). ### Use shell executor @@ -123,7 +123,7 @@ not without its own challenges: - By default, Docker 17.09 and higher uses `--storage-driver overlay2` which is the recommended storage driver. See [Using the overlayfs driver](#use-the-overlayfs-driver) for details. -- Since the `docker:19.03.12-dind` container and the Runner container don't share their +- Since the `docker:19.03.12-dind` container and the runner container don't share their root file system, the job's working directory can be used as a mount point for child containers. For example, if you have files you want to share with a child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH` @@ -160,7 +160,7 @@ details. The Docker daemon supports connection over TLS and it's done by default for Docker 19.03.12 or higher. This is the **suggested** way to use the Docker-in-Docker service and -[GitLab.com Shared Runners](../../user/gitlab_com/index.md#shared-runners) +[GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) support this. 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). @@ -179,7 +179,7 @@ support this. --docker-volumes "/certs/client" ``` - The above command registers a new Runner to use the special + The above command registers a new runner to use the special `docker:19.03.12` image, which is provided by Docker. **Notice that it's using the `privileged` mode to start the build and service containers.** If you want to use [Docker-in-Docker](https://www.docker.com/blog/docker-can-now-run-within-docker/) mode, you always @@ -255,7 +255,7 @@ Sometimes there are legitimate reasons why you might want to disable TLS. For example, you have no control over the GitLab Runner configuration that you are using. -Assuming that the Runner `config.toml` is similar to: +Assuming that the runner's `config.toml` is similar to: ```toml [[runners]] @@ -337,10 +337,10 @@ In order to do that, follow the steps: --docker-volumes /var/run/docker.sock:/var/run/docker.sock ``` - The above command registers a new Runner to use the special + The above command registers a new runner to use the special `docker:19.03.12` image which is provided by Docker. **Notice that it's using - the Docker daemon of the Runner itself, and any containers spawned by Docker - commands are siblings of the Runner rather than children of the Runner.** + the Docker daemon of the runner itself, and 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. The above command creates a `config.toml` entry similar to this: @@ -454,7 +454,7 @@ The steps in the `script` section for the `build` stage can be summed up to: ## Use the OverlayFS driver NOTE: **Note:** -The shared Runners on GitLab.com use the `overlay2` driver by default. +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 filesystem on every run. This is a disk-intensive operation @@ -504,10 +504,10 @@ 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 have to modify all configuration files. NOTE: **Note:** -Read more about the [Runner configuration](https://docs.gitlab.com/runner/configuration/) +Read more about the [runner configuration](https://docs.gitlab.com/runner/configuration/) and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index db39532bbf2..0fcd95c41ed 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -26,7 +26,7 @@ test them on a dedicated CI server. ## Register Docker Runner -To use GitLab Runner with Docker you need to [register a new Runner](https://docs.gitlab.com/runner/register/) +To use GitLab Runner with Docker you need to [register a new runner](https://docs.gitlab.com/runner/register/) to use the `docker` executor. An example can be seen below. First we set up a temporary template to supply the services: @@ -112,7 +112,7 @@ It may be a database like MySQL, or Redis, and even `docker:stable-dind` which allows you to use Docker in Docker. It can be practically anything that's required for the CI/CD job to proceed and is accessed by network. -To make sure this works, the Runner: +To make sure this works, the runner: 1. Checks which ports are exposed from the container by default. 1. Starts a special container that waits for these ports to be accessible. @@ -382,7 +382,7 @@ services: - mysql:latest ``` -The Runner would start two containers using the `mysql:latest` image, but both +The runner would start two containers using the `mysql:latest` image, but both of them would be added to the job's container with the `mysql` alias based on the [default hostname naming](#accessing-the-services). This would end with one of the services not being accessible. @@ -398,7 +398,7 @@ services: alias: mysql-2 ``` -The Runner still starts two containers using the `mysql:latest` image, +The runner still starts two containers using the `mysql:latest` image, however now each of them are also accessible with the alias configured in `.gitlab-ci.yml` file. @@ -448,23 +448,23 @@ As you can see, the syntax of `command` is similar to [Dockerfile's `CMD`](https > Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](#extended-docker-configuration-options). Before showing the available entrypoint override methods, let's describe shortly -how the Runner starts and uses a Docker image for the containers used in the +how the runner starts and uses a Docker image for the containers used in the CI jobs: -1. The Runner starts a Docker container using the defined entrypoint (default +1. The runner starts a Docker container using the defined entrypoint (default from `Dockerfile` that may be overridden in `.gitlab-ci.yml`) -1. The Runner attaches itself to a running container. -1. The Runner prepares a script (the combination of +1. The runner attaches itself to a running container. +1. The runner prepares a script (the combination of [`before_script`](../yaml/README.md#before_script-and-after_script), [`script`](../yaml/README.md#script), and [`after_script`](../yaml/README.md#before_script-and-after_script)). -1. The Runner sends the script to the container's shell STDIN and receives the +1. The runner sends the script to the container's shell STDIN and receives the output. To override the entrypoint of a Docker image, the recommended solution is to -define an empty `entrypoint` in `.gitlab-ci.yml`, so the Runner does not start +define an empty `entrypoint` in `.gitlab-ci.yml`, so the runner does not start a useless shell layer. However, that does not work for all Docker versions, and -you should check which one your Runner is using. Specifically: +you should check which one your runner is using. Specifically: - If Docker 17.06 or later is used, the `entrypoint` can be set to an empty value. - If Docker 17.03 or previous versions are used, the `entrypoint` can be set to @@ -477,7 +477,7 @@ inside it and you would like to use it as a base image for your job because you want to execute some tests with this database binary. Let's also assume that this image is configured with `/usr/bin/super-sql run` as an entrypoint. That means that when starting the container without additional options, it runs -the database's process, while Runner expects that the image has no +the database's process, while the runner expects that the image has no entrypoint or that the entrypoint is prepared to start a shell command. With the extended Docker configuration options, instead of creating your @@ -527,7 +527,7 @@ To define which should be used, the GitLab Runner process reads the configuratio - `DOCKER_AUTH_CONFIG` variable provided as either: - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`. - A project's variables stored on the projects **Settings > CI/CD** page. -- `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the Runner. +- `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the runner. - `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process. If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user, the home directory of the main GitLab Runner process user is used. @@ -543,7 +543,7 @@ runtime. - This feature requires GitLab Runner **1.8** or higher. - For GitLab Runner versions **>= 0.6, <1.8** there was a partial support for using private registries, which required manual configuration - of credentials on runner's host. We recommend to upgrade your Runner to + of credentials on runner's host. We recommend to upgrade your runner to at least version **1.8** if you want to use private registries. - Available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html) in GitLab Runner 13.1 and later. @@ -556,9 +556,9 @@ private registry. Both require setting the environment variable 1. Per-job: To configure one job to access a private registry, add `DOCKER_AUTH_CONFIG` as a job variable. -1. Per-runner: To configure a Runner so all its jobs can access a +1. Per-runner: To configure a runner so all its jobs can access a private registry, add `DOCKER_AUTH_CONFIG` to the environment in the - Runner's configuration. + runner's configuration. See below for examples of each. @@ -652,12 +652,12 @@ registries to the `"auths"` hash as described above. NOTE: **Note:** The full `hostname:port` combination is required everywhere -for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if +for the runner to match the `DOCKER_AUTH_CONFIG`. For example, if `registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`. Specifying only `registry.example.com` does not work. -### Configuring a Runner +### Configuring a runner If you have many pipelines that access the same registry, it is probably better to set up registry access at the runner level. This @@ -670,16 +670,16 @@ registry with the same privilege, even across projects. If you need to control access to the registry, you need to be sure to control access to the runner. -To add `DOCKER_AUTH_CONFIG` to a Runner: +To add `DOCKER_AUTH_CONFIG` to a runner: -1. Modify the Runner's `config.toml` file as follows: +1. Modify the runner's `config.toml` file as follows: ```toml [[runners]] environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"] ``` -1. Restart the Runner service. +1. Restart the runner service. NOTE: **Note:** The double quotes included in the `DOCKER_AUTH_CONFIG` @@ -687,7 +687,7 @@ data must be escaped with backslashes. This prevents them from being interpreted as TOML. NOTE: **Note:** -The `environment` option is a list. So your Runner may +The `environment` option is a list. So your runner may have existing entries and you should add this to the list, not replace it. @@ -713,7 +713,7 @@ To configure credentials store, follow these steps: } ``` - - Or, if you're running self-managed Runners, add the above JSON to + - Or, if you're running self-managed runners, add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. @@ -762,7 +762,7 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th This configures Docker to use the credential helper for all Amazon ECR registries. - - Or, if you're running self-managed Runners, + - Or, if you're running self-managed runners, add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 41c8f04f66e..a62f4db4fe4 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -22,8 +22,8 @@ build](using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) ## Requirements -In order to utilize kaniko with GitLab, a [GitLab Runner](https://docs.gitlab.com/runner/) -using one of the following executors is required: +In order to utilize kaniko with GitLab, [a runner](https://docs.gitlab.com/runner/) +with one of the following executors is required: - [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html). - [Docker](https://docs.gitlab.com/runner/executors/docker.html). @@ -85,13 +85,13 @@ This can be solved by adding your CA's certificate to the kaniko certificate store: ```yaml - before_script: - - mkdir -p /kaniko/.docker - - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json - - | - echo "-----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE-----" >> /kaniko/ssl/certs/additional-ca-cert-bundle.crt +before_script: + - mkdir -p /kaniko/.docker + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - | + echo "-----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE-----" >> /kaniko/ssl/certs/additional-ca-cert-bundle.crt ``` ## Video walkthrough of a working example @@ -100,8 +100,8 @@ The [Least Privilege Container Builds with Kaniko on GitLab](https://www.youtube video is a walkthrough of the [Kaniko Docker Build](https://gitlab.com/guided-explorations/containers/kaniko-docker-build) Guided Exploration project pipeline. It was tested on: -- [GitLab.com Shared Runners](../../user/gitlab_com/index.md#shared-runners) -- [The Kubernetes Runner executor](https://docs.gitlab.com/runner/executors/kubernetes.html) +- [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) +- [The Kubernetes runner executor](https://docs.gitlab.com/runner/executors/kubernetes.html) The example can be copied to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page. |