@@ -139,10 +139,10 @@ third party ports for other languages like JavaScript, Python, Ruby, and so on.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0.
> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above.
The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/index.md#output-terraform-plan-information-into-a-merge-request). The collected Terraform
The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#setup). The collected Terraform
plan report uploads to GitLab as an artifact and displays
in merge requests. For more information, see
[Output `terraform plan` information into a merge request](../../user/infrastructure/index.md#output-terraform-plan-information-into-a-merge-request).
[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md).
1. In a `before_script`, change to your `TF_ROOT`:
```yaml
before_script:
-cd ${TF_ROOT}
stages:
-prepare
-validate
-build
-deploy
init:
stage:prepare
script:
-gitlab-terraform init
validate:
stage:validate
script:
-gitlab-terraform validate
plan:
stage:build
script:
-gitlab-terraform plan
-gitlab-terraform plan-json
artifacts:
name:plan
paths:
-${TF_ROOT}/plan.cache
reports:
terraform:${TF_ROOT}/plan.json
apply:
stage:deploy
environment:
name:production
script:
-gitlab-terraform apply
dependencies:
-plan
when:manual
only:
-master
```
1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline
runs the `gitlab-terraform init`, `gitlab-terraform validate`, and
`gitlab-terraform plan` commands.
The output from the above `terraform` commands should be viewable in the job logs.
CAUTION: **Caution:**
Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository.
Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan
includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly
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.
## Copy Terraform state between backends
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
GitLab managed Terraform state. It's also useful if you need to change the state
## Output Terraform Plan information into a merge request
Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform),
you can expose details from `terraform plan` runs directly into a merge request widget,
enabling you to see statistics about the resources that Terraform creates,
modifies, or destroys.
## Terraform integration in Merge Requests
Let's explore how to configure a GitLab Terraform Report artifact. You can
either use a pre-built image which includes a `gitlab-terraform` helper as
above, where `gitlab-terraform plan-json` outputs the required artifact, or you
can configure this manually as follows:
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.
1. For simplicity, let's define a few reusable variables to allow us to
refer to these files multiple times:
```yaml
variables:
PLAN:plan.cache
PLAN_JSON:plan.json
```
1. Install `jq`, a
[lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/).
1. Create an alias for a specific `jq` command that parses out the information we
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/#designated-technical-writers
---
# 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.
## Output Terraform Plan information into a merge request
Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform),
you can expose details from `terraform plan` runs directly into a merge request widget,
enabling you to see statistics about the resources that Terraform creates,
modifies, or destroys.
## Setup
NOTE: **Note:**
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.
To manually configure a GitLab Terraform Report artifact requires the following steps:
1. For simplicity, let's define a few reusable variables to allow us to
refer to these files multiple times:
```yaml
variables:
PLAN:plan.cache
PLAN_JSON:plan.json
```
1. Install `jq`, a
[lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/).
1. Create an alias for a specific `jq` command that parses out the information we
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/#designated-technical-writers
---
# GitLab managed Terraform State
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0.
1. In a `before_script`, change to your `TF_ROOT`:
```yaml
before_script:
-cd ${TF_ROOT}
stages:
-prepare
-validate
-build
-deploy
init:
stage:prepare
script:
-gitlab-terraform init
validate:
stage:validate
script:
-gitlab-terraform validate
plan:
stage:build
script:
-gitlab-terraform plan
-gitlab-terraform plan-json
artifacts:
name:plan
paths:
-${TF_ROOT}/plan.cache
reports:
terraform:${TF_ROOT}/plan.json
apply:
stage:deploy
environment:
name:production
script:
-gitlab-terraform apply
dependencies:
-plan
when:manual
only:
-master
```
1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline
runs the `gitlab-terraform init`, `gitlab-terraform validate`, and
`gitlab-terraform plan` commands.
The output from the above `terraform` commands should be viewable in the job logs.
CAUTION: **Caution:**
Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository.
Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan
includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly
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.
## Using a GitLab managed Terraform state backend as a remote data source
You can use a GitLab-managed Terraform state as a
[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html).
To use your existing Terraform state backend as a data source, provide the following details
as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html):
-**address**: The URL of the remote state backend you want to use as a data source.
For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`.
-**username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for
authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`.
-**password**: The password to authenticate with the data source. If you are using a Personal Access Token for
authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable.
An example setup is shown below:
1. Create a file named `example.auto.tfvars` with the following contents:
example_access_token=<GitLab Personal Acceess Token>
```
1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`):
```hcl
data"terraform_remote_state""example"{
backend="http"
config={
address=var.example_remote_state_address
username=var.example_username
password=var.example_access_token
}
}
```
Outputs from the data source can now be referenced within your Terraform resources
using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`.
You need at least [developer access](../permissions.md) to the target project
to read the Terraform state.
## Migrating to GitLab Managed Terraform state
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
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.
