GitLab Terraform helpers

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.

CommandForwards command line?Implicit init?Description
gitlab-terraform applyYesYesRuns terraform apply.
gitlab-terraform destroyYesYesRuns terraform destroy.
gitlab-terraform fmtYesNoRuns terraform fmt in check mode.
gitlab-terraform initYesNot applicableRuns terraform init.
gitlab-terraform planYesYesRuns terraform plan and produces a plan.cache file.
gitlab-terraform plan-jsonNoNoConverts a plan.cache file into a GitLab Terraform report for a MR integration.
gitlab-terraform validateYesYes (without backend)Runs terraform validate.
gitlab-terraform -- <cmd>YesNoRuns terraform <cmd>, even if it is wrapped.
gitlab-terraform <cmd>YesNoRuns terraform <cmd>, if the command is not wrapped.

Generic variables

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

VariableDefaultDescription
TF_ROOTNot setRoot 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/.terraformrcLocation of the Terraform configuration file.
TF_IN_AUTOMATIONtrueSet to true to indicate that Terraform commands are automated.
TF_GITLAB_SOURCEDfalseSet 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.

VariableDefaultDescription
TF_STATE_NAMENot setIf 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_ADDRESSTerraform 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 setUsed as default for TF_HTTP_USERNAME.
TF_PASSWORD$CI_JOB_TOKENUsed 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_METHODPOST 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_METHODDELETE 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_MIN5 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.

VariableDefaultDescription
TF_IMPLICIT_INITtrueIf true, an implicit terraform init runs before the wrapped commands that require it.
TF_INIT_NO_RECONFIGUREfalseIf true, the implicit terraform init runs without -reconfigure.
TF_INIT_FLAGSNot setAdditional 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.

VariableDefault
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 nameTagDescription
stablelatestLatest terraform-images release bundled with the latest Terraform release.
releases/$TERRAFORM_VERSIONlatestLatest terraform-images release bundled with a specific Terraform release.
releases/$TERRAFORM_VERSION$TERRAFORM_IMAGES_VERSIONSpecific terraform-images release bundled with a specific Terraform release.

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