Merge branch 'docs/fix-gke-iac-instructions-jcunha' into 'master'

Fix GKE IAC instructions

See merge request gitlab-org/gitlab!70433

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}**).