Commit 5e10faa3 authored by Evan Read's avatar Evan Read

Merge branch 'private-registry-docs' into 'master'

Expand docs on configuring jobs with private registry access

Closes gitlab-runner#3963

See merge request gitlab-org/gitlab-ce!27231
parents 77c35ac8 40618fe3
...@@ -463,8 +463,6 @@ that runner. ...@@ -463,8 +463,6 @@ that runner.
> support for using private registries, which required manual configuration > 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. > 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: 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 ** ...@@ -489,6 +487,19 @@ it's provided as an environment variable. This is because GitLab Runnner uses **
runtime. runtime.
### Using statically-defined credentials ### 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` 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. 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: ...@@ -501,30 +512,41 @@ Let's also assume that these are the login credentials:
| username | `my_username` | | username | `my_username` |
| password | `my_password` | | 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 ```bash
accomplish this: docker login registry.example.com:5000 --username my_username --password my_password
- **First way -** Do a `docker login` on your local machine: ```
```bash Then copy the content of `~/.docker/config.json`.
docker login registry.example.com:5000 --username my_username --password my_password
```
Then copy the content of `~/.docker/config.json`. If you don't need access to the registry from your computer, you
- **Second way -** In some setups, it's possible that Docker client will use can do a `docker logout`:
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 ```bash
need to prepare the required base64-encoded version of docker logout registry.example.com:5000
`${username}:${password}` manually. Open a terminal and execute the ```
following command:
- **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 #### Configuring a job
echo -n "my_username:my_password" | base64
# Example output to copy To configure a single job with access for `registry.example.com:5000`,
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= follow these steps:
```
1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the 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: Docker configuration file as the value:
...@@ -539,14 +561,6 @@ To configure access for `registry.example.com:5000`, follow these steps: ...@@ -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 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: `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 ...@@ -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`. then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`.
Specifying only `registry.example.com` will not work. 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 ### Using Credentials Store
> Support for using Credentials Store was added in GitLab Runner 9.5. > Support for using Credentials Store was added in GitLab Runner 9.5.
...@@ -741,7 +787,6 @@ creation. ...@@ -741,7 +787,6 @@ creation.
[tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/ [tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/
[postgres-hub]: https://hub.docker.com/r/_/postgres/ [postgres-hub]: https://hub.docker.com/r/_/postgres/
[mysql-hub]: https://hub.docker.com/r/_/mysql/ [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 [entrypoint]: https://docs.docker.com/engine/reference/builder/#entrypoint
[cmd]: https://docs.docker.com/engine/reference/builder/#cmd [cmd]: https://docs.docker.com/engine/reference/builder/#cmd
[register]: https://docs.gitlab.com/runner/register/ [register]: https://docs.gitlab.com/runner/register/
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment