diff options
Diffstat (limited to 'doc/user/packages/container_registry/index.md')
| -rw-r--r-- | doc/user/packages/container_registry/index.md | 342 |
1 files changed, 169 insertions, 173 deletions
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 077666bc036..baadd3c91a7 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -9,235 +9,186 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker > versions earlier than 1.10. -> - Starting from GitLab 8.12, if you have 2FA 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. -> - Multiple level image names support was added in GitLab 9.1. -> - The group level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10. +> - Starting in GitLab 8.12, if you have [two-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 to +> sign in to the Container Registry. +> - Support for multiple level image names was added in GitLab 9.1. +> - The group-level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10. > - Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. -NOTE: **Note:** -This document is the user guide. To learn how to enable GitLab Container -Registry across your GitLab instance, visit the -[administrator documentation](../../../administration/packages/container_registry.md). - -With the Docker Container Registry integrated into GitLab, every project can +With the Docker Container Registry integrated into GitLab, every GitLab project can have its own space to store its Docker images. You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. - - -## Enable the Container Registry for your project - -CAUTION: **Warning:** -The Container Registry follows the visibility settings of the project. If the project is public, so is the Container Registry. - -If you cannot find the **Packages & Registries > Container Registry** entry under your -project's sidebar, it is not enabled in your GitLab instance. Ask your -administrator to enable GitLab Container Registry following the -[administration documentation](../../../administration/packages/container_registry.md). +This document is the user guide. To learn how to enable the Container +Registry for your GitLab instance, visit the +[administrator documentation](../../../administration/packages/container_registry.md). -If you are using GitLab.com, this is enabled by default so you can start using -the Registry immediately. Currently there is a soft (10GB) size restriction for -Registry on GitLab.com, as part of the [repository size limit](../../project/repository/index.md). +## View the Container Registry -Once enabled for your GitLab instance, to enable Container Registry for your -project: +You can view the Container Registry for a project or group. -1. Go to your project's **Settings > General** page. -1. Expand the **Visibility, project features, permissions** section - and enable the **Container Registry** feature on your project. For new - projects this might be enabled by default. For existing projects - (prior GitLab 8.8), enable it explicitly. -1. Press **Save changes** for the changes to take effect. You should now be able - to see the **Packages & Registries > Container Registry** link in the sidebar. +1. Go to your project or group. +1. Go to **Packages & Registries > Container Registry**. -## Control Container Registry from within GitLab +You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) containers on this page. -GitLab offers a simple Container Registry management panel. This management panel is available -for both projects and groups. +Only members of the project or group can access a private project's Container Registry. -### Control Container Registry for your project +If a project is public, so is the Container Registry. -Navigate to your project's **{package}** **Packages & Registries > Container Registry**. +## Use images from the Container Registry - +To download and run a container image hosted in the GitLab Container Registry: -This view allows you to: +1. Copy the link to your container image: + - Go to your project or group's **Packages & Registries > Container Registry** + and find the image you want. + - Next to the image name, click the **Copy** button. -- Show all the image repositories that belong to the project. -- Filter image repositories by their name. -- [Delete](#delete-images-from-within-gitlab) one or more image repository. -- Navigate to the image repository details page. -- Show a **Quick start** dropdown with the most common commands to log in, build and push. -- Show a banner if the optional [cleanup policy](#cleanup-policy) is enabled for this project. +  -### Control Container Registry for your group +1. Use `docker run` with the image link: -Navigate to your group's **{package}** **Packages & Registries > Container Registry**. + ```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/). -This view allows you to: +## Image naming convention -- Show all the image repositories of the projects that belong to this group. -- [Delete](#delete-images-from-within-gitlab) one or more image repositories. -- Navigate to a specific image repository details page. +Images follow this naming convention: -### Image Repository details page +```plaintext +<registry URL>/<namespace>/<project>/<image> +``` -Clicking on the name of any image repository navigates to the details. +If your project is `gitlab.example.com/mynamespace/myproject`, for example, +then your image must be named `gitlab.example.com/mynamespace/myproject/my-app` at a minimum. - +You can append additional names to the end of an image name, up to three levels deep. -NOTE: **Note:** -The following page has the same functionalities both in the **Group level container registry** -and in the **Project level container registry**. +For example, these are all valid image names for images within the project named `myproject`: -This view: +```plaintext +registry.example.com/mynamespace/myproject:some-tag +``` -- Shows all the image repository details. -- Shows all the tags of the image repository. -- Allows you to quickly copy the tag path (by clicking on the clipboard button near the tag name). -- Allows you to [delete one or more tags](#delete-images-from-within-gitlab). +```plaintext +registry.example.com/mynamespace/myproject/image:latest +``` -## Use images from GitLab Container Registry +```plaintext +registry.example.com/mynamespace/myproject/my/image:rc1 +``` -To download and run a container from images hosted in GitLab Container Registry, -use `docker run`: +## Build and push images by using Docker commands -```shell -docker run [options] registry.example.com/group/project/image [arguments] -``` +To build and push to the Container Registry, you can use Docker commands. -For more information on running Docker containers, visit the -[Docker documentation](https://docs.docker.com/engine/userguide/intro/). +### Authenticate with the Container Registry -## Authenticating to the GitLab Container Registry +Before you can build and push images, you must authenticate with the Container Registry. -If you visit the **Packages & Registries > Container Registry** link under your project's -menu, you can see the explicit instructions to login to the Container Registry -using your GitLab credentials. +To authenticate, you can use: -For example if the Registry's URL is `registry.example.com`, then you should be -able to login with: +- A [personal access token](../../profile/personal_access_tokens.md). +- A [deploy token](../../project/deploy_tokens/index.md). -```shell -docker login registry.example.com -``` +Both of these require the minimum scope to be: -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. +- For read (pull) access, `read_registry`. +- For write (push) access, `write_registry`. -Credentials must be provided for authorization to any non-public registry. Only project members can access private, -GitLab-hosted registries. +To authenticate, run the `docker` command. For example: -There are two ways to authenticate: + ```shell + docker login registry.example.com -u <username> -p <token> + ``` -- By using a [personal access token](../../profile/personal_access_tokens.md). -- By using a [deploy token](../../project/deploy_tokens/index.md). +### Build and push images by using Docker commands -The minimum scope needed for both of them is `read_registry`. +To build and push to the Container Registry: -Example of using a token: +1. Authenticate with the Container Registry. -```shell -docker login registry.example.com -u <username> -p <token> -``` +1. Run the command to build or push. For example, to build: -## Build and push images from your local machine + ```shell + docker build -t registry.example.com/group/project/image . + ``` -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 -that is hosted on GitLab: + Or to push: -```shell -docker build -t registry.example.com/group/project/image . -docker push registry.example.com/group/project/image -``` + ```shell + docker push registry.example.com/group/project/image + ``` -Your image is named after the following scheme: +You can also view these commands by going to your project's **Packages & Registries > Container Registry**. -```plaintext -<registry URL>/<namespace>/<project>/<image> -``` +## Build and push by using GitLab CI/CD -GitLab supports up to three levels of image repository names. -The following examples of image tags are valid: +Use [GitLab CI/CD](../../../ci/yaml/README.md) to build and push images to the +Container Registry. Use it to test, build, and deploy your project from the Docker +image you created. -```plaintext -registry.example.com/group/project:some-tag -registry.example.com/group/project/image:latest -registry.example.com/group/project/my/image:rc1 -``` +### Authenticate by using GitLab CI/CD -## Build and push images using GitLab CI/CD - -While you can build and push your images from your local machine, take -full advantage of the Container Registry by combining it with GitLab CI/CD. -You can then create workflows and automate any processes that involve testing, -building, and eventually deploying your project from the Docker image you -created. - -Before diving into the details, some things you should be aware of: - -- 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 is 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. +Before you can build and push images by using GitLab CI/CD, you must authenticate with the Container Registry. -### Authenticating to the Container Registry with GitLab CI/CD +To use CI/CD to authenticate, you can use: -There are three ways to authenticate to the Container Registry via -[GitLab CI/CD](../../../ci/yaml/README.md): +- The `CI_REGISTRY_USER` variable. -- **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: + This variable has read-write access to the Container Registry and is valid for + one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. ```shell docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -- **Using the GitLab Deploy Token**: You can create and use a - [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) - with your projects. - Once created, you can use the special environment variables, and GitLab CI/CD - fills them in for you. You can use the following example as-is: +- A [CI job token](../../../ci/triggers/README.md#ci-job-token). ```shell - docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY ``` -- **Using a personal access token**: You can create and use a - [personal access token](../../profile/personal_access_tokens.md) - in case your project is private: +- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. - - For read (pull) access, the scope should be `read_registry`. - - For write (push) access, the scope should be `write_registry`. + ```shell + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` - Replace the `<username>` and `<access_token>` in the following example: +- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. ```shell docker login -u <username> -p <access_token> $CI_REGISTRY ``` +### Configure your `.gitlab-ci.yml` file + +You can configure your `.gitlab-ci.yml` file to build and push images to the Container Registry. + +- If multiple jobs require authentication, put the authentication command in the `before_script`. +- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly + longer, but it ensures your image is up-to-date. +- Before each `docker run`, do an explicit `docker pull` to fetch + the image that was just built. This is especially important if you are + using multiple runners that cache images locally. + + If you use the Git SHA in your image tag, each job is unique and you + should never 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. +- Don't build directly to the `latest` tag because multiple jobs may be + happening simultaneously. + ### Container Registry examples with GitLab CI/CD If you're using Docker-in-Docker on your runners, this is how your `.gitlab-ci.yml` @@ -359,15 +310,15 @@ in addition to the steps in the Below is an example of what your `.gitlab-ci.yml` should look like: ```yaml - build: - image: $CI_REGISTRY/group/project/docker:19.03.12 - services: - - name: $CI_REGISTRY/group/project/docker:19.03.12-dind - alias: docker - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests +build: + image: $CI_REGISTRY/group/project/docker:19.03.12 + services: + - name: $CI_REGISTRY/group/project/docker:19.03.12-dind + alias: docker + 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.12` image is unable to find the @@ -394,7 +345,7 @@ the deleted images. To delete images from within GitLab: -1. Navigate to your project's or group's **{package}** **Packages & Registries > Container Registry**. +1. Navigate to your project's or group's **Packages & Registries > Container Registry**. 1. From the **Container Registry** page, you can select what you want to delete, by either: @@ -406,8 +357,6 @@ To delete images from within GitLab: 1. In the dialog box, click **Remove tag**. -  - ### Delete images using the API If you want to automate the process of deleting images, GitLab provides an API. For more @@ -512,9 +461,28 @@ Cleanup policies can be run on all projects, with these exceptions: for all projects (even those created before 12.8) in [GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true. + Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) + ``` There are performance risks with enabling it for all projects, especially if you are using an [external registry](./index.md#use-with-external-container-registries). +- For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific + project. + + To enable it: + + ```ruby + Feature.enable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` + + To disable it: + + ```ruby + Feature.disable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` ### How the cleanup policy works @@ -636,7 +604,7 @@ you can use the Container Registry to store Helm Charts. However, due to the way and stored by Docker, it is not possible for GitLab to parse this data and meet performance standards. [This epic](https://gitlab.com/groups/gitlab-org/-/epics/2313) updates the architecture of the Container Registry to support Helm Charts. -You can read more about the above challenges [here](https://gitlab.com/gitlab-org/gitlab/-/issues/38047#note_298842890). +[Read more about the above challenges](https://gitlab.com/gitlab-org/gitlab/-/issues/38047#note_298842890). ## Limitations @@ -647,6 +615,19 @@ Container Registry, you must delete all existing images. - Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag are not deleted by the cleanup policy. +## Disable the Container Registry for a project + +The Container Registry is enabled by default. + +You can, however, remove the Container Registry for a project: + +1. Go to your project's **Settings > General** page. +1. Expand the **Visibility, project features, permissions** section + and disable **Container Registry**. +1. Click **Save changes**. + +The **Packages & Registries > Container Registry** entry is removed from the project's sidebar. + ## Troubleshooting the GitLab Container Registry ### Docker connection error @@ -661,6 +642,21 @@ To get around this, you can [change the group path](../../group/index.md#changin [change the project path](../../project/settings/index.md#renaming-a-repository) or change the branch name. +You may also get a `404 Not Found` or `Unknown Manifest` message if you are using +a Docker Engine version earlier than 17.12. Later versions of Docker Engine use +[the v2 API](https://docs.docker.com/registry/spec/manifest-v2-2/). + +The images in your GitLab Container Registry must also use the Docker v2 API. +For information on how to update your images, see the [Docker help](https://docs.docker.com/registry/spec/deprecated-schema-v1). + +### `Blob unknown to registry` error when pushing a manifest list + +When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) to the GitLab Container Registry, you may receive the error `manifest blob unknown: blob unknown to registry`. This issue occurs when the individual child manifests referenced in the manifest list were not pushed to the same repository. + +For example, you may have two individual images, one for `amd64` and another for `arm64v8`, and you want to build a multi-arch image with them. The `amd64` and `arm64v8` images must be pushed to the same repository where you want to push the multi-arch image. + +As a workaround, you should include the architecture in the tag name of individual images. For example, use `mygroup/myapp:1.0.0-amd64` instead of using sub repositories, like `mygroup/myapp/amd64:1.0.0`. You can then tag the manifest list with `mygroup/myapp:1.0.0`. + ### Troubleshoot as a GitLab server admin Troubleshooting the GitLab Container Registry, most of the times, requires |