Merge branch 'docs-new-connect-clusters-doc' into 'master'

Docs: Create new doc for connecting clusters

See merge request gitlab-org/gitlab!69309

doc/user/infrastructure/clusters/connect/index.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
+---
+
+# Connect a cluster to GitLab **(FREE)**
+
+You can create new or connect existing clusters to GitLab through different [levels](#cluster-levels),
+using different [methods](#methods-to-connect-a-cluster-to-gitlab).
+
+Before getting started:
+
+1. Check the [supported Kubernetes cluster versions](#supported-cluster-versions).
+1. Define the [cluster level](#cluster-levels) according to your case.
+
+After that:
+
+1. Choose the [method](#methods-to-connect-a-cluster-to-gitlab)
+to connect your cluster according to your case.
+1. [View your clusters](#view-your-clusters) connected to GitLab.
+
+## Methods to connect a cluster to GitLab
+
+GitLab offers three methods to connect existing and create new clusters:
+
+- **GitLab Kubernetes Agent**: the best solution to
+[connect existing clusters](#connect-existing-clusters-to-gitlab).
+- **Infrastructure as Code**: it's a broader infrastructure management
+toolset that includes managing your cluster. It's the recommended
+solution to [create a new cluster](#create-new-clusters-from-gitlab)
+from GitLab.
+- **Certificate-based method**: our first and legacy solution uses
+cluster certificates to connect your cluster to GitLab. It is no longer
+recommended for [security implications](#security-implications-for-clusters-connected-with-certificates).
+
+### Connect existing clusters to GitLab
+
+To safely connect and configure an existing cluster on the **project level**,
+we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md).
+We are working to support [the Agent for connecting a cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784).
+
+Alternatively, you can use [cluster certificates](../../../project/clusters/add_existing_cluster.md)
+to connect clusters in all levels (projects, group, instance). However,
+for [security implications](#security-implications-for-clusters-connected-with-certificates),
+we don't recommend using this method.
+
+### Create new clusters from GitLab
+
+To safely create new clusters from GitLab, use
+[Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac).
+
+The [certificate-based method to create a new cluster](../../../project/clusters/add_remove_clusters.md)
+is still available through the GitLab UI but was **deprecated** in GitLab 14.0.
+If possible, we don't recommend using this method.
+
+### Connect multiple clusters to a single project
+
+To connect multiple clusters to a single project in GitLab,
+we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md).
+
+You can also use the [certificate-based method](../../../project/clusters/multiple_kubernetes_clusters.md),
+but, for [security implications](#security-implications-for-clusters-connected-with-certificates),
+we don't recommend using this method.
+
+## Cluster levels
+
+Choose your cluster's level according to its purpose:
+
+| Level | Purpose |
+|--|--|
+| [Project level](../../../project/clusters/index.md) | Use your cluster for a single project. |
+| [Group level](../../../group/clusters/index.md) | Use the same cluster across multiple projects within your group. |
+| [Instance level](../../../instance/clusters/index.md) **(FREE SELF)** | Use the same cluster across groups and projects within your instance. |
+
+## 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
+provide a three-month deprecation period before we remove support of a specific
+version. The range of supported versions is based on the evaluation of:
+
+- The versions supported by major managed Kubernetes providers.
+- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions).
+
+GitLab supports the following Kubernetes versions, and you can upgrade your
+Kubernetes version to any supported version at any time:
+
+- 1.19 (support ends on February 22, 2022)
+- 1.18 (support ends on November 22, 2021)
+- 1.17 (support ends on September 22, 2021)
+
+Some GitLab features may support versions outside the range provided here.
+
+## View your clusters
+
+To view the Kubernetes clusters connected to your project,
+group, or instance, open the cluster's page according to the
+[level](#cluster-levels) of your cluster.
+
+**Project-level clusters:**
+
+1. Go to your project's homepage.
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+
+**Group-level clusters:**
+
+1. Go to your group's homepage.
+1. On the left sidebar, select **Kubernetes**.
+
+**Instance-level clusters:** **(FREE SELF)**
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Kubernetes**.
+
+## Security implications for clusters connected with certificates
+
+WARNING:
+The whole cluster security is based on a model where [developers](../../../permissions.md)
+are trusted, so **only trusted users should be allowed to control your clusters**.
+
+The use of cluster certificates to connect your cluster grants
+access to a wide set of functionalities needed to successfully
+build and deploy a containerized application. Bear in mind that
+the same credentials are used for all the applications running
+on the cluster.

doc/user/project/clusters/add_eks_clusters.md

@@ -166,7 +166,7 @@ When you create a new cluster, you have the following settings:
 | Kubernetes cluster name | Your cluster's name. |
 | 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. |
+| Kubernetes version      | The [Kubernetes version](../../infrastructure/clusters/connect/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. |
 | VPC                     | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. |
 | Subnets                 | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. |

doc/user/project/clusters/add_existing_cluster.md

@@ -217,7 +217,8 @@ integration to work properly.
 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.
+[security concern](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates),
+and may not be desirable.
 
 To effectively disable RBAC, global permissions can be applied granting full access:
 

doc/user/project/clusters/add_remove_clusters.md

@@ -54,7 +54,7 @@ As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.
 to connect your cluster to GitLab.
 
 Alternativelly, you can [add an existing cluster](add_existing_cluster.md)
-through the certificate-based method, but we don't recommend using this method for [security implications](index.md#security-implications).
+through the certificate-based method, but we don't recommend using this method for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates).
 
 ## Configure your cluster
 

doc/user/project/clusters/index.md

@@ -33,75 +33,11 @@ features such as:
 
 ## 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
-provide a three-month deprecation period before we remove support of a specific
-version. The range of supported versions is based on the evaluation of:
+See the [Kubernetes clusters versions supported by GitLab](../../infrastructure/clusters/connect/index.md#supported-cluster-versions).
 
-- The versions supported by major managed Kubernetes providers.
-- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions).
+## Connect your cluster to GitLab
 
-GitLab supports the following Kubernetes versions, and you can upgrade your
-Kubernetes version to any supported version at any time:
-
-- 1.20 (support ends on April 22, 2022)
-- 1.19 (support ends on February 22, 2022)
-- 1.18 (support ends on November 22, 2021)
-- 1.17 (support ends on September 22, 2021)
-
-Some GitLab features may support versions outside the range provided here.
-
-## Add and remove clusters
-
-You can create new or add existing clusters to GitLab through different [levels](#cluster-levels),
-using different methods.
-
-### Methods to connect existing clusters
-
-To safely connect and configure an existing cluster on the **project level**, we
-**recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md).
-We are working to support [the Agent for connecting a
-cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784).
-
-You can use [cluster certificates](add_existing_cluster.md) to connect
-clusters in all levels (projects, group, instance). However, for
-[security implications](#security-implications), this method is no longer recommended.
-
-To create new clusters, we **recommend** using
-[Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac).
-
-### Cluster levels
-
-You can connect clusters to GitLab in different levels, according to their purpose:
-
-- 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)**
-
-## Security implications
-
-WARNING:
-The whole cluster security is based on a model where [developers](../../permissions.md)
-are trusted, so **only trusted users should be allowed to control your clusters**.
-
-The default cluster configuration grants access to a wide set of
-functionalities needed to successfully build and deploy a containerized
-application. Bear in mind that the same credentials are used for all the
-applications running on the cluster.
-
-## 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
-
-See how to associate [multiple Kubernetes clusters](multiple_kubernetes_clusters.md)
-with your GitLab project.
+Learn how to [create new and connect existing clusters to GitLab](../../infrastructure/clusters/connect/index.md).
 
 ## Cluster integrations