diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template index f5fb66a0ba0e61d8073d191a3c0c4f87f07458f7..d0fc0ec2a10b462ca9295da9cabe8e0ba12f3236 100644 --- a/.gitlab/README.md.template +++ b/.gitlab/README.md.template @@ -97,6 +97,34 @@ fmt: ... ``` +### GitLab-managed Terraform state backend + +This component - by leveraging the [`gitlab-tofu`](src/gitlab-tofu.sh) CLI internally - +automatically configures the +[GitLab-managed Terraform state backend](https://docs.gitlab.com/ee/user/infrastructure/iac/terraform_state.html). +The only thing required is that the Terraform configuration must specify an empty `http` backend block, like this: + +```hcl +terraform { + backend "http" {} +} +``` + +We recommend having a dedicated `backend.tf` file inside your `root_dir` +with the aforementioned block. + +### Access to Terraform Module Registry + +Similar to automatically configuring the [GitLab-managed Terraform state backend] +the component also sets up credentials to authenticate with the +[Terraform Module Registry](https://docs.gitlab.com/ee/user/packages/terraform_module_registry/) +of the project the pipeline runs in. +It basically sets the `TF_TOKEN_<domain>` variable to the `$CI_JOB_TOKEN`, where `<domain>` is +the GitLab instance domain, for example for GitLab.com this would set `TF_TOKEN_gitlab_com` to +the `$CI_JOB_TOKEN`. However, it'll only do so if the variable is not already provided. +Thus, if you want to authenticate differently or to another Terraform Module Registry, +you may just provide the `TF_TOKEN_<domain>` variable yourself, e.g. via CI/CD variables. + ### Opinionated Templates This component repository also provides some templates that may often be used, diff --git a/README.md b/README.md index 36e7bb75ae17c3a89ae9807dffc946bbb193077d..07cfffb817385b08062be39b1e325018be2e1db4 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,34 @@ fmt: ... ``` +### GitLab-managed Terraform state backend + +This component - by leveraging the [`gitlab-tofu`](src/gitlab-tofu.sh) CLI internally - +automatically configures the +[GitLab-managed Terraform state backend](https://docs.gitlab.com/ee/user/infrastructure/iac/terraform_state.html). +The only thing required is that the Terraform configuration must specify an empty `http` backend block, like this: + +```hcl +terraform { + backend "http" {} +} +``` + +We recommend having a dedicated `backend.tf` file inside your `root_dir` +with the aforementioned block. + +### Access to Terraform Module Registry + +Similar to automatically configuring the [GitLab-managed Terraform state backend] +the component also sets up credentials to authenticate with the +[Terraform Module Registry](https://docs.gitlab.com/ee/user/packages/terraform_module_registry/) +of the project the pipeline runs in. +It basically sets the `TF_TOKEN_<domain>` variable to the `$CI_JOB_TOKEN`, where `<domain>` is +the GitLab instance domain, for example for GitLab.com this would set `TF_TOKEN_gitlab_com` to +the `$CI_JOB_TOKEN`. However, it'll only do so if the variable is not already provided. +Thus, if you want to authenticate differently or to another Terraform Module Registry, +you may just provide the `TF_TOKEN_<domain>` variable yourself, e.g. via CI/CD variables. + ### Opinionated Templates This component repository also provides some templates that may often be used,