Merge branch 'docs-refactor-k8s-cluster-index' into 'master'

Docs: Reorg K8s Clusters index

See merge request gitlab-org/gitlab!64539

app/views/clusters/clusters/_provider_details_form.html.haml

@@ -43,13 +43,13 @@
         label_class: 'label-bold' }
       .form-text.text-muted
         = s_('ClusterIntegration|Allow GitLab to manage namespaces and service accounts for this cluster.')
-        = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'gitlab-managed-clusters'), target: '_blank'
+        = link_to _('More information'), help_page_path('user/project/clusters/gitlab_managed_clusters.md'), target: '_blank'
 
     .form-group
       = field.check_box :namespace_per_environment, { label: s_('ClusterIntegration|Namespace per environment'), label_class: 'label-bold' }
       .form-text.text-muted
         = s_('ClusterIntegration|Deploy each environment to its own namespace. Otherwise, environments within a project share a project-wide namespace. Note that anyone who can trigger a deployment of a namespace can read its secrets. If modified, existing environments will use their current namespaces until the cluster cache is cleared.')
-        = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'custom-namespace'), target: '_blank'
+        = link_to _('More information'), help_page_path('user/project/clusters/deploy_to_cluster.md', anchor: 'custom-namespace'), target: '_blank'
 
     - if cluster.allow_user_defined_namespace?
       = render('clusters/clusters/namespace', platform_field: platform_field, field: field)

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

@@ -3,8 +3,8 @@
       anchor: 'additional-requirements-for-self-managed-instances') }
   = s_('Amazon authentication is not %{link_start}correctly configured%{link_end}. Ask your GitLab administrator if you want to use this service.').html_safe % { link_start: documentation_link_start, link_end: '<a/>'.html_safe }
 - else
-  .js-create-eks-cluster-form-container{ data: { 'gitlab-managed-cluster-help-path' => help_page_path('user/project/clusters/index.md', anchor: 'gitlab-managed-clusters'),
-    'namespace-per-environment-help-path' => help_page_path('user/project/clusters/index.md', anchor: 'custom-namespace'),
+  .js-create-eks-cluster-form-container{ data: { 'gitlab-managed-cluster-help-path' => help_page_path('user/project/clusters/gitlab_managed_clusters.md'),
+    'namespace-per-environment-help-path' => help_page_path('user/project/clusters/deploy_to_cluster.md', anchor: 'custom-namespace'),
     'create-role-path' => clusterable.authorize_aws_role_path,
     'create-cluster-path' => clusterable.create_aws_clusters_path,
     'account-id' => Gitlab::CurrentSettings.eks_account_id,

app/views/clusters/clusters/gcp/_form.html.haml

@@ -74,13 +74,13 @@
       label_class: 'label-bold' }
     .form-text.text-muted
       = s_('ClusterIntegration|Allow GitLab to manage namespaces and service accounts for this cluster.')
-      = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'gitlab-managed-clusters'), target: '_blank'
+      = link_to _('More information'), help_page_path('user/project/clusters/gitlab_managed_clusters.md', anchor: 'gitlab-managed-clusters'), target: '_blank'
 
   .form-group
     = field.check_box :namespace_per_environment, { label: s_('ClusterIntegration|Namespace per environment'), label_class: 'label-bold' }
     .form-text.text-muted
       = s_('ClusterIntegration|Deploy each environment to its own namespace. Otherwise, environments within a project share a project-wide namespace. Note that anyone who can trigger a deployment of a namespace can read its secrets. If modified, existing environments will use their current namespaces until the cluster cache is cleared.')
-      = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'custom-namespace'), target: '_blank'
+      = link_to _('More information'), help_page_path('user/project/clusters/deploy_to_cluster.md', anchor: 'custom-namespace'), target: '_blank'
 
   .form-group.js-gke-cluster-creation-submit-container
     = field.submit s_('ClusterIntegration|Create Kubernetes cluster'),

app/views/clusters/clusters/user/_form.html.haml

@@ -47,13 +47,13 @@
       label_class: 'label-bold' }
     .form-text.text-muted
       = s_('ClusterIntegration|Allow GitLab to manage namespaces and service accounts for this cluster.')
