Manage multiple Terraform versions with tfenv

In my Terraform for Kubernetes beginners article, I used Terraform 11, and in an upcoming article, I'll cover upgrading from Terraform 11 to 12. To prepare for that, in this article, I'll show you how to use tfenv, a tool that makes it much easier to convert from one version to another, as well as to manage multiple Terraform versions in your work environment.

Install tfenv

Many coding languages have tools that allow you to go back and forth between versions based on environmental rules. One example (which tfenv is based on) is rbenv, which allows you to choose which version of Ruby you want to work with.

tfenv works on Linux, macOS, and Windows; I'll cover the Linux installation using Ubuntu 18.04, but the tool's GitHub repository has installation instructions for the other operating systems.

The Linux installation uses some Git commands (check out the intro to Git series if you're not already familiar with it).

First, create a .tfenv folder in your ${HOME} directory:

jess@Athena:~$ mkdir .tfenv

Clone the tfenv repository:

jess@Athena:~$ git clone https://github.com/tfutils/tfenv.git ~/.tfenv
Cloning into '/home/jess/.tfenv'...
remote: Enumerating objects: 21, done.
remote: Counting objects: 100% (21/21), done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 1105 (delta 8), reused 10 (delta 2), pack-reused 1084
Receiving objects: 100% (1105/1105), 216.01 KiB | 2.84 MiB/s, done.
Resolving deltas: 100% (703/703), done.

If you prefer Homebrew, you can use:

$ brew install tfenv

Export your path into your Bash profile:

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

If you want to use just the base commands for Ubuntu/Debian-based systems, there is another option that makes things a little easier. After doing the clone in the .tfenv directory, set your profile to put the tfenv command into your profile in your next session:

jess@Athena:~/.tfenv$ . ~/.profile

Once the profile is set, you can symlink your directory to your .local/bin directory to make tfenv an executable binary:

jess@Athena:~/.tfenv$ ln -s ~/.tfenv/bin/* ~/.local/bin

Run the which command, and you should see tfenv's location:

jess@Athena:~/.tfenv$ which tfenv
/home/jess/.local/bin/tfenv

How to use tfenv

Now that everything is installed, check out what commands are available:

jess@Athena:~$ tfenv
tfenv 2.0.0-37-g0494129
Usage: tfenv <command> [<options>]

Commands:
   install   	Install a specific version of Terraform
   use       	Switch a version to use
   uninstall 	Uninstall a specific version of Terraform
   list      	List all installed versions
   list-remote  List all installable versions

As you can see, it's a pretty straightforward tool that enables you to install and uninstall Terraform versions as needed.

Before you decide what to install, check which versions are available. This is a small snippet, as the list is about a mile long:

jess@Athena:~$ tfenv list-remote
0.14.0-beta1
0.14.0-alpha20201007
0.14.0-alpha20200923
0.14.0-alpha20200910
0.13.5
0.13.4
0.13.3
0.13.2
0.13.1
0.13.0
0.13.0-rc1
0.13.0-beta3
0.13.0-beta2
0.13.0-beta1
0.12.29
0.12.28
0.12.27

Install Terraform versions

To install the latest version of Terraform:

jess@Athena:~$ tfenv install latest
Installing Terraform v0.13.5
Downloading release tarball from https://releases.hashicorp.com/terraform/0.13.5/terraform_0.13.5_linux_amd64.zip
###################################################################################################################################################################################### 100.0%
Downloading SHA hash file from https://releases.hashicorp.com/terraform/0.13.5/terraform_0.13.5_SHA256SUMS
No keybase install found, skipping OpenPGP signature verification
Archive:  tfenv_download.N3bzZ2/terraform_0.13.5_linux_amd64.zip
  inflating: /home/jess/.tfenv/versions/0.13.5/terraform  
Installation of terraform v0.13.5 successful. To make this your default version, run 'tfenv use 0.13.5'

To install a specific Terraform version (in this case, 0.12.29):

jess@Athena:~$ tfenv install 0.12.29
Installing Terraform v0.12.29
Downloading release tarball from https://releases.hashicorp.com/terraform/0.12.29/terraform_0.12.29_linux_amd64.zip
###################################################################################################################################################################################### 100.0%
Downloading SHA hash file from https://releases.hashicorp.com/terraform/0.12.29/terraform_0.12.29_SHA256SUMS
No keybase install found, skipping OpenPGP signature verification
Archive:  tfenv_download.1YFOLh/terraform_0.12.29_linux_amd64.zip
  inflating: /home/jess/.tfenv/versions/0.12.29/terraform  
Installation of terraform v0.12.29 successful. To make this your default version, run 'tfenv use 0.12.29'

Finally, to install the latest version of Terraform 0.11:

jess@Athena:~$ tfenv install latest:^0.11
Installing Terraform v0.11.15-oci
Downloading release tarball from https://releases.hashicorp.com/terraform/0.11.15-oci/terraform_0.11.15-oci_linux_amd64.zip
###################################################################################################################################################################################### 100.0%
Downloading SHA hash file from https://releases.hashicorp.com/terraform/0.11.15-oci/terraform_0.11.15-oci_SHA256SUMS
No keybase install found, skipping OpenPGP signature verification
Archive:  tfenv_download.8OxQ8k/terraform_0.11.15-oci_linux_amd64.zip
  inflating: /home/jess/.tfenv/versions/0.11.15-oci/terraform  
Installation of terraform v0.11.15-oci successful. To make this your default version, run 'tfenv use 0.11.15-oci'

That was simple, and now you can put them to use!

Change Terraform versions

Once you have installed several versions of Terraform, you can pick one to use. First, find out your options by listing the installed versions:

jess@Athena:~$ tfenv list
  0.13.5 (set by /home/jess/.tfenv/version)
  0.12.29
  0.11.15-oci

By default, tfenv chooses the most up-to-date version of Terraform you have installed. Find out the default by running the tfenv use command:

jess@Athena:~$ tfenv use
Switching default version to v0.13.5
Switching completed

jess@Athena:~$ terraform --version
Terraform v0.13.5

But what if you need to use an older version? This example switches to the oldest version I have installed:

jess@Athena:~$ tfenv use 0.11.15-oci
Switching default version to v0.11.15-oci
Switching completed

jess@Athena:~$ terraform -version
Terraform v0.11.15-oci

Your version of Terraform is out of date! The latest version
is 0.13.5. You can update by downloading from www.terraform.io/downloads.html

It's easy as pie! Just run the list command and use the naming convention provided.

Uninstall Terraform versions

If you have a version of Terraform you don't want or need any more, you can remove it with the uninstall command. For example, I don't need Terraform version 0.13:

jess@Athena:~$ tfenv uninstall 0.13.5
Uninstall Terraform v0.13.5
Terraform v0.13.5 is successfully uninstalled

To confirm it's no longer installed:

jess@Athena:~$ tfenv list
  0.12.29
  0.11.15-oci

Final thoughts

The tfenv tool is great for many reasons. If you need to update from one version of Terraform to another, this is one of the faster ways to upgrade and test the outcome. If your environment has things running on several Terraform versions, it's easy to switch back and forth as needed. If you use Terraform, try tfenv and see how it can transform your environment.