Merge branch 'docs-refactor-add-clusters' into 'master'

Docs: Refactor adding and removing clusters doc

See merge request gitlab-org/gitlab!62846

app/views/clusters/clusters/aws/_new.html.haml

@@ -12,6 +12,6 @@
     'role-arn' => @aws_role.role_arn,
     'instance-types' => @instance_types,
     'kubernetes-integration-help-path' => help_page_path('user/project/clusters/index'),
-    'account-and-external-ids-help-path' => help_page_path('user/project/clusters/add_eks_clusters.md', anchor: 'new-eks-cluster'),
-    'create-role-arn-help-path' => help_page_path('user/project/clusters/add_eks_clusters.md', anchor: 'new-eks-cluster'),
+    'account-and-external-ids-help-path' => help_page_path('user/project/clusters/add_eks_clusters.md', anchor: 'create-a-new-certificate-based-eks-cluster'),
+    'create-role-arn-help-path' => help_page_path('user/project/clusters/add_eks_clusters.md', anchor: 'create-a-new-certificate-based-eks-cluster'),
     'external-link-icon' => sprite_icon('external-link') } }

doc/user/clusters/management_project.md

@@ -22,7 +22,7 @@ This can be useful for:
 ## Permissions
 Only the management project receives `cluster-admin` privileges. All
-other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources).
+other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/cluster_access.md#rbac-cluster-resources).
 Management projects are restricted to the following:

doc/user/group/clusters/index.md

@@ -163,7 +163,7 @@ are deployed to the Kubernetes cluster, see the documentation for
 ## Security of runners
 For important information about securely configuring runners, see
