Add latest changes from gitlab-org/gitlab@15-8-stable-eev15.8.0-rc42

6 files changed, 237 insertions, 3 deletions

diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
index 8a5c32150c9..cefa8885bfe 100644
--- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
@@ -60,6 +60,53 @@ To create a GitLab agent for Kubernetes:
 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.
 
+## Set up AWS credentials
+
+Set up your AWS credentials when you want to authenticate AWS with GitLab.
+
+1. Create an [IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) or [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).
+1. Make sure that your IAM user or role has the appropriate permissions for your project. For this example project, you must have the permissions shown below. You can expand this when you set up your own project.
+
+    ```json
+    // IAM custom Policy definition
+    {
+      "Version": "2012-10-17",
+      "Statement": [
+          {
+              "Sid": "VisualEditor0",
+              "Effect": "Allow",
+              "Action": [
+                  "ec2:*",
+                  "eks:*",
+                  "elasticloadbalancing:*",
+                  "autoscaling:*",
+                  "cloudwatch:*",
+                  "logs:*",
+                  "kms:DescribeKey",
+                  "iam:AddRoleToInstanceProfile",
+                  "iam:AttachRolePolicy",
+                  "iam:CreateInstanceProfile",
+                  "iam:CreateRole",
+                  "iam:CreateServiceLinkedRole",
+                  "iam:GetRole",
+                  "iam:ListAttachedRolePolicies",
+                  "iam:ListRolePolicies",
+                  "iam:ListRoles",
+                  "iam:PassRole",
+                  // required for destroy step
+                  "iam:DetachRolePolicy",
+                  "iam:ListInstanceProfilesForRole",
+                  "iam:DeleteRole"
+              ],
+              "Resource": "*"
+          }
+      ]
+    }
+    ```
+
+1. [Create an access key for the user or role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
+1. Save your access key and secret. You need these to authenticate AWS with GitLab.
+
 ## Configure your project
 
 Use CI/CD environment variables to configure your project.
diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
index 4c68ec42712..3084cc28c9b 100644
--- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
+++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
@@ -35,7 +35,7 @@ These values can be specified using [CI/CD variables](../../../../../ci/variable
 
 The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `CI_SERVER_URL` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `gitlabUrl:` in `applications/gitlab-runner/values.yaml.gotmpl`.
 
-The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protected-cicd-variables) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file.
+The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file.
 
 You can customize the installation of GitLab Runner by defining
 `applications/gitlab-runner/values.yaml.gotmpl` file in your cluster
diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md
new file mode 100644
index 00000000000..8be949c40cd
--- /dev/null
+++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md
@@ -0,0 +1,137 @@
+---
+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/product/ux/technical-writing/#assignments
+---
+
+# GitLab Terraform helpers **(FREE)**
+
+GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md).
+
+- The `gitlab-terraform` script, which is a thin wrapper around the `terraform` command.
+- The `terraform-images` container images, which include the `gitlab-terraform` script and `terraform` itself.
+
+Both helpers are maintained in the [Terraform Images](https://gitlab.com/gitlab-org/terraform-images)
+project.
+
+## `gitlab-terraform`
+
+The `gitlab-terraform` script is a thin wrapper around the `terraform` command.
+
+Run `gitlab-terraform` in a CI/CD pipeline to set up the necessary environment
+variables to connect to the [GitLab-managed Terraform State](terraform_state.md) backend.
+
+### Source (but do not run) the helper script
+
+When the `gitlab-terraform` script is sourced, it
+configures the environment for a `terraform` call, but does not
+actually run `terraform`. You can source the script when you need to do
+extra steps to prepare your environment, or to use alternative
+tools like `terragrunt`.
+
+To source the script, execute:
+
+```shell
+source $(which gitlab-terraform)
+```
+
+Some shells, like BusyBox, do not support the case
+of another script sourcing your script. For more information, see [this Stack Overflow thread](https://stackoverflow.com/a/28776166).
+To resolve this issue, you should use `bash`, `zsh` or `ksh`, or source `gitlab-terraform` directly
+from the shell.
+
+### Commands
+
+You can run `gitlab-terraform` with the following commands.
+
+| Command                      | Forwards command line? | Implicit init?        | Description                                                                                            |
+|------------------------------|------------------------|-----------------------|--------------------------------------------------------------------------------------------------------|
+| `gitlab-terraform apply`     | Yes                    | Yes                   | Runs `terraform apply`.                                                                                |
+| `gitlab-terraform destroy`   | Yes                    | Yes                   | Runs `terraform destroy`.                                                                              |
+| `gitlab-terraform fmt`       | Yes                    | No                    | Runs `terraform fmt` in check mode.                                                                    |
+| `gitlab-terraform init`      | Yes                    | Not applicable        | Runs `terraform init`.                                                                                 |
+| `gitlab-terraform plan`      | Yes                    | Yes                   | Runs `terraform plan` and produces a `plan.cache` file.                                                |
+| `gitlab-terraform plan-json` | No                     | No                    | Converts a `plan.cache` file into a GitLab Terraform report for a [MR integration](mr_integration.md). |
+| `gitlab-terraform validate`  | Yes                    | Yes (without backend) | Runs `terraform validate`.                                                                             |
+| `gitlab-terraform -- <cmd>`  | Yes                    | No                    | Runs `terraform <cmd>`, even if it is wrapped.                                                         |
+| `gitlab-terraform <cmd>`     | Yes                    | No                    | Runs `terraform <cmd>`, if the command is not wrapped.                                                 |
+
+### Generic variables
+
+When you run `gitlab-terraform`, these variables are configured.
+
+| Variable             | Default                                    | Description                                                                                                                                                                |
+|----------------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `TF_ROOT`            | Not set                                    | Root of the Terraform configuration. If set, it is used as the Terraform `-chdir` argument value. All read and written files are relative to the given configuration root. |
+| `TF_CLI_CONFIG_FILE` | `$HOME/.terraformrc`                       | Location of the [Terraform configuration file](https://developer.hashicorp.com/terraform/cli/config/config-file).                                                          |
+| `TF_IN_AUTOMATION`   | `true`                                     | Set to `true` to indicate that Terraform commands are automated.                                                                                                           |
+| `TF_GITLAB_SOURCED`  | `false`                                    | Set to `true` if `gitlab-terraform` [was sourced](#source-but-do-not-run-the-helper-script).                                                                               |
+| `TF_PLAN_CACHE`      | `$TF_ROOT/plan.cache` or `$PWD/plan.cache` | Location of the plan cache file. If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`).                                             |
+| `TF_PLAN_JSON`       | `$TF_ROOT/plan.json` or `$PWD/plan.json`   | Location of the plan JSON file for [MR integration](mr_integration.md). If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`).      |
+| `DEBUG_OUTPUT`       | `"false"`                                  | If set to `"true"` every statement is logged with `set -x`.                                                                                                                |
+
+### GitLab-managed Terraform state variables
+
+When you run `gitlab-terraform`, these variables are configured.
+
+| Variable                 | Default                                                                                                                 | Description                                                                                                                                                                                                               |
+|--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `TF_STATE_NAME`          | Not set                                                                                                                 | If `TF_ADDRESS` is not set, and `TF_STATE_NAME` is provided, then the value of `TF_STATE_NAME` is used as [GitLab-managed Terraform State](terraform_state.md) name.                                                      |
+| `TF_ADDRESS`             | Terraform State API URL for `$TF_STATE_NAME`                                                                            | Used as default for [`TF_HTTP_ADDRESS`](https://developer.hashicorp.com/terraform/language/settings/backends/http#address). Uses `TF_STATE_NAME` as [GitLab-managed Terraform State](terraform_state.md) name by default. |
+| `TF_USERNAME`            | [`$GITLAB_USER_LOGIN`](../../../ci/variables/predefined_variables.md) or `gitlab-ci-token` if `$TF_PASSWORD` is not set | Used as default for [`TF_HTTP_USERNAME`](https://developer.hashicorp.com/terraform/language/settings/backends/http#username).                                                                                             |
+| `TF_PASSWORD`            | [`$CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md)                                                        | Used as default for [`TF_HTTP_PASSWORD`](https://developer.hashicorp.com/terraform/language/settings/backends/http#password).                                                                                             |
+| `TF_HTTP_ADDRESS`        | `$TF_ADDRESS`                                                                                                           | [Address to the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#address).                                                                                                    |
+| `TF_HTTP_LOCK_ADDRESS`   | `$TF_ADDRESS/lock`                                                                                                      | [Address to the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_address).                                                                                 |
+| `TF_HTTP_LOCK_METHOD`    | `POST`                                                                                                                  | [Method to use for the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_method).                                                                           |
+| `TF_HTTP_UNLOCK_ADDRESS` | `$TF_ADDRESS/lock`                                                                                                      | [Address to the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_address).                                                                             |
+| `TF_HTTP_UNLOCK_METHOD`  | `DELETE`                                                                                                                | [Method to use for the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_method).                                                                       |
+| `TF_HTTP_USERNAME`       | `$TF_USERNAME`                                                                                                          | [Username to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#username).                                                                                |
+| `TF_HTTP_PASSWORD`       | `$TF_PASSWORD`                                                                                                          | [Password to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#password).                                                                                |
+| `TF_HTTP_RETRY_WAIT_MIN` | `5`                                                                                                                     | [Minimum time in seconds to wait](https://developer.hashicorp.com/terraform/language/settings/backends/http#retry_wait_min) between HTTP request attempts to the Terraform backend.                                       |
+
+### Command variables
+
+When you run `gitlab-terraform`, these variables are configured.
+
+| Variable                 | Default  | Description                                                                               |
+|--------------------------|----------|-------------------------------------------------------------------------------------------|
+| `TF_IMPLICIT_INIT`       | `true`   | If `true`, an implicit `terraform init` runs before the wrapped commands that require it. |
+| `TF_INIT_NO_RECONFIGURE` | `false`  | If `true`, the implicit `terraform init` runs without `-reconfigure`.                     |
+| `TF_INIT_FLAGS`          | Not set  | Additional `terraform init` flags.                                                        |
+
+### Terraform input variables
+
+When you run `gitlab-terraform`, these Terraform input variables are set automatically.
+For more information about the default values, see [Predefined variables](../../../ci/variables/predefined_variables.md).
+
+| Variable                      | Default                 |
+|-------------------------------|-------------------------|
+| `TF_VAR_CI_JOB_ID`            | `$CI_JOB_ID`            |
+| `TF_VAR_CI_COMMIT_SHA`        | `$CI_COMMIT_SHA`        |
+| `TF_VAR_CI_JOB_STAGE`         | `$CI_JOB_STAGE`         |
+| `TF_VAR_CI_PROJECT_ID`        | `$CI_PROJECT_ID`        |
+| `TF_VAR_CI_PROJECT_NAME`      | `$CI_PROJECT_NAME`      |
+| `TF_VAR_CI_PROJECT_NAMESPACE` | `$CI_PROJECT_NAMESPACE` |
+| `TF_VAR_CI_PROJECT_PATH`      | `$CI_PROJECT_PATH`      |
+| `TF_VAR_CI_PROJECT_URL`       | `$CI_PROJECT_URL`       |
+
+## Terraform images
+
+The `gitlab-terraform` helper script and `terraform` itself are provided in container images
+under `registry.gitlab.com/gitlab-org/terraform-images/`. You can use these images to configure
+and manage your integration.
+
+The following images are provided:
+
+| Image name                    | Tag                         | Description                                                                    |
+|-------------------------------|-----------------------------|--------------------------------------------------------------------------------|
+| `stable`                      | `latest`                    | Latest `terraform-images` release bundled with the latest Terraform release.   |
+| `releases/$TERRAFORM_VERSION` | `latest`                    | Latest `terraform-images` release bundled with a specific Terraform release.   |
+| `releases/$TERRAFORM_VERSION` | `$TERRAFORM_IMAGES_VERSION` | Specific `terraform-images` release bundled with a specific Terraform release. |
+
+For supported combinations, see [the `terraform-images` container registry](https://gitlab.com/gitlab-org/terraform-images/container_registry).
+
+## Related topics
+
+- [Terraform CI/CD templates](index.md)
+- [Terraform template recipes](terraform_template_recipes.md)
diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md
index fc86210ed56..eb6a8db0c05 100644
--- a/doc/user/infrastructure/iac/terraform_state.md
+++ b/doc/user/infrastructure/iac/terraform_state.md
@@ -82,7 +82,9 @@ To configure GitLab CI/CD as a backend:
 
 The output from the above `terraform` commands should be viewable in the job logs.
 
-The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. You can [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh) if you're interested.
+The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. For more information,
+see [GitLab Terraform helpers](gitlab_terraform_helpers.md),
+or [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh).
 
 If you prefer to call the `terraform` commands explicitly, you can override
 the template, and instead, use it as reference for what you can achieve.
diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md
index ab2c8c1c48a..0d1b56ae979 100644
--- a/doc/user/infrastructure/iac/terraform_template_recipes.md
+++ b/doc/user/infrastructure/iac/terraform_template_recipes.md
@@ -181,3 +181,51 @@ deploy:
 ```
 
 For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage).
+
+## Deploy Terraform to multiple environments
+
+You can run pipelines in multiple environments, each with a unique Terraform state.
+
+```yaml
+stages:
+  - validate
+  - test
+  - build
+  - deploy
+
+include:
+  - template: Terraform/Base.latest.gitlab-ci.yml
+  - template: Jobs/SAST-IaC.latest.gitlab-ci.yml
+
+variables:
+  # x prevents TF_STATE_NAME from beeing empty for non environment jobs like validate
+  # wait for https://gitlab.com/groups/gitlab-org/-/epics/7437 to use variable defaults
+  TF_STATE_NAME: x${CI_ENVIRONMENT_NAME}
+  TF_CLI_ARGS_plan: "-var-file=vars/${CI_ENVIRONMENT_NAME}.tfvars"
+
+fmt:
+  extends: .terraform:fmt
+validate:
+  extends: .terraform:validate
+
+plan dev:
+  extends: .terraform:build
+  environment:
+    name: dev
+plan prod:
+  extends: .terraform:build
+  environment:
+    name: prod
+
+apply dev:
+  extends: .terraform:deploy
+  environment:
+    name: dev
+
+apply prod:
+  extends: .terraform:deploy
+  environment:
+    name: prod
+```
+
+This configuration is modified from the [base GitLab template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml).
diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md
index ad1821fbe10..2aa1e5d3284 100644
--- a/doc/user/infrastructure/iac/troubleshooting.md
+++ b/doc/user/infrastructure/iac/troubleshooting.md
@@ -110,7 +110,7 @@ If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with
 To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the
 job that returned the error:
 
-1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) for the job.
+1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#for-a-project) for the job.
 1. Set the job's [environment](../../../ci/yaml/index.md#environment), matching the environment scope from the previous step.
 
 ### Error refreshing state: HTTP remote state endpoint requires auth