Merge branch 'docs-iac-review-part1' into 'master'

Docs: IaC review (overview)

See merge request gitlab-org/gitlab!80422

doc/user/infrastructure/iac/index.md

@@ -6,68 +6,98 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Infrastructure as Code with Terraform and GitLab **(FREE)**
 
-With Terraform in GitLab, you can use GitLab authentication and authorization with
-your GitOps and Infrastructure-as-Code (IaC) workflows.
-Use these features if you want to collaborate on Terraform code within GitLab or would like to use GitLab as a Terraform state storage that incorporates best practices out of the box.
+To manage your infrastructure with GitLab, you can use the integration with
+Terraform to define resources that you can version, reuse, and share:
+
+- Manage low-level components like compute, storage, and networking resources.
+- Manage high-level components like DNS entries and SaaS features.
+- Incorporate GitOps deployments and Infrastructure-as-Code (IaC) workflows.
+- Use GitLab as a Terraform state storage.
+- Store and use Terraform modules to simplify common and complex infrastructure patterns.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch [a video overview](https://www.youtube.com/watch?v=iGXjUrkkzDI) of the features GitLab provides with the integration with Terraform.
 
 ## Integrate your project with Terraform
 
 > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6.
 
-In GitLab 14.0 and later, to integrate your project with Terraform, add the following
-to your `.gitlab-ci.yml` file:
+The integration with GitLab and Terraform happens through GitLab CI/CD.
+Use an `include` attribute to add the Terraform template to your project and
+customize from there.
 
-```yaml
-include:
-  - template: Terraform.latest.gitlab-ci.yml
+To get started, choose the template that best suits your needs:
 
-variables:
-  # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables
-  TF_STATE_NAME: default
-  TF_CACHE_KEY: default
-  # If your terraform files are in a subdirectory, set TF_ROOT accordingly
-  # TF_ROOT: terraform/production
-```
+- [Latest template](#latest-terraform-template)
+- [Stable template and advanced template](#stable-and-advanced-terraform-templates)
 
-The `Terraform.latest.gitlab-ci.yml` template:
+All templates:
 
-- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images).
-- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as
+- Use the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as
   the Terraform state storage backend.
-- Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml):
-  `test`, `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)
-  `test`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch.
-- Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually),
-  that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`.
+- Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`.
+- Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch.
+- Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually).
+
+### Latest Terraform template
+
+The [latest template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml)
+is compatible with the most recent GitLab version. It provides the most recent
+GitLab features, but can potentially include breaking changes.
+
+You can safely use the latest Terraform template:
+
+- If you use GitLab.com.
+- If you use a self-managed instance updated with every new GitLab release.
 
-You can override the values in the default template by updating your `.gitlab-ci.yml` file.
+### Stable and advanced Terraform templates
 
-The latest template might contain breaking changes between major GitLab releases.
-For a more stable template, we recommend:
+If you use earlier versions of GitLab, you might face incompatibility errors
+between the GitLab version and the template version. In this case, you can opt
+to use one of these templates:
 
-- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml)
-- [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml)
+- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with an skeleton that you can built on top of.
+- [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup.
 
-This video from January 2021 walks you through all the GitLab Terraform integration features:
+### Use a Terraform template
+
+To use a Terraform template:
+
+1. On the top bar, select **Menu > Projects** and find the project you want to integrate with Terraform.
+1. On the left sidebar, select **Repository > Files**.
+1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template:
+
+   ```yaml
+   include:
+    # To fetch the latest template, use:
+     - template: Terraform.latest.gitlab-ci.yml
+    # To fetch the stable template, use:
+     - template: Terraform/Base.gitlab-ci.yml
+    # To fetch the advanced template, use:
+     - template: Terraform/Base.latest.gitlab-ci.yml
+   ```
+
+1. Add the variables as described below:
+
+   ```yaml
+   variables:
+    TF_STATE_NAME: default
+    TF_CACHE_KEY: default
+    # If your terraform files are in a subdirectory, set TF_ROOT accordingly. For example:
+    # TF_ROOT: terraform/production
+   ```
 
-<div class="video-fallback">
-  See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>.
-</div>
-<figure class="video-container">
-  <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe>
-</figure>
+1. (Optional) Override in your `.gitlab-ci.yaml` file the attributes present
+in the template you fetched to customize your configuration.
 
 ## GitLab-managed Terraform state
 
-[Terraform remote backends](https://www.terraform.io/language/settings/backends)
+[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html)
 enable you to store the state file in a remote, shared store. GitLab uses the
-[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http)
+[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html)
 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. It spares you from setting up additional remote resources like
+The GitLab-managed Terraform state backend can safely store your Terraform state. 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.
@@ -110,6 +140,7 @@ is available as part of the official Terraform provider documentation.
 - 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).
 
-## Troubleshooting
+## Related topics
 
-See the [troubleshooting](troubleshooting.md) documentation.
+- [Terraform images](https://gitlab.com/gitlab-org/terraform-images).
+- [Troubleshooting](troubleshooting.md) issues with GitLab and Terraform.

doc/user/infrastructure/iac/mr_integration.md

@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings.
 
 ## Configure Terraform report artifacts
 
-GitLab ships with a [pre-built CI template](index.md#integrate-your-project-with-terraform) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup.
+GitLab [integrates with Terraform](index.md#integrate-your-project-with-terraform) through CI/CD templates that use GitLab-managed Terraform state and display Terraform changes on merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup.
 
 To manually configure a GitLab Terraform Report artifact: