How to Manage Multiple OpenTofu Versions With Tofuenv

Mishin Nikolai — Tue, 09 Jan 2024 21:14:41 +0000

When we work with only one OpenTofu project, we install needed version and don’t have any issues. But when we start to work with multiple projects with different versions of OpenTofu - we are in trouble.

How could this problem be solved earlier? We downloaded the required version of OpenTofu and placed it somewhere in $PATH. After that we renamed the downloaded file and used it something like this:

$ tofu-1.6.0-rc1 -version
OpenTofu v1.6.0-rc1
on darwin_amd64

But this is hard and inconvenient to switch between versions, and we need to remember, which version of OpenTofu has to be used every time.

Here tofuenv is going to help us. tofuenv is an OpenTofu version manager. It allows us to easily install a version, switch between them, and set specific version for specific repository.

Installing tofuenv

tofuenv can be installed to all major operating systems, such as MacOS, Linux and Windows.

We can use brew to install tofuenv to the macos:

$ brew tap tofuutils/tap
$ brew install tofuenv

For linux, we can manually install tofuenv.

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

$ git clone --depth=1 https://github.com/tofuutils/tofuenv.git ~/.tofuenv

Add ~/.tofuenv/bin to your $PATH any way you like:

bash:

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

zsh:

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

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

$ ln -s ~/.tofuenv/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 $PATH or by running . ${HOME}/.profile it will get added to the current shell session's $PATH.

