From 40618fe3f9eb669b138ebe9866f6c930ad518d6f Mon Sep 17 00:00:00 2001 From: Ross Vandegrift Date: Mon, 1 Jul 2019 21:54:58 +0000 Subject: Expand docs on configuring jobs with private registry access Fixes: https://gitlab.com/gitlab-org/gitlab-runner/issues/3963 --- doc/ci/docker/using_docker_images.md | 105 +++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 30 deletions(-) diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index f752f942e24..e012f4f8595 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -463,8 +463,6 @@ that runner. > support for using private registries, which required manual configuration > 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. -> - If the repository is private you need to authenticate your GitLab Runner in the -> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. To access private container registries, the GitLab Runner process can use: @@ -489,6 +487,19 @@ it's provided as an environment variable. This is because GitLab Runnner uses ** runtime. ### Using statically-defined credentials +There are two approaches that you can take in order to access a +private registry. Both require setting the environment variable +`DOCKER_AUTH_LOGIN` with appropriate authentication info. + +1. Per-job: To configure one job to access a private registry, add + `DOCKER_AUTH_LOGIN` as a job variable. +1. Per-runner: To configure a Runner so all its jobs can access a + private registry, add `DOCKER_AUTH_LOGIN` to the environment in the + Runner's configuration. + +See below for examples of each. + +#### Determining your `DOCKER_AUTH_LOGIN` data As an example, let's assume that you want to use the `registry.example.com:5000/private/image:latest` image which is private and requires you to login into a private container registry. @@ -501,30 +512,41 @@ Let's also assume that these are the login credentials: | username | `my_username` | | password | `my_password` | -To configure access for `registry.example.com:5000`, follow these steps: +There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: + +- **First way -** Do a `docker login` on your local machine: -1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to - accomplish this: - - **First way -** Do a `docker login` on your local machine: + ```bash + docker login registry.example.com:5000 --username my_username --password my_password + ``` - ```bash - docker login registry.example.com:5000 --username my_username --password my_password - ``` + Then copy the content of `~/.docker/config.json`. - Then copy the content of `~/.docker/config.json`. - - **Second way -** In some setups, it's possible that Docker client will use - the available system keystore to store the result of `docker login`. In - that case, it's impossible to read `~/.docker/config.json`, so you will - need to prepare the required base64-encoded version of - `${username}:${password}` manually. Open a terminal and execute the - following command: + If you don't need access to the registry from your computer, you + can do a `docker logout`: + + ```bash + docker logout registry.example.com:5000 + ``` + +- **Second way -** In some setups, it's possible that Docker client +will use the available system keystore to store the result of `docker +login`. In that case, it's impossible to read `~/.docker/config.json`, +so you will need to prepare the required base64-encoded version of +`${username}:${password}` manually. Open a terminal and execute the +following command: + + ```bash + echo -n "my_username:my_password" | base64 + + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` - ```bash - echo -n "my_username:my_password" | base64 +#### Configuring a job - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` +To configure a single job with access for `registry.example.com:5000`, +follow these steps: 1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: @@ -539,14 +561,6 @@ To configure access for `registry.example.com:5000`, follow these steps: } ``` -1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG` - value, do a `docker logout` on your computer if you don't need access to the - registry from it: - - ```bash - docker logout registry.example.com:5000 - ``` - 1. You can now use any private image from `registry.example.com:5000` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: @@ -567,6 +581,38 @@ for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`. Specifying only `registry.example.com` will not work. +### Configuring a Runner + +If you have many pipelines that access the same registry, it'll +probably be better to setup registry access at the runner level. This +allows pipeline authors to have access to a private registry just by +running a job on the appropriate runner. It also makes registry +changes and credential rotations much simpler. + +Of course this means that any job on that runner can access the +registry with the same privilege, even across projects. If you need to +control access to the registry, you'll need to be sure to control +access to the runner. + +To add `DOCKER_AUTH_CONFIG` to a Runner: + +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. + +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. + +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. + ### Using Credentials Store > Support for using Credentials Store was added in GitLab Runner 9.5. @@ -741,7 +787,6 @@ creation. [tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/ [postgres-hub]: https://hub.docker.com/r/_/postgres/ [mysql-hub]: https://hub.docker.com/r/_/mysql/ -[runner-priv-reg]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#using-a-private-container-registry [entrypoint]: https://docs.docker.com/engine/reference/builder/#entrypoint [cmd]: https://docs.docker.com/engine/reference/builder/#cmd [register]: https://docs.gitlab.com/runner/register/ -- cgit v1.2.3