Add latest changes from gitlab-org/gitlab@13-3-stable-ee

1 files changed, 124 insertions, 102 deletions

diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index 429d29b7677..f46ad99e573 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -49,7 +49,7 @@ project:
 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), you will have to explicitly enable it.
+   (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.
 
@@ -64,14 +64,14 @@ Navigate to your project's **{package}** **Packages & Registries > Container Reg
 
 ![Container Registry project repositories](img/container_registry_repositories_with_quickstart_v13_1.png)
 
-This view will:
+This view allows you to:
 
 - Show all the image repositories that belong to the project.
-- Allow you to filter image repositories by their name.
-- Allow you to [delete](#delete-images-from-within-gitlab) one or more image repository.
-- Allow you to navigate to the image repository details page.
+- 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
-- Optionally, a banner will be visible if the [cleanup policy](#cleanup-policy) is enabled for this project.
+- Show a banner if the optional [cleanup policy](#cleanup-policy) is enabled for this project.
 
 ### Control Container Registry for your group
 
@@ -79,15 +79,15 @@ Navigate to your groups's **{package}** **Packages & Registries > Container Regi
 
 ![Container Registry group repositories](img/container_registry_group_repositories_v13_1.png)
 
-This view will:
+This view allows you to:
 
 - Show all the image repositories of the projects that belong to this group.
-- Allow to [delete](#delete-images-from-within-gitlab) one or more image repositories.
-- Allow to navigate to a specific image repository details page.
+- [Delete](#delete-images-from-within-gitlab) one or more image repositories.
+- Navigate to a specific image repository details page.
 
 ### Image Repository details page
 
-Clicking on the name of any image repository will navigate to the details.
+Clicking on the name of any image repository navigates to the details.
 
 ![Container Registry project repository details](img/container_registry_repository_details_v13.0.png)
 
@@ -133,8 +133,10 @@ 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:
+Credentials must be provided for authorization to any non-public registry. Only project members can access private,
+GitLab-hosted registries.
+
+There are two ways to authenticate:
 
 - By using a [personal access token](../../profile/personal_access_tokens.md).
 - By using a [deploy token](../../project/deploy_tokens/index.md).
@@ -158,7 +160,7 @@ docker build -t registry.example.com/group/project/image .
 docker push registry.example.com/group/project/image
 ```
 
-Your image will be named after the following scheme:
+Your image is named after the following scheme:
 
 ```plaintext
 <registry URL>/<namespace>/<project>/<image>
@@ -175,8 +177,8 @@ registry.example.com/group/project/my/image:rc1
 
 ## Build and push images using GitLab CI/CD
 
-While you can build and push your images from your local machine, the true
-power of the Container Registry comes when you combine it with 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.
@@ -192,7 +194,7 @@ Before diving into the details, some things you should be aware of:
 - 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
+  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
@@ -201,10 +203,7 @@ Before diving into the details, some things you should be aware of:
 ### 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:
+[GitLab CI/CD](../../../ci/yaml/README.md):
 
 - **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
@@ -216,14 +215,22 @@ Available for all projects, though more suitable for public ones:
   docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
   ```
 
-For private and internal projects:
+- **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:
+
+  ```shell
+  docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $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:
 
   - For read (pull) access, the scope should be `read_registry`.
-  - For read/write (pull/push) access, use `api`.
+  - For write (push) access, the scope should be `write_registry`.
 
   Replace the `<username>` and `<access_token>` in the following example:
 
@@ -231,16 +238,6 @@ For private and internal projects:
   docker login -u <username> -p <access_token> $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 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
-  ```
-
 ### Container Registry examples with GitLab CI/CD
 
 If you're using Docker-in-Docker on your Runners, this is how your `.gitlab-ci.yml`
@@ -276,7 +273,7 @@ build:
 
 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
+and your branch name can contain forward slashes (for example, `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.
@@ -352,8 +349,8 @@ 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
+To use your own Docker images for Docker-in-Docker, follow these steps
+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.
@@ -373,8 +370,8 @@ Below is an example of what your `.gitlab-ci.yml` should look like:
      - docker run my-docker-image /script/to/run/tests
 ```
 
-If you forget to set the service alias, the `docker:19.03.12` image won't find the
-`dind` service, and an error like the following will be thrown:
+If you forget to set the service alias, the `docker:19.03.12` image is unable to find the
+`dind` service, and an error like the following is thrown:
 
 ```plaintext
 error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host
@@ -496,81 +493,71 @@ Container Registry.
 > - [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 a cleanup policy. When the policy is applied, tags matching the regex pattern are removed.
+The cleanup policy is a scheduled job you can use to remove tags from the Container Registry.
+For the project where it's defined, 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
+To delete the underlying layers and images that aren't associated with any tags, 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, 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
-[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
+Cleanup policies can be run on all projects, with these exceptions:
 
-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 after 2020-02-22.
+  Support for projects created earlier
+  [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124).
+- For self-managed GitLab instances, the project must have been created
+  in GitLab 12.8 or later. However, an administrator can enable the cleanup policy
+  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.
 
-The UI allows you to configure the following:
+  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).
 
-- **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 `.*`.
+### How the cleanup policy works
 
-#### Troubleshooting cleanup policies
+The cleanup policy collects all tags in the Container Registry and excludes tags
+until only the tags to be deleted remain.
 
-If you see the following message:
-
-"Something went wrong while updating the cleanup policy."
-
-Check the regex patterns to ensure they are valid.
+The cleanup policy:
 
-You can use [Rubular](https://rubular.com/) to check your regex.
-View some common [regex pattern examples](#regex-pattern-examples).
+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.
 
-### Managing project cleanup policy through the API
+### Create a cleanup policy
 
-You can set, update, and disable the cleanup policies using the GitLab API.
+You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI.
 
-Examples:
+To create a cleanup policy in the UI:
 
-- 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:
+1. For your project, go to **Settings > CI/CD**.
+1. Expand the **Cleanup policy for tags** section.
+1. Complete the fields.
 
-  ```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'
-  ```
+   | 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. 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). |
 
-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 +589,41 @@ 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 runs a policy to remove thousands of tags
+the GitLab background jobs 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 number of tags
+being cleaned up is 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/),
@@ -616,9 +638,9 @@ You can read more about the above challenges [here](https://gitlab.com/gitlab-or
 - 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.
+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
-will not be deleted by the cleanup policy.
+are not deleted by the cleanup policy.
 
 ## Troubleshooting the GitLab Container Registry
 
@@ -637,7 +659,7 @@ name.
 ### Troubleshoot as a GitLab server admin
 
 Troubleshooting the GitLab Container Registry, most of the times, requires
-administration access to the GitLab server.
+administrator access to the GitLab server.
 
 [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting).
 
@@ -655,22 +677,22 @@ the project.
 
 The following procedure uses these sample project names:
 
-- For the current project: `example.gitlab.com/org/build/sample_project/cr:v2.9.1`
-- For the new project: `example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1`
+- For the current project: `gitlab.example.com/org/build/sample_project/cr:v2.9.1`
+- For the new project: `gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1`
 
 Use your own URLs to complete the following steps:
 
 1. Download the Docker images on your computer:
 
    ```shell
-   docker login example.gitlab.com
-   docker pull example.gitlab.com/org/build/sample_project/cr:v2.9.1
+   docker login gitlab.example.com
+   docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1
    ```
 
 1. Rename the images to match the new project name:
 
    ```shell
-   docker tag example.gitlab.com/org/build/sample_project/cr:v2.9.1 example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1
+   docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1
    ```
 
 1. Delete the images in both projects by using the [UI](#delete-images) or [API](../../../api/packages.md#delete-a-project-package).
@@ -680,7 +702,7 @@ Use your own URLs to complete the following steps:
 1. Restore the images:
 
    ```shell
-   docker push example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1
+   docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1
    ```
 
 Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18383) for details.