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

3 files changed, 82 insertions, 47 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).