-      = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'gitlab-managed-clusters'), target: '_blank'
+      = link_to _('More information'), help_page_path('user/project/clusters/gitlab_managed_clusters.md'), target: '_blank'
 
   .form-group
     = field.check_box :namespace_per_environment, { label: s_('ClusterIntegration|Namespace per environment'), label_class: 'label-bold' }
     .form-text.text-muted
       = s_('ClusterIntegration|Deploy each environment to its own namespace. Otherwise, environments within a project share a project-wide namespace. Note that anyone who can trigger a deployment of a namespace can read its secrets. If modified, existing environments will use their current namespaces until the cluster cache is cleared.')
-      = link_to _('More information'), help_page_path('user/project/clusters/index.md', anchor: 'custom-namespace'), target: '_blank'
+      = link_to _('More information'), help_page_path('user/project/clusters/deploy_to_cluster.md', anchor: 'custom-namespace'), target: '_blank'
 
   = field.fields_for :platform_kubernetes, @user_cluster.platform_kubernetes do |platform_kubernetes_field|
     - if @user_cluster.allow_user_defined_namespace?

app/views/projects/settings/ci_cd/_autodevops_form.html.haml

@@ -6,7 +6,7 @@
 - kubernetes_cluster_path = help_page_path('user/project/clusters/index')
 - kubernetes_cluster_link_start = link_start % { url: kubernetes_cluster_path }
 
-- base_domain_path = help_page_path('user/project/clusters/index', anchor: 'base-domain')
+- base_domain_path = help_page_path('user/project/clusters/gitlab_managed_clusters', anchor: 'base-domain')
 - base_domain_link_start = link_start % { url: base_domain_path }
 
 .row

doc/api/instance_clusters.md

@@ -160,7 +160,7 @@ Parameters:
 | Attribute                                            | Type    | Required | Description                                                                                           |
 | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
 | `name`                                               | string  | yes      | The name of the cluster                                                                               |
-| `domain`                                             | string  | no       | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster                       |
+| `domain`                                             | string  | no       | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster                       |
 | `environment_scope`                                  | string  | no       | The associated environment to the cluster. Defaults to `*`                                            |
 | `management_project_id`                              | integer | no       | The ID of the [management project](../user/clusters/management_project.md) for the cluster            |
 | `enabled`                                            | boolean | no       | Determines if cluster is active or not, defaults to `true`                                            |
@@ -228,7 +228,7 @@ Parameters:
 | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
 | `cluster_id`                                | integer | yes      | The ID of the cluster                                                                      |
 | `name`                                      | string  | no       | The name of the cluster                                                                    |
-| `domain`                                    | string  | no       | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster            |
+| `domain`                                    | string  | no       | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster            |
 | `environment_scope`                         | string  | no       | The associated environment to the cluster                                                  |
 | `management_project_id`                     | integer | no       | The ID of the [management project](../user/clusters/management_project.md) for the cluster |
 | `enabled`                                   | boolean | no       | Determines if cluster is active or not                                                     |

doc/api/project_clusters.md

@@ -188,7 +188,7 @@ Parameters:
 | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
 | `id`                                                 | integer or string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                                                 |
 | `name`                                               | string  | yes      | The name of the cluster                                                                               |
