diff options
Diffstat (limited to 'doc/user/infrastructure/iac/terraform_state.md')
| -rw-r--r-- | doc/user/infrastructure/iac/terraform_state.md | 72 |
1 files changed, 54 insertions, 18 deletions
diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index a45ef02622f..8fd38215b04 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -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 --- -# GitLab managed Terraform State **(FREE)** +# GitLab-managed Terraform state **(FREE)** > [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 a split state across nodes, making subsequent executions of Terraform inconsistent. 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 Amazon S3 or Google Cloud Storage. Its features include: @@ -33,11 +33,13 @@ before using this feature. ## Permissions for using Terraform -In GitLab version 13.1, the [Maintainer role](../../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the -[Maintainer role](../../permissions.md) is required to lock, unlock, and write to the state -(using `terraform apply`), while the [Developer role](../../permissions.md) is required to read -the state (using `terraform plan -lock=false`). +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`). ## Set up GitLab-managed Terraform state @@ -72,9 +74,8 @@ 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 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`: + Terraform state, and stores that state in your GitLab project. This example + uses `gitlab.com`: ```shell terraform init \ @@ -88,6 +89,10 @@ local machine, this is a simple way to get started: -backend-config="retry_wait_min=5" ``` + WARNING: + The name of your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. + If you already have a GitLab-managed Terraform state, you can use the `terraform init` command with the pre-populated parameters values: @@ -205,7 +210,7 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. WARNING: -Like any other job artifact, Terraform plan data is viewable by anyone with the Guest [role](../../permissions.md) on the repository. +Like any other job artifact, Terraform plan data is viewable by anyone with the Guest role on 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. @@ -214,7 +219,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. -## 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 [Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). @@ -255,16 +260,16 @@ An example setup is shown below: 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 the [Developer role](../../permissions.md) in the target project +You need at least the Developer role in the target project 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 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 @@ -313,6 +318,7 @@ the old state is, you can tell it about the new location: TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" terraform init \ + -migrate-state \ -backend-config=address=${TF_ADDRESS} \ -backend-config=lock_address=${TF_ADDRESS}/lock \ -backend-config=unlock_address=${TF_ADDRESS}/lock \ @@ -364,7 +370,7 @@ location. You can then go back to running it in GitLab CI/CD. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. -Users with Developer and greater [permissions](../../permissions.md) can view the +Users with at least the Developer role can view the 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: @@ -383,9 +389,27 @@ Additional improvements to the [graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) are planned. +## 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>" +``` + ## Remove a state file -Users with Maintainer and greater [permissions](../../permissions.md) can use the +Users with at least the Maintainer role can use the following options to remove a state file: - **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, @@ -444,3 +468,15 @@ This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration 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. + +### 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. |