etsy / terraform-demux

A user-friendly launcher (à la bazelisk) for Terraform.

terraform-demux

A seamless launcher for Terraform.

Installation

Homebrew

Note: installing terraform-demux via Homebrew will automatically create a symlink named terraform.

1. brew tap etsy/terraform-demux https://github.com/etsy/terraform-demux
2. brew install terraform-demux

Manual

1. Grab the latest binary from the releases page
2. Copy it to a location in your $PATH as terraform (or leave it as terraform-demux if you'd like)

Usage

Simply navigate to any folder that contains Terraform configuration and run terraform as you usually would. terraform-demux will attempt to locate the appropriate version constraint by searching in the current working directory and recursively through parent directories. If terraform-demux cannot determine a constraint, it will default to the latest possible version.

Architecture Compatability

terraform-demux supports a native arm64 build that can also run amd64 versions of terraform by specifying the TF_DEMUX_ARCH environment variable. This might be necessary for terraform workspaces that need older terraform versions that do not have arm64 builds, or use older providers that do not have arm64 builds.

It is recommended to set up the following shell alias for handy amd64 invocations:

alias terraform-amd64="TF_DEMUX_ARCH=amd64 terraform-demux"

Enhanced State Operations Control

We highly encourage leveraging native Terraform refactoring blocks whenever feasible, provided your Terraform version supports them. In line with this, we've implemented stricter controls over state operations to enhance security and stability. It's important to note that state operations now require the TF_DEMUX_ALLOW_STATE_COMMANDS environment variable to be set for execution.

Usage Details

• For Terraform 1.1.0 and above: We recomment utilizing Terraform moved block instead terraform state mv command.

• For Terraform 1.5.0 and above: We recomment utilizing Terraform import block instead terraform import command.

• For Terraform 1.7.0 and above: We recomment utilizing Terraform removed block instead terraform state rm command.

However, if necessary, you can still utilize the Terraform CLI to manipulate states. Before proceeding, ensure to set the environment variable TF_DEMUX_ALLOW_STATE_COMMANDS=true to confirm your intent.

Logging

Setting the TF_DEMUX_LOG environment variable to any non-empty value will cause terraform-demux to write out debug logs to stderr.

Cache Directory

terraform-demux keeps a cache of Hashicorp's releases index and downloaded Terraform binaries in the directory returned by os.UserCacheDir, under terraform-demux/ (e.g. ~/Library/Caches/terraform-demux/ on MacOS).