Add latest changes from gitlab-org/gitlab@13-8-stable-eev13.8.0-rc42

6 files changed, 114 insertions, 42 deletions

diff --git a/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png b/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png
new file mode 100644
index 00000000000..7d619b6ad7e
--- /dev/null
+++ b/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png
diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_5.png b/doc/user/infrastructure/img/terraform_list_view_v13_5.png
deleted file mode 100644
index b23dfa6289e..00000000000
--- a/doc/user/infrastructure/img/terraform_list_view_v13_5.png
+++ /dev/null
diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_8.png b/doc/user/infrastructure/img/terraform_list_view_v13_8.png
new file mode 100644
index 00000000000..6eb85285e81
--- /dev/null
+++ b/doc/user/infrastructure/img/terraform_list_view_v13_8.png
diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md
index 4c012fbf1d9..60453b007ba 100644
--- a/doc/user/infrastructure/index.md
+++ b/doc/user/infrastructure/index.md
@@ -8,11 +8,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 ## Motivation
 
-The Terraform integration features within GitLab enable your GitOps / Infrastructure-as-Code (IaC)
+The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC)
 workflows to tie into GitLab authentication and authorization. These features focus on
-lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within
+lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in
 GitLab, and support Terraform best practices.
 
+## Quick Start
+
+Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration
+for GitLab versions 13.5 and later:
+
+```yaml
+include:
+  - template: Terraform.latest.gitlab-ci.yml
+
+variables:
+  # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables
+  TF_STATE_NAME: default
+  TF_CACHE_KEY: default
+```
+
+This template uses `.latest.`, instead of stable, and may include breaking changes.
+This template also includes some opinionated decisions, which you can override:
+
+- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images).
+- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as
+  the Terraform state storage backend.
+- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml):
+  `init`, `validate`, `build`, and `deploy`. These stages
+  [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml)
+  `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`.
+
 ## GitLab Managed Terraform state
 
 [Terraform remote backends](https://www.terraform.io/docs/backends/index.html)
@@ -22,7 +48,7 @@ to securely store the state files in local storage (the default) or
 [the remote store of your choice](../../administration/terraform_state.md).
 
 The GitLab managed Terraform state backend can store your Terraform state easily and
-securely, and spares you from setting up additional remote resources like
+securely. It spares you from setting up additional remote resources like
 Amazon S3 or Google Cloud Storage. Its features include:
 
 - Supporting encryption of the state file both in transit and at rest.
@@ -39,32 +65,23 @@ recommends encrypting plan output or modifying the project visibility settings.
 
 ## Terraform integration in Merge Requests
 
-Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows.
+Collaborating around Infrastructure as Code (IaC) changes requires both code changes
+and expected infrastructure changes to be checked and approved. GitLab provides a
+solution to help collaboration around Terraform code changes and their expected
+effects using the Merge Request pages. This way users don't have to build custom
+tools or rely on 3rd party solutions to streamline their IaC workflows.
 
 Read more on setting up and [using the merge request integrations](mr_integration.md).
 
-## Quick Start
-
-Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration
-for GitLab versions 13.5 and greater:
+## The GitLab terraform provider
 
-```yaml
-include:
-  - template: Terraform.latest.gitlab-ci.yml
-
-variables:
-  # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables
-  TF_STATE_NAME: default
-  TF_CACHE_KEY: default
-```
+WARNING:
+The GitLab Terraform provider is released separately from GitLab.
+We are working on migrating the GitLab Terraform provider for GitLab.com.
 
-This template uses `.latest.`, instead of stable, and may include breaking changes.
-This template also includes some opinionated decisions, which you can override:
+You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab)
+to manage various aspects of GitLab using Terraform. The provider is an open source project,
+owned by GitLab, where everyone can contribute.
 
-- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images).
-- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as
-  the Terraform state storage backend.
-- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml):
-  `init`, `validate`, `build`, and `deploy`. These stages
-  [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml)
-  `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`.
+The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
+is available as part of the official Terraform provider documentations.
diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md
index c86e5ddf1db..2704e7b7c8d 100644
--- a/doc/user/infrastructure/mr_integration.md
+++ b/doc/user/infrastructure/mr_integration.md
@@ -72,10 +72,10 @@ To manually configure a GitLab Terraform Report artifact requires the following
          terraform: $PLAN_JSON
    ```
 
-   For a full example using the pre-built image, see [Example `.gitlab-ci.yaml`
-   file](#example-gitlab-ciyaml-file).
+   For a full example using the pre-built image, see [Example `.gitlab-ci.yml`
+   file](#example-gitlab-ciyml-file).
 
-   For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports).
+   For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports).
 
 1. Running the pipeline displays the widget in the merge request, like this:
 
@@ -86,7 +86,7 @@ To manually configure a GitLab Terraform Report artifact requires the following
 
    ![Terraform plan logs](img/terraform_plan_log_v13_0.png)
 
-### Example `.gitlab-ci.yaml` file
+### Example `.gitlab-ci.yml` file
 
 ```yaml
 default:
diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md
index cbd2a63524d..30838b1cabd 100644
--- a/doc/user/infrastructure/terraform_state.md
+++ b/doc/user/infrastructure/terraform_state.md
@@ -62,7 +62,7 @@ local machine, this is a simple way to get started:
 1. On your local machine, run `terraform init`, passing in the following options,
    replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`,  `<YOUR-USERNAME>` and
    `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your
-   Terraform state, and stores that state within your GitLab project. The name of
+   Terraform state, and stores that state in your GitLab project. The name of
    your state can contain only uppercase and lowercase letters, decimal digits,
    hyphens, and underscores. This example uses `gitlab.com`:
 
@@ -104,7 +104,7 @@ and the CI YAML file:
    ```
 
 1. In the root directory of your project repository, configure a
-   `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a
+   `.gitlab-ci.yml` file. This example uses a pre-built image which includes a
    `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab
    Terraform Images project](https://gitlab.com/gitlab-org/terraform-images).
 
@@ -112,7 +112,7 @@ and the CI YAML file:
    image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
    ```
 
-1. In the `.gitlab-ci.yaml` file, define some environment variables to ease
+1. In the `.gitlab-ci.yml` file, define some environment variables to ease
    development. In this example, `TF_ROOT` is the directory where the Terraform
    commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab
    instance where this pipeline runs, and the final path segment in `TF_ADDRESS`
@@ -194,7 +194,7 @@ recommends encrypting plan output or modifying the project visibility settings.
 
 ### Example project
 
-See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC.
+See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC.
 
 ## Using a GitLab managed Terraform state backend as a remote data source
 
@@ -234,7 +234,7 @@ An example setup is shown below:
    }
    ```
 
-Outputs from the data source can now be referenced within your Terraform resources
+Outputs from the data source can now be referenced in your Terraform resources
 using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`.
 
 You need at least [developer access](../permissions.md) to the target project
@@ -340,21 +340,76 @@ commands will detect it and remind you to do so if necessary.
 ```
 
 If you type `yes`, it copies your state from the old location to the new
-location. You can then go back to running it from within GitLab CI.
+location. You can then go back to running it in GitLab CI/CD.
 
 ## Managing state files
 
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8.
+
+Users with Developer and greater [permissions](../permissions.md) can view the
+state files attached to a project at **Operations > Terraform**. Users with
+Maintainer permissions can perform commands on the state files. The user interface
+contains these fields:
+
+![Terraform state list](img/terraform_list_view_v13_8.png)
+
+- **Name**: The name of the environment, with a locked (**{lock}**) icon if the
+  state file is locked.
+- **Pipeline**: A link to the most recent pipeline and its status.
+- **Details**: Information about when the state file was created or changed.
+- **Actions**: Actions you can take on the state file, including downloading,
+  locking, unlocking, or [removing](#remove-a-state-file) the state file and versions:
+
+  ![Terraform state list](img/terraform_list_view_actions_v13_8.png)
+
 NOTE:
-We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563).
+Additional improvements to the
+[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563)
+are planned.
+
+## Remove a state file
+
+Users with Maintainer and greater [permissions](../permissions.md) can use the
+following options to remove a state file:
 
-![Terraform state list](img/terraform_list_view_v13_5.png)
+- **GitLab UI**: Go to **Operations > Terraform**. In the **Actions** column,
+  click the vertical ellipsis (**{ellipsis_v}**) button and select
+  **Remove state file and versions**.
+- **GitLab REST API**: You can remove a state file by making a request to the
+  REST API. For example:
 
-The state files attached to a project can be found under Operations / Terraform.
+  ```shell
+  curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>"
+  ```
 
-## Removing a State file
+- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api).
 
-You can only remove a state file by making a request to the API, like the following example:
+### Remove a state file with the GitLab GraphQL API
+
+You can remove a state file by making a GraphQL API request. For example:
+
+```shell
+mutation deleteState {
+  terraformStateDelete(input: { id: "<global_id_for_the_state>" }) {
+    errors
+  }
+}
+```
+
+You can obtain the `<global_id_for_the_state>` by querying the list of states:
 
 ```shell
-curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>"
+query ProjectTerraformStates {
+  project(fullPath: "<your_project_path>") {
+    terraformStates {
+      nodes {
+        id
+        name
+      }
+    }
+  }
+}
 ```
+
+For those new to the GitLab GraphQL API, read
+[Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md).