Merge branch 'agent-project-authorization-docs' into 'master'

Document authorizing projects for an Agent

See merge request gitlab-org/gitlab!73229

doc/user/clusters/agent/ci_cd_tunnel.md

@@ -38,11 +38,11 @@ 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`.
 
-## Share the CI/CD Tunnel provided by an Agent with other projects and group
+## Share the CI/CD Tunnel provided by an Agent with other projects and groups
 
 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.
 
-You can read more on how to [authorize access to groups in the Agent configuration reference](repository.md#authorize-groups-to-use-an-agent).
+You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent).
 
 ## Example for a `kubectl` command using the CI/CD Tunnel
 

doc/user/clusters/agent/repository.md

@@ -149,39 +149,52 @@ gitops:
     - glob: '/**/*.yaml'
 ```
 
-## Authorize groups to use an Agent
+## Authorize projects and groups to use an Agent
 
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
+> - 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
-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.
+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.
 
-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.
+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 groups in the same group hierarchy as the Agent's configuration project. At most
-100 groups can be authorized per 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.
 
-To authorize a group:
+### Authorize projects to use an Agent
 
-1. Edit your `config.yaml` file under the `.gitlab/agents/<agent name>` directory.
-1. Add the `ci_access` root attribute.
-1. Add the `groups` attribute into `ci_access`.
-1. Add the group `id` into `groups`, identifying the authorized group through its path.
+To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md):
 
-For example:
+1. Go to your Agent's configuration project.
+1. Edit the Agent's configuration file (`config.yaml`).
+1. Add the `projects` attribute into `ci_access`.
+1. Identify the new project through its path:
 
-```yaml
-ci_access:
-  # This agent is accessible from CI jobs in projects in these groups
+   ```yaml
+   ci_access:
+     projects:
+     - id: path/to/project
+   ```
+
+### Authorize groups to use an Agent
+
+To grant access to all projects within a group:
+
+1. Go to your Agent's configuration project.
+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:
+
+   ```yaml
+   ci_access:
      groups:
-  - id: group/subgroup
-```
+     - id: path/to/group/subgroup
+   ```
 
 ## Surface network security alerts from cluster to GitLab **(ULTIMATE)**
 

doc/user/infrastructure/clusters/index.md

@@ -68,7 +68,6 @@ The concept of [project-level](../../project/clusters/index.md),
 [instance-level](../../instance/clusters/index.md) clusters becomes
 extinct in the new model, although the functionality remains to some extent.
 
-The Agent is always configured in a GitLab project, but you can:
-
-- [Grant your cluster's access to GitLab groups through the Agent](../../clusters/agent/repository.md#authorize-groups-to-use-an-agent).
-- [Share access to the Agent with other projects and groups through the CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md#share-the-cicd-tunnel-provided-by-an-agent-with-other-projects-and-group).
+The Agent is always configured in a single GitLab project, but you can use the CI/CD Tunnel to
+[authorize other projects and groups to use the same Agent](../../clusters/agent/repository.md#authorize-projects-and-groups-to-use-an-agent).
+By doing so, you are granting these projects and groups access to the same cluster, which is similar to group-level clusters' use case.