For self-managed instances, cleanup policies may be enabled by an admin in the
[GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true.
Note the inherent [risks involved](./index.md#use-with-external-container-registries).
The cleanup policy algorithm starts by collecting all the tags for a given repository in a list,
then goes through a process of excluding tags from it until only the ones to be deleted remain:
1. Collect all the tags for a given repository in a list.
1. Excludes the tag named `latest` from the list.
1. Evaluates the `name_regex`, excluding non-matching names from the list.
1. Excludes any tags that do not have a manifest (not part of the options).
1. Orders the remaining tags by `created_date`.
1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain).
1. Excludes from the list the tags more recent than the `older_than` value (Cleanup interval).
1. Excludes from the list any tags matching the `name_regex_keep` value (Images to preserve).
1. Finally, the remaining tags in the list are deleted from the Container Registry.
### Enable the cleanup policy
### Managing project cleanup policy through the UI
The cleanup policy is enabled for all projects by default.
To manage project cleanup policy, navigate to **{settings}****Settings > CI/CD > Container Registry tag cleanup policy**.
- For GitLab.com, the project must have been created before February, 2020.
by setting `container_expiration_policies_enable_historic_entries` to true.
-**Cleanup policy:** enable or disable the cleanup policy.
-**Cleanup interval:** how long tags are exempt from being deleted.
-**Cleanup schedule:** how often the cron job checking the tags should run.
-**Number of tags to retain:** 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 cleaned up. To qualify all tags for cleanup, use the default value of `.*`.
-**Docker tags with names matching this regex pattern will be preserved:** the regex used to determine what tags should be preserved. To preserve all tags, use the default value of `.*`.
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).
#### Troubleshooting cleanup policies
### How the cleanup policy works
If you see the following message:
The cleanup policy collects all tags in the Container Registry and excludes tags
until only the tags to be deleted remain.
"Something went wrong while updating the cleanup policy."
The cleanup policy:
Check the regex patterns to ensure they are valid.
1. Collects all tags for a given repository in a list.
1. Excludes the tag named `latest` from the list.
1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list.
1. Excludes any tags that do not have a manifest (not part of the options in the UI).
1. Orders the remaining tags by `created_date`.
1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain).
1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval).
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.
You can use [Rubular](https://rubular.com/) to check your regex.
View some common [regex pattern examples](#regex-pattern-examples).
### Create a cleanup policy
### Managing project cleanup policy through the API
You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI.
You can set, update, and disable the cleanup policies using the GitLab API.
To create a cleanup policy in the UI:
Examples:
1. For your project, go to **Settings > CI/CD**.
1. Expand the **Cleanup policy for tags** section.
1. Complete the fields.
- 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'
| **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 will expire:** | The regex pattern that determines which tags to remove. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). |
| **Tags with names matching this regex pattern will be 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). |
See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project).
1. Click **Set cleanup policy**.
### Use with external container registries
Depending on the interval you chose, the policy is scheduled to run.
When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint),
running a cleanup policy on a project may have some performance risks. If a project is going to run
a policy that will remove large quantities of tags (in the thousands), the GitLab background jobs that
run the policy may get backed up or fail completely. It is recommended you only enable container cleanup
policies for projects that were created before GitLab 12.8 if you are confident the amount of tags
being cleaned up will be minimal.
NOTE: **Note:**
If you edit the policy and click **Set cleanup policy** again, the interval is reset.
### Regex pattern examples
...
...
@@ -602,6 +593,40 @@ Here are examples of regex patterns you may want to use:
(?:v.+|master|release)
```
### Use the cleanup policy API
You can set, update, and disable the cleanup policies using the GitLab API.
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'
```
See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project).
### Use with external container registries
When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint),
running a cleanup policy on a project may have some performance risks. If a project is going to run
a policy that will remove large quantities of tags (in the thousands), the GitLab background jobs that
run the policy may get backed up or fail completely. It is recommended you only enable container cleanup
policies for projects that were created before GitLab 12.8 if you are confident the amount of tags
being cleaned up will be minimal.
### Troubleshooting cleanup policies
If you see the following message:
"Something went wrong while updating the cleanup policy."
Check the regex patterns to ensure they are valid.
You can use [Rubular](https://rubular.com/) to check your regex.
View some common [regex pattern examples](#regex-pattern-examples).
## Use the Container Registry to store Helm Charts
With the launch of [Helm v3](https://helm.sh/docs/topics/registries/),
