How to Manage Multiple OpenTofu Versions

Nikolai MishinNikolai Mishin
5 min read

tofuenv, an OpenTofu version manager that simplifies installation, switching, and setting specific versions for repositories.

When we work with only one OpenTofu project, we install needed version and don’t have any issues. But when we start to working 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

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

Here OpenTofu version managers are going to help us. tofuenv is a version manager written on bash, which supports OpenTofu management only. Also tenv is a version manager written in Go, that supports both OpenTofu and Terraform. In this article, we will talk about tofuenv, because tenv is still under development and the first version isn't available yet.

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
tofuenv install latest
Installing OpenTofu v1.6.0
Downloading release tarball from https://github.com/opentofu/opentofu/releases/download/v1.6.0/tofu_1.6.0_darwin_amd64.zip
######################################################################################################################################################## 100.0%
Downloading SHA hash file from https://github.com/opentofu/opentofu/releases/download/v1.6.0/tofu_1.6.0_SHA256SUMS
Archive:  /var/folders/nb/k6bv49gd4pd9kyvwwn519_2m0000gn/T/tofuenv_download.XXXXXX.cwpSqQMZ/tofu_1.6.0_darwin_amd64.zip
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0/CHANGELOG.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0/LICENSE  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0/README.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0/tofu  
Installation of tofu v1.6.0 successful. To make this your default version, run 'tofuenv use 1.6.0'

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 in the next tofuenv releases.

tofuenv supports a lot of different types of OpenTofu installation, you can find all available installation options in the tofuenv GitHub.

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
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 a few 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 (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.

This article is updated version of my origin article: https://hackernoon.com/how-to-manage-multiple-opentofu-versions-with-tofuenv

0
Subscribe to my newsletter

Read articles from Nikolai Mishin directly inside your inbox. Subscribe to the newsletter, and don't miss out.

tofuenvtenvTerraformopentofu

Written by

Nikolai Mishin
Nikolai Mishin