-| `domain`                                             | string  | no       | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster                       |
+| `domain`                                             | string  | no       | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster                       |
 | `management_project_id`                              | integer | no       | The ID of the [management project](../user/clusters/management_project.md) for the cluster            |
 | `enabled`                                            | boolean | no       | Determines if cluster is active or not, defaults to `true`                                            |
 | `managed`                                            | boolean | no       | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` |
@@ -286,7 +286,7 @@ Parameters:
 | `id`                                        | integer or string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                                      |
 | `cluster_id`                                | integer | yes      | The ID of the cluster                                                                      |
 | `name`                                      | string  | no       | The name of the cluster                                                                    |
-| `domain`                                    | string  | no       | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster            |
+| `domain`                                    | string  | no       | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster            |
 | `management_project_id`                     | integer | no       | The ID of the [management project](../user/clusters/management_project.md) for the cluster |
 | `enabled`                                   | boolean | no       | Determines if cluster is active or not                                                     |
 | `managed`                                   | boolean | no       | Determines if GitLab manages namespaces and service accounts for this cluster          |

doc/ci/variables/README.md

@@ -628,7 +628,7 @@ Integrations that are responsible for deployment configuration can define their
 variables that are set in the build environment. These variables are only defined
 for [deployment jobs](../environments/index.md).
 
-For example, the [Kubernetes integration](../../user/project/clusters/index.md#deployment-variables)
+For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables)
 defines deployment variables that you can use with the integration.
 
 The [documentation for each integration](../../user/project/integrations/overview.md)

doc/ci/variables/predefined_variables.md

@@ -14,7 +14,7 @@ Some variables are only available with more recent versions of [GitLab Runner](h
 You can [output the values of all variables available for a job](README.md#list-all-environment-variables)
 with a `script` command.
 
-There are also [Kubernetes-specific deployment variables](../../user/project/clusters/index.md#deployment-variables).
+There are also [Kubernetes-specific deployment variables](../../user/project/clusters/deploy_to_cluster.md#deployment-variables).
 
 | Variable                                 | GitLab | Runner | Description |
 |------------------------------------------|--------|--------|-------------|

doc/topics/autodevops/customize.md

@@ -378,7 +378,7 @@ applications.
 | `HELM_UPGRADE_EXTRA_ARGS`               | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. |
 | `INCREMENTAL_ROLLOUT_MODE`              | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. |
 | `K8S_SECRET_*`                          | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. |
-| `KUBE_INGRESS_BASE_DOMAIN`              | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. |
+| `KUBE_INGRESS_BASE_DOMAIN`              | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) for more information. |
 | `PRODUCTION_REPLICAS`                   | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. |
 | `REPLICAS`                              | Number of replicas to deploy. Defaults to 1. |
 | `ROLLOUT_RESOURCE_TYPE`                 | From GitLab 11.9, allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. |

doc/topics/autodevops/index.md

@@ -224,7 +224,7 @@ The Auto DevOps base domain is required to use
 any of the following places:
 
 - Either under the cluster's settings, whether for an instance,
-  [projects](../../user/project/clusters/index.md#base-domain) or
+  [projects](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) or
   [groups](../../user/group/clusters/index.md#base-domain)
 - Or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN`
 - Or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`
@@ -263,7 +263,7 @@ See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requir
 
 When using Auto DevOps, you can deploy different environments to
 different Kubernetes clusters, due to the 1:1 connection
-[existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters).
+[existing between them](../../user/project/clusters/multiple_kubernetes_clusters.md).
 
 The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
 used by Auto DevOps currently defines 3 environment names:

doc/topics/autodevops/stages.md

@@ -250,7 +250,7 @@ such as after merging a merge request, the Review App is also deleted.
 Review apps are deployed using the
 [auto-deploy-app](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) chart with
 Helm, which you can [customize](customize.md#custom-helm-chart). The application deploys
-into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables)
+into the [Kubernetes namespace](../../user/project/clusters/deploy_to_cluster.md#deployment-variables)
 for the environment.
 
 In GitLab 11.4 and later, [local Tiller](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22036) is
@@ -366,7 +366,7 @@ commands. This is an easy way to
 
 Helm uses the [auto-deploy-app](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app)
 chart to deploy the application into the
-[Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables)
+[Kubernetes namespace](../../user/project/clusters/deploy_to_cluster.md#deployment-variables)
 for the environment.
 
 In GitLab 11.4 and later, a

doc/topics/autodevops/troubleshooting.md

@@ -49,7 +49,7 @@ To fix this issue, you must either:
 
 Auto Deploy fails if GitLab can't create a Kubernetes namespace and
 service account for your project. For help debugging this issue, see
-[Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting).
+[Troubleshooting failed deployment jobs](../../user/project/clusters/deploy_to_cluster.md#troubleshooting).
 
 ## Detected an existing PostgreSQL database
 

doc/user/clusters/management_project.md

@@ -71,7 +71,7 @@ configure cluster:
 ### Setting the environment scope
 
 [Environment
-scopes](../project/clusters/index.md#setting-the-environment-scope)
+scopes](../project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope)
 are usable when associating multiple clusters to the same management
 project.
 

doc/user/group/clusters/index.md

@@ -66,7 +66,7 @@ automatically. If you're using [Auto DevOps](../../../topics/autodevops/index.md
 for deployments with a cluster not managed by GitLab, you must ensure:
 
 - The project's deployment service account has permissions to deploy to
-  [`KUBE_NAMESPACE`](../../project/clusters/index.md#deployment-variables).
+  [`KUBE_NAMESPACE`](../../project/clusters/deploy_to_cluster.md#deployment-variables).
 - `KUBECONFIG` correctly reflects any changes to `KUBE_NAMESPACE`
   (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/-/issues/31519)). Editing
   `KUBE_NAMESPACE` directly is discouraged.
@@ -96,7 +96,7 @@ per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifyin
 this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during
 the [Auto DevOps](../../../topics/autodevops/index.md) stages.
 
-The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/index.md#base-domain).
+The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/gitlab_managed_clusters.md#base-domain).
 
 ## Environment scopes **(PREMIUM)**
 

doc/user/project/canary_deployments.md

@@ -92,7 +92,7 @@ Here's an example setup flow from scratch:
 1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project.
 1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project.
 1. Install [NGINX Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) in your cluster.
-1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress
+1. Set up [the base domain](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) based on the Ingress
    Endpoint assigned above.
 1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions).
    If it isn't, follow the documentation to specify the image version.

doc/user/project/clusters/add_eks_clusters.md

@@ -164,7 +164,7 @@ When you create a new cluster, you have the following settings:
 | Setting                 | Description |
 | ----------------------- |------------ |
 | Kubernetes cluster name | Your cluster's name. |
-| Environment scope       | The [associated environment](index.md#setting-the-environment-scope). |
+| Environment scope       | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). |
 | Service role            | The **EKS IAM role** (**role A**). |
 | Kubernetes version      | The [Kubernetes version](index.md#supported-cluster-versions) for your cluster. |
 | Key pair name           | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. |

doc/user/project/clusters/add_existing_cluster.md

@@ -66,7 +66,7 @@ To add a Kubernetes cluster to your project, group, or instance:
 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.
+      [associated environment](multiple_kubernetes_clusters.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.

doc/user/project/clusters/add_gke_clusters.md

@@ -69,7 +69,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance:
    **Sign in with Google** button.
 1. Choose your cluster's settings:
    - **Kubernetes cluster name** - The name you wish to give the cluster.
-   - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster.
+   - **Environment scope** - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster.
    - **Google Cloud Platform project** - Choose the project you created in your GCP
      console to host the Kubernetes cluster. Learn more about
      [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
@@ -81,7 +81,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance:
    - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster.
      See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information.
    - **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.
+     See the [Managed clusters section](gitlab_managed_clusters.md) for more information.
 1. Finally, click the **Create Kubernetes cluster** button.
 
 After a couple of minutes, your cluster is ready.

doc/user/project/clusters/deploy_to_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
+---
+
+# Deploy to a Kubernetes cluster
+
+A Kubernetes cluster can be the destination for a deployment job. If
+
+- The cluster is integrated with GitLab, special
+  [deployment variables](#deployment-variables) are made available to your job
+  and configuration is not required. You can immediately begin interacting with
+  the cluster from your jobs using tools such as `kubectl` or `helm`.
+- You don't use the GitLab cluster integration, you can still deploy to your
+  cluster. However, you must configure Kubernetes tools yourself
+  using [CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables)
+  before you can interact with the cluster from your jobs.
+
+## Deployment variables
+
+Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) named
+[`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the
+following command in your deployment job script, for Kubernetes to access the registry:
+
+- Using Kubernetes 1.18+:
+
+  ```shell
+  kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run=client | kubectl apply -f -
+  ```
+
+- Using Kubernetes <1.18:
+
+  ```shell
+  kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f -
+  ```
+
+The Kubernetes cluster integration exposes these
+[deployment variables](../../../ci/variables/README.md#deployment-variables) in the
+GitLab CI/CD build environment to deployment jobs. Deployment jobs have
+[defined a target environment](../../../ci/environments/index.md).
+
+| Deployment Variable        | Description |
+|----------------------------|-------------|
+| `KUBE_URL`                 | Equal to the API URL. |
+| `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. |
+| `KUBECONFIG`               | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. |
+| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](gitlab_managed_clusters.md#base-domain) for more information. |
+
+## Custom namespace
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
+> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5.
+
+The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace
+to deployment jobs. It defaults to using project-environment specific namespaces
+of the form `<prefix>-<environment>`, where `<prefix>` is of the form
+`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables).
+
+You can customize the deployment namespace in a few ways:
+
+- You can choose between a **namespace per [environment](../../../ci/environments/index.md)**
+  or a **namespace per project**. A namespace per environment is the default and recommended
+  setting, as it prevents the mixing of resources between production and non-production environments.
+- When using a project-level cluster, you can additionally customize the namespace prefix.
+  When using namespace-per-environment, the deployment namespace is `<prefix>-<environment>`,
+  but otherwise just `<prefix>`.
+- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`,
+  but the user is responsible for ensuring its existence. You can fully customize
+  this value using
+  [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments)
+  in `.gitlab-ci.yml`.
+
+When you customize the namespace, existing environments remain linked to their current
+namespaces until you [clear the cluster cache](gitlab_managed_clusters.md#clearing-the-cluster-cache).
+
+### Protecting credentials
+
+By default, anyone who can create a deployment job can access any CI/CD variable in
+an environment's deployment job. This includes `KUBECONFIG`, which gives access to
+any secret available to the associated service account in your cluster.
+To keep your production credentials safe, consider using
+[protected environments](../../../ci/environments/protected_environments.md),
+combined with *one* of the following:
+
+- A GitLab-managed cluster and namespace per environment.
+- An environment-scoped cluster per protected environment. The same cluster
+  can be added multiple times with multiple restricted service accounts.
+
+## Web terminals for Kubernetes clusters
+
+> Introduced in GitLab 8.15.
+
+The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals)
+support to your [environments](../../../ci/environments/index.md). This is based
+on the `exec` functionality found in Docker and Kubernetes, so you get a new
+shell session in your existing containers. To use this integration, you
+should deploy to Kubernetes using the deployment variables above, ensuring any
+deployments, replica sets, and pods are annotated with:
+
+- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG`
+- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG`
+
+`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of
+the CI/CD variables.
+
+You must be the project owner or have `maintainer` permissions to use terminals.
+Support is limited to the first container in the first pod of your environment.
+
+## Troubleshooting
+
+Before the deployment jobs starts, GitLab creates the following specifically for
+the deployment job:
+
+- A namespace.
+- A service account.
+
+However, sometimes GitLab cannot create them. In such instances, your job can fail with the message:
+
+```plaintext
+This job failed because the necessary resources were not successfully created.
+```
+
+To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog).
+
+Reasons for failure include:
+
+- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+  privileges required by GitLab.
+- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching
+  [`environment:name`](../../../ci/environments/index.md). If your job has no
+  `environment:name` set, the Kubernetes credentials are not passed to it.
+
+NOTE:
+Project-level clusters upgraded from GitLab 12.0 or older may be configured
+in a way that causes this error. Ensure you deselect the
+[GitLab-managed cluster](gitlab_managed_clusters.md) option if you want to manage
+namespaces and service accounts yourself.

