Merge branch 'nagyv-gitlab-master-patch-88771' into 'master'

Emphasize the Agent more

See merge request gitlab-org/gitlab!69343

doc/user/infrastructure/index.md

@@ -14,10 +14,10 @@ are more likely to control their whole DevOps lifecycle, including deployments a
 
 GitLab offers various features to speed up and simplify your infrastructure management practices.
 
-## Generic infrastructure management
+## Infrastructure as Code
 
-GitLab has deep integrations with Terraform to run your infrastructure as code pipelines
-and support your processes. Terraform is considered the standard in cloud infrastructure provisioning.
+GitLab has deep integrations with Terraform to run Infrastructure as Code pipelines
+and support various processes. Terraform is considered the standard in cloud infrastructure provisioning.
 The various GitLab integrations help you:
 
 - Get started quickly without any setup.
@@ -25,11 +25,7 @@ The various GitLab integrations help you:
   with code changes.
 - Scale using a module registry.
 
-Read more about the [Infrastructure as Code features](iac/index.md), including:
-
-- [The GitLab Managed Terraform State](iac/terraform_state.md).
-- [The Terraform MR widget](iac/mr_integration.md).
-- [The Terraform module registry](../packages/terraform_module_registry/index.md).
+Learn more about how GitLab can help you run [Infrastructure as Code](iac/index.md).
 
 ## Integrated Kubernetes management
 
@@ -39,16 +35,7 @@ DevSecOps pipeline by default targeted at Kubernetes based deployments. To suppo
 all the GitLab features, GitLab offers a cluster management project for easy onboarding.
 The deploy boards provide quick insights into your cluster, including pod logs tailing.
 
-The recommended approach to connect to a cluster is using [the GitLab Kubernetes Agent](../clusters/agent/index.md).
-
-Read more about [the Kubernetes cluster support and integrations](../project/clusters/index.md), including:
-
-- Certificate-based integration for [projects](../project/clusters/index.md),
-  [groups](../group/clusters/index.md), or [instances](../instance/clusters/index.md).
-- [Agent-based integration](../clusters/agent/index.md). **(PREMIUM)**
-  - The [Kubernetes Agent Server](../../administration/clusters/kas.md) is [available on GitLab.com](../clusters/agent/index.md#set-up-the-kubernetes-agent-server)
-    at `wss://kas.gitlab.com`. **(PREMIUM)**
-- [Agent-based access from GitLab CI/CD](../clusters/agent/ci_cd_tunnel.md).
+Learn more about the [GitLab integration with Kubernetes](../project/clusters/index.md).
 
 ## Runbooks in GitLab
 

doc/user/project/clusters/add_existing_cluster.md

@@ -4,11 +4,17 @@ 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
+# Connect existing clusters through cluster certificates
 
 If you have an existing Kubernetes cluster, you can add it to a project, group,
 or instance and benefit from the integration with GitLab.
 
+WARNING:
+The process described on this page uses cluster certificates to connect your cluster
+to GitLab. Although this method still works, it is **no longer recommended**.
+To connect your cluster to GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md)
+instead. **(PREMIUM)**
+
 ## Prerequisites
 
 See the prerequisites below to add existing clusters to GitLab.

doc/user/project/clusters/deploy_to_cluster.md

@@ -4,7 +4,13 @@ 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
+# Deploy to a Kubernetes cluster with cluster certificates
+
+WARNING:
+The process described on this page uses cluster certificates to deploy to your cluster
+from GitLab. Although this method still works, it is **no longer recommended**.
+To deploy to your cluster from GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md)
+instead. **(PREMIUM)**
 
 A Kubernetes cluster can be the destination for a deployment job. If
 

doc/user/project/clusters/index.md

@@ -16,10 +16,6 @@ We offer extensive integrations to help you connect and manage your Kubernetes c
 
 Read through this document to get started.
 
-## Clusters infrastructure
-
-Use [Infrastructure as Code](../../infrastructure) to create and manage your clusters with the GitLab integration with Terraform.
-
 ## Benefit from the GitLab-Kubernetes integration
 
 Using the GitLab-Kubernetes integration, you can benefit of GitLab
@@ -58,34 +54,33 @@ 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:
-
-- 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)**
+You can create new or add existing clusters to GitLab through different levels,
+using different methods.
 
-To create new clusters, use one of the following methods:
+### Cluster levels
 
-- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**).
-- [Cluster certificates](add_remove_clusters.md) (**deprecated**).
+You can connect clusters to GitLab in different levels, according to their purpose:
 
-You can also [add existing clusters](add_existing_cluster.md) 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)**
 
-## View your clusters
+### Methods to create new 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:
+To create new clusters, we **recommend** using [Infrastructure as Code](../../infrastructure/index.md).
 
-- Nodes count.
-- Rough estimates of memory and CPU usage.
+### Methods to connect existing clusters
 
-## Configuring your Kubernetes cluster
+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).
 
-Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely
-configure your clusters. Otherwise, there are [security implications](#security-implications).
+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.
 
-### Security implications
+## Security implications
 
 WARNING:
 The whole cluster security is based on a model where [developers](../../permissions.md)
@@ -96,6 +91,15 @@ 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)