Commit d9c472a9 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'selhorn-terraform-small-edits' into 'master'

Small edits for consistency

See merge request gitlab-org/gitlab!79456
parents b6a1aaa8 8fc47817
...@@ -6,36 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -6,36 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Infrastructure as Code with Terraform and GitLab **(FREE)** # Infrastructure as Code with Terraform and GitLab **(FREE)**
## Motivation 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.
The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) ## Integrate your project with Terraform
workflows to tie into GitLab authentication and authorization. These features focus on
lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in
GitLab, and support Terraform best practices.
## Quick Start
> SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6.
Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration In GitLab 14.0 and later, to integrate your project with Terraform, add the following
for GitLab versions 14.0 and later: to your `.gitlab-ci.yml` file:
```yaml ```yaml
include: include:
- template: Terraform.latest.gitlab-ci.yml - template: Terraform.latest.gitlab-ci.yml
variables: variables:
# If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables
TF_STATE_NAME: default TF_STATE_NAME: default
TF_CACHE_KEY: default TF_CACHE_KEY: default
# If your terraform files are in a subdirectory, set TF_ROOT accordingly # If your terraform files are in a subdirectory, set TF_ROOT accordingly
# TF_ROOT: terraform/production # TF_ROOT: terraform/production
``` ```
This template includes the following parameters that you can override: The `Terraform.latest.gitlab-ci.yml` template:
- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). - Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images).
- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as - Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as
the Terraform state storage backend. 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): - 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 `test`, `validate`, `build`, and `deploy`. These stages
...@@ -44,10 +41,12 @@ This template includes the following parameters that you can override: ...@@ -44,10 +41,12 @@ This template includes the following parameters that you can override:
- Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually), - 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`. that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`.
The latest template described above might contain breaking changes between major GitLab releases. For users requiring more stable setups, we You can override the values in the default template by updating your `.gitlab-ci.yml` file.
recommend using the stable templates:
The latest template might contain breaking changes between major GitLab releases.
For a more stable template, we recommend:
- [A ready to use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) - [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) - [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml)
This video from January 2021 walks you through all the GitLab Terraform integration features: This video from January 2021 walks you through all the GitLab Terraform integration features:
...@@ -59,7 +58,7 @@ This video from January 2021 walks you through all the GitLab Terraform integrat ...@@ -59,7 +58,7 @@ This video from January 2021 walks you through all the GitLab Terraform integrat
<iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe>
</figure> </figure>
## GitLab Managed Terraform state ## GitLab-managed Terraform state
[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) [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 enable you to store the state file in a remote, shared store. GitLab uses the
...@@ -67,7 +66,7 @@ enable you to store the state file in a remote, shared store. GitLab uses the ...@@ -67,7 +66,7 @@ enable you to store the state file in a remote, shared store. GitLab uses the
to securely store the state files in local storage (the default) or to securely store the state files in local storage (the default) or
[the remote store of your choice](../../../administration/terraform_state.md). [the remote store of your choice](../../../administration/terraform_state.md).
The GitLab managed Terraform state backend can store your Terraform state easily and The GitLab-managed Terraform state backend can store your Terraform state easily and
securely. It 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: Amazon S3 or Google Cloud Storage. Its features include:
...@@ -75,7 +74,7 @@ Amazon S3 or Google Cloud Storage. Its features include: ...@@ -75,7 +74,7 @@ Amazon S3 or Google Cloud Storage. Its features include:
- Locking and unlocking state. - Locking and unlocking state.
- Remote Terraform plan and apply execution. - Remote Terraform plan and apply execution.
Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md). Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md).
## Terraform module registry ## Terraform module registry
...@@ -104,7 +103,7 @@ to manage various aspects of GitLab using Terraform. The provider is an open sou ...@@ -104,7 +103,7 @@ to manage various aspects of GitLab using Terraform. The provider is an open sou
owned by GitLab, where everyone can contribute. owned by GitLab, where everyone can contribute.
The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
is available as part of the official Terraform provider documentations. is available as part of the official Terraform provider documentation.
## Create a new cluster through IaC (DEPRECATED) ## Create a new cluster through IaC (DEPRECATED)
......
...@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings. ...@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings.
## Configure Terraform report artifacts ## Configure Terraform report artifacts
GitLab ships with a [pre-built CI template](index.md#quick-start) 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 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.
To manually configure a GitLab Terraform Report artifact: To manually configure a GitLab Terraform Report artifact:
......
...@@ -4,7 +4,7 @@ group: Configure ...@@ -4,7 +4,7 @@ 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 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
--- ---
# GitLab managed Terraform State **(FREE)** # GitLab-managed Terraform state **(FREE)**
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0.
...@@ -19,7 +19,7 @@ Using local storage (the default) on clustered deployments of GitLab will result ...@@ -19,7 +19,7 @@ Using local storage (the default) on clustered deployments of GitLab will result
a split state across nodes, making subsequent executions of Terraform inconsistent. a split state across nodes, making subsequent executions of Terraform inconsistent.
You are highly advised to use a remote storage resource in that case. You are highly advised to use a remote storage resource in that case.
The GitLab managed Terraform state backend can store your Terraform state easily and 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, and spares you from setting up additional remote resources like
Amazon S3 or Google Cloud Storage. Its features include: Amazon S3 or Google Cloud Storage. Its features include:
...@@ -216,7 +216,7 @@ recommends encrypting plan output or modifying the project visibility settings. ...@@ -216,7 +216,7 @@ recommends encrypting plan output or modifying the project visibility settings.
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. 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 ## Using a GitLab-managed Terraform state backend as a remote data source
You can use a GitLab-managed Terraform state as a You can use a GitLab-managed Terraform state as a
[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). [Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html).
...@@ -260,13 +260,13 @@ using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. ...@@ -260,13 +260,13 @@ using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`.
You need at least the Developer role in the target project You need at least the Developer role in the target project
to read the Terraform state. to read the Terraform state.
## Migrating to GitLab Managed Terraform state ## Migrating to GitLab-managed Terraform state
Terraform supports copying the state when the backend is changed or Terraform supports copying the state when the backend is changed or
reconfigured. This can be useful if you need to migrate from another backend to reconfigured. This can be useful if you need to migrate from another backend to
GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. GitLab-managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab-managed Terraform state.
The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab-managed Terraform state from a different state storage backend.
### Setting up the initial backend ### Setting up the initial backend
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment