Add latest changes from gitlab-org/gitlab@14-7-stable-eev14.7.0-rc42

4 files changed, 48 insertions, 247 deletions

diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 93768164df2..f1c49b87383 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -19,11 +19,8 @@ Only CI/CD jobs set in the configuration project can access one of the configure
 
 ## Prerequisites
 
-- A running [`kas` instance](install/index.md#set-up-the-agent-server).
-- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file
-  installed (`.gitlab/agents/<agent-name>/config.yaml`).
-- A [registered agent](install/index.md#register-an-agent-with-gitlab).
-- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster).
+- An existing Kubernetes cluster.
+- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster).
 
 ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD
 
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index c950a4f0dc0..a235c0ef6f8 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -18,10 +18,6 @@ is an active in-cluster component for connecting Kubernetes clusters to GitLab s
 
 The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution.
 
-INFO:
-Get Network Security Alerts in GitLab by upgrading to Ultimate.
-[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-cluster-agent-docs).
-
 With GitOps, you can manage containerized clusters and applications from a Git repository that:
 
 - Is the single source of truth of your system.
@@ -136,7 +132,22 @@ with the following differences:
 
 ## Remove an agent
 
-1. Get the `<cluster-agent-id>` and the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer.
+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).
+
+### Remove an agent through the GitLab UI
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323055) in GitLab 14.7.
+
+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**.
+
+### 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.
 
@@ -157,7 +168,7 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e
    }
    ```
 
-1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`.
+1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`.
 
    ```graphql
    mutation deleteAgent {
@@ -190,6 +201,10 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e
    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
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index cf8467a8d28..b2372789284 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -10,42 +10,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 To get started with the Agent, install it in your cluster.
 
-Pre-requisites:
+## Prerequisites **(SELF)**
 
 - An existing Kubernetes cluster.
-- An account on GitLab.
+- 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:
 
-1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance.
 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. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret).
-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.
 
-### Set up the Agent Server
-
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`.
-
-To use the KAS:
-
-- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md).
-- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`.
-
 ### 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:
-
-1. A GitLab repository to hold the configuration file.
-1. Install the Agent in a cluster.
+To create an agent, you need a GitLab repository to hold the configuration file.
 
 After installed, when you update the configuration file, GitLab transmits the
 information to the cluster automatically without downtime.
@@ -62,7 +47,7 @@ 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. It doesn't do anything so far, but, later on, you can use this
+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:
 
 - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md).
@@ -71,10 +56,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as
 
 To see all the settings available, read the [Agent configuration repository documentation](../repository.md).
 
-### Access your cluster from GitLab CI/CD
-
-Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD.
-
 ### Register an 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.
@@ -92,242 +73,53 @@ In GitLab:
 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**.
 
+### Install the agent into the cluster
+
 In your computer:
 
 1. Open your local terminal and connect to your cluster.
-1. Run the command you copied from the installation form.
+1. Run the command you copied when registering your cluster in the previous step.
 
-### Install the agent into the cluster
+See the following sections to learn about customizing the installation.
 
-To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace,
-for example, `gitlab-kubernetes-agent`, run:
+## Simple installation method
 
-```shell
-kubectl create namespace gitlab-kubernetes-agent
-```
+The command provided by GitLab does the following things:
 
-To perform a one-liner installation, run the command below. Make sure to replace:
+- 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.
+- Creates a `Deployment` resource for the `agentk` pod.
 
-- `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 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.
+The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run:
 
 ```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=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f -
+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.
 
-To find out the various options the above Docker container supports, run:
-
-```shell
-docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
-```
-
-## Advanced installation
+## Advanced installation method
 
 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).
 
 Otherwise, follow the manual installation steps described below.
 
