debian-mirror-gitlab/doc/user/infrastructure/iac/gitlab_terraform_helpers.md

stage	group	info
Deploy	Environments	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

GitLab Terraform helpers (FREE)

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.

Related topics

• Terraform CI/CD templates
• Terraform template recipes