Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42

10 files changed, 206 insertions, 107 deletions

diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 09123fdd472..1ea5168f30c 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -4,40 +4,52 @@ group: Configure
 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
 ---
 
-# CI/CD Tunnel
+# CI/CD Tunnel **(PREMIUM)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
-> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
+> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
+> - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
 
 The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network
 connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster.
 
 Only CI/CD jobs set in the configuration project can access one of the configured agents.
 
-Prerequisites:
+## Prerequisites
 
 - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server).
 - A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file
   installed (`.gitlab/agents/<agent-name>/config.yaml`).
 - An [Agent record](index.md#create-an-agent-record-in-gitlab).
-- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster).
+- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster).
 
-If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected.
+## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD
 
+If your project has access to one or more Agent records available, its CI/CD
+jobs provide a `KUBECONFIG` variable compatible with `kubectl`.
+
+Also, each Agent has a separate context (`kubecontext`). By default,
+there isn't any context selected.
 Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`.
+To get the list of available contexts, run `kubectl config get-contexts`.
+
+## Example for a `kubectl` command using the CI/CD Tunnel
 
-To access your cluster from a CI/CD job through the tunnel:
+The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel.
+You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`,
+`kpt`, and so on. To do so:
 
-1. In your `.gitlab-ci.yml` select the context for the agent you wish to use:
+1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`.
+1. Run Kubernetes commands.
 
-   ```yaml
-   deploy:
-     image:
-       name: bitnami/kubectl:latest
-       entrypoint: [""]
-     script:
-     - kubectl config use-context path/to/agent-configuration-project:your-agent-name
-     - kubectl get pods
-   ```
+For example:
 
-1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created.
+```yaml
+ deploy:
+   image:
+     name: bitnami/kubectl:latest
+     entrypoint: [""]
+   script:
+   - kubectl config use-context path/to/agent-configuration-project:your-agent-name
+   - kubectl get pods
+```
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index c59d2a1f61c..d2dc57c0849 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -20,7 +20,7 @@ tasks in a secure and cloud-native way. It enables:
 - Pull-based GitOps deployments.
 - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster.
 - Real-time access to API endpoints in a cluster.
-- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy).
+- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy).
 - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster.
 
 Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329)
@@ -77,6 +77,8 @@ The setup process involves a few steps to enable GitOps deployments:
 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster).
 1. [Create manifest files](#create-manifest-files).
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process.
+
 ### Upgrades and version compatibility
 
 As the GitLab Kubernetes Agent is a new product, we are constantly adding new features
@@ -104,7 +106,8 @@ To use the KAS:
 
 ### Define a configuration repository
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository.
+> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
 
 To configure an Agent, you need:
 
@@ -123,6 +126,7 @@ In your repository, add the Agent configuration file under:
 Your `config.yaml` file specifies all configurations of the Agent, such as:
 
 - The manifest projects to synchronize.
+- The groups that can access this Agent via the [CI/CD Tunnel](ci_cd_tunnel.md).
 - The address of the `hubble-relay` for the Network Security policy integrations.
 
 As an example, a minimal Agent configuration that sets up only the manifest
@@ -174,17 +178,14 @@ To perform a one-liner installation, run the command below. Make sure to replace
 - `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output).
 - `gitlab-kubernetes-agent` with the namespace you defined in the previous step.
 - `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`.
+- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu.
 
 ```shell
-docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f -
+docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f -
 ```
 
-Set `--agent-version` to the latest released patch version matching your
-GitLab installation's major and minor versions. For example, if you have
-GitLab v13.9.0, set `--agent-version=v13.9.1`.
-
 WARNING:
-Version `stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for
+`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for
 testing purposes but for production please make sure to specify a matching version explicitly.
 
 To find out the various options the above Docker container supports, run:
@@ -287,7 +288,7 @@ spec:
       containers:
       - name: agent
         # Make sure to specify a matching version for production
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable"
+        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z
         args:
         - --token-file=/config/token
         - --kas-address
@@ -383,29 +384,16 @@ Each time you push a change to a monitored manifest repository, the Agent logs t
 
 #### Example manifest file
 
-This file creates an NGINX deployment.
+This file creates a minimal `ConfigMap`:
 
 ```yaml
-apiVersion: apps/v1
-kind: Deployment
+apiVersion: v1
+kind: ConfigMap
 metadata:
-  name: nginx-deployment
+  name: demo-map
   namespace: gitlab-kubernetes-agent  # Can be any namespace managed by you that the agent has access to.
-spec:
-  selector:
-    matchLabels:
-      app: nginx
-  replicas: 2
-  template:
-    metadata:
-      labels:
-        app: nginx
-    spec:
-      containers:
-      - name: nginx
-        image: nginx:1.14.2
-        ports:
-        - containerPort: 80
+data:
+  key: value
 ```
 
 ## Example projects
