Skip to content

G
gitlab-ce
Commit c26add1e authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Merge branch 'docs-container-registry-cleanup-docker-build' into 'master' 

Move over Docker build docs to container registry

See merge request gitlab-org/gitlab!23901
parents 596e8ea3 42711ea6
Hide whitespace changes
Inline Side-by-side
Showing with 266 additions and 275 deletions
doc/ci/docker/using_docker_build.md
View file @ c26add1e
...@@ -108,7 +108,7 @@ By enabling `--docker-privileged`, you are effectively disabling all of ...@@ -108,7 +108,7 @@ By enabling `--docker-privileged`, you are effectively disabling all of
the security mechanisms of containers and exposing your host to privilege the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For more information, check escalation which can lead to container breakout. For more information, check
out the official Docker documentation on out the official Docker documentation on
[Runtime privilege and Linux capabilities][docker-cap]. [Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).
Docker-in-Docker works well, and is the recommended configuration, but it is Docker-in-Docker works well, and is the recommended configuration, but it is
not without its own challenges: not without its own challenges:
...@@ -409,7 +409,7 @@ any image that's used with the `--cache-from` argument must first be pulled ...@@ -409,7 +409,7 @@ any image that's used with the `--cache-from` argument must first be pulled
### Using Docker caching ### Using Docker caching
Here's a simple `.gitlab-ci.yml` file showing how Docker caching can be utilized: Here's a `.gitlab-ci.yml` file showing how Docker caching can be used:
```yaml ```yaml
image: docker:19.03.1 image: docker:19.03.1
...@@ -503,229 +503,8 @@ If you're running multiple Runners you will have to modify all configuration fil ...@@ -503,229 +503,8 @@ If you're running multiple Runners you will have to modify all configuration fil
## Using the GitLab Container Registry ## Using the GitLab Container Registry
> **Notes:**
>
> - This feature requires GitLab 8.8 and GitLab Runner 1.2.
> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
> to pass a [personal access token][pat] instead of your password in order to
> 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/packages/container_registry/index.md). [GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd).
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 `$CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to
push to the Registry connected to your project. Its password is automatically
set with the `$CI_REGISTRY_PASSWORD` 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:
```shell
docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $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:
```shell
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:
```shell
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
### Using docker-in-docker image from Container Registry
If you want to use your own Docker images for docker-in-docker there are a few things you need to do in addition to the steps in the [docker-in-docker](#use-docker-in-docker-workflow-with-docker-executor) section:
1. Update the `image` and `service` to point to your registry.
1. Add a service [alias](../yaml/README.md#servicesalias).
Below is an example of what your `.gitlab-ci.yml` should look like,
assuming you have it configured with [TLS enabled](#tls-enabled):
```yaml
build:
image: $CI_REGISTRY/group/project/docker:19.03.1
services:
- name: $CI_REGISTRY/group/project/docker:19.03.1-dind
alias: docker
variables:
# Specify to Docker where to create the certificates, Docker will
# create them automatically on boot, and will create
# `/certs/client` that will be shared between the service and
# build container.
DOCKER_TLS_CERTDIR: "/certs"
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
If you forget to set the service alias, the `docker:19.03.1` image won't find the
`dind` service, and an error like the following is thrown:
```shell
$ docker info
error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host
```
### Container Registry examples
If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml`
could look like:
```yaml
build:
image: docker:19.03.1
stage: build
services:
- docker:19.03.1-dind
variables:
# Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $CI_REGISTRY/group/project/image:latest .
- docker push $CI_REGISTRY/group/project/image:latest
```
You can also make use of [other variables](../variables/README.md) to avoid hardcoding:
```yaml
build:
image: docker:19.03.1
stage: build
services:
- docker:19.03.1-dind
variables:
# Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $IMAGE_TAG .
- docker push $IMAGE_TAG
```
Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied
to this project. Since `$CI_COMMIT_REF_NAME` resolves to the branch or tag name,
and your branch-name can contain forward slashes (e.g., feature/my-feature), it is
safer to use `$CI_COMMIT_REF_SLUG` as the image tag. This is due to that image tags
cannot contain forward slashes. We also declare our own variable, `$IMAGE_TAG`,
combining the two to save us some typing in the `script` section.
Here's a more elaborate example that splits up the tasks into 4 pipeline stages,
including two tests that run in parallel. The `build` is stored in the container
registry and used by subsequent stages, downloading the image
when needed. Changes to `master` also get tagged as `latest` and deployed using
an application-specific deploy script:
```yaml
image: docker:19.03.1
services:
- docker:19.03.1-dind
stages:
- build
- test
- release
- deploy
variables:
# Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
build:
stage: build
script:
- docker build --pull -t $CONTAINER_TEST_IMAGE .
- docker push $CONTAINER_TEST_IMAGE
test1:
stage: test
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker run $CONTAINER_TEST_IMAGE /script/to/run/tests
test2:
stage: test
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test
release-image:
stage: release
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
- docker push $CONTAINER_RELEASE_IMAGE
only:
- master
deploy:
stage: deploy
script:
- ./deploy.sh
only:
- master
```
NOTE: **Note:**
This example explicitly calls `docker pull`. If you prefer to implicitly pull the
built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html)
or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor,
make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work)
is set to `always`.
[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
[2fa]: ../../user/profile/account/two_factor_authentication.md
[pat]: ../../user/profile/personal_access_tokens.md
## Troubleshooting ## Troubleshooting
......
doc/development/architecture.md
View file @ c26add1e
...@@ -131,7 +131,7 @@ Component statuses are linked to configuration documentation for each component. ...@@ -131,7 +131,7 @@ Component statuses are linked to configuration documentation for each component.
| [GitLab Workhorse](#gitlab-workhorse) | Smart reverse proxy, handles large HTTP requests | [✅][workhorse-omnibus] | [✅][workhorse-charts] | [✅][workhorse-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][workhorse-source] | ✅ | CE & EE | | [GitLab Workhorse](#gitlab-workhorse) | Smart reverse proxy, handles large HTTP requests | [✅][workhorse-omnibus] | [✅][workhorse-charts] | [✅][workhorse-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][workhorse-source] | ✅ | CE & EE |
| [GitLab Shell](#gitlab-shell) | Handles `git` over SSH sessions | [✅][shell-omnibus] | [✅][shell-charts] | [✅][shell-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][shell-source] | [✅][gitlab-yml] | CE & EE | | [GitLab Shell](#gitlab-shell) | Handles `git` over SSH sessions | [✅][shell-omnibus] | [✅][shell-charts] | [✅][shell-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][shell-source] | [✅][gitlab-yml] | CE & EE |
| [GitLab Pages](#gitlab-pages) | Hosts static websites | [⚙][pages-omnibus] | [❌][pages-charts] | [❌][pages-charts] | [✅](../user/gitlab_com/index.md#gitlab-pages) | [⚙][pages-source] | [⚙][pages-gdk] | CE & EE | | [GitLab Pages](#gitlab-pages) | Hosts static websites | [⚙][pages-omnibus] | [❌][pages-charts] | [❌][pages-charts] | [✅](../user/gitlab_com/index.md#gitlab-pages) | [⚙][pages-source] | [⚙][pages-gdk] | CE & EE |
| [Registry](#registry) | Container registry, allows pushing and pulling of images | [⚙][registry-omnibus] | [✅][registry-charts] | [✅][registry-charts] | [✅](../user/packages/container_registry/index.md#build-and-push-images) | [⤓][registry-source] | [⚙][registry-gdk] | CE & EE | | [Registry](#registry) | Container registry, allows pushing and pulling of images | [⚙][registry-omnibus] | [✅][registry-charts] | [✅][registry-charts] | [✅](../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd) | [⤓][registry-source] | [⚙][registry-gdk] | CE & EE |
| [Redis](#redis) | Caching service | [✅][redis-omnibus] | [✅][redis-omnibus] | [✅][redis-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⤓][redis-source] | ✅ | CE & EE | | [Redis](#redis) | Caching service | [✅][redis-omnibus] | [✅][redis-omnibus] | [✅][redis-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⤓][redis-source] | ✅ | CE & EE |
| [PostgreSQL](#postgresql) | Database | [✅][postgres-omnibus] | [✅][postgres-charts] | [✅][postgres-charts] | [✅](../user/gitlab_com/index.md#postgresql) | [⤓][postgres-source] | ✅ | CE & EE | | [PostgreSQL](#postgresql) | Database | [✅][postgres-omnibus] | [✅][postgres-charts] | [✅][postgres-charts] | [✅](../user/gitlab_com/index.md#postgresql) | [⤓][postgres-source] | ✅ | CE & EE |
| [PgBouncer](#pgbouncer) | Database connection pooling, failover | [⚙][pgbouncer-omnibus] | [❌][pgbouncer-charts] | [❌][pgbouncer-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#database-architecture) | ❌ | ❌ | EE Only | | [PgBouncer](#pgbouncer) | Database connection pooling, failover | [⚙][pgbouncer-omnibus] | [❌][pgbouncer-charts] | [❌][pgbouncer-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#database-architecture) | ❌ | ❌ | EE Only |
......
doc/user/application_security/container_scanning/index.md
View file @ c26add1e
...@@ -46,17 +46,31 @@ To enable Container Scanning in your pipeline, you need: ...@@ -46,17 +46,31 @@ To enable Container Scanning in your pipeline, you need:
- Docker `18.09.03` or higher installed on the machine where the Runners are - Docker `18.09.03` or higher installed on the machine where the Runners are
running. If you're using the shared Runners on GitLab.com, this is already running. If you're using the shared Runners on GitLab.com, this is already
the case. the case.
- To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples) - To [build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd)
your Docker image to your project's [Container Registry](../../packages/container_registry/index.md). your Docker image to your project's Container Registry.
The name of the Docker image should match the following scheme: The name of the Docker image should use the following
[predefined environment variables](../../../ci/variables/predefined_variables.md)
as defined below:
```text ```text
$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
``` ```
The variables above can be found in the These can be used directly in your `.gitlab-ci.yml` file:
[predefined environment variables](../../../ci/variables/predefined_variables.md)
document. ```yaml
build:
image: docker:19.03.1
stage: build
services:
- docker:19.03.1-dind
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_REF_SHA
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $IMAGE_TAG .
- docker push $IMAGE_TAG
```
## Configuration ## Configuration
......
doc/user/packages/container_registry/index.md
View file @ c26add1e
...@@ -43,15 +43,27 @@ project: ...@@ -43,15 +43,27 @@ project:
1. Press **Save changes** for the changes to take effect. You should now be able 1. Press **Save changes** for the changes to take effect. You should now be able
to see the **Packages > Container Registry** link in the sidebar. to see the **Packages > Container Registry** link in the sidebar.
## Build and push images ## Control Container Registry from within GitLab
GitLab offers a simple Container Registry management panel. Go to your project
and click **Packages > Container Registry** in the project menu.
This view will show you all Docker images in your project and will easily allow you to
delete them.
## Use images from GitLab Container Registry
To download and run a container from images hosted in GitLab Container Registry,
use `docker run`:
```shell
docker run [options] registry.example.com/group/project/image [arguments]
```
For more information on running Docker containers, visit the
[Docker documentation](https://docs.docker.com/engine/userguide/intro/).
> **Notes:** ## Authenticating to the GitLab Container Registry
>
> - Moving or renaming existing container registry repositories is not supported
> once you have pushed images because the images are signed, and the
> signature includes the repository name.
> - To move or rename a repository with a container registry you will have to
> delete all existing images.
If you visit the **Packages > Container Registry** link under your project's If you visit the **Packages > Container Registry** link under your project's
menu, you can see the explicit instructions to login to the Container Registry menu, you can see the explicit instructions to login to the Container Registry
...@@ -64,6 +76,28 @@ able to login with: ...@@ -64,6 +76,28 @@ able to login with:
docker login registry.example.com docker login registry.example.com
``` ```
NOTE: **Note:**
If you have [2 Factor Authentication](../../profile/account/two_factor_authentication.md)
enabled in your account, you need to pass a
[personal access token](../../profile/personal_access_tokens.md) instead
of your password in order to login to GitLab's Container Registry.
If a project is private, credentials will need to be provided for authorization.
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 minimum scope needed for both of them is `read_registry`.
Example of using a token:
```sh
docker login registry.example.com -u <username> -p <token>
```
## Build and push images from your local machine
Building and publishing images should be a straightforward process. Just make Building and publishing images should be a straightforward process. Just make
sure that you are using the Registry URL with the namespace and project name sure that you are using the Registry URL with the namespace and project name
that is hosted on GitLab: that is hosted on GitLab:
...@@ -80,8 +114,7 @@ Your image will be named after the following scheme: ...@@ -80,8 +114,7 @@ Your image will be named after the following scheme:
``` ```
GitLab supports up to three levels of image repository names. GitLab supports up to three levels of image repository names.
The following examples of image tags are valid:
Following examples of image tags are valid:
```text ```text
registry.example.com/group/project:some-tag registry.example.com/group/project:some-tag
...@@ -89,53 +122,211 @@ registry.example.com/group/project/image:latest ...@@ -89,53 +122,211 @@ registry.example.com/group/project/image:latest
registry.example.com/group/project/my/image:rc1 registry.example.com/group/project/my/image:rc1
``` ```
## Use images from GitLab Container Registry ## Build and push images using GitLab CI/CD
To download and run a container from images hosted in GitLab Container Registry, While you can build and push your images from your local machine, the true
use `docker run`: power of the Container Registry comes when you combine it with GitLab CI/CD.
You can then create workflows and automate any processes that involve testing,
```shell building, and eventually deploying your project from the Docker image you
docker run [options] registry.example.com/group/project/image [arguments] created.
```
Before diving into the details, some things you should be aware of:
For more information on running Docker containers, visit the
[Docker documentation](https://docs.docker.com/engine/userguide/intro/). - You must [authenticate to the container registry](#authenticating-to-the-container-registry-with-gitlab-cicd)
before running any 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 in case your cache is stale. It takes slightly
longer, but it means you don’t get stuck without security patches for 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 with GitLab CI/CD
There are three ways to authenticate to the Container Registry via
[GitLab CI/CD](../../../ci/yaml/README.md) which depend on the visibility of
your project.
Available for all projects, though more suitable for public ones:
- **Using the special `CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to
push to the Registry connected to your project. Its password is automatically
set with the `CI_REGISTRY_PASSWORD` 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 $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
```
## Control Container Registry from within GitLab For private and internal projects:
GitLab offers a simple Container Registry management panel. Go to your project - **Using a personal access token**: You can create and use a
and click **Packages > Container Registry** in the project menu. [personal access token](../../profile/personal_access_tokens.md)
in case your project is private:
This view will show you all tags in your project and will easily allow you to - For read (pull) access, the scope should be `read_registry`.
delete them. - For read/write (pull/push) access, use `api`.
## Build and push images using GitLab CI Replace the `<username>` and `<access_token>` in the following example:
NOTE: **Note:** ```sh
This feature requires GitLab 8.8 and GitLab Runner 1.2. docker login -u <username> -p <access_token> $CI_REGISTRY
```
Make sure that your GitLab Runner is configured to allow building Docker images by - **Using the GitLab Deploy Token**: You can create and use a
following the [Using Docker Build](../../../ci/docker/using_docker_build.md) [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token)
and [Using the GitLab Container Registry documentation](../../../ci/docker/using_docker_build.md#using-the-gitlab-container-registry). with your private projects. It provides read-only (pull) access to the Registry.
Alternatively, you can [build images with Kaniko](../../../ci/docker/using_kaniko.md) if the Docker builds are not an option for you. 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:
## Using with private projects ```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
> Personal Access tokens were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/11845) in GitLab 9.3. ### Container Registry examples with GitLab CI/CD
> Project Deploy Tokens were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/17894) in GitLab 10.7
If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml`
should look similar to this:
```yaml
build:
image: docker:19.03.1
stage: build
services:
- docker:19.03.1-dind
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $CI_REGISTRY/group/project/image:latest .
- docker push $CI_REGISTRY/group/project/image:latest
```
If a project is private, credentials will need to be provided for authorization. You can also make use of [other variables](../../../ci/variables/README.md) to avoid hardcoding:
There are two ways to do this:
```yaml
build:
image: docker:19.03.1
stage: build
services:
- docker:19.03.1-dind
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $IMAGE_TAG .
- docker push $IMAGE_TAG
```
- By using a [personal access token](../../profile/personal_access_tokens.md). Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied
- By using a [deploy token](../../project/deploy_tokens/index.md). to this project. Since `$CI_COMMIT_REF_NAME` resolves to the branch or tag name,
and your branch-name can contain forward slashes (e.g., feature/my-feature), it is
safer to use `$CI_COMMIT_REF_SLUG` as the image tag. This is due to that image tags
cannot contain forward slashes. We also declare our own variable, `$IMAGE_TAG`,
combining the two to save us some typing in the `script` section.
Here's a more elaborate example that splits up the tasks into 4 pipeline stages,
including two tests that run in parallel. The `build` is stored in the container
registry and used by subsequent stages, downloading the image
when needed. Changes to `master` also get tagged as `latest` and deployed using
an application-specific deploy script:
```yaml
image: docker:19.03.1
services:
- docker:19.03.1-dind
stages:
- build
- test
- release
- deploy
variables:
# Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
build:
stage: build
script:
- docker build --pull -t $CONTAINER_TEST_IMAGE .
- docker push $CONTAINER_TEST_IMAGE
test1:
stage: test
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker run $CONTAINER_TEST_IMAGE /script/to/run/tests
test2:
stage: test
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test
release-image:
stage: release
script:
- docker pull $CONTAINER_TEST_IMAGE
- docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
- docker push $CONTAINER_RELEASE_IMAGE
only:
- master
deploy:
stage: deploy
script:
- ./deploy.sh
only:
- master
```
The minimal scope needed for both of them is `read_registry`. NOTE: **Note:**
This example explicitly calls `docker pull`. If you prefer to implicitly pull the
built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html)
or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor,
make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work)
is set to `always`.
### Using a docker-in-docker image from your Container Registry
If you want to use your own Docker images for docker-in-docker, there are a few
things you need to do in addition to the steps in the
[docker-in-docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) section:
1. Update the `image` and `service` to point to your registry.
1. Add a service [alias](../../../ci/yaml/README.md#servicesalias).
Below is an example of what your `.gitlab-ci.yml` should look like:
```yaml
build:
image: $CI_REGISTRY/group/project/docker:19.03.1
services:
- name: $CI_REGISTRY/group/project/docker:19.03.1-dind
alias: docker
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
Example of using a token: If you forget to set the service alias, the `docker:19.03.1` image won't find the
`dind` service, and an error like the following will be thrown:
```shell ```plaintext
docker login registry.example.com -u <username> -p <token> error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host
``` ```
## Expiration policy ## Expiration policy
...@@ -179,6 +370,13 @@ The UI allows you to configure the following: ...@@ -179,6 +370,13 @@ The UI allows you to configure the following:
- **Expiration latest:** how many tags to _always_ keep for each image. - **Expiration latest:** how many tags to _always_ keep for each image.
- **Docker tags with names matching this regex pattern will expire:** the regex used to determine what tags should be expired. To qualify all tags for expiration, use the default value of `.*`. - **Docker tags with names matching this regex pattern will expire:** the regex used to determine what tags should be expired. To qualify all tags for expiration, use the default value of `.*`.
## Limitations
Moving or renaming existing Container Registry repositories is not supported
once you have pushed images, because the images are signed, and the
signature includes the repository name. To move or rename a repository with a
Container Registry, you will have to delete all existing images.
## Troubleshooting the GitLab Container Registry ## Troubleshooting the GitLab Container Registry
### Docker connection error ### Docker connection error
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7