Add latest changes from gitlab-org/gitlab@14-8-stable-eev14.8.0-rc42

11 files changed, 615 insertions, 423 deletions

diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index f1c49b87383..5fe772d9686 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -12,53 +12,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5.
 > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5.
 
-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.
+To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel.
 
-Only CI/CD jobs set in the configuration project can access one of the configured agents.
+You can authorize multiple projects to access the same cluster, so you
+can keep your application's codebase in one repository and configure
+your cluster in another. This method is scalable and can save you resources.
 
-## Prerequisites
-
-- An existing Kubernetes cluster.
-- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster).
+To ensure access to your cluster is safe, only the projects you
+authorize can access your Agent through the CI/CD Tunnel.
 
-## 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`.
+## Prerequisites
 
-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`.
+To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the
+[GitLab Agent](install/index.md#install-the-agent-onto-the-cluster).
 
-## Share the CI/CD Tunnel provided by an Agent with other projects and groups
+To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster.
 
-The Agent can be configured to enable access to the CI/CD Tunnel to other projects or all the projects under a given group. This way you can have a single agent serving all the requests for several projects saving on resources and maintenance.
+## How the CI/CD Tunnel works
 
-You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent).
+When you authorize a project to use an Agent, the Tunnel automatically
+injects a `KUBECONFIG` variable into its CI/CD jobs. This way, you can
+run `kubectl` commands from GitLab CI/CD scripts that belong to the
+authorized project.
 
-## Restrict access of authorized projects and groups **(PREMIUM)**
+When you authorize a group, all the projects that belong to that group
+become authorized to access the selected Agent.
 
-You can [configure various impersonations](repository.md#use-impersonation-to-restrict-project-and-group-access) to restrict the permissions of a shared CI/CD Tunnel.
+An Agent can only authorize projects or groups in the same group
+hierarchy as the Agent's configuration project. You can authorize
+up to 100 projects and 100 groups per Agent.
 
-## Example for a `kubectl` command using the CI/CD Tunnel
+Also, each Agent has a separate context (`kubecontext`).
+The Tunnel uses this information to safely allow access to the cluster from
+jobs running in the projects you authorized.
 
-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:
+### `~/.kube/cache` permissions
+ 
+`kubectl` and other tools based on the same libraries (such as Helm, `kpt`, and `kustomize`) cache information about
+the cluster in `~/.kube/cache`. If this directory is not writable, the tool fetches information on each invocation,
+making interactions slower and creating unnecessary load on the cluster. Make sure that this directory in the container image
+you use is writable for the best experience.
 
-1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`.
-1. Run Kubernetes commands.
+## Configure the CI/CD Tunnel
 
-For example:
+The CI/CD Tunnel is configured directly through the
+Agent's configuration file ([`config.yaml`](repository.md)) to:
 
