Merge branch 'agent-gke-example-project-docs' into 'master'

Update documentation for GKE/Terraform example project

See merge request gitlab-org/gitlab!82063

doc/user/infrastructure/clusters/connect/new_gke_cluster.md

@@ -4,65 +4,59 @@ 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
 ---
 
-# New GKE cluster through IaC (DEPRECATED)
-
-> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-
-WARNING:
-The process described on this page uses cluster certificates to connect the
-new cluster to GitLab, [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-You can still create a cluster and then connect it to GitLab through the [agent](../index.md).
-[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/343660)
-to migrate this functionality to the [agent](../index.md).
+# Create a Google GKE cluster
 
 Learn how to create a new cluster on Google Kubernetes Engine (GKE) through
-[Infrastructure as Code (IaC)](../../index.md).
-
-This process combines the GitLab Terraform and Google Terraform providers
-with Kubernetes to help you create GKE clusters and deploy them through
-GitLab.
-
-This document describes how to set up a [group-level cluster](../../../group/clusters/index.md) on GKE by importing an example project to get you started.
-You can then modify the project files according to your needs.
+[Infrastructure as Code (IaC)](../../index.md). This process uses the Google
+and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab
+by using the GitLab agent for Kubernetes.
 
 **Prerequisites:**
 
-- A GitLab group.
-- A GitLab user with the Maintainer role in the group.
-- A [GitLab personal access token](../../../profile/personal_access_tokens.md) with `api` access, created by a user with at least the Maintainer role in the group.
 - A [Google Cloud Platform (GCP) service account](https://cloud.google.com/docs/authentication/getting-started).
+- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline.
 
 **Steps:**
 
 1. [Import the example project](#import-the-example-project).
-1. [Create your GCP and GitLab credentials](#create-your-gcp-and-gitlab-credentials).
+1. [Register the agent for Kubernetes](#register-the-agent).
+1. [Create your GCP credentials](#create-your-gcp-credentials).
 1. [Configure your project](#configure-your-project).
-1. [Deploy your cluster](#deploy-your-cluster).
+1. [Provision your cluster](#provision-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.
+To create a cluster from GitLab using Infrastructure as Code, you must
+create a project to manage the cluster from. In this tutorial, you start with
+a sample project and modify it according to your needs.
 
-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.
+Start by [importing the example project by URL](../../../project/import/repo_by_url.md).
 
-This project provides you with the following resources:
+To import the project:
+
+1. On the top bar, select **Menu > Create new project**.
+1. Select **Import project**.
+1. Select **Repo by URL**.
+1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git`.
+1. Complete the fields and select **Create project**.
+
+This project provides you with:
 
 - 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:
-
-   ```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
-   ```
+- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/agent.tf) installed in the cluster.
 
-## Create your GCP and GitLab credentials
+## Register the agent
+
+To create a GitLab agent for Kubernetes:
+
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. Select **Actions**.
+1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**.
+1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later.
+1. GitLab provides an address for the agent server (KAS), which you will also need later.
+
+## Create your GCP credentials
 
 To set up your project to communicate to GCP and the GitLab API:
 
@@ -85,18 +79,14 @@ The Admin role creates a service account in the `kube-system` namespace.
 
 ## Configure your project
 
-**Required configuration:**
-
-Use CI/CD environment variables to configure your project as detailed below.
+Use CI/CD environment variables to configure your project.
 
 **Required configuration:**
 
 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.
 
 **Optional configuration:**
 
@@ -105,22 +95,57 @@ contains other variables that you can override according to your needs:
 
 - `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.
+- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes.
+- `TF_VAR_node_count`: Set the number of Kubernetes nodes.
+- `TF_VAR_agent_version`: Set the version of the GitLab agent.
+- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent.
 
-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.
+Refer to the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options.
 
-## Deploy your cluster
+## Provision your cluster
 
-After configuring your project, manually trigger the deployment of your cluster. In GitLab:
+After configuring your project, manually trigger the provisioning 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}**).
-1. Select **deploy** to manually trigger the deployment job.
+1. On the left sidebar, go to **CI/CD > Pipelines**.
+1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**).
+1. Select **Deploy** to manually trigger the deployment job.
 
 When the pipeline finishes successfully, you can see your new cluster:
 
 - In GCP: on your [GCP console's Kubernetes list](https://console.cloud.google.com/kubernetes/list).
 - In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**.
+
+## Use your cluster
+
+After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection:
+
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. In the list, view the **Connection status** column.
+
+For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md).
+
+## Remove the cluster
+
+A cleanup job is not included in your pipeline by default. To remove all created resources, you
+must modify your GitLab CI/CD template before running the cleanup job.
+
+To remove all resources:
+
+1. Add the following to your `.gitlab-ci.yml` file:
+
+    ```yaml
+    stages:
+      - init
+      - validate
+      - build
+      - deploy
+      - cleanup
+
+    destroy:
+      extends: .destroy
+      needs: []
+    ```
+
+1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline.
+1. For the `destroy` job, select **Play** (**{play}**).

doc/user/infrastructure/iac/index.md

@@ -108,14 +108,7 @@ is available as part of the official Terraform provider documentation.
 ## Create a new cluster through IaC
 
 - Learn how to [create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md).
-- Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md) (DEPRECATED).
-
-NOTE:
-The linked GKE tutorial connects the cluster to GitLab through cluster certificates,
-and this method was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8)
-in GitLab 14.5. You can still create a cluster through IaC and then connect it to GitLab
-through the [agent](../../clusters/agent/index.md), the default and fully supported
-method to connect clusters to GitLab.
+- Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md).
 
 ## Troubleshooting