Merge branch 'group-level-agent-tunnel-docs' into 'master'

Docs: Authorize groups in an Agent configuration project

See merge request gitlab-org/gitlab!70574

doc/user/clusters/agent/ci_cd_tunnel.md

@@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
 > - 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.
@@ -29,10 +30,8 @@ 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>`.
-
-You can get the list of available contexts by running `kubectl config get-contexts`.
+To get the list of available contexts, run `kubectl config get-contexts`.
 
 ## Example for a `kubectl` command using the CI/CD Tunnel
 

doc/user/clusters/agent/index.md

@@ -106,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:
 
@@ -125,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

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).