doc/user/project/clusters/gitlab_managed_clusters.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
+---
+
+# GitLab-managed clusters
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5.
+> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11.
+
+You can choose to allow GitLab to manage your cluster for you. If your cluster
+is managed by GitLab, resources for your projects are automatically created. See
+the [Access controls](add_remove_clusters.md#access-controls) section for
+details about the created resources.
+
+If you choose to manage your own cluster, project-specific resources aren't created
+automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must
+explicitly provide the `KUBE_NAMESPACE` [deployment variable](deploy_to_cluster.md#deployment-variables)
+for your deployment jobs to use. Otherwise, a namespace is created for you.
+
+WARNING:
+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).
+
+## Clearing the cluster cache
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6.
+
+If you allow GitLab to manage your cluster, GitLab stores a cached
+version of the namespaces and service accounts it creates for your projects. If you
+modify these resources in your cluster manually, this cache can fall out of sync with
+your cluster. This can cause deployment jobs to fail.
+
+To clear the cache:
+
+1. Navigate to your project's **Infrastructure > Kubernetes clusters** page, and select your cluster.
+1. Expand the **Advanced settings** section.
+1. Click **Clear cluster cache**.
+
+## Base domain
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8.
+
+Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable.
+If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different
+stages. For example, Auto Review Apps and Auto Deploy.
+
+The domain should have a wildcard DNS configured to the Ingress IP address.
+You can either:
+
+- Create an `A` record that points to the Ingress IP address with your domain provider.
+- Enter a wildcard DNS address using a service such as `nip.io` or `xip.io`. For example, `192.168.1.1.xip.io`.
+
+To determine the external Ingress IP address, or external Ingress hostname:
+
+- *If the cluster is on GKE*:
+  1. Click the **Google Kubernetes Engine** link in the **Advanced settings**,
+     or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/).
+  1. Select the proper project and cluster.
+  1. Click **Connect**
+  1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**.
+
+- *If the cluster is not on GKE*: Follow the specific instructions for your
+  Kubernetes provider to configure `kubectl` with the right credentials.
+  The output of the following examples show the external endpoint of your
+  cluster. This information can then be used to set up DNS entries and forwarding
+  rules that allow external access to your deployed applications.
+
+Depending an your Ingress, the external IP address can be retrieved in various ways.
+This list provides a generic solution, and some GitLab-specific approaches:
+
+- In general, you can list the IP addresses of all load balancers by running:
+
+  ```shell
+  kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} '
+  ```
+
+- If you installed Ingress using the **Applications**, run:
+
+  ```shell
+  kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
+  ```
+
+- Some Kubernetes clusters return a hostname instead, like
+  [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run:
+
+  ```shell
+  kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
+  ```
+
+  If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/)
+  is also created, which incurs additional AWS costs.
+
+- Istio/Knative uses a different command. Run:
+
+  ```shell
+  kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} '
+  ```
+
+If you see a trailing `%` on some Kubernetes versions, do not include it.

