Add latest changes from gitlab-org/gitlab@master

1 files changed, 29 insertions, 37 deletions

diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 6c319f575c5..bfa47291b0b 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -12,53 +12,45 @@ 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).
-
-## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD
+To ensure access to your cluster is safe, only the projects you
+authorize can access your Agent through the CI/CD Tunnel.
 
-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: `<namespace>/<project-name>:<agent-name>`.
-To get the list of available contexts, run `kubectl config get-contexts`.
+## Prerequisites
 
-## Share the CI/CD Tunnel provided by an Agent with other projects and groups
+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).
 
-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.
+To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster.
 
-You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent).
+## How the CI/CD Tunnel works
 
-## Restrict access of authorized projects and groups **(PREMIUM)**
+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.
 
-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.
+When you authorize a group, all the projects that belong to that group
+become authorized to access the selected Agent.
 
-## Example for a `kubectl` command using the 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.
 
-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:
+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.
 
-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).