2021-11-11 11:23:49 +05:30
---
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/engineering/ux/technical-writing/#assignments
---
2022-04-04 11:22:00 +05:30
# GitLab-managed Terraform state **(FREE)**
2021-11-11 11:23:49 +05:30
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0.
[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/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 ).
WARNING:
Using local storage (the default) on clustered deployments of GitLab will result in
a split state across nodes, making subsequent executions of Terraform inconsistent.
2022-01-26 12:08:38 +05:30
You are highly advised to use a remote storage resource in that case.
2021-11-11 11:23:49 +05:30
2022-04-04 11:22:00 +05:30
The GitLab-managed Terraform state backend can store your Terraform state easily and
2021-11-11 11:23:49 +05:30
securely, and spares you from setting up additional remote resources like
Amazon S3 or Google Cloud Storage. Its features include:
- Versioning of Terraform state files.
- Supporting encryption of the state file both in transit and at rest.
- Locking and unlocking state.
- Remote Terraform plan and apply execution.
2022-01-26 12:08:38 +05:30
A GitLab **administrator** must [set up the Terraform state storage configuration ](../../../administration/terraform_state.md )
2021-11-11 11:23:49 +05:30
before using this feature.
## Permissions for using Terraform
2022-04-04 11:22:00 +05:30
In GitLab version 13.1, at least the Maintainer role was required to use a
GitLab managed Terraform state backend.
In GitLab versions 13.2 and later, at least:
- The Maintainer role is required to lock, unlock, and write to the state (using `terraform apply` ).
- The Developer role is required to read the state (using `terraform plan -lock=false` ).
2021-11-11 11:23:49 +05:30
## Set up GitLab-managed Terraform state
To get started with a GitLab-managed Terraform state, there are two different options:
- [Use a local machine ](#get-started-using-local-development ).
- [Use GitLab CI ](#get-started-using-gitlab-ci ).
Terraform States can be found by navigating to a Project's
**{cloud-gear}** **Infrastructure > Terraform** page.
### Get started using local development
If you plan to only run `terraform plan` and `terraform apply` commands from your
local machine, this is a simple way to get started:
1. Create your project on your GitLab instance.
1. Navigate to **Settings > General** and note your **Project name**
and **Project ID** .
1. Define the Terraform backend in your Terraform project to be:
```hcl
terraform {
backend "http" {
}
}
```
1. Create a [Personal Access Token ](../../profile/personal_access_tokens.md ) with
the `api` scope.
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
2022-04-04 11:22:00 +05:30
Terraform state, and stores that state in your GitLab project. This example
uses `gitlab.com` :
2021-11-11 11:23:49 +05:30
```shell
terraform init \
-backend-config="address=https://gitlab.com/api/v4/projects/< YOUR-PROJECT-ID > /terraform/state/< YOUR-STATE-NAME > " \
-backend-config="lock_address=https://gitlab.com/api/v4/projects/< YOUR-PROJECT-ID > /terraform/state/< YOUR-STATE-NAME > /lock" \
-backend-config="unlock_address=https://gitlab.com/api/v4/projects/< YOUR-PROJECT-ID > /terraform/state/< YOUR-STATE-NAME > /lock" \
-backend-config="username=< YOUR-USERNAME > " \
-backend-config="password=< YOUR-ACCESS-TOKEN > " \
-backend-config="lock_method=POST" \
-backend-config="unlock_method=DELETE" \
-backend-config="retry_wait_min=5"
```
2022-04-04 11:22:00 +05:30
WARNING:
The name of your state can contain only uppercase and lowercase letters, decimal digits,
hyphens, and underscores.
2021-11-11 11:23:49 +05:30
If you already have a GitLab-managed Terraform state, you can use the `terraform init` command
2022-01-26 12:08:38 +05:30
with the pre-populated parameters values:
2021-11-11 11:23:49 +05:30
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Infrastructure > Terraform** .
1. Next to the environment you want to use, select the [Actions menu ](#managing-state-files )
** {ellipsis_v}** and select **Copy Terraform init command** .
You can now run `terraform plan` and `terraform apply` as you normally would.
### Get started using GitLab CI
If you don't want to start with local development, you can also use GitLab CI to
run your `terraform plan` and `terraform apply` commands.
Next, [configure the backend ](#configure-the-backend ).
#### Configure the backend
After executing the `terraform init` command, you must configure the Terraform backend
and the CI YAML file:
1. In your Terraform project, define the [HTTP backend ](https://www.terraform.io/docs/language/settings/backends/http.html )
by adding the following code block in a `.tf` file (such as `backend.tf` ) to
define the remote backend:
```hcl
terraform {
backend "http" {
}
}
```
1. In the root directory of your project repository, configure 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).
```yaml
image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
```
1. In the `.gitlab-ci.yml` file, define some CI/CD 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`
is the name of the Terraform state. Projects may have multiple states, and
this name is arbitrary, so in this example we set it to `example-production`
which corresponds with the directory we're using as our `TF_ROOT` , and we
ensure that the `.terraform` directory is cached between jobs in the pipeline
using a cache key based on the state name (`example-production`):
```yaml
variables:
TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production
TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production
cache:
key: example-production
paths:
- ${TF_ROOT}/.terraform
```
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.
WARNING:
2022-04-04 11:22:00 +05:30
Like any other job artifact, Terraform plan data is viewable by anyone with the Guest role on the repository.
2021-11-11 11:23:49 +05:30
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 in a custom VPC.
2022-04-04 11:22:00 +05:30
## Using a GitLab-managed Terraform state backend as a remote data source
2021-11-11 11:23:49 +05:30
You can use a GitLab-managed Terraform state as a
[Terraform data source ](https://www.terraform.io/docs/language/state/remote-state-data.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/language/values/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/CD variable.
An example setup is shown below:
1. Create a file named `example.auto.tfvars` with the following contents:
```plaintext
example_remote_state_address=https://gitlab.com/api/v4/projects/< TARGET-PROJECT-ID > /terraform/state/< TARGET-STATE-NAME >
example_username=< GitLab username >
example_access_token=< GitLab Personal Access 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 in your Terraform resources
using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>` .
2022-04-04 11:22:00 +05:30
You need at least the Developer role in the target project
2021-11-11 11:23:49 +05:30
to read the Terraform state.
2022-04-04 11:22:00 +05:30
## Migrating to GitLab-managed Terraform state
2021-11-11 11:23:49 +05:30
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
2022-04-04 11:22:00 +05:30
GitLab-managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab-managed Terraform state.
2021-11-11 11:23:49 +05:30
2022-04-04 11:22:00 +05:30
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.
2021-11-11 11:23:49 +05:30
### Setting up the initial backend
```shell
PROJECT_ID="< gitlab-project-id > "
TF_USERNAME="< gitlab-username > "
TF_PASSWORD="< gitlab-personal-access-token > "
TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name"
terraform init \
-backend-config=address=${TF_ADDRESS} \
-backend-config=lock_address=${TF_ADDRESS}/lock \
-backend-config=unlock_address=${TF_ADDRESS}/lock \
-backend-config=username=${TF_USERNAME} \
-backend-config=password=${TF_PASSWORD} \
-backend-config=lock_method=POST \
-backend-config=unlock_method=DELETE \
-backend-config=retry_wait_min=5
```
```plaintext
Initializing the backend...
Successfully configured the backend "http"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing provider plugins...
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
If you ever set or change modules or backend configuration for Terraform,
2022-01-26 12:08:38 +05:30
re-run this command to reinitialize your working directory. If you forget, other
2021-11-11 11:23:49 +05:30
commands will detect it and remind you to do so if necessary.
```
### Changing the backend
Now that `terraform init` has created a `.terraform/` directory that knows where
the old state is, you can tell it about the new location:
```shell
TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name"
terraform init \
2022-04-04 11:22:00 +05:30
-migrate-state \
2021-11-11 11:23:49 +05:30
-backend-config=address=${TF_ADDRESS} \
-backend-config=lock_address=${TF_ADDRESS}/lock \
-backend-config=unlock_address=${TF_ADDRESS}/lock \
-backend-config=username=${TF_USERNAME} \
-backend-config=password=${TF_PASSWORD} \
-backend-config=lock_method=POST \
-backend-config=unlock_method=DELETE \
-backend-config=retry_wait_min=5
```
```plaintext
Initializing the backend...
Backend configuration changed!
Terraform has detected that the configuration specified for the backend
has changed. Terraform will now check for existing state in the backends.
Acquiring state lock. This may take a few moments...
Do you want to copy existing state to the new backend?
Pre-existing state was found while migrating the previous "http" backend to the
newly configured "http" backend. No existing state was found in the newly
configured "http" backend. Do you want to copy this state to the new "http"
backend? Enter "yes" to copy and "no" to start with an empty state.
Enter a value: yes
Successfully configured the backend "http"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing provider plugins...
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
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 in GitLab CI/CD.
## Managing state files
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8.
2022-04-04 11:22:00 +05:30
Users with at least the Developer role can view the
2021-11-11 11:23:49 +05:30
state files attached to a project at **Infrastructure > Terraform** . Users with the
Maintainer role can perform commands on the state files. The user interface
contains these fields:
- **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 copying the `terraform init` command,
downloading, locking, unlocking, or [removing ](#remove-a-state-file ) the state file and versions.
NOTE:
Additional improvements to the
[graphical interface for managing state files ](https://gitlab.com/groups/gitlab-org/-/epics/4563 )
are planned.
2022-04-04 11:22:00 +05:30
## Manage individual Terraform state versions
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207347) in GitLab 13.4.
Individual state versions can be managed using the GitLab REST API.
Users with the [Developer role ](../../permissions.md ) can retrieve state versions using their serial number. To retrieve a version:
```shell
curl --header "Private-Token: < your_access_token > " "https://gitlab.example.com/api/v4/projects/< your_project_id > /terraform/state/< your_state_name > /versions/< version-serial > "
```
Users with the [Maintainer role ](../../permissions.md ) can remove state versions using their serial number. To remove a version:
```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 > /versions/< version-serial > "
```
2021-11-11 11:23:49 +05:30
## Remove a state file
2022-04-04 11:22:00 +05:30
Users with at least the Maintainer role can use the
2021-11-11 11:23:49 +05:30
following options to remove a state file:
- **GitLab UI**: Go to **Infrastructure > 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:
```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 > "
```
- [GitLab GraphQL API ](#remove-a-state-file-with-the-gitlab-graphql-api ).
### 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
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 ).
## Troubleshooting
### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job
When passing `-backend-config=` to `terraform init` , Terraform persists these values inside the plan
cache file. This includes the `password` value.
As a result, to create a plan and later use the same plan in another CI job, you might get the error
`Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN` .
This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job.
As a workaround, use [http backend configuration variables ](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables ) in your CI job,
which is what happens behind the scenes when following the
[Get started using GitLab CI ](#get-started-using-gitlab-ci ) instructions.
2022-04-04 11:22:00 +05:30
### Error: "address": required field is not set
By default, we set `TF_ADDRESS` to `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}` .
If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with the error message
`Error: "address": required field is not set` .
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/#add-a-cicd-variable-to-a-project ) for the job.
1. Set the job's [environment ](../../../ci/yaml/#environment ), matching the environment scope from the previous step.