doc/user/project/clusters/multiple_kubernetes_clusters.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
+---
+
+# Multiple Kubernetes clusters for a single project
+
+> - 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.
+
+You can associate more than one Kubernetes cluster to your
+project. That way you can have different clusters for different environments,
+like development, staging, production, and so on.
+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
+
+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
+[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) work.
+
+The default environment scope is `*`, which means all jobs, regardless of their
+environment, use that cluster. Each scope can be used only by a single cluster
+in a project, and a validation error occurs if otherwise. Also, jobs that don't
+have an environment keyword set can't access any cluster.
+
+For example, let's say the following Kubernetes clusters exist in a project:
+
+| Cluster     | Environment scope |
+| ----------- | ----------------- |
+| Development | `*`               |
+| Production  | `production`      |
+
+And the following environments are set in
+[`.gitlab-ci.yml`](../../../ci/yaml/README.md):
+
+```yaml
+stages:
+  - test
+  - deploy
+
+test:
+  stage: test
+  script: sh test
+
+deploy to staging:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: staging
+    url: https://staging.example.com/
+
+deploy to production:
+  stage: deploy
+  script: make deploy
+  environment:
+    name: production
+    url: https://example.com/
+```
+
+The results:
+
+- The Development cluster details are available in the `deploy to staging`
+  job.
+- The production cluster details are available in the `deploy to production`
+  job.
+- No cluster details are available in the `test` job because it doesn't
+  define any environment.