-### Create the Kubernetes secret
-
-After generating the token, you must apply it to the Kubernetes cluster.
-
-To create your Secret, run:
-
-```shell
-kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN'
-```
-
-The following example file contains the
-Kubernetes resources required for the Agent to be installed. You can modify this
-example [`resources.yml` file](#example-resourcesyml-file) in the following ways:
-
-- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`.
-- You can configure `kas-address` (Agent Server) in several ways.
-  The agent can use the WebSockets or gRPC protocols to connect to the Agent Server.
-  Select the option appropriate for your cluster configuration and GitLab architecture:
-  - The `wss` scheme (an encrypted WebSockets connection) is specified by default
-    after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab.
-    When using the sub-chart, you must set `wss://kas.host.tld:443` as
-    `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation.
-    When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as
-    `kas-address`, where `GitLab.host.tld` is your GitLab hostname.
-  - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`)
-    to use an unencrypted WebSockets connection.
-    When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`).
-  - Specify the `grpc` scheme if both Agent and Server are installed in one cluster.
-    In this case, you may specify `kas-address` value as
-    `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas`
-    is the name of the service created by `gitlab-kas` chart, and `<your-namespace>`
-    is the namespace where the chart was installed.
-  - Specify the `grpcs` scheme to use an encrypted gRPC connection.
-  - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the
-    `kas-address` for `wss` and `ws` schemes to whatever you need.
-    Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress)
-    to learn more about it.
-  - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details.
-- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your
-  secret name in the `secretName:` section.
-
-To apply this file, run the following command:
+### Customize the permissions for the `agentk` service account
 
-```shell
-kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml
-```
-
-To review your configuration, run the following command:
-
-```shell
-$ kubectl get pods -n gitlab-kubernetes-agent
-
-NAMESPACE                NAME                                          READY   STATUS    RESTARTS   AGE
-gitlab-kubernetes-agent  gitlab-kubernetes-agent-77689f7dcb-5skqk      1/1     Running   0          51s
-```
-
-#### Example `resources.yml` file
-
-```yaml
----
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: gitlab-kubernetes-agent
----
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: gitlab-kubernetes-agent
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: gitlab-kubernetes-agent
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: gitlab-kubernetes-agent
-  template:
-    metadata:
-      labels:
-        app: gitlab-kubernetes-agent
-    spec:
-      serviceAccountName: gitlab-kubernetes-agent
-      containers:
-      - name: agent
-        # Make sure to specify a matching version for production
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z"
-        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
-      volumes:
-      - name: token-volume
-        secret:
-          secretName: gitlab-kubernetes-agent-token
-  strategy:
-    type: RollingUpdate
-    rollingUpdate:
-      maxSurge: 0
-      maxUnavailable: 1
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: gitlab-kubernetes-agent-write
-rules:
-- resources:
-  - '*'
-  apiGroups:
-  - '*'
-  verbs:
-  - create
-  - update
-  - delete
-  - patch
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: gitlab-kubernetes-agent-write-binding
-roleRef:
-  name: gitlab-kubernetes-agent-write
-  kind: ClusterRole
-  apiGroup: rbac.authorization.k8s.io
-subjects:
-- name: gitlab-kubernetes-agent
-  kind: ServiceAccount
-  namespace: gitlab-kubernetes-agent
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: gitlab-kubernetes-agent-read
-rules:
-- resources:
-  - '*'
-  apiGroups:
-  - '*'
-  verbs:
-  - get
-  - list
-  - watch
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: gitlab-kubernetes-agent-read-binding
-roleRef:
-  name: gitlab-kubernetes-agent-read
-  kind: ClusterRole
-  apiGroup: rbac.authorization.k8s.io
-subjects:
-- name: gitlab-kubernetes-agent
-  kind: ServiceAccount
-  namespace: gitlab-kubernetes-agent
-```
-
-### Create manifest files
+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.
 
-In a previous step, you configured a `config.yaml` to point to the GitLab projects
-the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a
-templating engine or other means.
+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.
 
-The agent is authorized to download manifests for the configuration
-project, and public projects. Support for other private projects is
-planned in the issue [Agent authorization for private manifest
-projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
+To create restricted permissions:
 
-Each time you push a change to a monitored manifest repository, the Agent logs the change:
+1. Copy the `cluster` directory.
+1. Edit the `kustomization.yaml` and `components/*` files based on your requirements.
+1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration.
 
-```plaintext
-2020-09-15_14:09:04.87946 gitlab-k8s-agent      : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea
-```
-
-#### Example manifest file
-
-This file creates a minimal `ConfigMap`:
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: demo-map
-  namespace: gitlab-kubernetes-agent  # Can be any namespace managed by you that the agent has access to.
-data:
-  key: value
-```
+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
 
diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md
index c8ab037118e..22964fde395 100644
--- a/doc/user/clusters/agent/repository.md
+++ b/doc/user/clusters/agent/repository.md
@@ -12,9 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
 > - [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.
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
 The [GitLab Agent](index.md) supports hosting your configuration for
 multiple agents in a single repository. These agents can be running
 in the same cluster or in multiple clusters, and potentially with more than one agent per cluster.