Merge branch 'terraform-eks-example-docs' into 'master'

Add documentation for EKS/Terraform example project

See merge request gitlab-org/gitlab!80866

doc/user/infrastructure/clusters/connect/new_eks_cluster.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
+---
+
+# Create a new EKS cluster through IaC
+
+Learn how to create a new cluster on Amazon Elastic Kubernetes Service (EKS) through
+[Infrastructure as Code (IaC)](../../index.md).
+
+This process combines the AWS and Kubernetes Terraform providers to help you create EKS clusters
+and connect them to GitLab using the [GitLab agent for Kubernetes](../../../clusters/agent/index.md).
+
+This document describes how to set up a Kubernetes cluster on EKS by importing an example project to get you started.
+You can then modify the project files according to your needs.
+
+**Prerequisites:**
+
+- An Amazon Web Services (AWS) account, with a set of configured
+  [security credentials](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html).
+- [Configured GitLab Runners](https://docs.gitlab.com/runner/install/) to run the infrastructure pipeline from GitLab CI/CD.
+
+**Steps:**
+
+1. [Import the example project](#import-the-example-project).
+1. [Register the Agent](#register-the-agent).
+1. [Configure your project](#configure-your-project).
+1. [Provision your cluster](#provision-your-cluster).
+
+## Import the example project
+
+To create a new 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-eks.git` as the URL.
+
+This project provides you with the following resources:
+
+- An Amazon [Virtual Private Cloud (VPC)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/vpc.tf).
+- An Amazon [Elastic Kubernetes Service (EKS)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/eks.tf) cluster.
+- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/agent.tf) installed into the cluster.
+
+## Register the Agent
+
+To create an Agent in GitLab:
+
+1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**.
+1. Select **Actions**.
+1. From the **Select an Agent** dropdown list, select `eks-agent` and select **Register an Agent**.
+1. GitLab generates a registration token for this Agent. Securely store this secret token, as you will need it to [configure your project](#configure-your-project) below.
+1. GitLab provides you with a KAS address, which will also be needed when configuring your project below.
+
+## Configure your project
+
+Use CI/CD environment variables to configure your project as detailed below.
+
+**Required configuration:**
+
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **Variables**.
+1. Set the variable `AWS_ACCESS_KEY_ID` to your AWS access key ID.
+1. Set the variable `AWS_SECRET_ACCESS_KEY` to your AWS secret access key.
+1. Set the variable `TF_VAR_agent_token` to the Agent token displayed in the previous step.
+1. Set the variable `TF_VAR_kas_address` to the KAS address displayed in the previous step.
+
+**Optional configuration:**
+
+The file [`variables.tf`](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/variables.tf)
+contains other variables that you can override according to your needs:
+
+- `TF_VAR_region`: Set your cluster's region.
+- `TF_VAR_cluster_name`: Set your cluster's name.
+- `TF_VAR_cluster_version`: Set the version of Kubernetes.
+- `TF_VAR_instance_type`: Set the instance type for the Kubernetes nodes.
+- `TF_VAR_instance_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 [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options.
+
+## Provision your cluster
+
+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.
+
+When the pipeline finishes successfully, you can see your new cluster:
+
+- In AWS: from the [EKS console](https://console.aws.amazon.com/eks/home) select **Amazon EKS > Clusters**.
+- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**.
+
+## Removing the cluster
+
+A cleanup job is not included in your pipeline by default. To remove all created resources, you
+need to modify your GitLab CI/CD template before running the cleanup job.
+
+To remove all resources:
+
+1. Add the following to your `.gitlab-ci.yml`:
+
+    ```yaml
+    stages:
+      - init
+      - validate
+      - build
+      - deploy
+      - cleanup
+
+    destroy:
+      extends: .destroy
+      needs: []
+    ```
+
+1. From your project's sidebar, go to **CI/CD > Pipelines** and select the most recent pipeline.
+1. Click the play icon (**{play}**) for the `destroy` job.

doc/user/infrastructure/iac/index.md

@@ -105,12 +105,13 @@ owned by GitLab, where everyone can contribute.
 The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
 is available as part of the official Terraform provider documentation.
 
-## Create a new cluster through IaC (DEPRECATED)
+## Create a new cluster through IaC
 
-Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md).
+- 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 tutorial connects the cluster to GitLab through cluster certificates,
+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

doc/user/project/clusters/add_eks_clusters.md

@@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
 
 WARNING:
-This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated)
+This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac)
 to create new clusters.
 
 Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic
@@ -23,7 +23,7 @@ use the [GitLab Agent](../../clusters/agent/index.md).
 
 ## Create a new EKS cluster
 
-To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated).
+To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac).
 
 ### How to create a new cluster on EKS through cluster certificates (DEPRECATED)
 

doc/user/project/clusters/add_remove_clusters.md

@@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 WARNING:
 This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
-To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated).
+To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac).
 
 NOTE:
 Every new Google Cloud Platform (GCP) account receives
@@ -29,7 +29,7 @@ in a few clicks.
 
 > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
 
-As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated)
+As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac)
 to **safely create new clusters from GitLab**.
 
 Creating clusters from GitLab using cluster certificates is still available on the