Managing multiple versions of Terraform

Large organizations that rely heavily on Terraform often wind up needing to support multiple versions. With the basic Terraform installation you can only install one version on a delegate at time. This means that up until now you would have to run a separate delegate for every version of Terraform that you needed to support.

Now, thanks to asdf this is no longer a problem. asdf is a utility that helps you manage multiple runtime versions of an application with a single CLI tool extendable via plugins. There are other tools similar to this that help you manage versions of a single utility (pyenv, tfenv, rbenv, etc.) but this essentially combines all of that functionality under one roof and, from our experience, is far easier to configure and plays nicely within the Harness ecosystem.

Here we will walk you through installing and configuring asdf on your delegate and using it in your workflows.

Delegate Configuration

First, we’ll setup a new delegate profile that we will install everything on.


#Setup Variables
TERRAFORM_VERSIONS="0.13.6 0.14.0 0.14.5 0.14.8"

# Install dependencies
apt-get update
apt-get install -y git curl unzip

# Install asdf
git clone $ASDF_PATH --branch v0.8.0
echo '. $ASDF_PATH/' >> ~/.bashrc
echo PATH=\$PATH:\$HOME/.asdf/shims:\$HOME/.asdf/bin >> /root/.bashrc
asdf --version 

export PATH=$HOME/.asdf/shims:$HOME/.asdf/bin:$PATH 

# Install and configure Terraform plugin and versions
asdf plugin-add terraform 
for version in $TERRAFORM_VERSIONS; do
  asdf install terraform $version

# Verify Terraform versions
asdf list terraform

# Set a default version on the delegate
echo "terraform 0.14.8" > $HOME/.tool-versions 

Terraform Configuration

Now in your Terraform repository we need to create a new file that asdf will read to determine which version of Terraform your module requires. In the root of your module create a .tools-version file like this:

# .tool-versions
terraform 0.14.0


Running your workflow

Whenever Harness issues a terraform command, the asdf utility will interceps it and read the .tool-versions file to determine which Terraform version to use. If this file is not present in the working directory, then the default $HOME/.tool-versions file is used.

In the example below the default ~/.tool-versions file specified “terraform 0.14.8, but it was overridden by the local repo file .tool-versions that specified the version 0.14.0


In the event that the version of Terraform requested is not installed on the delegate you will see an error like this:

To resolve this just update your delegate profile script to include the new version.

Wrapping up

Hopefully this will make managing not only versions of Terraform on your delegate simpler but many other tools as well.

Special Thanks to Noah Hay at CVent and Robin Elliott at Harness for their contributions to this article.


Nice solution. But I feel like this is something that Harness should manage automatically. At this point terraform stages doesn’t do anything that can’t be replaced with a simple bash script