-```yaml
- deploy:
-   image:
-     name: bitnami/kubectl:latest
-     entrypoint: [""]
-   script:
-   - kubectl config use-context path/to/agent-configuration-project:your-agent-name
-   - kubectl get pods
-```
+- Authorize [projects](repository.md#authorize-projects-to-use-an-agent) and [groups](repository.md#authorize-groups-to-use-an-agent) to use the same Agent.
+- [Run `kubectl` commands using the CI/CD Tunnel](repository.md#run-kubectl-commands-using-the-cicd-tunnel).
+- [Restrict access of authorized projects and groups through impersonation strategies](repository.md#use-impersonation-to-restrict-project-and-group-access).
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index a235c0ef6f8..3fb141e402f 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -4,60 +4,71 @@ 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
 ---
 
-# GitLab Agent for Kubernetes **(FREE)**
+# Connecting a Kubernetes cluster with GitLab
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4.
 > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program.
-> - Introduced in GitLab 13.11, the GitLab Agent became available to every project on GitLab.com.
+> - Agent Server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10.
+> - The agent became available to every project on GitLab.com in GitLab 13.11.
 > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
-> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab Agent for Kubernetes" in GitLab 14.6.
+> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6.
 
-The [GitLab Agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short)
-is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring.
+You can connect your Kubernetes cluster with GitLab to deploy, manage,
+and monitor your cloud-native solutions. You can choose from two primary workflows.
 
-The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution.
+In a **GitOps workflow**, you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and
+any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based,
+because the cluster is pulling updates from your GitLab repository.
+
+In a **CI/CD** workflow, you use GitLab CI/CD to query and update your cluster by using the Kubernetes API.
+This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster.
+
+Both of these workflows require you to [install an agent in your cluster](install/index.md).
+
+## Supported cluster versions
+
+GitLab supports the following Kubernetes versions. You can upgrade your
+Kubernetes version to a supported version at any time:
+
+- 1.20 (support ends on July 22, 2022)
+- 1.19 (support ends on February 22, 2022)
+- 1.18 (support ends on November 22, 2021)
+- 1.17 (support ends on September 22, 2021)
+
+GitLab supports at least two production-ready Kubernetes minor
+versions at any given time. GitLab regularly reviews the supported versions and
+provides a three-month deprecation period before removing support for a specific
+version. The list of supported versions is based on:
+
+- The versions supported by major managed Kubernetes providers.
+- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions).
+
+[This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for other Kubernetes versions.
+
+Some GitLab features might work on versions not listed here.
+
+## Using Kubernetes with GitOps **(PREMIUM)**
 
 With GitOps, you can manage containerized clusters and applications from a Git repository that:
 
 - Is the single source of truth of your system.
 - Is the single place where you operate your system.
-- Is a single resource to monitor your system.
 
-By combining GitLab, Kubernetes, and GitOps, it results in a robust infrastructure:
+By combining GitLab, Kubernetes, and GitOps, you can have:
 
 - GitLab as the GitOps operator.
 - Kubernetes as the automation and convergence system.
-- GitLab CI/CD as the Continuous Integration and Continuous Deployment engine.
+- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment.
 
 Beyond that, you can use all the features offered by GitLab as
 the all-in-one DevOps platform for your product and your team.
 
-## Agent's features
+### GitOps workflow **(PREMIUM)**
 
-By using the Agent, you can:
-
-- Connect GitLab with a Kubernetes cluster behind a firewall or a
-Network Address Translation (NAT).
-- Have real-time access to API endpoints in your cluster from GitLab CI/CD.
-- Use GitOps to configure your cluster through the [Agent's repository](repository.md).
-- Perform pull-based or push-based GitOps deployments.
-- Configure [Network Security Alerts](#kubernetes-network-security-alerts)
-based on [Container Network Policies](../../application_security/policies/index.md#container-network-policy).
-- Track objects applied to your cluster through [inventory objects](../../infrastructure/clusters/deploy/inventory_object.md).
-- Use the [CI/CD Tunnel](ci_cd_tunnel.md) to access Kubernetes clusters
-from GitLab CI/CD jobs while keeping the cluster's APIs safe and unexposed
-to the internet.
-- [Deploy the GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html).
-
-See the [Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development.
-
-To contribute to the Agent, see the [Agent's development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc).
-
-## Agent's GitOps workflow **(PREMIUM)**
-
-The Agent uses multiple GitLab projects to provide a flexible workflow
+The agent uses multiple GitLab projects to provide a flexible workflow
 that can suit various needs. This diagram shows these repositories and the main
+The agent uses multiple GitLab projects to provide a flexible workflow.
+This diagram shows these repositories and the main
 actors involved in a deployment:
 
 ```mermaid
@@ -65,7 +76,7 @@ sequenceDiagram
   participant D as Developer
   participant A as Application code repository
   participant M as Manifest repository
-  participant K as GitLab Agent
+  participant K as GitLab agent
   participant C as Agent configuration repository
   loop Regularly
     K-->>C: Grab the configuration
@@ -78,61 +89,28 @@ sequenceDiagram
   end
 ```
 
-For more details, refer to our [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project.
-
-## Install the Agent in your cluster
-
-See how to [install the Agent in your cluster](install/index.md).
-
-## GitOps deployments **(PREMIUM)**
-
-To perform GitOps deployments with the Agent, you need:
+For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture).
 
-- A properly-configured Kubernetes cluster where the Agent is running.
-- A [configuration repository](repository.md) that contains a
-`config.yaml` file, which tells the Agent the repositories to synchronize
-with the cluster.
-- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster.
+To perform GitOps deployments, you need:
 
-You can use a single GitLab project or different projects for the Agent
-configuration and manifest files, as follows:
+- A properly-configured Kubernetes cluster where the GitLab agent is running.
+- A project that contains the agent's configuration file (`config.yaml`) in the repository.
+  This file tells the agent which repositories to synchronize with the cluster.
+- A project that contains Kubernetes manifests. Any changes to manifests are applied to the cluster.
 
-- Single GitLab project (recommended): When you use a single repository to hold
-  both the manifest and the configuration files, these projects can be either
-  private or public.
-- Two GitLab projects: When you use two different GitLab projects (one for
-  manifest files and another for configuration files), the manifests project must
-  be public, while the configuration project can be either private or public.
+You can keep the agent's configuration file and Kubernetes manifests in one project, or you can use multiple.
 
-Support for separated private manifest and configuration repositories is tracked in this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
+- One GitLab project (recommended): When you use one project for both the Kubernetes manifests
+  and the agent's configuration file, the projects can be either private or public.
+- Two GitLab projects: When you use two different GitLab projects (one for Kubernetes
+  manifests and another for the agent's configuration file), the project with Kubernetes manifests must
+  be public. The project with the agent's configuration file can be either private or public.
 
-## Kubernetes Network Security Alerts **(ULTIMATE)**
-
-The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to
-generate network policy-related alerts and to surface those alerts in GitLab.
-
-There are several components that work in concert for the Agent to generate the alerts:
-
-- A working Kubernetes cluster.
-- Cilium integration through either of these options:
-  - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium).
-  - 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/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)
-
-The setup process follows the same [Agent's installation steps](install/index.md),
-with the following differences:
-
-- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab).
-- You do not need to specify the `gitops` configuration section.
+Support for separate private projects is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885).
 
 ## Remove an agent
 
-You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or through the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api).
+You can remove an agent by using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api).
 
 ### Remove an agent through the GitLab UI
 
@@ -140,16 +118,16 @@ You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitla
 
 To remove an agent from the UI:
 
-1. Go to your agent's configuration repository.
-1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**.
-1. Select your agent from the table, and then in the **Options** column, click the vertical ellipsis
-(**{ellipsis_v}**) button and select **Delete agent**.
+1. On the top bar, select **Menu > Projects** and find the project that contains the agent's configuration file.
+1. From the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**).
+1. Select **Delete agent**.
 
 ### Remove an agent with the GitLab GraphQL API
 
 1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer.
-For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer.
-For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your own instance's URL.
+   - For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer.
+   - For self-managed GitLab, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your instance's URL.
 
    ```graphql
    query{
@@ -195,185 +173,48 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e
    }
    ```
 
-1. Delete the Agent in your cluster:
+1. Delete the agent in your cluster:
 
    ```shell
    kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml
    ```
 
-## Migrating to the GitLab Agent from the legacy certificate-based integration
-
-Find out how to [migrate to the GitLab Agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration depending on the features you use.
-
-## Troubleshooting
-
-If you face any issues while using the Agent, read the
-service logs with the following command:
-
-```shell
-kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent
-```
-
-GitLab administrators can additionally view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting).
-
-### Agent logs
-
-#### Transport: Error while dialing failed to WebSocket dial
+## Migrating to the agent from the legacy certificate-based integration
 
-```json
-{
-  "level": "warn",
-  "time": "2020-11-04T10:14:39.368Z",
-  "msg": "GetConfiguration failed",
-  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""
-}
-```
-
-This error is shown if there are some connectivity issues between the address
-specified as `kas-address`, and your Agent pod. To fix it, make sure that you
-specified the `kas-address` correctly.
-
-```json
-{
-  "level": "error",
-  "time": "2021-06-25T21:15:45.335Z",
-  "msg": "Reverse tunnel",
-  "mod_name": "reverse_tunnel",
-  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""
-}
-```
-
-This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the
-`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/`
-or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
-
-#### ValidationError(Deployment.metadata)
-
-```json
-{
-  "level": "info",
-  "time": "2020-10-30T08:56:54.329Z",
-  "msg": "Synced",
-  "project_id": "root/kas-manifest001",
-  "resource_key": "apps/Deployment/kas-test001/nginx-deployment",
-  "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"
-}
-```
+Find out how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration.
 
-This error is shown if a manifest file is malformed, and Kubernetes can't
-create specified objects. Make sure that your manifest files are valid. You
-may try using them to create objects in Kubernetes directly for more troubleshooting.
+## Kubernetes network security alerts **(ULTIMATE)**
 
-#### Error while dialing failed to WebSocket dial: failed to send handshake request
-
-```json
-{
-  "level": "warn",
-  "time": "2020-10-30T09:50:51.173Z",
-  "msg": "GetConfiguration failed",
-  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""
-}
-```
-
-This error is shown if you configured `wss` as `kas-address` on the agent side,
-but KAS on the server side is not available via `wss`. To fix it, make sure the
-same schemes are configured on both sides.
-
-It's not possible to set the `grpc` scheme due to the issue
-[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the
-issue is in progress, directly edit the deployment with the
-`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use
-`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`.
-
-#### Decompressor is not installed for grpc-encoding
-
-```json
-{
-  "level": "warn",
-  "time": "2020-11-05T05:25:46.916Z",
-  "msg": "GetConfiguration.Recv failed",
-  "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""
-}
-```
+> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0.
 
-This error is shown if the version of the agent is newer that the version of KAS.
-To fix it, make sure that both `agentk` and KAS use the same versions.
+WARNING:
+Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476)
+for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477)
+in GitLab 15.0.
 
-#### Certificate signed by unknown authority
+The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to
+generate network policy-related alerts and to surface those alerts in GitLab.
 
-```json
-{
-  "level": "error",
-  "time": "2021-02-25T07:22:37.158Z",
-  "msg": "Reverse tunnel",
-  "mod_name": "reverse_tunnel",
-  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""
-}
-```
+Several components work in concert for the agent to generate the alerts:
 
-This error is shown if your GitLab instance is using a certificate signed by an internal CA that
-is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent
-via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it
-will be picked up automatically.
+- A working Kubernetes cluster.
+- Cilium integration through either of these options:
+  - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium).
+  - 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/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)
 
-For example, if your internal CA certificate is `myCA.pem`:
+The setup process follows the same [agent's installation steps](install/index.md),
+with the following differences:
 
-```plaintext
-kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem
-```
+- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab).
+- You do not need to specify the `gitops` configuration section.
 
-Then in `resources.yml`:
-
-```yaml
-    spec:
-      serviceAccountName: gitlab-kubernetes-agent
-      containers:
-      - name: agent
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
-        args:
-        - --token-file=/config/token
-        - --kas-address
-        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
-        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
-        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
-        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
-        volumeMounts:
-        - name: token-volume
-          mountPath: /config
-        - name: ca-pemstore-volume
-          mountPath: /etc/ssl/certs/myCA.pem
-          subPath: myCA.pem
-      volumes:
-      - name: token-volume
-        secret:
-          secretName: gitlab-kubernetes-agent-token
-      - name: ca-pemstore-volume
-        configMap:
-          name: ca-pemstore
-          items:
-          - key: myCA.pem
-            path: myCA.pem
-```
+## Related topics
 
-Alternatively, you can mount the certificate file at a different location and include it using the
-`--ca-cert-file` agent parameter:
-
-```yaml
-      containers:
-      - name: agent
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
-        args:
-        - --ca-cert-file=/tmp/myCA.pem
-        - --token-file=/config/token
-        - --kas-address
-        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
-        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
-        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
-        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
-        volumeMounts:
-        - name: token-volume
-          mountPath: /config
-        - name: ca-pemstore-volume
-          mountPath: /tmp/myCA.pem
-          subPath: myCA.pem
-```
+- [Troubleshooting](troubleshooting.md)
+- [Contribute to the GitLab agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc)
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index b2372789284..4d196e57f8f 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -6,112 +6,140 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Install the GitLab Agent **(FREE)**
 
-> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
+> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
+> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures.
 
-To get started with the Agent, install it in your cluster.
+To connect a cluster to GitLab, you need to install the GitLab Agent
+onto your cluster.
 
-## Prerequisites **(SELF)**
+## Prerequisites
 
-- An existing Kubernetes cluster.
+- An existing Kubernetes cluster. If you don't have a cluster yet, you can create a new cluster on cloud providers, such as:
+  - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart)
+  - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
+  - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/)
 - On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md).
 
 ## Installation steps
 
-To install the [Agent](../index.md) in your cluster:
+To install the GitLab Agent on your cluster:
 
 1. [Define a configuration repository](#define-a-configuration-repository).
-1. [Register an agent with GitLab](#register-an-agent-with-gitlab).
-1. [Install the agent into the cluster](#install-the-agent-into-the-cluster).
+1. [Register the Agent with GitLab](#register-the-agent-with-gitlab).
+1. [Install the Agent onto the cluster](#install-the-agent-onto-the-cluster).
 
 <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.
 
+When you complete the installation process, you can
+[view your Agent's status and activity information](#view-your-agents).
+You can also [configure](#configure-the-agent) it to your needs.
+
 ### 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.
 > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
 
-To create an agent, you need a GitLab repository to hold the configuration file.
+To create an Agent, you need a GitLab repository to hold its
+configuration file. If you already have a repository holding your
+cluster's manifest files, you can use it to store your
+Agent's configuration file and sync them with no further steps.
 
-After installed, when you update the configuration file, GitLab transmits the
-information to the cluster automatically without downtime.
+#### Create the Agent's configuration file
 
-In your repository, add the Agent configuration file under:
+To create an Agent, go to the repository where you want to store
+it and add the Agent's configuration file under:
 
 ```plaintext
 .gitlab/agents/<agent-name>/config.yaml
 ```
 
-Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name).
-
-WARNING:
-The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized.
-
-You **don't have to add any content** to this file when you create it. The fact that the file exists
-tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this
-file to [configure the agent](../repository.md) by setting up parameters such as:
+You **don't have to add any content** to this file at the moment you
+create it. The fact that the file exists tells GitLab that this is
+an Agent. You can edit it later to [configure the Agent](#configure-the-agent).
 
-- Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md).
-- [Manifest projects to synchronize](../repository.md#synchronize-manifest-projects).
-- The address of the `hubble-relay` for the [Network Security policy integrations](../../../project/clusters/protect/index.md).
+When creating this file, pay special attention to:
 
-To see all the settings available, read the [Agent configuration repository documentation](../repository.md).
+- The [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name).
+- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized.
 
-### Register an agent with GitLab
+### Register the Agent with GitLab
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI.
 
-Next, create a GitLab Rails Agent record to associate it with
-the configuration repository project. Creating this record also creates a Secret needed to configure
-the Agent in subsequent steps.
+Now that you've created your Agent's configuration file, register it
+with GitLab.
+When you register the Agent, GitLab generates a token that you need for
+installing the Agent onto your cluster.
 
-In GitLab:
+In GitLab, go to the project where you added your Agent's configuration
+file and:
 
 1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project).
 1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**.
 1. Select **Actions**.
-1. From the **Select an agent** dropdown, select the agent you want to connect and select **Register an agent** to access the installation form.
-1. The form reveals your registration token. Securely store this secret token as you cannot view it again.
-1. Copy the command under **Recommended installation method**.
+1. From the **Select an Agent** dropdown list, select the Agent you want to register and select **Register an Agent**.
+1. GitLab generates a registration token for this Agent. Securely store this secret token, as you need it to install the Agent onto your cluster and to [update the Agent](#update-the-agent-version) to another version.
+1. Copy the command under **Recommended installation method**. You need it to install the Agent onto your cluster through the one-liner installation method.
+
+### Install the Agent onto the cluster
 
-### Install the agent into the cluster
+To connect your cluster to GitLab, install the registered Agent
+onto your cluster. To install it, you can use either:
 
-In your computer:
+- [The one-liner installation method](#one-liner-installation).
+- [The advanced installation method](#advanced-installation).
 
-1. Open your local terminal and connect to your cluster.
+You can use the one-liner installation for trying to use the Agent for the first time, to do internal setups with
+high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation
+method to benefit from more configuration options.
+
+#### One-liner installation
+
+The one-liner installation is the simplest process, but you need
+Docker installed locally. If you don't have it, you can either install
+it or opt to the [advanced installation method](#advanced-installation).
+
+To install the Agent on your cluster using the one-liner installation:
+
+1. In your computer, open the terminal and connect to your cluster.
 1. Run the command you copied when registering your cluster in the previous step.
 
-See the following sections to learn about customizing the installation.
+Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation).
 
-## Simple installation method
+##### Customize the one-liner installation
 
-The command provided by GitLab does the following things:
+The one-liner command generated by GitLab:
 
 - Creates a namespace for the deployment (`gitlab-kubernetes-agent`).
-- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account).
-- Creates a `Secret` resource for the agent registration token.
+- Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)).
+- Creates a `Secret` resource for the Agent's registration token.
 - Creates a `Deployment` resource for the `agentk` pod.
 
-The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run:
+You can edit these parameters according to your needs to customize the
+one-liner installation command at the command line. To find all available
+options, run in your terminal:
 
 ```shell
 docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
 ```
 
 WARNING:
-`--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.
-
-## Advanced installation method
+`--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.
 
-For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent).
+#### Advanced installation
 
-Otherwise, follow the manual installation steps described below.
+For advanced installation options, use [the `kpt` installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent).
 
-### Customize the permissions for the `agentk` service account
+##### Customize the permissions for the `agentk` service account
 
-The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent.
+The GitLab Agent allows you to fully own your cluster and grant GitLab
+the permissions you want. Still, to facilitate the process, by default the
+generated manifests provide `cluster-admin` rights to the Agent.
 
-As part of the advanced installation method, you can restrict the agent access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation.
+You can restrict the Agent's access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation.
 
 To create restricted permissions:
 
@@ -121,50 +149,115 @@ To create restricted permissions:
 
 The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time.
 
-## Example projects
+## Configure the Agent
 
-The following example projects can help you get started with the Agent.
+When successfully installed, you can [configure the Agent](../repository.md)
+by editing its configuration file.
+When you update the configuration file, GitLab transmits the
+information to the cluster automatically without downtime.
 
-- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent)
-- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project)
+## View your Agents
 
-## View installed Agents
+> The version of installed `agentk` shown on the Agent tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8.
+If you have at least the Developer role, you can access the Agent's
+configuration repository and view the Agent's list:
 
-Users with at least the [Developer](../../../permissions.md) can access the user interface
-for the Agent at **Infrastructure > Kubernetes clusters**, under the
-**Agent** tab. This page lists all registered agents for the current project,
-and the configuration directory for each agent:
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. Select **Agent** tab to view clusters connected to GitLab through the Agent.
 
-![GitLab Agent list UI](../../img/kubernetes-agent-ui-list_v14_5.png)
+On this page, you can view:
 
-Additional management interfaces are planned for the GitLab Agent.
-[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739).
+- All the registered Agents for the current project.
+- The connection status.
+- The version of `agentk` installed on your cluster.
+- The path to each Agent's configuration file.
 
-## View Agent activity information
+Furthermore, if you select one of the Agents on your list, you can view its
+[activity information](#view-the-agents-activity-information).
+
+### View the Agent's activity information
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6.
 
-Users with at least the [Developer](../../../permissions.md) can view the Agent's activity events.
-The activity logs help you to identify problems and get the information you need for troubleshooting.
-You can see events from a week before the current date.
-To access an agent's activity:
+The activity logs help you to identify problems and get the information
+you need for troubleshooting. You can see events from a week before the
+current date. To access an Agent's activity:
+
+1. In your Agent's repository, go to the Agents list as described [above](#view-your-agents).
+1. Select the Agent you want to see the activity.
+
+The activity list includes:
+
+- Agent registration events: when a new token is **created**.
+- Connection events: when an Agent is successfully **connected** to a cluster.
+
+Note that the connection status is logged when you connect an Agent for
+the first time or after more than an hour of inactivity.
 
-1. Go to your agent's configuration repository.
-1. From the sidebar, select **Infrastructure > Kubernetes clusters**.
+To check what else is planned for the Agent's UI and provide feedback,
+see the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739).
+
+### View vulnerabilities in cluster images **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8 [with a flag](../../../../administration/feature_flags.md) named `cluster_vulnerabilities`. Enabled by default.
+
+Users with at least the [Developer role](../../../permissions.md)
+can view cluster vulnerabilities. You can access them through the [vulnerability report](../../../application_security/vulnerabilities/index.md)
+or in your cluster's image through the following process:
+
+1. Configure [cluster image scanning](../../../application_security/cluster_image_scanning/index.md)
+   to your build process.
+1. Go to your Agent's configuration repository.
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
 1. Select the **Agent** tab.
-1. Select the agent you want to see the activity.
+1. Select the Agent you want to see the vulnerabilities for.
+
+![Cluster Agent security tab UI](../../img/cluster_agent_security_tab_v14_8.png)
+
+## Create multiple Agents
+
+You can create and install multiple Agents using the same process
+documented above. Give each Agent's configuration file a unique name
+and you're good to go. You can create multiple Agents, for example:
+
+- To reach your cluster from different projects.
+- To connect multiple clusters to GitLab.
+
+## Update the Agent version
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the Agent's list page to update the Agent version installed on your cluster.
+
+To update the Agent's version on your cluster, you need to re-run the [installation command](#install-the-agent-onto-the-cluster)
+with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`.
+You can find the available `agentk` versions in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc).
 
-You can see the following events on the activity list:
+If you don't have access to your Agent's token, you can retrieve it from your cluster:
 
-- Agent registration:
-  - When a new token is **created**.
-- Connection events:
-  - When an agent is successfully **connected** to a cluster.
+1. On your computer, open the terminal and connect to your cluster.
+1. To retrieve the namespace, run:
 
-Note that the connection status is logged when you connect an agent for the first time
-or after more than an hour of inactivity.
+    ```shell
+    kubectl get namespaces
+    ```
 
-![GitLab Agent activity events UI](../../img/gitlab_agent_activity_events_v14_6.png)
+1. To retrieve the secret, run:
+
+    ```shell
+    kubectl -n <namespace> get secrets
+    ```
+
+1. To retrieve the token, run:
+
+    ```shell
+    kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode
+    ```
+
+## Example projects
+
+The following example projects can help you get started with the Agent.
+
+- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent)
+- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project)
 
 ## Upgrades and version compatibility
 
@@ -178,7 +271,8 @@ A feature introduced in a given GitLab minor version might work with other `agen
 To make sure that it works, use at least the same `agentk` and `kas` minor version. For example,
 if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2.
 
-We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to upgrade the `agentk` installations after upgrading GitLab.
+We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to
+[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab.
 
 The available `agentk` and `kas` versions can be found in
 [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/).
diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md
index 22964fde395..a9d9fd1c13d 100644
--- a/doc/user/clusters/agent/repository.md
+++ b/doc/user/clusters/agent/repository.md
@@ -40,6 +40,9 @@ with Kubernetes resource definitions in YAML or JSON format. The Agent monitors
 each project you declare, and when the project changes, GitLab deploys the changes
 using the Agent.
 
+WARNING:
+When using separate GitLab projects for manifest files and configuration repository, the manifests project must be public.
+
 To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section.
 
 ```yaml
@@ -150,26 +153,19 @@ gitops:
 
 ## Authorize projects and groups to use an Agent
 
-> - Group authorization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
-> - Project authorization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4.
-
-If you use the same cluster across multiple projects, you can set up the [CI/CD Tunnel](ci_cd_tunnel.md)
-to grant access to an Agent from one or more projects or groups. This way, all the authorized
-projects can access the same Agent, which facilitates you to save resources and have a scalable setup.
+With the [CI/CD Tunnel](ci_cd_tunnel.md), you can authorize [projects](#authorize-projects-to-use-an-agent)
+and [groups](#authorize-groups-to-use-an-agent) to use an Agent.
 
-When you authorize a project to use an agent through the [CI/CD Tunnel](ci_cd_tunnel.md),
-the selected Kubernetes context is automatically injected into CI/CD jobs, allowing you to
-run Kubernetes commands from your authorized projects' scripts. When you authorize a group,
-all the projects that belong to that group can access the selected agent.
-
-An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration
-project. You can authorize up to 100 projects and 100 groups per Agent.
+Then, you can reach your cluster from authorized projects and [run Kubernetes commands from GitLab CI/CD scripts](#run-kubectl-commands-using-the-cicd-tunnel)
+in these projects.
 
 ### Authorize projects to use an Agent
 
-To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md):
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4.
+
+To grant projects access to the Agent through the CI/CD Tunnel:
 
-1. Go to your Agent's configuration project.
+1. Go to your Agent's configuration repository.
 1. Edit the Agent's configuration file (`config.yaml`).
 1. Add the `projects` attribute into `ci_access`.
 1. Identify the project through its path:
@@ -182,9 +178,11 @@ To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md
 
 ### Authorize groups to use an Agent
 
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
+
 To grant access to all projects within a group:
 
-1. Go to your Agent's configuration project.
+1. Go to your Agent's configuration repository.
 1. Edit the Agent's configuration file (`config.yaml`).
 1. Add the `groups` attribute into `ci_access`.
 1. Identify the group or subgroup through its path:
@@ -195,7 +193,64 @@ To grant access to all projects within a group:
      - id: path/to/group/subgroup
    ```
 
-### Use impersonation to restrict project and group access **(PREMIUM)**
+## Run `kubectl` commands using the CI/CD Tunnel
+
+After you authorize your project or group to use the Agent, you need to
+configure the project's `.gitlab-ci.yaml` file to access the Agent.
+This makes it possible to deploy applications to your cluster and run
+any Kubernetes-specific commands from the authorized project.
+
+First, configure your Agent:
+
+1. Go to your Agent's configuration repository.
+1. Edit your Agent's `config.yaml` file authorizing the [project](#authorize-projects-to-use-an-agent) or [group](#authorize-groups-to-use-an-agent) you want to run Kubernetes commands from.
+
+Then, configure the other project:
+
+1. Go to the project where you want to run Kubernetes commands from.
+1. Edit your project's `.gitlab-ci.yml` file.
+1. Set your Agent's context in the first command of the script with the format `path/to/agent/repository:agent-name`.
+1. Run Kubernetes commands.
+
+For example:
+
+```yaml
+ deploy:
+   image:
+     name: bitnami/kubectl:latest
+     entrypoint: [""]
+   script:
+   - kubectl config use-context path/to/agent/repository:agent-name
+   - kubectl get pods
+```
+
+When you use the Agent, KubeContexts are named as `path/to/agent/repository:agent-name`.
+
+To get the list of available contexts:
+
+1. Open your terminal and connect to your cluster.
+1. Run `kubectl config get-contexts`.
+
+### `kubectl` commands not supported
+
+The commands `kubectl exec`, `kubectl cp`, and `kubectl attach` are not supported by the CI/CD tunnel.
+Anything else that uses the same API endpoints does not work either as they use the deprecated
+SPDY protocol.
+We [plan to add support for these features](https://gitlab.com/gitlab-org/gitlab/-/issues/346248)
+in a future version of GitLab.
+
+### `kubectl` requires TLS
+
+`kubectl` would never send credentials over an unencrypted connection. Self-managed users should ensure that their
+GitLab instance is configured with TLS for the CI/CD tunnel feature to work. Trying to use it without TLS
+would produce errors:
+
+```shell
+$ kubectl get pods
+error: You must be logged in to the server (the server has asked for the client to provide credentials)
+```
+
+## Use impersonation to restrict project and group access **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5.
 
@@ -211,11 +266,11 @@ You can impersonate:
 - The CI job that accesses the cluster.
 - A specific user or system account defined within the cluster.
 
-#### Impersonate the Agent
+### Impersonate the Agent
 
 The Agent is impersonated by default. You don't need to do anything to impersonate it.
 
-#### Impersonate the CI job that accesses the cluster
+### Impersonate the CI job that accesses the cluster
 
 To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value
 under the `access_as` key.
@@ -261,7 +316,7 @@ ci_access:
       ci_job: {}
 ```
 
-#### Impersonate a static identity
+### Impersonate a static identity
 
 For the given CI/CD Tunnel connection, you can use a static identity for the impersonation.
 
@@ -278,6 +333,13 @@ See the [official Kubernetes documentation for more details](https://kubernetes.
 
 ## Surface network security alerts from cluster to GitLab **(ULTIMATE)**
 
+> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0.
+
+WARNING:
+Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476)
+for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477)
+in GitLab 15.0.
+
 The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts).
 To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the
 only configuration option is the Hubble relay address:
diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md
new file mode 100644
index 00000000000..2c9f98b7c45
--- /dev/null
+++ b/doc/user/clusters/agent/troubleshooting.md
@@ -0,0 +1,193 @@
+---
+stage: Configure
+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
+---
+
+# Troubleshooting the GitLab Agent for Kubernetes
+
+When you are using the GitLab Agent for Kubernetes, you might experience issues you need to troubleshoot.
+
+You can start by viewing the service logs:
+
+```shell
+kubectl logs -f -l=app=gitlab-agent -n gitlab-kubernetes-agent
+```
+
+If you are a GitLab administrator, you can also view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting).
+
+## Transport: Error while dialing failed to WebSocket dial
+
+```json
+{
+  "level": "warn",
+  "time": "2020-11-04T10:14:39.368Z",
+  "msg": "GetConfiguration failed",
+  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""
+}
+```
+
+This error is shown if there are some connectivity issues between the address
+specified as `kas-address`, and your Agent pod. To fix it, make sure that you
+specified the `kas-address` correctly.
+
+```json
+{
+  "level": "error",
+  "time": "2021-06-25T21:15:45.335Z",
+  "msg": "Reverse tunnel",
+  "mod_name": "reverse_tunnel",
+  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""
+}
+```
+
+This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the
+`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/`
+or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
+
+## ValidationError(Deployment.metadata)
+
+```json
+{
+  "level": "info",
+  "time": "2020-10-30T08:56:54.329Z",
+  "msg": "Synced",
+  "project_id": "root/kas-manifest001",
+  "resource_key": "apps/Deployment/kas-test001/nginx-deployment",
+  "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"
+}
+```
+
+This error is shown if a manifest file is malformed, and Kubernetes can't
+create specified objects. Make sure that your manifest files are valid. You
+may try using them to create objects in Kubernetes directly for more troubleshooting.
+
+## Error while dialing failed to WebSocket dial: failed to send handshake request
+
+```json
+{
+  "level": "warn",
+  "time": "2020-10-30T09:50:51.173Z",
+  "msg": "GetConfiguration failed",
+  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""
+}
+```
+
+This error is shown if you configured `wss` as `kas-address` on the agent side,
+but KAS on the server side is not available via `wss`. To fix it, make sure the
+same schemes are configured on both sides.
+
+It's not possible to set the `grpc` scheme due to the issue
+[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the
+issue is in progress, directly edit the deployment with the
+`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use
+`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`.
+
+## Decompressor is not installed for grpc-encoding
+
+```json
+{
+  "level": "warn",
+  "time": "2020-11-05T05:25:46.916Z",
+  "msg": "GetConfiguration.Recv failed",
+  "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""
+}
+```
+
+This error is shown if the version of the agent is newer that the version of KAS.
+To fix it, make sure that both `agentk` and KAS use the same versions.
+
+## Certificate signed by unknown authority
+
+```json
+{
+  "level": "error",
+  "time": "2021-02-25T07:22:37.158Z",
+  "msg": "Reverse tunnel",
+  "mod_name": "reverse_tunnel",
+  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""
+}
+```
+
+This error is shown if your GitLab instance is using a certificate signed by an internal CA that
+is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent
+via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it
+will be picked up automatically.
+
+For example, if your internal CA certificate is `myCA.pem`:
+
+```plaintext
+kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem
+```
+
+Then in `resources.yml`:
+
+```yaml
+    spec:
+      serviceAccountName: gitlab-kubernetes-agent
+      containers:
+      - name: agent
+        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
+        args:
+        - --token-file=/config/token
+        - --kas-address
+        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
+        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
+        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
+        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
+        volumeMounts:
+        - name: token-volume
+          mountPath: /config
+        - name: ca-pemstore-volume
+          mountPath: /etc/ssl/certs/myCA.pem
+          subPath: myCA.pem
+      volumes:
+      - name: token-volume
+        secret:
+          secretName: gitlab-kubernetes-agent-token
+      - name: ca-pemstore-volume
+        configMap:
+          name: ca-pemstore
+          items:
+          - key: myCA.pem
+            path: myCA.pem
+```
+
+Alternatively, you can mount the certificate file at a different location and include it using the
+`--ca-cert-file` agent parameter:
+
+```yaml
+      containers:
+      - name: agent
+        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
+        args:
+        - --ca-cert-file=/tmp/myCA.pem
+        - --token-file=/config/token
+        - --kas-address
+        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
+        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
+        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
+        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
+        volumeMounts:
+        - name: token-volume
+          mountPath: /config
+        - name: ca-pemstore-volume
+          mountPath: /tmp/myCA.pem
+          subPath: myCA.pem
+```
+
+## Project not found
+
+```json
+{
+  "level ":"error ",
+  "time ":"2022-01-05T15:18:11.331Z",
+  "msg ":"GetObjectsToSynchronize.Recv failed ",
+  "mod_name ":"gitops ",
+  "error ":"rpc error: code = NotFound desc = project not found ",
+}
+```
+
+This error is shown if the manifest project is not public. To fix it,
+[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files
+are stored in the Agent's configuration repository.
diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md
index 14850ca85b3..c99eef385ce 100644
--- a/doc/user/clusters/cost_management.md
+++ b/doc/user/clusters/cost_management.md
@@ -22,7 +22,7 @@ insights within GitLab:
 
 ## Configure cluster cost management
 
-To get started with cluster cost management, you need the [Maintainer role](../permissions.md) in a project or group.
+To get started with cluster cost management, you need the Maintainer role for a project or group.
 
 1. Clone the [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/)
    example repository, which contains minor modifications to the upstream Kubecost
diff --git a/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png b/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png
new file mode 100644
index 00000000000..91d7e40429e
--- /dev/null
+++ b/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png
diff --git a/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png b/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png
deleted file mode 100644
index 90b41ee849c..00000000000
--- a/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png
+++ /dev/null
diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png
deleted file mode 100644
index 3463eeb5d93..00000000000
--- a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png
+++ /dev/null
diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png
new file mode 100644
index 00000000000..5b5ba3a9804
--- /dev/null
+++ b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png
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 20c4408d57e..b2ba1bef338 100644
--- a/doc/user/clusters/migrating_from_gma_to_project_template.md
+++ b/doc/user/clusters/migrating_from_gma_to_project_template.md
@@ -23,16 +23,16 @@ 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:
+   - 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:
 
-      ```yaml
-      script:
-        - gl-fail-if-helm2-releases-exist <your_custom_namespace>
-      ```
+     ```yaml
+     script:
+       - gl-fail-if-helm2-releases-exist <your_custom_namespace>
+     ```
 
-    - If you kept the default name (`gitlab-managed-apps`), then the script is already
-      set up.
+   - If you kept the default name (`gitlab-managed-apps`), then the script is already
+     set up.
 
    Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the
    `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they.
@@ -53,7 +53,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
 
    ```shell
    helm ls -n gitlab-managed-apps
-   
+
    NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
    runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0
    ```
@@ -67,39 +67,42 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
 1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently
    deployed values. For example, for GitLab Runner:
 
-    1. Copy the output of the following command (it might be big):
+   1. Copy the output of the following command (it might be big):
 
-   ```shell
-   helm get values runner -n gitlab-managed-apps -a --output yaml
-   ```
+      ```shell
+      helm get values runner -n gitlab-managed-apps -a --output yaml
+      ```
 
-    1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command.
+   1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command.
 
    This safe step will guarantee that no unexpected default values overwrite your currently deployed values.
    For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake.
 
 1. Some apps require special attention:
 
-    - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see
-      `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file)
-      command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`,
-      you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`.
-      Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps`
-      and then overwriting each `ClusterIP` that it complains about with the value you got from that command.
-
-    - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart
-      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)).
+   - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see
+     `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file)
+     command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`,
+     you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`.
+     Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps`
+     and then overwriting each `ClusterIP` that it complains about with the value you got from that command.
+
+   - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart
+     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 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 the latest cert-manager instead. To install this version, uncomment `applications/cert-manager/helmfile.yaml`
+       from [`./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-legacy/helmfile.yaml`
+       in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)).
+
+       WARNING:
+       Cert-manager v0.10 breaks when Kubernetes is upgraded to version 1.20 or later.
 
 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
@@ -118,7 +121,7 @@ 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.
+   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`.