Commit 13f66deb authored by Evan Read's avatar Evan Read

Merge branch 'selhorn-cleanuppolicies' into 'master'

Docs: Change "expiration policy" to "cleanup policy"

See merge request gitlab-org/gitlab!34014
parents 00cf510d d81bf91e
......@@ -1052,7 +1052,7 @@ POST /projects
| `show_default_award_emojis` | boolean | no | Show default award emojis |
| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `container_expiration_policy_attributes` | hash | no | Update the image expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
| `container_expiration_policy_attributes` | hash | no | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
| `import_url` | string | no | URL to import repository from |
......@@ -1193,7 +1193,7 @@ PUT /projects/:id
| `show_default_award_emojis` | boolean | no | Show default award emojis |
| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `container_expiration_policy_attributes` | hash | no | Update the image expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
| `container_expiration_policy_attributes` | hash | no | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
| `import_url` | string | no | URL to import repository from |
......
......@@ -71,7 +71,7 @@ This view will:
- Allow you to [delete](#delete-images-from-within-gitlab) one or more image repository.
- Allow you to navigate to the image repository details page.
- Show a **Quick start** dropdown with the most common commands to log in, build and push
- Optionally, a banner will be visible if the [expiration policy](#expiration-policy) is enabled for this project.
- Optionally, a banner will be visible if the [cleanup policy](#cleanup-policy) is enabled for this project.
### Control Container Registry for your group
......@@ -486,29 +486,33 @@ You can download the latest `reg` release from
the code example by changing the `REG_SHA256` and `REG_VERSION` variables
defined in the `delete_image` job.
### Delete images using an expiration policy
### Delete images by using a cleanup policy
You can create a per-project [expiration policy](#expiration-policy) to ensure
older tags and images are regularly removed from the Container Registry.
You can create a per-project [cleanup policy](#cleanup-policy) to ensure older tags and images are regularly removed from the
Container Registry.
## Expiration policy
## Cleanup policy
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8.
> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2.
For a specific project, if you want to remove tags you no longer need,
you can create an expiration policy. When the policy is applied, tags matching the regex pattern are removed.
you can create a cleanup policy. When the policy is applied, tags matching the regex pattern are removed.
The underlying layers and images remain.
To delete the underlying layers and images no longer associated with any tags, Instance Administrators can use
[garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch.
NOTE: **Note:**
For GitLab.com, expiration policies are not available for projects created before GitLab 12.8.
For self-managed instances, expiration policies may be enabled by an admin in the
For GitLab.com, cleanup policies are not available for projects created
before this feature was deployed to production (February 2020).
Support for pre-existing projects on GitLab.com
[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124).
For self-managed instances, cleanup policies may be enabled by an admin in the
[CI/CD Package Registry settings](./../../admin_area/settings/index.md#cicd).
Note the inherent [risks involved](./index.md#use-with-external-container-registries).
The expiration policy algorithm starts by collecting all the tags for a given repository in a list,
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.
......@@ -517,43 +521,41 @@ then goes through a process of excluding tags from it until only the ones to be
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 (Expiration interval).
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.
### Managing project expiration policy through the UI
### Managing project cleanup policy through the UI
To manage project expiration policy, navigate to **{settings}** **Settings > CI/CD > Container Registry tag expiration policy**.
![Expiration Policy App](img/expiration_policy_app_v13_0.png)
To manage project cleanup policy, navigate to **{settings}** **Settings > CI/CD > Container Registry tag cleanup policy**.
The UI allows you to configure the following:
- **Expiration policy:** enable or disable the expiration policy.
- **Expiration interval:** how long tags are exempt from being deleted.
- **Expiration schedule:** how often the cron job checking the tags should run.
- **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 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 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 `.*`.
#### Troubleshooting expiration policies
#### Troubleshooting cleanup policies
If you see the following message:
"Something went wrong while updating the expiration policy."
"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).
### Managing project expiration policy through the API
### Managing project cleanup policy through the API
You can set, update, and disable the expiration policies using the GitLab 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, expire any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled:
- 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'
......@@ -564,15 +566,15 @@ See the API documentation for further details: [Edit project](../../../api/proje
### 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 an expiration policy on a project may have some performance risks. If a project is going to run
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 expiration
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.
### Regex pattern examples
Expiration policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API.
Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API.
Here are examples of regex patterns you may want to use:
......@@ -616,7 +618,7 @@ 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.
- Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag
will not be deleted by the expiration policy.
will not be deleted by the cleanup policy.
## Troubleshooting the GitLab Container Registry
......
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