diff options
Diffstat (limited to 'doc/user/packages/container_registry/index.md')
| -rw-r--r-- | doc/user/packages/container_registry/index.md | 45 |
1 files changed, 26 insertions, 19 deletions
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 1cb6c951bd9..4e8d105adfa 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Container Registry @@ -16,6 +16,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - 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: +If you pull container images from Docker Hub, you can also use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid running into rate limits and speed up your pipelines. + With the Docker Container Registry integrated into GitLab, every GitLab project can have its own space to store its Docker images. @@ -127,7 +130,7 @@ To build and push to the Container Registry: docker push registry.example.com/group/project/image ``` -You can also view these commands by going to your project's **Packages & Registries > Container Registry**. +To view these commands, go to your project's **Packages & Registries > Container Registry**. ## Build and push by using GitLab CI/CD @@ -291,7 +294,7 @@ deploy: - master ``` -NOTE: **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, @@ -332,11 +335,11 @@ error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker You can delete images from your Container Registry in multiple ways. -CAUTION: **Warning:** +WARNING: Deleting images is a destructive action and can't be undone. To restore a deleted image, you must rebuild and re-upload it. -NOTE: **Note:** +NOTE: Administrators should review how to [garbage collect](../../../administration/packages/container_registry.md#container-registry-garbage-collection) the deleted images. @@ -368,7 +371,7 @@ information, see the following endpoints: ### Delete images using GitLab CI/CD -CAUTION: **Warning:** +WARNING: GitLab CI/CD doesn't provide a built-in way to remove your images, but this example uses a third-party tool called [reg](https://github.com/genuinetools/reg) that talks to the GitLab Registry API. You are responsible for your own actions. @@ -426,7 +429,7 @@ delete_image: - master ``` -TIP: **Tip:** +NOTE: You can download the latest `reg` release from [the releases page](https://github.com/genuinetools/reg/releases), then update the code example by changing the `REG_SHA256` and `REG_VERSION` variables @@ -489,6 +492,8 @@ Cleanup policies can be run on all projects, with these exceptions: The cleanup policy collects all tags in the Container Registry and excludes tags until only the tags to be deleted remain. +The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. + The cleanup policy: 1. Collects all tags for a given repository in a list. @@ -501,7 +506,7 @@ The cleanup policy: 1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. -CAUTION: **Warning:** +WARNING: On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, so it may take multiple runs for all tags to be deleted. @@ -513,29 +518,31 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: 1. For your project, go to **Settings > CI/CD**. -1. Expand the **Cleanup policy for tags** section. +1. Expand the **Clean up image tags** section. 1. Complete the fields. | Field | Description | |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| - | **Cleanup policy** | Turn the policy on or off. | - | **Expiration interval** | How long tags are exempt from being deleted. | - | **Expiration schedule** | How often the policy should run. | - | **Number of tags to retain** | How many tags to _always_ keep for each image. | - | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | - | **Tags with names matching this regex pattern are preserved:** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Toggle** | Turn the policy on or off. | + | **Run cleanup** | How often the policy should run. | + | **Keep the most recent** | How many tags to _always_ keep for each image. | + | **Keep tags matching** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Remove tags older than** | Remove only tags older than X days. | + | **Remove tags matching** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | -1. Click **Set cleanup policy**. +1. Click **Save**. Depending on the interval you chose, the policy is scheduled to run. -NOTE: **Note:** -If you edit the policy and click **Set cleanup policy** again, the interval is reset. +NOTE: +If you edit the policy and click **Save** again, the interval is reset. ### Regex pattern examples Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. +Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. + Here are examples of regex patterns you may want to use: - Match all tags: @@ -573,7 +580,7 @@ Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" ``` See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). |