doc/user/project/clusters/protect/container_host_security/quick_start_guide.md

@@ -20,7 +20,7 @@ The following steps are recommended to install and use Container Host Security t
 1. Install and configure an Ingress node:
 
    - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd).
-   - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain)
+   - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../gitlab_managed_clusters.md#base-domain)
      into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes
      cluster.
 
@@ -50,7 +50,7 @@ kubectl -n gitlab-managed-apps logs -l app=falco
 Your CI/CD pipeline may occasionally fail or have trouble connecting to the cluster. Here are some
 initial troubleshooting steps that resolve the most common problems:
 
-1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache)
+1. [Clear the cluster cache](../../gitlab_managed_clusters.md#clearing-the-cluster-cache)
 1. If things still aren't working, a more assertive set of actions may help get things back to a
    good state:
 

doc/user/project/clusters/protect/container_network_security/quick_start_guide.md

@@ -20,7 +20,7 @@ The following steps are recommended to install and use Container Network Securit
 1. Install and configure an Ingress node:
 
    - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd).
-   - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain)
+   - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../gitlab_managed_clusters.md#base-domain)
      into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes
      cluster.
 
@@ -120,7 +120,7 @@ traffic that you want to allow in the node.
 Occasionally, your CI/CD pipeline may fail or have trouble connecting to the cluster. Here are some
 initial troubleshooting steps that resolve the most common problems:
 
-1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache).
+1. [Clear the cluster cache](../../gitlab_managed_clusters.md#clearing-the-cluster-cache).
 1. If things still aren't working, a more assertive set of actions may help get things back into a
    good state: