diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 24203e8d9225ff50c1055e5d991e233729b00c6e..469c65b4c0e06b31ea5d4bd1fbcb6f9352df5ba6 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -109,66 +109,6 @@ You should use a local terminal to run the commands needed for migrating to GitL 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. -## Use your GitLab backend as a remote data source - -You can use a GitLab-managed Terraform state backend as a -[Terraform data source](https://www.terraform.io/language/state/remote-state-data). - -1. In your `main.tf` or other relevant file, declare these variables. Leave the values empty. - - ```hcl - variable "example_remote_state_address" { - type = string - description = "Gitlab remote state file address" - } - - variable "example_username" { - type = string - description = "Gitlab username to query remote state" - } - - variable "example_access_token" { - type = string - description = "GitLab access token to query remote state" - } - ``` - -1. To override the values from the previous step, create a file named `example.auto.tfvars`. This file should **not** be versioned in your project repository. - - ```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. In a `.tf` file, define the data source by using [Terraform input variables](https://www.terraform.io/language/values/variables): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - - - **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 value is your GitLab username. If you are using GitLab CI/CD, this value is `'gitlab-ci-token'`. - - **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this value is the token value (the token must have the **API** scope). - If you are using GitLab CI/CD, this value is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. - -Outputs from the data source can now be referenced in your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. - -To read the Terraform state in the target project, you need at least the Developer role. - ### Set up the initial backend ```shell @@ -264,6 +204,66 @@ 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. +## Use your GitLab backend as a remote data source + +You can use a GitLab-managed Terraform state backend as a +[Terraform data source](https://www.terraform.io/language/state/remote-state-data). + +1. In your `main.tf` or other relevant file, declare these variables. Leave the values empty. + + ```hcl + variable "example_remote_state_address" { + type = string + description = "Gitlab remote state file address" + } + + variable "example_username" { + type = string + description = "Gitlab username to query remote state" + } + + variable "example_access_token" { + type = string + description = "GitLab access token to query remote state" + } + ``` + +1. To override the values from the previous step, create a file named `example.auto.tfvars`. This file should **not** be versioned in your project repository. + + ```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. In a `.tf` file, define the data source by using [Terraform input variables](https://www.terraform.io/language/values/variables): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + + - **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 value is your GitLab username. If you are using GitLab CI/CD, this value is `'gitlab-ci-token'`. + - **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this value is the token value (the token must have the **API** scope). + If you are using GitLab CI/CD, this value is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. + +Outputs from the data source can now be referenced in your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +To read the Terraform state in the target project, you need at least the Developer role. + ## Manage Terraform state files > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8.