Add latest changes from gitlab-org/gitlab@14-4-stable-eev14.4.0-rc42

5 files changed, 148 insertions, 42 deletions

diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md
index ada278292a9..636cb1bb457 100644
--- a/doc/user/infrastructure/clusters/connect/index.md
+++ b/doc/user/infrastructure/clusters/connect/index.md
@@ -63,16 +63,6 @@ You can also use the [certificate-based method](../../../project/clusters/multip
 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
@@ -86,29 +76,42 @@ version. The range of supported versions is based on the evaluation of:
 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 July 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)
 
+[Adding support to other versions of Kubernetes is managed under this epic](https://gitlab.com/groups/gitlab-org/-/epics/4827).
+
 Some GitLab features may support versions outside the range provided here.
 
-## View your clusters
+## 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) | Use the same cluster across groups and projects within your instance. |
+
+### 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.
+group, or instance, open the cluster's page according to
+your cluster's level.
 
 **Project-level clusters:**
 
-1. Go to your project's homepage.
+1. On the top bar, select **Menu > Projects** and find your project.
 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
 
 **Group-level clusters:**
 
-1. Go to your group's homepage.
+1. On the top bar, select **Menu > Groups** and find your group.
 1. On the left sidebar, select **Kubernetes**.
 
-**Instance-level clusters:** **(FREE SELF)**
+**Instance-level clusters:**
 
 1. On the top bar, select **Menu > Admin**.
 1. On the left sidebar, select **Kubernetes**.
diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
index 90044fa74e1..3c934b72886 100644
--- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
@@ -26,25 +26,46 @@ You can then modify the project files according to your needs.
 **Steps:**
 
 1. [Import the example project](#import-the-example-project).
-1. [Add your GCP credentials to GitLab](#add-your-gcp-credentials-to-gitlab).
+1. [Create your GCP and GitLab credentials](#create-your-gcp-and-gitlab-credentials).
 1. [Configure your project](#configure-your-project).
 1. [Deploy your cluster](#deploy-your-cluster).
 
 ## Import the example project
 
+To create a new group-level cluster from GitLab using Infrastructure as Code, it is necessary
+to create a project to manage the cluster from. In this tutorial, we import a pre-configured
+sample project to help you get started.
+
 Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git` as URL.
 
-## Add your GCP credentials to GitLab
+This project provides you with the following resources:
+
+- A [cluster on Google Cloud Platform (GCP)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gke.tf)
+with defaults for name, location, node count, and Kubernetes version.
+- A [`gitlab-admin` K8s service account](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gitlab-admin.tf) with `cluster-admin` privileges.
+- The new group-level cluster connected to GitLab.
+- Pre-configures Terraform files:
 
-After importing the project, you need to set up [CI environment variables](../../../../ci/variables/index.md) to associate your cluster on GCP to your group in GitLab.
+   ```plaintext
+   ├── backend.tf         # State file Location Configuration
+   ├── gke.tf             # Google GKE Configuration
+   ├── gitlab-admin.tf    # Adding kubernetes service account
+   └── group_cluster.tf   # Registering kubernetes cluster to GitLab `apps` Group
+   ```
 
-We advise that you [set environment variables through the GitLab UI](../../../../ci/variables/index.md#add-a-cicd-variable-to-a-project)
-so that your credentials are not exposed through the code. To do so, follow the steps below.
+## Create your GCP and GitLab credentials
 
-### Prepare your credentials on GCP
+To set up your project to communicate to GCP and the GitLab API:
 
-1. Create a [GCP service account](https://cloud.google.com/docs/authentication/getting-started) to authenticate GCP with GitLab. It needs the following roles: `Computer Network Viewer`, `Kubernetes Engine Admin`, and `Service Account User`.
-1. Download the JSON file with the service account key.
+1. Create a [GitLab personal access token](../../../profile/personal_access_tokens.md) with
+   `api` scope. The Terraform script uses it to connect the cluster to your GitLab group. Take note of the generated token. You will
+   need it when you [configure your project](#configure-your-project).
+1. To authenticate GCP with GitLab, create a [GCP service account](https://cloud.google.com/docs/authentication/getting-started)
+with following roles: `Compute Network Viewer`, `Kubernetes Engine Admin`, `Service Account User`, and `Service Account Admin`. Both User and Admin
+service accounts are necessary. The User role impersonates the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account)
+when [creating the node pool](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#node-pool-management).
+The Admin role creates a service account in the `kube-system` namespace.
+1. Download the JSON file with the service account key you created in the previous step.
 1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key):
 
    ```shell
@@ -53,36 +74,38 @@ so that your credentials are not exposed through the code. To do so, follow the
 
 1. Use the output of this command as the `BASE64_GOOGLE_CREDENTIALS` environment variable in the next step.
 
-### Add your credentials to GitLab as environment variables
+## Configure your project
 
-1. On GitLab, from your project's sidebar, go to **Settings > CI/CD** and expand **Variables**.
-1. Add your `GITLAB_TOKEN` ([personal access token](../../../profile/personal_access_tokens.md)).
-1. Add the variable `BASE64_GOOGLE_CREDENTIALS` from the previous step.
+**Required configuration:**
 
-## Configure your project
+Use CI/CD environment variables to configure your project as detailed below.
 
-After authenticating with GCP, replace the project's defaults from the example
-project with your own. To do so, edit the files as described below.
+**Required configuration:**
 
-Edit `gke.tf`:
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **Variables**.
+1. Set the variable `TF_VAR_gitlab_token` to the GitLab personal access token you just created.
+1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created.
+1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name.
+1. Set the variable `TF_VAR_gitlab_group` to the name of the group you want to connect your cluster to. If your group's URL is `https://gitlab.example.com/my-example-group`, `my-example-group` is your group's name.
 
-1. **(Required)** Replace the GCP `project` with a unique project name.
-1. **(Optional)** Choose the `name` of your cluster.
-1. **(Optional)** Choose the `region` and `zone` that you would like to deploy your cluster to.
-1. Push the changes to your project's default branch.
+**Optional configuration:**
 
-Edit `group_cluster.tf`:
+The file [`variables.tf`](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/variables.tf)
+contains other variables that you can override according to your needs:
 
-1. **(Required)**: Replace the `full_path` with the path to your group.
-1. **(Optional)**: Choose your cluster base domain through `domain`.
-1. **(Optional)**: Choose your environment through `environment_scope`.
-1. Push the changes to your project's default branch.
+- `TF_VAR_gcp_region`: Set your cluster's region.
+- `TF_VAR_cluster_name`: Set your cluster's name.
+- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes.
+- `TF_VAR_cluster_description`: Set a description for the cluster. We recommend setting this to `$CI_PROJECT_URL` to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard.
+- `TF_VAR_base_domain`: Set to the base domain to provision resources under.
+- `TF_VAR_environment_scope`: Set to the environment scope for your cluster.
 
 Refer to the [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) and the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) documentation for further resource options.
 
 ## Deploy your cluster
 
-After adjusting the files in the previous step, manually trigger the deployment of your cluster. In GitLab:
+After configuring your project, manually trigger the deployment of your cluster. In GitLab:
 
 1. From your project's sidebar, go to **CI/CD > Pipelines**.
 1. Select the dropdown icon (**{angle-down}**) next to the play icon (**{play}**).
diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md
new file mode 100644
index 00000000000..16ca6d02865
--- /dev/null
+++ b/doc/user/infrastructure/clusters/index.md
@@ -0,0 +1,66 @@
+---
+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
+---
+
+# Kubernetes clusters **(FREE)**
+
+> - Project-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1.
+> - Group-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6.
+> - Instance-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11.
+
+Kubernetes is a container orchestration platform to deploy applications
+in a cluster without downtime and that scales as you need.
+
+With the GitLab integration with Kubernetes, you can:
+
+1. [Connect your cluster](#connect-your-cluster-to-gitlab).
+1. [Manage your cluster](#manage-your-cluster).
+1. [Deploy your cluster](#deploy-to-your-cluster).
+
+See the [Kubernetes clusters versions supported by GitLab](connect/index.md#supported-cluster-versions).
+
+## Connect your cluster to GitLab
+
+Learn how to [create new and connect existing clusters to GitLab](connect/index.md).
+
+## Manage your cluster
+
+- [Cluster Management Project](../../clusters/management_project.md):
+create a project to manage your cluster's shared resources requiring
+`cluster-admin` privileges such as an Ingress controller.
+  - [Cluster Management Project Template](../../clusters/management_project_template.md): start a cluster management project directly from a template.
+  - [Migrate to Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md): migrate from the deprecated GitLab Managed Apps to Cluster Management Projects.
+  - [GitLab Managed Apps](../../clusters/applications.md) (deprecated in favor of Cluster Management Projects): configure applications in your cluster directly from GitLab.
+- [Cluster integrations](../../clusters/integrations.md): install
+third-party applications into your cluster and manage them from GitLab.
+- [GitLab-managed clusters](../../project/clusters/gitlab_managed_clusters.md):
+enable GitLab to automatically create resources for your clusters.
+- [Cost management](../../clusters/cost_management.md): see insights into your cluster's resource usage.
+- [Crossplane integration](../../clusters/crossplane.md): manage your cluster's resources and cloud infrastructure with Crossplane.
+
+### Monitor your cluster
+
+- [Prometheus monitoring](../../project/integrations/prometheus_library/kubernetes.md): detect and monitor Kubernetes metrics with Prometheus.
+- [NGINX monitoring](../../project/integrations/prometheus_library/nginx.md): automatically monitor NGINX Ingress.
+- [Clusters health](manage/clusters_health.md): monitor your cluster's health, such as CPU and memory usage.
+
+### Secure your cluster
+
+- [Container Host Security](../../project/clusters/protect/container_host_security/index.md): monitor and block activity inside a container and enforce security policies across the cluster.
+- [Container Network security](../../project/clusters/protect/container_network_security/index.md): filter traffic going in and out of the cluster and traffic between pods through a firewall with Cilium NetworkPolicies.
+
+## Deploy to your cluster
+
+- [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md): use the CI/CD Tunnel to run Kubernetes commands from different projects.
+- [Inventory object](deploy/inventory_object.md): track objects applied to a cluster configured with the Kubernetes Agent.
+- [Auto DevOps](../../../topics/autodevops/index.md): enable Auto DevOps
+to allow GitLab automatically detect, build, test, and deploy applications.
+- [Cluster environments](../../clusters/environments.md): view CI/CD environments deployed to Kubernetes clusters.
+- [Canary Deployments](../../project/canary_deployments.md): deploy app updates to a small portion of the fleet with this Continuous Delivery strategy.
+- [Deploy to your cluster](../../project/clusters/deploy_to_cluster.md):
+deploy applications into your cluster using cluster certificates.
+- [Deploy Boards](../../project/deploy_boards.md): view the current health and status of each CI/CD environment running on your cluster, and the status of deployment pods.
+- [Pod logs](../../project/clusters/kubernetes_pod_logs.md): view the logs of your cluster's running pods.
+- [Serverless](../../project/clusters/serverless/index.md) (deprecated): deploy Serverless applications in Kubernetes environments and cloud Function as a Service (FaaS) environments.
diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md
new file mode 100644
index 00000000000..009945589ad
--- /dev/null
+++ b/doc/user/infrastructure/clusters/manage/clusters_health.md
@@ -0,0 +1,14 @@
+---
+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
+---
+
+# Clusters health **(FREE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2.
+
+When [the Prometheus cluster integration is enabled](../../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.
+
+![Cluster Monitoring](img/k8s_cluster_monitoring.png)
diff --git a/doc/user/infrastructure/clusters/manage/img/k8s_cluster_monitoring.png b/doc/user/infrastructure/clusters/manage/img/k8s_cluster_monitoring.png
new file mode 100644
index 00000000000..0a8c5043c65
--- /dev/null
+++ b/doc/user/infrastructure/clusters/manage/img/k8s_cluster_monitoring.png