@@ -433,8 +421,8 @@ There are several components that work in concert for the Agent to generate the
   - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an
     existing installation.
 - One or more network policies through any of these options:
-  - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies.
-  - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration.
+  - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies.
+  - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration.
   - Add the required labels and annotations to existing network policies.
 - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab)
 
diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md
index a3a3e4c29b0..ea57ded3320 100644
--- a/doc/user/clusters/agent/repository.md
+++ b/doc/user/clusters/agent/repository.md
@@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7.
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
+> - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
 
 WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
@@ -147,6 +148,40 @@ gitops:
     - glob: '/**/*.yaml'
 ```
 
+## Authorize groups to use an Agent
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
+
+If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel
+to grant the Agent access to one or more groups. This way, all the projects that belong
+to the authorized groups can access the same Agent. This enables you to save resources and
+have a scalable setup.
+
+When you authorize a group, the agent's Kubernetes context is automatically injected
+into every project of the authorized group, and users can select the connection as
+described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md).
+To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md),
+use the `ci_access` attribute in your `config.yaml` configuration file.
+
+An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most
+100 groups can be authorized per Agent.
+
+To authorize a group:
+
+1. Edit your `.config.yaml` file under the `.gitlab/agents/<agent name>` directory.
+1. Add the `ci_access` attribute.
+1. Add the `groups` attribute into `ci_access`.
+1. Add the group `id` into `groups`, identifying the authorized group through its path.
+
+For example:
+
+```yaml
+ci_access:
+  # This agent is accessible from CI jobs in projects in these groups
+  groups:
+  - id: group/subgroup
+```
+
 ## Surface network security alerts from cluster to GitLab
 
 The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts).
diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md
index 5d247f04d3b..2da8396cfd7 100644
--- a/doc/user/clusters/applications.md
+++ b/doc/user/clusters/applications.md
@@ -285,10 +285,10 @@ postgresql:
 ```
 
 Support for installing the Sentry managed application is provided by the
-GitLab Health group. If you run into unknown issues,
+GitLab Monitor group. If you run into unknown issues,
 [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
 least 2 people from the
-[Health group](https://about.gitlab.com/handbook/product/categories/#health-group).
+[Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group).
 
 ### Install PostHog using GitLab CI/CD
 
@@ -366,9 +366,9 @@ project. Refer to the
 of the Prometheus chart's README for the available configuration options.
 
 Support for installing the Prometheus managed application is provided by the
-GitLab APM group. If you run into unknown issues,
+GitLab Monitor group. If you run into unknown issues,
 [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
-least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group).
+least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group).
 
 ### Install GitLab Runner using GitLab CI/CD
 
@@ -819,9 +819,9 @@ management project. Refer to the
 available configuration options.
 
 Support for installing the Elastic Stack managed application is provided by the
-GitLab APM group. If you run into unknown issues,
+GitLab Monitor group. If you run into unknown issues,
 [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
-least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group).
+least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group).
 
 ### Install Crossplane using GitLab CI/CD
 
diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md
index cb721115e76..cad55f0cf0b 100644
--- a/doc/user/clusters/environments.md
+++ b/doc/user/clusters/environments.md
@@ -36,7 +36,7 @@ In order to:
   [deploy to a Kubernetes cluster](../project/clusters/index.md#deploying-to-a-kubernetes-cluster)
   successfully.
 - Show pod usage correctly, you must
-  [enable Deploy Boards](../project/deploy_boards.md#enabling-deploy-boards).
+  [enable deploy boards](../project/deploy_boards.md#enabling-deploy-boards).
 
 After you have successful deployments to your group-level or instance-level cluster:
 
diff --git a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png
deleted file mode 100644
index 5fd1bac5e05..00000000000
--- a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png
+++ /dev/null
diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md
index 5e6843144fc..70f940c775b 100644
--- a/doc/user/clusters/integrations.md
+++ b/doc/user/clusters/integrations.md
@@ -33,9 +33,6 @@ You can integrate your Kubernetes cluster with
 [Prometheus](https://prometheus.io/) for monitoring key metrics of your
 apps directly from the GitLab UI.
 
-[Alerts](../../operations/metrics/alerts.md) can be configured the same way as
-for [external Prometheus instances](../../operations/metrics/alerts.md#external-prometheus-instances).
-
 Once enabled, you can see metrics from services available in the
 [metrics library](../project/integrations/prometheus_library/index.md).
 
diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md
index 204afa9fc89..ca6843f6fde 100644
--- a/doc/user/clusters/management_project.md
+++ b/doc/user/clusters/management_project.md
@@ -32,28 +32,30 @@ Management projects are restricted to the following:
   group (or descendants) as the cluster's group.
 - For instance-level clusters, there are no such restrictions.
 
-## Usage
+## How to create and configure a cluster management project
 
-To use a cluster management project for a cluster:
+To use a cluster management project to manage your cluster:
 
-1. Select the project.
-1. Configure your pipelines.
-1. Set an environment scope.
+1. Create a new project to serve as the cluster management project
+for your cluster. We recommend that you
+[create this project based on the Cluster Management project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template).
+1. [Associate the cluster with the management project](#associate-the-cluster-management-project-with-the-cluster).
+1. [Configure your cluster's pipelines](#configuring-your-pipeline).
+1. [Set the environment scope](#setting-the-environment-scope).
 
-### Selecting a cluster management project
+### Associate the cluster management project with the cluster
 
-To select a cluster management project to use:
+To associate a cluster management project with your cluster:
 
 1. Navigate to the appropriate configuration page. For a:
    - [Project-level cluster](../project/clusters/index.md), go to your project's
      **Infrastructure > Kubernetes clusters** page.
    - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes**
      page.
-   - [Instance-level cluster](../instance/clusters/index.md), go to **Menu >** **{admin}** **Admin > Kubernetes** page.
-1. Select the project using **Cluster management project field** in the **Advanced settings**
-   section.
-
-![Selecting a cluster management project under Advanced settings](img/advanced-settings-cluster-management-project-v12_5.png)
+   - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Menu > Admin > Kubernetes**.
+1. Expand **Advanced settings**.
+1. From the **Cluster management project** dropdown, select the cluster management project
+you created in the previous step.
 
 ### Configuring your pipeline
 
diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md
index 1de17396bf4..9e2b00a0f54 100644
--- a/doc/user/clusters/management_project_template.md
+++ b/doc/user/clusters/management_project_template.md
@@ -4,35 +4,68 @@ group: Configure
 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
 ---
 
-# Cluster Management Project Template **(FREE)**
+# Cluster Management project template **(FREE)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2.
-> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below.
+> - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead.
 
-This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates)
-provides a quicker start for users interested in managing cluster
-applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the
-[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that
-should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not
-need, or even add new ones that are not built-in.
+With a [cluster management project](management_project.md) you can manage
+your cluster's deployment and applications through a repository in GitLab.
 
-## How to use this template
+The Custer Management project template provides you a baseline to get
+started and flexibility to customize your project to your cluster's needs.
+For instance, you can:
 
-1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates).
-1. Make this project a [cluster management project](management_project.md).
-1. If you used the [GitLab Managed Apps](applications.md), refer to
-   [Migrating from GitLab Managed Apps](migrating_from_gma_to_project_template.md).
+- Extend the CI/CD configuration.
+- Configure the built-in cluster applications.
+- Remove the built-in cluster applications you don't need.
+- Add other cluster applications using the same structure as the ones already available.
 
-### Components
+The template contains the following [components](#available-components):
 
-In the repository of the newly-created project, you will find:
+- A pre-configured GitLab CI/CD file so that you can configure deployment pipelines.
+- A pre-configured [Helmfile](https://github.com/roboll/helmfile) so that
+you can manage cluster applications with [Helm v3](https://helm.sh/).
+- An `applications` directory with a `helmfile.yaml` configured for each
+application available in the template.
 
-- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml)
-  file, with a CI pipeline already configured.
-- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage.
-- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides.
+WARNING:
+If you used [GitLab Managed Apps](applications.md) to manage your
+cluster from GitLab, see how to [migrate from GitLab Managed Apps](migrating_from_gma_to_project_template.md) to the Cluster Management
+project.
 
-#### The `.gitlab-ci.yml` file
+## Set up the management project from the Cluster Management project template
+
+To set up your cluster's management project off of the Cluster Management project template:
+
+1. [Create a new project based on the Cluster Management template](#create-a-new-project-based-on-the-cluster-management-template).
+1. [Associate the cluster management project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster).
+1. Use the [available components](#available-components) to manage your cluster.
+
+### Create a new project based on the Cluster Management template
+
+To get started, create a new project based on the Cluster Management
+project template to use as a cluster management project.
+
+You can either create the [new project](../project/working_with_projects.md#create-a-project)
+from the template or import the project from the URL. Importing
+the project is useful if you are using a GitLab self-managed
+instance that may not have the latest version of the template.
+
+To create the new project:
+
+- From the template: select the **GitLab Cluster Management** project template.
+- Importing from the URL: use `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`.
+
+## Available components
+
+Use the available components to configure your cluster:
+
+- [A `.gitlab-ci.yml` file](#the-gitlab-ciyml-file).
+- [A main `helmfile.yml` file](#the-main-helmfileyml-file).
+- [A directory with built-in applications](#built-in-applications).
+
+### The `.gitlab-ci.yml` file
 
 The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications)
 project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts):
@@ -48,23 +81,21 @@ project. This image consists of a set of Bash utility scripts to support [Helm v
   facilitate the GitLab Managed Apps adoption.
 - `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command.
 
-#### The main `helmfile.yml` file
+### The main `helmfile.yml` file
 
 This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment
-the paths for the apps that you would like to manage.
+the paths for the apps that you would like to use in your cluster.
 
-By default, each `helmfile.yaml` in these sub-paths have the attribute `installed: true`. This signifies that every time
+By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that every time
 the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your
 cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app
 from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works.
 
-Furthermore, each app has an `applications/{app}/values.yaml` file. This is the
-place where you can define some default values for your app's Helm chart. Some apps already have defaults
+Furthermore, each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the
+place where you can define default values for your app's Helm chart. Some apps already have defaults
 pre-defined by GitLab.
 
-#### Built-in applications
-
-The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features.
+### Built-in applications
 
 The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are:
 
@@ -79,8 +110,3 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp
 - [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md)
 - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md)
 - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md)
-
-### Migrate from GitLab Managed Apps
-
-If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to
-[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md)
diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md
index dc16cf5cc45..2da058fb5bc 100644
--- a/doc/user/clusters/migrating_from_gma_to_project_template.md
+++ b/doc/user/clusters/migrating_from_gma_to_project_template.md
@@ -4,13 +4,24 @@ group: Configure
 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
 ---
 
-# Migrating from GitLab Managed Apps to a management project template
+# Migrate from GitLab Managed Apps to Cluster Management Projects
 
-The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them:
+The [GitLab Managed Apps](applications.md) were deprecated in GitLab 14.0
+in favor of [Cluster Management Projects](management_project.md).
+Managing your cluster applications through a project enables you a
+lot more flexibility to manage your cluster than through the late GitLab Managed Apps.
+To migrate to the cluster management project you need
+[GitLab Runners](../../ci/runners/index.md)
+available and be familiar with [Helm](https://helm.sh/).
 
-1. Read how the [management project template](management_project_template.md) works, and
-   create a new project based on the "GitLab Cluster Management" template.
-1. Create a new project as explained in the [management project template](management_project_template.md).
+## Migrate to a Cluster Management Project
+
+To migrate from GitLab Managed Apps to a Cluster Management Project,
+follow the steps below.
+See also [video walk-throughs](#video-walk-throughs) with examples.
+
+1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template).
+1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster).
 1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file:
     - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`,
       and make sure the script is receiving the correct namespace as an argument:
@@ -80,6 +91,16 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig
       used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the
       chart version proposed in `applications/vault/values.yaml`.
 
+    - Cert-manager:
+      - For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid and
+        and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010)
+        , and install cert-manager v1.4 instead. To install this version, uncomment the `applications/cert-manager-1-4/helmfile.yaml`
+        from the [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file).
+        This triggers a pipeline to install the new version.
+      - For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting
+        `applications/cert-manager/helmfile.yaml`
+        in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)).
+
 1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually)
    and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any
    unexpected updates.
@@ -93,3 +114,21 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig
 
 After getting a successful pipeline, repeat these steps for any other deployed apps
 you want to manage with the Cluster Management Project.
+
+## Backup and uninstall cert-manager v0.10
+
+1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to
+  backup your cert-manager v0.10 data.
+1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the
+   `applications/cert-manager/helmfile.yaml` file.
+1. Search for any left-over resources by executing the following command `kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager`.
+1. For each of the resources found in the previous step, delete them with `kubectl delete -n gitlab-managed-apps {ResourceType} {ResourceName}`.
+   For example, if you found a resource of type `ConfigMap` named `cert-manager-controller`, delete it by executing:
+   `kubectl delete configmap -n gitlab-managed-apps cert-manager-controller`.
+
+## Video walk-throughs
+
+You can watch these videos with examples on how to migrate from GMA to a Cluster Management project:
+
+- [Migrating from scratch using a brand new cluster management project](https://youtu.be/jCUFGWT0jS0). Also covers Helm v2 apps migration.
+- [Migrating from an existing GitLab managed apps CI/CD project](https://youtu.be/U2lbBGZjZmc).