Commit 3a9b75ab authored by Evan Read's avatar Evan Read

Merge branch 'docs/docker-build' into 'master'

Add the ways needed to authenticate to the registry via CI/CD

Closes gitlab-com/support-forum#3825

See merge request gitlab-org/gitlab-ce!21538
parents ad5ab1a6 63e4a81a
...@@ -395,8 +395,67 @@ If you're running multiple Runners you will have to modify all configuration fil ...@@ -395,8 +395,67 @@ If you're running multiple Runners you will have to modify all configuration fil
> login to GitLab's Container Registry. > login to GitLab's Container Registry.
Once you've built a Docker image, you can push it up to the built-in Once you've built a Docker image, you can push it up to the built-in
[GitLab Container Registry](../../user/project/container_registry.md). For example, [GitLab Container Registry](../../user/project/container_registry.md).
if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml` Some things you should be aware of:
- You must [log in to the container registry](#authenticating-to-the-container-registry)
before running commands. You can do this in the `before_script` if multiple
jobs depend on it.
- Using `docker build --pull` fetches any changes to base
images before building just in case your cache is stale. It takes slightly
longer, but means you don’t get stuck without security patches to base images.
- Doing an explicit `docker pull` before each `docker run` fetches
the latest image that was just built. This is especially important if you are
using multiple runners that cache images locally. Using the git SHA in your
image tag makes this less necessary since each job will be unique and you
shouldn't ever have a stale image. However, it's still possible to have a
stale image if you re-build a given commit after a dependency has changed.
- You don't want to build directly to `latest` tag in case there are multiple jobs
happening simultaneously.
### Authenticating to the Container Registry
There are three ways to authenticate to the Container Registry via GitLab CI/CD
and depend on the visibility of your project.
For all projects, mostly suitable for public ones:
- **Using the special `gitlab-ci-token` user**: This user is created for you in order to
push to the Registry connected to your project. Its password is automatically
set with the `$CI_JOB_TOKEN` variable. This allows you to automate building and deploying
your Docker images and has read/write access to the Registry. This is ephemeral,
so it's only valid for one job. You can use the following example as-is:
```sh
docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
```
For private and internal projects:
- **Using a personal access token**: You can create and use a
[personal access token](../../user/profile/personal_access_tokens.md)
in case your project is private:
- For read (pull) access, the scope should be `read_registry`.
- For read/write (pull/push) access, use `api`.
Replace the `<username>` and `<access_token>` in the following example:
```sh
docker login -u <username> -p <access_token> $CI_REGISTRY
```
- **Using the GitLab Deploy Token**: You can create and use a
[special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token)
with your private projects. It provides read-only (pull) access to the Registry.
Once created, you can use the special environment variables, and GitLab CI/CD
will fill them in for you. You can use the following example as-is:
```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
### Container Registry examples
If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml`
could look like: could look like:
```yaml ```yaml
...@@ -414,11 +473,6 @@ could look like: ...@@ -414,11 +473,6 @@ could look like:
- docker push registry.example.com/group/project/image:latest - docker push registry.example.com/group/project/image:latest
``` ```
You have to use the special `gitlab-ci-token` user created for you in order to
push to the Registry connected to your project. Its password is provided in the
`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment
of your Docker images.
You can also make use of [other variables](../variables/README.md) to avoid hardcoding: You can also make use of [other variables](../variables/README.md) to avoid hardcoding:
```yaml ```yaml
...@@ -508,22 +562,6 @@ deploy: ...@@ -508,22 +562,6 @@ deploy:
- master - master
``` ```
Some things you should be aware of when using the Container Registry:
- You must log in to the container registry before running commands. Putting
this in `before_script` will run it before each job.
- Using `docker build --pull` makes sure that Docker fetches any changes to base
images before building just in case your cache is stale. It takes slightly
longer, but means you don’t get stuck without security patches to base images.
- Doing an explicit `docker pull` before each `docker run` makes sure to fetch
the latest image that was just built. This is especially important if you are
using multiple runners that cache images locally. Using the git SHA in your
image tag makes this less necessary since each job will be unique and you
shouldn't ever have a stale image, but it's still possible if you re-build a
given commit after a dependency has changed.
- You don't want to build directly to `latest` in case there are multiple jobs
happening simultaneously.
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
[2fa]: ../../user/profile/account/two_factor_authentication.md [2fa]: ../../user/profile/account/two_factor_authentication.md
......
...@@ -45,16 +45,14 @@ the following table. ...@@ -45,16 +45,14 @@ the following table.
| Scope | Description | | Scope | Description |
| ----- | ----------- | | ----- | ----------- |
|`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). | |`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. | | `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). | | `read_registry` | Allows to read (pull) [container registry] images if a project is private and authorization is required ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3). |
| `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). | | `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). |
| `read_repository` | Allows read-access to the repository through git clone. | | `read_repository` | Allows read-access (pull) to the repository through git clone. |
[2fa]: ../account/two_factor_authentication.md [2fa]: ../account/two_factor_authentication.md
[api]: ../../api/README.md [api]: ../../api/README.md
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 [ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
[ce-14838]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838 [ce-14838]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838
[container registry]: ../project/container_registry.md [container registry]: ../project/container_registry.md
[users]: ../../api/users.md [users]: ../../api/users.md
......
...@@ -119,12 +119,17 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do ...@@ -119,12 +119,17 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
> Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7 > Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7
If a project is private, credentials will need to be provided for authorization. If a project is private, credentials will need to be provided for authorization.
The preferred way to do this, is either by using a [personal access tokens][pat] or a [project deploy token][pdt]. There are two ways to do this:
- By using a [personal access token](../profile/personal_access_tokens.md).
- By using a [deploy token](../project/deploy_tokens/index.md).
The minimal scope needed for both of them is `read_registry`. The minimal scope needed for both of them is `read_registry`.
Example of using a personal access token: Example of using a token:
```
docker login registry.example.com -u <your_username> -p <your_access_token> ```sh
docker login registry.example.com -u <username> -p <token>
``` ```
## Troubleshooting the GitLab Container Registry ## Troubleshooting the GitLab Container Registry
......
...@@ -9,7 +9,7 @@ at midnight UTC and that they can be only managed by [maintainers](https://docs. ...@@ -9,7 +9,7 @@ at midnight UTC and that they can be only managed by [maintainers](https://docs.
## Creating a Deploy Token ## Creating a Deploy Token
You can create as many deploy tokens as you like from the settings of your project: You can create as many deploy tokens as you like from the settings of your project:
1. Log in to your GitLab account. 1. Log in to your GitLab account.
1. Go to the project you want to create Deploy Tokens for. 1. Go to the project you want to create Deploy Tokens for.
...@@ -49,14 +49,13 @@ To download a repository using a Deploy Token, you just need to: ...@@ -49,14 +49,13 @@ To download a repository using a Deploy Token, you just need to:
2. Take note of your `username` and `token` 2. Take note of your `username` and `token`
3. `git clone` the project using the Deploy Token: 3. `git clone` the project using the Deploy Token:
```sh
git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
```
```bash Replace `<username>` and `<deploy_token>` with the proper values.
git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
```
Just replace `<username>` and `<deploy_token>` with the proper values
### Read container registry images ### Read Container Registry images
To read the container registry images, you'll need to: To read the container registry images, you'll need to:
...@@ -64,21 +63,29 @@ To read the container registry images, you'll need to: ...@@ -64,21 +63,29 @@ To read the container registry images, you'll need to:
2. Take note of your `username` and `token` 2. Take note of your `username` and `token`
3. Log in to GitLab’s Container Registry using the deploy token: 3. Log in to GitLab’s Container Registry using the deploy token:
``` ```sh
docker login registry.example.com -u <username> -p <deploy_token> docker login registry.example.com -u <username> -p <deploy_token>
``` ```
Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply
pull images from your Container Registry. pull images from your Container Registry.
### GitLab Deploy Token ### GitLab Deploy Token
> [Introduced][ce-18414] in GitLab 10.8. > [Introduced][ce-18414] in GitLab 10.8.
There's a special case when it comes to Deploy Tokens, if a user creates one There's a special case when it comes to Deploy Tokens. If a user creates one
named `gitlab-deploy-token`, the username and token of the Deploy Token will be named `gitlab-deploy-token`, the username and token of the Deploy Token will be
automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and
`CI_DEPLOY_PASSWORD`, respectively. `CI_DEPLOY_PASSWORD`, respectively. With the GitLab Deploy Token, the
`read_registry` scope is implied.
After you create the token, you can login to the Container Registry using
those variables:
```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
[ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894 [ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845 [ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
......
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