$ mkdir -p ~/.local/bin/ 
$ . ~/.profile
$ ln -s ~/.tofuenv/bin/* ~/.local/bin 
$ which tofuenv

Run tofuenv to verify installation and check available options:

$ tofuenv
tofuenv 1.0.3
Usage: tofuenv <command> [<options>]

Commands:
   install       Install a specific version of OpenTofu
   use           Switch a version to use
   uninstall     Uninstall a specific version of OpenTofu
   list          List all installed versions
   list-remote   List all installable versions
   version-name  Print current version of OpenTofu
   init          Update environment to use tofuenv correctly.
   pin           Write the current active version to ./.opentofu-version

In case of any problems, you may refer to official documentation at tofuenv github repository.

Installing OpenTofu with tofuenv

After we have tofuenv installed, we can install opentofu in the following way.

To install specific version of opentofu use the following command:

$ tofuenv install 1.6.0-rc1

To install latest stable version we can use specific word latest:

$ tofuenv install latest

But due to the fact that at the time of writing this article OpenTofu doesn’t have a stable version, installation via latest word doesn't work.

Anyway, we can install the latest available version of OpenTofu 1.6:

$ tofuenv install latest:1.6
tofuenv install latest:1.6
Installing OpenTofu v1.6.0-rc1
Downloading release tarball from https://github.com/opentofu/opentofu/releases/download/v1.6.0-rc1/tofu_1.6.0-rc1_darwin_amd64.zip
########################################################################################################################################################### 100.0%
Downloading SHA hash file from https://github.com/opentofu/opentofu/releases/download/v1.6.0-rc1/tofu_1.6.0-rc1_SHA256SUMS
Archive:  /var/folders/nb/k6bv49gd4pd9kyvwwn519_2m0000gn/T/tofuenv_download.XXXXXX.fqdxfWoz/tofu_1.6.0-rc1_darwin_amd64.zip
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/CHANGELOG.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/LICENSE  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/README.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/tofu  
Installation of tofu v1.6.0-rc1 successful. To make this your default version, run 'tofuenv use 1.6.0-rc1'

For now the latest available version of OpenTofu 1.6 is 1.6.0-rc1 and for that reason, it was installed by tofuenv.

Note: If shasum is present in the path, tofuenv will verify the download against OpenTofu published sha256 hash. Also GPG signature will be added for verification as soon as OpenTofu will support it.

List OpenTofu versions

With tofuenv we can list locally installed versions and remote versions, which are available for installation.

To list locally installed versions, run the following command:

$ tofuenv list
  1.6.0-alpha1
* 1.6.0-rc1 (set by /usr/local/Cellar/tofuenv/1.0.3/version)

Asterisk marks the version currently used.

To list remote versions, run the following command:

$ tofuenv list-remote
1.6.0-rc1
1.6.0-beta5
1.6.0-beta4
1.6.0-beta3
1.6.0-beta2
1.6.0-beta1
1.6.0-alpha5
1.6.0-alpha4
1.6.0-alpha3
1.6.0-alpha2
1.6.0-alpha1

OpenTofu placed binary in GitHub, and GitHub has a strict rate limiting rule for non-authorised users. Because of this, you can catch the 403 error or "GitHub Rate limits exceeded" error. You can set environment variable TOFUENV_GITHUB_TOKEN with your own GitHub token for authentication against GitHub api and drastically increase the rate limits.

Switch a version to use

To switch between versions, we can use couple of techniques.

First of all, with use use parameter:

$ tofuenv use 1.6.0-alpha1
Switching default version to v1.6.0-alpha1
Default version (when not overridden by .opentofu-version or TOFUENV_TOFU_VERSION) is now: 1.6.0-alpha1

By default, environment variable TOFUENV_AUTO_INSTALL is set to true, and if version 1.6.0-alpha2 of OpenTofu isn’t available locally, it will be downloaded and used automatically:

$ tofuenv use 1.6.0-alpha2
No installed versions of opentofu matched '^1.6.0-alpha2$'. Trying to install a matching version since TOFUENV_AUTO_INSTALL=true
Installing OpenTofu v1.6.0-alpha2
Downloading release tarball from https://github.com/opentofu/opentofu/releases/download/v1.6.0-alpha2/tofu_1.6.0-alpha2_darwin_amd64.zip
########################################################################################################################################################### 100.0%
Downloading SHA hash file from https://github.com/opentofu/opentofu/releases/download/v1.6.0-alpha2/tofu_1.6.0-alpha2_SHA256SUMS
Archive:  /var/folders/nb/k6bv49gd4pd9kyvwwn519_2m0000gn/T/tofuenv_download.XXXXXX.3DyehSoJ/tofu_1.6.0-alpha2_darwin_amd64.zip
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/CHANGELOG.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/LICENSE  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/README.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/tofu  
Installation of tofu v1.6.0-alpha2 successful. To make this your default version, run 'tofuenv use 1.6.0-alpha2'
Switching default version to v1.6.0-alpha2
Default version (when not overridden by .opentofu-version or TOFUENV_TOFU_VERSION) is now: 1.6.0-alpha2

Second option is to use .opentofu-version file. If that file is present in the directory and contains needed version, it will be used automatically:

project1$ tofu -version
OpenTofu v1.6.0-rc1
on darwin_amd64
project1$ cat .opentofu-version 
1.6.0-rc1

project1$ cd ../project2
project2$ tofu -version
OpenTofu v1.6.0-alpha1
on darwin_amd64
project2$ cat .opentofu-version 
1.6.0-alpha1

That file can be created manually, for example:

$ echo 1.6.0-alpha1 > .opentofu-version

Or with using special command pin from tofuenv. That command will save currently used version of opentofu to the file in current directory:

$ tofu -version
OpenTofu v1.6.0-rc1
on darwin_amd64

$ tofuenv pin
Pinned version by writing "1.6.0-rc1" to ./.opentofu-version

Uninstall unneeded versions

For the cleanup of unneeded installed version we can use uninstall command:

$ tofuenv uninstall 1.6.0-rc1
Uninstall OpenTofu v1.6.0-rc1
OpenTofu v1.6.0-rc1 is successfully uninstalled

In conclusion

OpenTofu is a great open-source alternative to Terraform. Our team of tofuenv creators (me, Alexander Sharov and Anastasiia Kozlova) believes that OpenTofu will take decisive place in the market, and tofuenv will help everyone to use it successfully.