diff options
Diffstat (limited to 'doc/ci/docker')
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 22 | ||||
| -rw-r--r-- | doc/ci/docker/using_docker_images.md | 37 |
2 files changed, 19 insertions, 40 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 045fcd39c4d..a319c5f09ab 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -48,7 +48,6 @@ The simplest approach is to install GitLab Runner in `shell` execution mode. GitLab Runner then executes job scripts as the `gitlab-runner` user. 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/#installation). - 1. During GitLab Runner installation select `shell` as method of executing job scripts or use command: ```shell @@ -90,7 +89,6 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. 1. You can now use `docker` command (and **install** `docker-compose` if needed). -NOTE: **Note:** By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions. For more information please read [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful). @@ -101,7 +99,6 @@ The second approach is to use the special Docker-in-Docker (dind) (`docker`) and run the job script in context of that image in privileged mode. -NOTE: **Note:** `docker-compose` is not part of Docker-in-Docker (dind). To use `docker-compose` in your CI builds, follow the `docker-compose` [installation instructions](https://docs.docker.com/compose/install/). @@ -149,22 +146,17 @@ released. #### TLS enabled -NOTE: **Note:** -Requires GitLab Runner 11.11 or later, but is not supported if GitLab -Runner is installed using the [Helm -chart](https://docs.gitlab.com/runner/install/kubernetes.html). See the -[related -issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for -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) support this. -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). +GitLab Runner 11.11 or later is required, but it is not supported if GitLab +Runner is installed using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html). +See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for details. +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and `privileged` mode: @@ -225,7 +217,7 @@ support this. # 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, + # 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 @@ -287,7 +279,7 @@ variables: # 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, + # 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 @@ -324,7 +316,6 @@ are done to the services as well, making these incompatible. In order to do that, follow the steps: 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). - 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: ```shell @@ -506,7 +497,6 @@ environment = ["DOCKER_DRIVER=overlay2"] 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/) and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 0fcd95c41ed..185de159416 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -138,7 +138,6 @@ still succeeds even if that warning was printed. For example: As it was mentioned before, this feature is designed to provide **network accessible** services. A database is the simplest example of such a service. -NOTE: **Note:** The services feature is not designed to, and does not add any software from the defined `services` image(s) to the job's container. @@ -186,7 +185,6 @@ access to it from your build container under two hostnames to choose from: - `tutum-wordpress` - `tutum__wordpress` -NOTE: **Note:** Hostnames with underscores are not RFC valid and may cause problems in 3rd party applications. @@ -364,10 +362,9 @@ For example, the following two definitions are equal: | `name` | yes, when used with any other option | 9.4 | Full name of the image that should be used. It should contain the Registry part if needed. | | `entrypoint` | no | 9.4 |Command or script that should be executed as the container's entrypoint. It's translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. | | `command` | no | 9.4 |Command or script that should be used as the container's command. It's translated to arguments passed to Docker after the image's name. The syntax is similar to [`Dockerfile`'s `CMD`](https://docs.docker.com/engine/reference/builder/#cmd) directive, where each shell token is a separate string in the array. | -| `alias` | no | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. | +| `alias` (1) | no | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. | -NOTE: **Note:** -Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later. +(1) Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later. ### Starting multiple services from the same image @@ -532,7 +529,6 @@ To define which should be used, the GitLab Runner process reads the configuratio 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. -NOTE: **Note:** GitLab Runner reads this configuration **only** from `config.toml` and ignores it if it's provided as an environment variable. This is because GitLab Runner uses **only** `config.toml` configuration and does not interpolate **ANY** environment variables at @@ -547,6 +543,7 @@ runtime. 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. +- [Credentials Store](#using-credentials-store) and [Credential Helpers](#using-credential-helpers) require binaries to be added to the GitLab Runner's `$PATH`, and require access to do so. Therefore, these features are not available on shared runners or any other runner where the user does not have access to the environment where the runner is installed. ### Using statically-defined credentials @@ -600,7 +597,7 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: Open a terminal and execute the following command: ```shell - # Note the use of "-n" - it prevents encoding a newline in the password. + # The use of "-n" - prevents encoding a newline in the password. echo -n "my_username:my_password" | base64 # Example output to copy @@ -650,7 +647,6 @@ follow these steps: You can add configuration for as many registries as you want, adding more 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 `registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, @@ -679,17 +675,14 @@ To add `DOCKER_AUTH_CONFIG` to a runner: environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"] ``` -1. Restart the runner service. - -NOTE: **Note:** -The double quotes included in the `DOCKER_AUTH_CONFIG` -data must be escaped with backslashes. This prevents them from being -interpreted as TOML. + - The double quotes included in the `DOCKER_AUTH_CONFIG` + data must be escaped with backslashes. This prevents them from being + interpreted as TOML. + - The `environment` option is a list. Your runner may + have existing entries and you should add this to the list, not replace + it. -NOTE: **Note:** -The `environment` option is a list. So your runner may -have existing entries and you should add this to the list, not replace -it. +1. Restart the runner service. ### Using Credentials Store @@ -717,10 +710,9 @@ To configure credentials store, follow these steps: `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. -NOTE: **Note:** `credsStore` is used to access ALL the registries. -If you want to use both images from private registry and public images from DockerHub, -pulling from DockerHub would fail, because Docker daemon tries to use the same credentials for **ALL** the registries. +If you want to use both images from private registry and public images from Docker Hub, +pulling from Docker Hub would fail, because Docker daemon tries to use the same credentials for **ALL** the registries. ### Using Credential Helpers @@ -732,10 +724,8 @@ image which is private and requires you to log in into a private container regis To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow these steps: 1. Make sure `docker-credential-ecr-login` is available in GitLab Runner's `$PATH`. - 1. Have any of the following [AWS credentials setup](https://github.com/awslabs/amazon-ecr-credential-helper#aws-credentials). Make sure that GitLab Runner can access the credentials. - 1. Make GitLab Runner use it. There are two ways to accomplish this. Either: - Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) @@ -791,7 +781,6 @@ service containers. For all possible configuration variables check the documentation of each image provided in their corresponding Docker hub page. -NOTE: **Note:** All variables are passed to all services containers. It's not designed to distinguish which variable should go where. |