-[Security of runners](../../project/clusters/add_remove_clusters.md#security-of-runners)
+[Security of runners](../../project/clusters/cluster_access.md#security-of-runners)
 documentation for project-level clusters.
 ## More information

doc/user/project/clusters/add_existing_cluster.md

+---
+stage: Configure
+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
+---
+
+# Add an existing Kubernetes cluster
+
+If you have an existing Kubernetes cluster, you can add it to a project, group,
+or instance and benefit from the integration with GitLab.
+
+## Prerequisites
+
+See the prerequisites below to add existing clusters to GitLab.
+
+### All clusters
+
+To add any cluster to GitLab, you need:
+
+- Either a GitLab.com account or an account for a self-managed installation
+running GitLab 12.5 or later.
+- Maintainer permissions for group-level and project-level clusters.
+- Access to the Admin area for instance-level clusters. **(FREE SELF)**
+- A Kubernetes cluster.
+- Cluster administration access to the cluster with `kubectl`.
+
+You can host your cluster in [EKS](#eks-clusters), [GKE](#gke-clusters),
+on premises, and with other providers.
+To host them on premises and with other providers,
+use either the EKS or GKE method to guide you through and enter your cluster's
+settings manually.
+
+WARNING:
+GitLab doesn't support `arm64` clusters. See the issue
+[Helm Tiller fails to install on `arm64` cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838)
+for details.
+
+### EKS clusters
+
+To add an existing **EKS** cluster, you need:
+
+- An Amazon EKS cluster with worker nodes properly configured.
+- `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl)
+for access to the EKS cluster.
+- Ensure the token of the account has administrator privileges for the cluster.
+
+### GKE clusters
+
+To add an existing **GKE** cluster, you need:
+
+- The `container.clusterRoleBindings.create` permission to create a cluster
+role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
+to grant access.
+
+## How to add an existing cluster
+
+<!-- (REVISE -  BREAK INTO SMALLER STEPS) -->
+
+To add a Kubernetes cluster to your project, group, or instance:
+
+1. Navigate to your:
+   1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster.
+   1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster.
+   1. **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster.
+1. Click **Add Kubernetes cluster**.
+1. Click the **Add existing cluster** tab and fill in the details:
+   1. **Kubernetes cluster name** (required) - The name you wish to give the cluster.
+   1. **Environment scope** (required) - The
+      [associated environment](index.md#setting-the-environment-scope) to this cluster.
+   1. **API URL** (required) -
+      It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
+      exposes several APIs, we want the "base" URL that is common to all of them.
+      For example, `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
+
+      Get the API URL by running this command:
+
+      ```shell
+      kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}'
+      ```
+
+   1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default.
+      1. List the secrets with `kubectl get secrets`, and one should be named similar to
+         `default-token-xxxxx`. Copy that token name for use below.
+      1. Get the certificate by running this command:
+
+         ```shell
+         kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
+         ```
+
+         If the command returns the entire certificate chain, you must copy the Root CA
+         certificate and any intermediate certificates at the bottom of the chain.
+         A chain file has following structure:
+
+         ```plaintext
+            -----BEGIN MY CERTIFICATE-----
+            -----END MY CERTIFICATE-----
+            -----BEGIN INTERMEDIATE CERTIFICATE-----
+            -----END INTERMEDIATE CERTIFICATE-----
+            -----BEGIN INTERMEDIATE CERTIFICATE-----
+            -----END INTERMEDIATE CERTIFICATE-----
+            -----BEGIN ROOT CERTIFICATE-----
+            -----END ROOT CERTIFICATE-----
+         ```
+
+   1. **Token** -
+      GitLab authenticates against Kubernetes using service tokens, which are
+      scoped to a particular `namespace`.
+      **The token used should belong to a service account with
+      [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+      privileges.** To create this service account:
+      1. Create a file called `gitlab-admin-service-account.yaml` with contents:
+
+         ```yaml
+         apiVersion: v1
+         kind: ServiceAccount
+         metadata:
+           name: gitlab
+           namespace: kube-system
+         ---
+         apiVersion: rbac.authorization.k8s.io/v1
+         kind: ClusterRoleBinding
+         metadata:
+           name: gitlab-admin
+         roleRef:
+           apiGroup: rbac.authorization.k8s.io
+           kind: ClusterRole
+           name: cluster-admin
+         subjects:
+           - kind: ServiceAccount
+             name: gitlab
+             namespace: kube-system
+         ```
+
+      1. Apply the service account and cluster role binding to your cluster:
+
+         ```shell
+         kubectl apply -f gitlab-admin-service-account.yaml
+         ```
+
+         You need the `container.clusterRoleBindings.create` permission
+         to create cluster-level roles. If you do not have this permission,
+         you can alternatively enable Basic Authentication and then run the
+         `kubectl apply` command as an administrator:
+
+         ```shell
+         kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password>
+         ```
+
+         NOTE:
+         Basic Authentication can be turned on and the password credentials
+         can be obtained using the Google Cloud Console.
+
+         Output:
+
+         ```shell
+         serviceaccount "gitlab" created
+         clusterrolebinding "gitlab-admin" created
+         ```
+
+      1. Retrieve the token for the `gitlab` service account:
+
+         ```shell
+         kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}')
+         ```
+
+         Copy the `<authentication_token>` value from the output:
+
+         ```plaintext
+         Name:         gitlab-token-b5zv4
+         Namespace:    kube-system
+         Labels:       <none>
+         Annotations:  kubernetes.io/service-account.name=gitlab
+                      kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
+
+         Type:  kubernetes.io/service-account-token
+
+         Data
+         ====
+         ca.crt:     1025 bytes
+         namespace:  11 bytes
+         token:      <authentication_token>
+         ```
+
+   1. **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster.
+      See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information.
+   1. **Project namespace** (optional) - You don't have to fill this in. By leaving
+      it blank, GitLab creates one for you. Also:
+      - Each project should have a unique namespace.
+      - The project namespace is not necessarily the namespace of the secret, if
+        you're using a secret with broader permissions, like the secret from `default`.
+      - You should **not** use `default` as the project namespace.
+      - If you or someone created a secret specifically for the project, usually
+        with limited permissions, the secret's namespace and project namespace may
+        be the same.
+
+1. Select the **Add Kubernetes cluster** button.
+
+After about 10 minutes, your cluster is ready.
+
+## Disable Role-Based Access Control (RBAC) (optional)
+
+When connecting a cluster via GitLab integration, you may specify whether the
+cluster is RBAC-enabled or not. This affects how GitLab interacts with the
+cluster for certain operations. If you did *not* check the **RBAC-enabled cluster**
+checkbox at creation time, GitLab assumes RBAC is disabled for your cluster
+when interacting with it. If so, you must disable RBAC on your cluster for the
+integration to work properly.
+
+![RBAC](img/rbac_v13_1.png)
+
+WARNING:
+Disabling RBAC means that any application running in the cluster,
+or user who can authenticate to the cluster, has full API access. This is a
+[security concern](index.md#security-implications), and may not be desirable.
+
+To effectively disable RBAC, global permissions can be applied granting full access:
+
+```shell
+kubectl create clusterrolebinding permissive-binding \
+  --clusterrole=cluster-admin \
+  --user=admin \
+  --user=kubelet \
+  --group=system:serviceaccounts
+```

doc/user/project/clusters/add_gke_clusters.md

@@ -4,7 +4,15 @@ 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
 ---
-# Adding GKE clusters **(FREE)**
+# GKE clusters (DEPRECATED) **(FREE)**
+
+> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0.
+
+WARNING:
+Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0.
+
+Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic
+Kubernetes Service (EKS).
 GitLab supports adding new and existing GKE clusters.
@@ -19,7 +27,12 @@ requirements are met:
   take up to 10 minutes after you create a project. For more information see the
   ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
-## New GKE cluster
+## Add an existing GKE cluster
+
+If you already have a GKE cluster and want to integrate it with GitLab,
+see how to [add an existing cluster](add_existing_cluster.md).
+
+## Create new GKE cluster
 Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/25925), all the GKE clusters
 provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips).
@@ -30,13 +43,13 @@ Note the following:
   at the instance level. If that's not the case, ask your GitLab administrator to enable it. On
   GitLab.com, this is enabled.
 - Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55902), all GKE clusters
-  created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for
+  created by GitLab are RBAC-enabled. Take a look at the [RBAC section](cluster_access.md#rbac-cluster-resources) for
   more information.
 - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the
   cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR
   notation.
 - GitLab requires basic authentication enabled and a client certificate issued for the cluster to
-  set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions
+  set up an [initial service account](cluster_access.md). In [GitLab versions
   11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process
   explicitly requests GKE to create clusters with basic authentication enabled and a client
   certificate.
@@ -49,7 +62,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance:
    - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level
      cluster.
    - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster.
-   - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster.
+   - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster.
 1. Click **Integrate with a cluster certificate**.
 1. Under the **Create new cluster** tab, click **Google GKE**.
 1. Connect your Google account if you haven't done already by clicking the
@@ -81,8 +94,3 @@ You can choose to use Cloud Run for Anthos in place of installing Knative and Is
 separately after the cluster has been created. This means that Cloud Run
 (Knative), Istio, and HTTP Load Balancing are enabled on the cluster
 from the start, and cannot be installed or uninstalled.
-
-## Existing GKE cluster
-
-For information on adding an existing GKE cluster, see
-[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster).

doc/user/project/clusters/cluster_access.md

+---
+stage: Configure
+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
+---
+
+# Cluster access controls (RBAC or ABAC)
+
+> Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5.
+
+When creating a cluster in GitLab, you are asked if you would like to create either:
+
+- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+  cluster, which is the GitLab default and recommended option.
+- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster.
+
+When GitLab creates the cluster,
+a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace
+to manage the newly created cluster.
+
+Helm also creates additional service accounts and other resources for each
+installed application. Consult the documentation of the Helm charts for each application
+for details.
+
+If you are [adding an existing Kubernetes cluster](add_remove_clusters.md#add-existing-cluster),
+ensure the token of the account has administrator privileges for the cluster.
+
+The resources created by GitLab differ depending on the type of cluster.
+
+## Important notes
+
+Note the following about access controls:
+
+- Environment-specific resources are only created if your cluster is
+  [managed by GitLab](index.md#gitlab-managed-clusters).
+- If your cluster was created before GitLab 12.2, it uses a single namespace for all project
+  environments.
+
+## RBAC cluster resources
+
+GitLab creates the following resources for RBAC clusters.
+
+| Name                  | Type                 | Details                                                                                                    | Created when           |
+|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:-----------------------|
+| `gitlab`              | `ServiceAccount`     | `default` namespace                                                                                        | Creating a new cluster |
+| `gitlab-admin`        | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new cluster |
+| `gitlab-token`        | `Secret`             | Token for `gitlab` ServiceAccount                                                                          | Creating a new cluster |
+| Environment namespace | `Namespace`          | Contains all environment-specific resources                                                                | Deploying to a cluster |
+| Environment namespace | `ServiceAccount`     | Uses namespace of environment                                                                              | Deploying to a cluster |
+| Environment namespace | `Secret`             | Token for environment ServiceAccount                                                                       | Deploying to a cluster |
+| Environment namespace | `RoleBinding`        | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef         | Deploying to a cluster |
+
+The environment namespace `RoleBinding` was
+[updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6
+to `admin` roleRef. Previously, the `edit` roleRef was used.
+
+## ABAC cluster resources
+
+GitLab creates the following resources for ABAC clusters.
+
+| Name                  | Type                 | Details                              | Created when               |
+|:----------------------|:---------------------|:-------------------------------------|:---------------------------|
+| `gitlab`              | `ServiceAccount`     | `default` namespace                         | Creating a new cluster |
+| `gitlab-token`        | `Secret`             | Token for `gitlab` ServiceAccount           | Creating a new cluster |
+| Environment namespace | `Namespace`          | Contains all environment-specific resources | Deploying to a cluster |
+| Environment namespace | `ServiceAccount`     | Uses namespace of environment               | Deploying to a cluster |
+| Environment namespace | `Secret`             | Token for environment ServiceAccount        | Deploying to a cluster |
+
+## Security of runners
+
+Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode)
+enabled by default, which allows them to execute special commands and run
+Docker in Docker. This functionality is needed to run some of the
+[Auto DevOps](../../../topics/autodevops/index.md)
+jobs. This implies the containers are running in privileged mode and you should,
+therefore, be aware of some important details.
+
+The privileged flag gives all capabilities to the running container, which in
+turn can do almost everything that the host can do. Be aware of the
+inherent security risk associated with performing `docker run` operations on
+arbitrary images as they effectively have root access.
+
+If you don't want to use a runner in privileged mode, either:
+
+- Use shared runners on GitLab.com. They don't have this security issue.
+- Set up your own runners using the configuration described at
+[shared runners](../../gitlab_com/index.md#shared-runners) using
+[`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html).

doc/user/project/clusters/index.md

@@ -12,35 +12,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in
 >   GitLab 11.11 for [instances](../../instance/clusters/index.md).
-Using the GitLab project Kubernetes integration, you can:
-- Use [Review Apps](../../../ci/review_apps/index.md).
-- Run [pipelines](../../../ci/pipelines/index.md).
+You can use GitLab to manage your clusters and [benefit from the GitLab-Kubernetes integration](#benefit-from-the-gitlab-kubernetes-integration).
+See the [supported cluster versions](#supported-cluster-versions) before
+you begin.
+
+## Benefit from the GitLab-Kubernetes integration
+
+Using the GitLab-Kubernetes integration, you can benefit of GitLab
+features such as:
+
+- Preview your applications with [Review Apps](../../../ci/review_apps/index.md).
+- Create GitLab CI/CD [Pipelines](../../../ci/pipelines/index.md) to build, test, and deploy to your cluster.
 - [Deploy](#deploying-to-a-kubernetes-cluster) your applications.
-- Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster).
-- Use it with [Auto DevOps](#auto-devops).
+- Detect and [monitor](#monitoring-your-kubernetes-cluster) your clusters.
+- Use [Auto DevOps](#auto-devops) to automate the CI/CD process.
 - Use [Web terminals](#web-terminals).
 - Use [Deploy Boards](#deploy-boards).
 - Use [Canary Deployments](#canary-deployments). **(PREMIUM)**
 - Use [deployment variables](#deployment-variables).
-- Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls).
+- Use [role-based or attribute-based access controls](cluster_access.md).
 - View [Logs](#viewing-pod-logs).
 - Run serverless workloads on [Kubernetes with Knative](serverless/index.md).
-Besides integration at the project level, Kubernetes clusters can also be
-integrated at the [group level](../../group/clusters/index.md) or
-[GitLab instance level](../../instance/clusters/index.md).
-
-To view your project level Kubernetes clusters, navigate to **Infrastructure > Kubernetes clusters**
-from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters)
-and view information about your existing clusters, such as:
-
-- Nodes count.
-- Rough estimates of memory and CPU usage.
-
-## Setting up
-
-### Supported cluster versions
+- Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md).
+## Supported cluster versions
 GitLab is committed to support at least two production-ready Kubernetes minor
 versions at any given time. We regularly review the versions we support, and
@@ -61,19 +57,31 @@ Kubernetes version to any supported version at any time:
 Some GitLab features may support versions outside the range provided here.
-NOTE:
-[GKE Cluster creation](add_remove_clusters.md#create-new-cluster) by GitLab is currently not supported for Kubernetes 1.19+. For these versions you can create the cluster through GCP, then [Add existing cluster](add_remove_clusters.md#add-existing-cluster). See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331922) for more information.
-### Adding and removing clusters
-See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how
-to:
-- Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service
-  (EKS) using the GitLab UI.
-- Add an integration to an existing cluster from any Kubernetes platform.
-### Multiple Kubernetes clusters
+## Add and remove clusters
+
+You can create new or add existing clusters to GitLab:
+- On the project-level, to have a cluster dedicated to a project.
+- On the [group level](../../group/clusters/index.md), to use the same cluster across multiple projects within your group.
+- On the [instance level](../../instance/clusters/index.md), to use the same cluster across multiple groups and projects. **(FREE SELF)**
+To create new clusters, use one of the following methods:
+- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**).
+- [Cluster certificates](add_remove_clusters.md) (**deprecated**).
+You can also [add existing clusters](add_existing_cluster.md) to GitLab.
+
+## View your clusters
+
+To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters**
+from your project. On this page, you can add a new cluster
+and view information about your existing clusters, such as:
+
+- Nodes count.
+- Rough estimates of memory and CPU usage.
+
+## Multiple Kubernetes clusters
 > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2.
@@ -85,7 +93,7 @@ Add another cluster, like you did the first time, and make sure to
 [set an environment scope](#setting-the-environment-scope) that
 differentiates the new cluster from the rest.
-#### Setting the environment scope
+### Setting the environment scope
 When adding more than one Kubernetes cluster to your project, you need to differentiate
 them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the
@@ -141,8 +149,8 @@ The results:
 ## Configuring your Kubernetes cluster
-After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers
-important considerations for configuring Kubernetes clusters with GitLab.
+Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely
+configure your clusters. Otherwise, there are [security implications](#security-implications).
 ### Security implications
@@ -172,6 +180,8 @@ for your deployment jobs to use. Otherwise, a namespace is created for you.
 #### Important notes
+Note the following with GitLab and clusters:
+
 Be aware that manually managing resources that have been created by GitLab, like
 namespaces and service accounts, can cause unexpected errors. If this occurs, try
 [clearing the cluster cache](#clearing-the-cluster-cache).
@@ -253,6 +263,11 @@ This list provides a generic solution, and some GitLab-specific approaches:
 If you see a trailing `%` on some Kubernetes versions, do not include it.
+## Cluster integrations
+
+See the available [cluster integrations](../../clusters/integrations.md)
+to integrate third-party applications with your clusters through GitLab.
+
 ## Cluster management project
 Attach a [Cluster management project](../../clusters/management_project.md)
@@ -261,14 +276,8 @@ installation, such as an Ingress controller.
 ## Auto DevOps
-Auto DevOps automatically detects, builds, tests, deploys, and monitors your
-applications.
-
-To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and
-Auto Monitoring) the Kubernetes project integration must be enabled. However,
-Kubernetes clusters can be used without Auto DevOps.
-
-[Read more about Auto DevOps](../../../topics/autodevops/index.md).
+You can use [Auto DevOps](../../../topics/autodevops/index.md) to automatically
+detect, build, test, deploy, and monitor your applications.
 ## Deploying to a Kubernetes cluster
@@ -309,7 +318,7 @@ GitLab CI/CD build environment to deployment jobs. Deployment jobs have
 | Deployment Variable        | Description |
 |----------------------------|-------------|
 | `KUBE_URL`                 | Equal to the API URL. |
-| `KUBE_TOKEN`               | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. |
+| `KUBE_TOKEN`               | The Kubernetes token of the [environment service account](cluster_access.md). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. |
 | `KUBE_NAMESPACE`           | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. |
 | `KUBE_CA_PEM_FILE`         | Path to a file containing PEM data. Only present if a custom CA bundle was specified. |
 | `KUBE_CA_PEM`              | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. |