Merge branch 'eread/improve-add-cluster-docs' into 'master'

Improve add cluster documentation

Closes #30575

See merge request gitlab-org/gitlab!21806

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

@@ -11,6 +11,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_remove_clusters.md', anchor: 'eks-cluster'),
-    'create-role-arn-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'eks-cluster'),
+    'account-and-external-ids-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'new-eks-cluster'),
+    'create-role-arn-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'new-eks-cluster'),
     'external-link-icon' => icon('external-link') } }

doc/user/admin_area/index.md

@@ -27,6 +27,7 @@ The Admin Area is made up of the following sections:
 | Applications                    | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services.                                                                                                                                                                            |
 | Abuse Reports                   | Manage [abuse reports](abuse_reports.md) submitted by your users.                                                                                                                                                                                                                        |
 | License **(STARTER ONLY)**      | Upload, display, and remove [licenses](license.md).                                                                                                                                                                                                                                      |
+| Kubernetes                      | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md).                                                                                                                                                                                                   |
 | Push Rules **(STARTER)**        | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects.                                                                                                                                                                                                     |
 | Geo **(PREMIUM ONLY)**          | Configure and maintain [Geo nodes](geo_nodes.md).                                                                                                                                                                                                                                        |
 | Deploy Keys                     | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys).                                                                                                                                                                                                                 |

doc/user/group/clusters/index.md

@@ -53,8 +53,8 @@ differentiate the new cluster from the rest.
 
 ## 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.
+> - [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 will be automatically created. See the
@@ -170,6 +170,11 @@ For important information about securely configuring GitLab Runners, see
 Runners](../../project/clusters/add_remove_clusters.md#security-of-gitlab-runners)
 documentation for project-level clusters.
 
+## More information
+
+For information on integrating GitLab and Kubernetes, see
+[Kubernetes clusters](../../project/clusters/index.md).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

doc/user/instance/clusters/index.md

@@ -12,11 +12,12 @@ projects.
 
 ## Cluster precedence
 
-GitLab will try match to clusters in the following order:
+GitLab will try [to match](../../../ci/environments.md#scoping-environments-with-specs) clusters in
+the following order:
 
-- Project-level clusters
-- Group-level clusters
-- Instance level
+- Project-level clusters.
+- Group-level clusters.
+- Instance-level clusters.
 
 To be selected, the cluster must be enabled and
 match the [environment selector](../../../ci/environments.md#scoping-environments-with-specs).
@@ -26,3 +27,8 @@ match the [environment selector](../../../ci/environments.md#scoping-environment
 For a consolidated view of which CI [environments](../../../ci/environments.md)
 are deployed to the Kubernetes cluster, see the documentation for
 [cluster environments](../../clusters/environments.md).
+
+## More information
+
+For information on integrating GitLab and Kubernetes, see
+[Kubernetes clusters](../../project/clusters/index.md).

doc/user/project/clusters/eks_and_gitlab/index.md

 ---
-redirect_to: '../add_remove_clusters.md#add-existing-eks-cluster'
+redirect_to: '../add_remove_clusters.md#existing-eks-cluster'
 ---
 
-This document was moved to [another location](../add_remove_clusters.md#add-existing-eks-cluster).
+This document was moved to [another location](../add_remove_clusters.md#existing-eks-cluster).

doc/user/project/clusters/index.md

@@ -30,9 +30,6 @@ Using the GitLab project Kubernetes integration, you can:
 - View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)**
 - Run serverless workloads on [Kubernetes with Knative](serverless/index.md).
 
-See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to
-set up integrations.
-
 ### Deploy Boards **(PREMIUM)**
 
 GitLab's Deploy Boards offer a consolidated view of the current health and
@@ -79,10 +76,7 @@ Kubernetes clusters can be used without Auto DevOps.
 
 ### Web terminals
 
-NOTE: **Note:**
-Introduced in GitLab 8.15. 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.
+> Introduced in GitLab 8.15.
 
 When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals)
 support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in
@@ -97,6 +91,14 @@ pods are annotated with:
 `$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of
 the CI 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.
+
+## Adding and removing clusters
+
+See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to
+set up integrations with Google Cloud Platform (GCP) and Amazon Elastic Kubernetes Service (EKS).
+
 ## Cluster configuration
 
 After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers
@@ -115,8 +117,8 @@ applications running on the cluster.
 
 ### 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.
+> - [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 will be automatically created. See the

doc/user/project/clusters/serverless/index.md

@@ -43,7 +43,7 @@ To run Knative on GitLab, you will need:
      clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get
      started.
 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative.
-   The simplest way to get started is to add a cluster using [GitLab's GKE integration](../add_remove_clusters.md#gke-cluster).
+   The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md).
    The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory.
 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install
    Knative.