Repository files navigation

Terraform version manager inspired byrbenv

Currently tfenv supports the following OSes

• macOS
  • 64bit
  • Arm (Apple Silicon)
• Linux
  • 64bit
  • Arm
• Windows (64bit) - only tested in git-bash - currently presumed failing due to symlink issues in git-bash

Install via Homebrew

brew install tfenv

Install via Arch User Repository (AUR)

yay --sync tfenv

Install via puppet

Using puppet modulesergk-tfenv

include ::tfenv

1. Check out tfenv into any path (here is${HOME}/.tfenv)

git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv

2. Add~/.tfenv/bin to your$PATH any way you like

bash:

echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bash_profile

zsh:

$echo'export PATH="$HOME/.tfenv/bin:$PATH"'>>~/.zprofile

For WSL users:

echo'export PATH=$PATH:$HOME/.tfenv/bin'>>~/.bashrc

OR you can make symlinks fortfenv/bin/* scripts into a path that is already added to your$PATH (e.g./usr/local/bin)OSX/Linux Only!

ln -s ~/.tfenv/bin/* /usr/local/bin

On Ubuntu/Debian touching/usr/local/bin might require sudo access, but you can create${HOME}/bin or${HOME}/.local/bin and on next login it will get added to the session$PATHor by running. ${HOME}/.profile it will get added to the current shell session's$PATH.

mkdir -p ~/.local/bin/. ~/.profileln -s ~/.tfenv/bin/* ~/.local/binwhich tfenv

Install a specific version of Terraform.

If no parameter is passed, the version to use is resolved automatically viaTFENV_TERRAFORM_VERSION environment variable or.terraform-version files, in that order of precedence, i.e. TFENV_TERRAFORM_VERSION, then .terraform-version. The default is 'latest' if none are found.

If a parameter is passed, available options:

• x.y.zSemver 2.0.0 string specifying the exact version to install
• latest is a syntax to install latest version
• latest:<regex> is a syntax to install latest version matching regex (used by grep -e)
• latest-allowed is a syntax to scan your Terraform files to detect which version is maximally allowed.
• min-required is a syntax to scan your Terraform files to detect which version is minimally required.

Seerequired_version docs. Alsosee min-required & latest-allowed section below.

$tfenv install$tfenv install 0.7.0$tfenv install latest$tfenv install latest:^0.8$tfenv install latest-allowed$tfenv install min-required

Ifshasum is present in the path, tfenv will verify the download against Hashicorp's published sha256 hash.Ifkeybase is available in the path it will also verify the signature for those published hashes using Hashicorp's published public key.

You can opt-in to using GnuPG tools for PGP signature verification if keybase is not available:

WhereTFENV_INSTALL_DIR is for example,~/.tfenv or/usr/local/Cellar/tfenv/<version>

echo 'trust-tfenv: yes' > ${TFENV_INSTALL_DIR}/use-gpgvtfenv install

Thetrust-tfenv directive means that verification uses a copy of theHashicorp OpenPGP key found in the tfenv repository. Skipping that directivemeans that the Hashicorp key must be in the existing default trusted keys.Use the file${TFENV_INSTALL_DIR}/use-gnupg to instead invoke the fullgpg tool andsee web-of-trust status; beware that a lack of trust path will not cause avalidation failure.

If you use a.terraform-version file,tfenv install (no argument) will install the version written in it.

Please note that we don't do semantic version range parsing but use first ever found version as the candidate for minimally required one. It is up to the user to keep the definition reasonable. I.e.

// this will detect 0.12.3terraform {required_version="<0.12.3, >= 0.10.0"}

// this will detect 0.10.8 (the latest 0.10.x release)terraform {required_version="~> 0.10.0, <0.12.3"}

String (Default:amd64)

Specify architecture. Architecture other than the default amd64 can be specified with theTFENV_ARCH environment variable

Note: Default changes toarm64 for versions that have arm64 builds available when$(uname -m) matchesaarch64* | arm64*

TFENV_ARCH=arm64 tfenv install 0.7.9

String (Default: true)

Should tfenv automatically install terraform if the version specified by defaults or a .terraform-version file is not currently installed.

TFENV_AUTO_INSTALL=false terraform plan

terraform use <version that is not yet installed>

Integer (Default: 2)

Set the mechanism used for displaying download progress when downloading terraform versions from the remote server.

• 2: v1 Behaviour: Pass-# to curl
• 1: Use curl default
• 0: Pass-s to curl

Integer (Default: 0)

Set the debug level for TFENV.

• 0: No debug output
• 1: Simple debug output
• 2: Extended debug output, with source file names and interactive debug shells on error
• 3: Debug level 2 + Bash execution tracing

String (Default:https://releases.hashicorp.com)

To install from a remote other than the default

TFENV_REMOTE=https://example.jfrog.io/artifactory/hashicorp

Integer (Default: 0)

When using a custom remote, such as Artifactory, instead of the Hashicorp servers,the list of terraform versions returned by the curl of the remote directory may be inverted.In this case thelatest functionality will not work as expected because it expects theversions to be listed in order of release date from newest to oldest. If your remoteis instead providing a list that is oldes-first, setTFENV_REVERSE_REMOTE=1 andfunctionality will be restored.

TFENV_REVERSE_REMOTE=1 tfenv list-remote

Path (Default:$TFENV_ROOT)

The path to a directory where the local terraform versions and configuration files exist.

TFENV_CONFIG_DIR="$XDG_CONFIG_HOME/tfenv"

String (Default: "")

If not empty string, this variable overrides Terraform version, specified in.terraform-version files.latest andlatest:<regex> syntax are also supported.tfenv install andtfenv use command also respects this variable.

e.g.

TFENV_TERRAFORM_VERSION=latest:^0.11. terraform --version

String (Default: "")

If not empty string, this variable specifies the credentials file used to access the remote location (useful if used in conjunction with TFENV_REMOTE).

e.g.

TFENV_NETRC_PATH="$PWD/.netrc.tfenv"

Integer (Default: 1)

To disable colouring of console output, set to 0.

String (Default: +%F %T)

The display format for the date as passed to thedate binary to generate a datestamp used as a prefix to:

• FILE type log file lines.
• Each console output line whenBASHLOG_EXTRA=1

Integer (Default: 0)

By default, console output from tfenv does not print a date stamp or log severity.

To enable this functionality, making normal output equivalent to FILE log output, set to 1.

Integer (Default: 0)

Set to 1 to enable plain text logging to file (FILE type logging).

The default path for log files is defined by /tmp/$(basename $0).logEach executable logs to its own file.

e.g.

BASHLOG_FILE=1 tfenv use latest

will log to/tmp/tfenv-use.log

String (Default: /tmp/$(basename ${0}).log)

To specify a single file as the target for all FILE type logging regardless of the executing script.

String (Default: "")

BE CAREFUL - MISUSE WILL DESTROY EVERYTHING YOU EVER LOVED

This variable allows you to pass a string containing a command that will be executed usingeval in order to produce a prefix to each console output line, and each FILE type log entry.

e.g.

BASHLOG_I_PROMISE_TO_BE_CAREFUL_CUSTOM_EVAL_PREFIX='echo "${$$} "'

will prefix every log line with the calling process' PID.

Integer (Default: 0)

Set to 1 to enable JSON logging to file (JSON type logging).

The default path for log files is defined by /tmp/$(basename $0).log.jsonEach executable logs to its own file.

e.g.

BASHLOG_JSON=1 tfenv use latest

will log in JSON format to/tmp/tfenv-use.log.json

JSON log content:

{"timestamp":"<date +%s>","level":"<log-level>","message":"<log-content>"}

String (Default: /tmp/$(basename ${0}).log.json)

To specify a single file as the target for all JSON type logging regardless of the executing script.

Integer (Default: 0)

To log to syslog using thelogger binary, set this to 1.

The basic functionality is thus:

local tag="${BASHLOG_SYSLOG_TAG:-$(basename "${0}")}";local facility="${BASHLOG_SYSLOG_FACILITY:-local0}";local pid="${$}";logger --id="${pid}" -t "${tag}" -p "${facility}.${severity}" "${syslog_line}"

String (Default: local0)

The syslog facility to specify when using SYSLOG type logging.

String (Default: $(basename $0))

The syslog tag to specify when using SYSLOG type logging.

Defaults to the PID of the calling process.

Switch a version to use

If no parameter is passed, the version to use is resolved automatically via.terraform-version files orTFENV_TERRAFORM_VERSION environment variable (TFENV_TERRAFORM_VERSION takes precedence), defaulting to 'latest' if none are found.

latest is a syntax to use the latest installed version

latest:<regex> is a syntax to use latest installed version matching regex (used by grep -e)

min-required will switch to the version minimally required by your terraform sources (see abovetfenv install)

$tfenv use$tfenv use min-required$tfenv use 0.7.0$tfenv use latest$tfenv use latest:^0.8

Note:tfenv use latest ortfenv use latest:<regex> will find the latest matching version that is already installed. If no matching versions are installed, and TFENV_AUTO_INSTALL is set totrue (which is the default) the the latest matching version in the remote repository will be installed and used.

Uninstall a specific version of Terraformlatest is a syntax to uninstall latest versionlatest:<regex> is a syntax to uninstall latest version matching regex (used by grep -e)

$tfenv uninstall 0.7.0$tfenv uninstall latest$tfenv uninstall latest:^0.8

List installed versions

$tfenv list* 0.10.7 (set by /opt/tfenv/version)  0.9.0-beta2  0.8.8  0.8.4  0.7.0  0.7.0-rc4  0.6.16  0.6.2  0.6.1

List installable versions

$tfenv list-remote0.9.0-beta20.9.0-beta10.8.80.8.70.8.60.8.50.8.40.8.30.8.20.8.10.8.00.8.0-rc30.8.0-rc20.8.0-rc10.8.0-beta20.8.0-beta10.7.130.7.12...

If you put a.terraform-version file on your project root, or in your home directory, tfenv detects it and uses the version written in it. If the version islatest orlatest:<regex>, the latest matching version currently installed will be selected.

Note, thatTFENV_TERRAFORM_VERSION environment variable can be used to override version, specified by.terraform-version file.

$cat .terraform-version0.6.16$terraform versionTerraform v0.6.16Your version of Terraform is out of date! The latest versionis 0.7.3. You can update by downloading from www.terraform.io$echo 0.7.3> .terraform-version$terraform versionTerraform v0.7.3$echo latest:^0.8> .terraform-version$terraform versionTerraform v0.8.8$TFENV_TERRAFORM_VERSION=0.7.3 terraform --versionTerraform v0.7.3

git --git-dir=~/.tfenv/.git pull

rm -rf /some/path/to/tfenv

• tfenv itself
• rbenv
  • tfenv partially uses rbenv's source code