GitLab Terraform helpers

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
caution
The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0. See the deprecation announcement for more information.

GitLab provides two helpers to ease your integration with the GitLab-managed Terraform State.

  • The gitlab-terraform script, which is a thin wrapper around the terraform command.
  • The terraform-images container images, which include the gitlab-terraform script and terraform itself.

Both helpers are maintained in the Terraform Images project.

gitlab-terraform

The gitlab-terraform script is a thin wrapper around the terraform command.

Run gitlab-terraform in a CI/CD pipeline to set up the necessary environment variables to connect to the GitLab-managed Terraform State backend.

Source (but do not run) the helper script

When the gitlab-terraform script is sourced, it configures the environment for a terraform call, but does not actually run terraform. You can source the script when you need to do extra steps to prepare your environment, or to use alternative tools like terragrunt.

To source the script, execute: 

source $(which gitlab-terraform)

Some shells, like BusyBox, do not support the case of another script sourcing your script. For more information, see this Stack Overflow thread. To resolve this issue, you should use bash, zsh or ksh, or source gitlab-terraform directly from the shell.

Commands

You can run gitlab-terraform with the following commands.

Command Forwards command line? Implicit init? Description
gitlab-terraform apply Yes Yes Runs terraform apply.
gitlab-terraform destroy Yes Yes Runs terraform destroy.
gitlab-terraform fmt Yes No Runs terraform fmt in check mode.
gitlab-terraform init Yes Not applicable Runs terraform init.
gitlab-terraform plan Yes Yes Runs terraform plan and produces a plan.cache file.
gitlab-terraform plan-json No No Converts a plan.cache file into a GitLab Terraform report for a MR integration.
gitlab-terraform validate Yes Yes (without backend) Runs terraform validate.
gitlab-terraform -- <cmd> Yes No Runs terraform <cmd>, even if it is wrapped.
gitlab-terraform <cmd> Yes No Runs terraform <cmd>, if the command is not wrapped.

Generic variables

When you run gitlab-terraform, these variables are configured.

Variable Default Description
TF_ROOT Not set Root of the Terraform configuration. If set, it is used as the Terraform -chdir argument value. All read and written files are relative to the given configuration root.
TF_CLI_CONFIG_FILE $HOME/.terraformrc Location of the Terraform configuration file.
TF_IN_AUTOMATION true Set to true to indicate that Terraform commands are automated.
TF_GITLAB_SOURCED false Set to true if gitlab-terraform was sourced.
TF_PLAN_CACHE $TF_ROOT/plan.cache or $PWD/plan.cache Location of the plan cache file. If TF_ROOT is not set, then its path is relative to the current working directory ($PWD).
TF_PLAN_JSON $TF_ROOT/plan.json or $PWD/plan.json Location of the plan JSON file for MR integration. If TF_ROOT is not set, then its path is relative to the current working directory ($PWD).
DEBUG_OUTPUT "false" If set to "true" every statement is logged with set -x.

GitLab-managed Terraform state variables

When you run gitlab-terraform, these variables are configured.

Variable Default Description
TF_STATE_NAME Not set If TF_ADDRESS is not set, and TF_STATE_NAME is provided, then the value of TF_STATE_NAME is used as GitLab-managed Terraform State name.
TF_ADDRESS Terraform State API URL for $TF_STATE_NAME Used as default for TF_HTTP_ADDRESS. Uses TF_STATE_NAME as GitLab-managed Terraform State name by default.
TF_USERNAME $GITLAB_USER_LOGIN or gitlab-ci-token if $TF_PASSWORD is not set Used as default for TF_HTTP_USERNAME.
TF_PASSWORD $CI_JOB_TOKEN Used as default for TF_HTTP_PASSWORD.
TF_HTTP_ADDRESS $TF_ADDRESS Address to the Terraform backend.
TF_HTTP_LOCK_ADDRESS $TF_ADDRESS/lock Address to the Terraform backend lock endpoint.
TF_HTTP_LOCK_METHOD POST Method to use for the Terraform backend lock endpoint.
TF_HTTP_UNLOCK_ADDRESS $TF_ADDRESS/lock Address to the Terraform backend unlock endpoint.
TF_HTTP_UNLOCK_METHOD DELETE Method to use for the Terraform backend unlock endpoint.
TF_HTTP_USERNAME $TF_USERNAME Username to authenticate with the Terraform backend.
TF_HTTP_PASSWORD $TF_PASSWORD Password to authenticate with the Terraform backend.
TF_HTTP_RETRY_WAIT_MIN 5 Minimum time in seconds to wait between HTTP request attempts to the Terraform backend.

Command variables

When you run gitlab-terraform, these variables are configured.

Variable Default Description
TF_IMPLICIT_INIT true If true, an implicit terraform init runs before the wrapped commands that require it.
TF_INIT_NO_RECONFIGURE false If true, the implicit terraform init runs without -reconfigure.
TF_INIT_FLAGS Not set Additional terraform init flags.

Terraform input variables

When you run gitlab-terraform, these Terraform input variables are set automatically. For more information about the default values, see Predefined variables.

Variable Default
TF_VAR_CI_JOB_ID $CI_JOB_ID
TF_VAR_CI_COMMIT_SHA $CI_COMMIT_SHA
TF_VAR_CI_JOB_STAGE $CI_JOB_STAGE
TF_VAR_CI_PROJECT_ID $CI_PROJECT_ID
TF_VAR_CI_PROJECT_NAME $CI_PROJECT_NAME
TF_VAR_CI_PROJECT_NAMESPACE $CI_PROJECT_NAMESPACE
TF_VAR_CI_PROJECT_PATH $CI_PROJECT_PATH
TF_VAR_CI_PROJECT_URL $CI_PROJECT_URL

Terraform images

The gitlab-terraform helper script and terraform itself are provided in container images under registry.gitlab.com/gitlab-org/terraform-images/. You can use these images to configure and manage your integration.

The following images are provided:

Image name Tag Description
stable latest Latest terraform-images release bundled with the latest Terraform release.
releases/$TERRAFORM_VERSION latest Latest terraform-images release bundled with a specific Terraform release.
releases/$TERRAFORM_VERSION $TERRAFORM_IMAGES_VERSION Specific terraform-images release bundled with a specific Terraform release.

For supported combinations, see the terraform-images container registry.