Skip to main content
Version: 2.24 (prerelease)

Terraform Overview

Terraform support is in alpha stage

Pants is currently building support for developing and deploying Terraform. Simple use cases might be supported, but many options are missing.

Terraform release progress is tracked in the stability for release issue. Please share feedback for what you need to use Pants with your Terraform modules and deployments by commenting on that issue, opening a new GitHub issue or joining our Slack!

Initial setup​

First, activate the relevant backend in pants.toml:

pants.toml
[GLOBAL]
backend_packages = [
  ...
  "pants.backend.experimental.terraform",
  ...
]

The Terraform backend also needs Python to run Pants's analysers. The setting [python].interpreter_constraints will need to be set.

Terraform needs git to download modules. Many providers and provisioners need additional binaries to be available on the PATH. Currently, you can forward your PATH by adding "PATH" to [download-terraform].extra_env_vars in pants.toml, like:

[download-terraform]
extra_env_vars = [
  "PATH"
]

Adding Terraform targets​

The Terraform backend has 5 target types:

  • terraform_module for Terraform source code
  • terraform_deployment for deployments that can be deployed with the experimental-deploy goal
  • terraform_backend for backend configuration files (typically ending in .tfbackend)
  • terraform_var_files for files to pass with -var-file
  • _terraform_lockfile autogenerated target for lockfiles.

Modules​

The tailor goal will automatically generate terraform_module, terraform_backend, and terraform_var_files targets. Run pants tailor ::. For example:

❯ pants tailor ::
Created src/terraform/root/BUILD:
  - Add terraform_module target root

🚧 terraform_modules must be defined in a BUILD file in the same directory as the module sources

Terraform only uses files in a single directory. The Pants Terraform plugin uses the directory of the BUILD file for this.

Deployments​

terraform_deployments must be manually created. The deployment points to a terraform_module target as its root_module field. This module will be the "root" module that Terraform operations will be run on. Identify backend configs with a terraform_backend target, and var files with a terraform_var_files target. Pants will automatically use terraform_backends and terraform_var_files in the same directory as a terraform_deployment.

terraform_module(name="root")
terraform_deployment(name="prod", root_module=":root")
terraform_backend(name="tfbackend", source="main.tfbackend")
terraform_var_files(name="tfvars")

You can override this behaviour by explicitly specifying these in the dependencies field.

terraform_module(name="root")
terraform_backend(name="prod_backend", source="prod.tfbackend")
terraform_deployment(name="prod", root_module=":root", dependencies=["prod_backend"])
terraform_backend(name="test_backend", source="test.tfbackend")
terraform_deployment(name="test", root_module=":root", dependencies=["test_backend"])

Lockfiles​

Lockfiles will be loaded from the directory of the root module of a deployment, just like with the terraform command. Pants will automatically generate targets for them if they exist.

Pants can generate and update lockfiles with the generate-lockfiles command. Use the target of the terraform_module's address as the resolve name. For example, pants generate-lockfiles --resolve=tf:infrastructure.

terraform_deployment(name="prod", root_module="//tf:infrastructure")

Pants can generate multi-platform lockfiles for Terraform. The setting [download-terraform].platforms uses the same values as Terraform's multi-platform implementation.

[download_terraform]
platforms = ["windows_amd64", "darwin_amd64", "linux_amd64"]

Basic Operations​

Formatting​

Run terraform fmt as part of the fix, fmt, or lint goals.

pants fix ::
[INFO] Completed: pants.backend.terraform.lint.tffmt.tffmt.tffmt_fmt - terraform-fmt made no changes.

✓ terraform-fmt made no changes.

Validate​

Run terraform validate as part of the check goal.

pants check ::
[INFO] Completed: pants.backend.terraform.goals.check.terraform_check - terraform-validate succeeded.
Success! The configuration is valid.

✓ terraform-validate succeeded.

terraform validate isn't valid for all Terraform modules. Some child modules, in particular those using aliased providers, need to have their providers provided by a "root" module. You can opt these modules out of validate by setting skip_terraform_validate=True. For example:

terraform_module(skip_terraform_validate=True)

Deploying​

Terraform deployment support is in alpha stage

Many options and features aren't supported yet. For the local state backend, use an absolute path.

Run terraform apply as part of the experimental-deploy goal. The process is run interactively, so you will be prompted for variables and confirmation as usual.

pants experimental-deploy ::
[INFO] Deploying targets...
--- 8< ---
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes
--- 8< ---
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

✓ testprojects/src/terraform/root:root deployed

You can set auto approve by adding -auto-approve to the [download-terraform].args setting in pants.toml. You can also set it for a single pants invocation with --download-terraform-args='-auto-approve', for example pants experimental-deploy "--download-terraform-args='-auto-approve'".

To run terraform plan, use the --dry-run flag of the experimental-deploy goal.

pants experimental-deploy --dry-run ::