tenv

module
v1.0.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2024 License: Apache-2.0

README

Github release Contributors maintenance status


Logo

tenv

Terraform and OpenTofu version manager, written in Go.
· Report Bug · Request Feature

About The Project

Welcome to tenv, a versatile version manager for OpenTofu and Terraform, written in Go. Our tool simplifies the complexity of handling different versions of these powerful tools, ensuring developers and DevOps professionals can focus on what matters most - building and deploying efficiently.

tenv is a successor of tofuenv and tfenv.

Key Features

  • Versatile version management: Easily switch between different versions of Terraform and OpenTofu.
  • Semver 2.0.0 Compatibility: Utilizes go-version for semantic versioning and use the HCL parser to extract required version constraint from OpenTofu/Terraform files.
  • Signature verification: Supports cosign (if present on your machine) and PGP (via gopenpgp) for verifying OpenTofu signatures. However, unstable OpenTofu versions are signed only with cosign (in this case, if cosign is not found tenv will display a warning).
  • Intuitive installation: Simple installation process with Homebrew and manual options.

Table of Contents

Table of Contents
  1. About The Project
  2. Table of contents
  3. Getting Started
  4. Usage
  5. Environment variables
  6. Version files
  7. Technical details
  8. Contributing
  9. Community
  10. Authors
  11. Licence

Getting Started

Prerequisites

If you need to enable cosign checks, install cosign tool via one of the following commands:

MacOS (Homebrew)
brew install cosign
Alpine Linux
apk add cosign
Linux: RPM
LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | jq -r .tag_name | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-${LATEST_VERSION}-1.x86_64.rpm"
sudo rpm -ivh cosign-${LATEST_VERSION}.x86_64.rpm
Linux: dkpg
LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | jq -r .tag_name | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign_${LATEST_VERSION}_amd64.deb"
sudo dpkg -i cosign_${LATEST_VERSION}_amd64.deb

Installation

Automatic Installation
MacOS (Homebrew)
brew tap tofuutils/tap
brew install tenv
Ubuntu
LATEST_VERSION=$(curl --silent https://api.github.com/repos/tofuutils/tenv/releases/latest|jq -r .tag_name)
curl -O -L "https://github.com/tofuutils/tenv/releases/latest/download/tenv_${LATEST_VERSION}_amd64.deb"
sudo dpkg -i "tenv_${LATEST_VERSION}_amd64.deb"

Manual Installation

Get the most recent packaged binaries (.deb, .rpm, .apk, pkg.tar.zst , .zip or .tar.gz format) by visiting the release page. After downloading, unzip the folder and seamlessly integrate it into your system's PATH.

Docker Installation

You can use dockerized version of tenv via the following commands:

TODO

Usage

tenv supports OpenTofu, Terragrunt and Terraform. To manage each binary you can use tenv <tool> <command>. Below is a list of tools and commands that use actual subcommands:

tool env vars description
tofu TOFUENV_ OpenTofu
tf TFENV_ Terraform
tg TG_ Terragrunt
tenv <tool> install [version]
Install a requested version of <tool> (into <TOOL>_ROOT directory from <TOOL>_REMOTE url).

Without a parameter, the version to use is resolved automatically via the relevant <TOOL>_VERSION environment variable or version file (searched in the working directory, user home directory, and <TOOL>_ROOT directory).

Will default to "latest-stable" when no specified version is found.

If a parameter is passed, available options include:

  • an exact Semver 2.0.0 version string to install
  • a version constraint string (checked against versions available at <TOOL>_REMOTE url)
  • latest or latest-stable (checked against versions available at <TOOL>_REMOTE url)
  • latest-allowed or min-required to scan your IAC files to detect which version is maximally allowed or minimally required. See required_version docs.
tenv <tool> install
tenv <tool> install 1.6.0-beta5
tenv <tool> install "~> 1.6.0"
tenv <tool> install latest
tenv <tool> install latest-stable
tenv <tool> install latest-allowed
tenv <tool> install min-required
tenv <tool> use [version]

Switch the default OpenTofu version to use (set in version file ).

tenv use has a --working-dir, -w flag to write version file file in working directory.

Available parameter options:

  • an exact Semver 2.0.0 version string to install
  • a version constraint string (checked against versions available at <TOOL>_REMOTE url)
  • latest or latest-stable (checked against versions available at <TOOL>_REMOTE url)
  • latest-allowed or min-required to scan your IAC files to detect which version is maximally allowed or minimally required. See required_version docs.
tenv <tool> use min-required
tenv <tool> use v1.6.0-beta5
tenv <tool> use latest
tenv <tool> use latest-allowed
tenv <tool> detect

Detect the used version of tool for the working directory.

$ tenv tofu detect
OpenTofu 1.6.0 will be run from this directory.
tenv <tool> reset
Reset used version of tool (remove `.-version` file from `_ROOT`). 
tenv <tool> reset
tenv <tool> uninstall [version]
Uninstall a specific version of OpenTofu (remove it from `_ROOT` directory without interpretation). 
tenv <tool> uninstall v1.6.0-alpha4
tenv <tool> list

List installed tool versions (located in <TOOL>_ROOT directory), sorted in ascending version order.

tenv <tool> list has a --descending, -d flag to sort in descending order.

$ tenv <tool> list
  1.6.0-rc1 
* 1.6.0 (set by /home/dvaumoron/.tenv/.opentofu-version)
tenv <tool> list-remote
List installable tool versions (from `TOOL_REMOTEHappy_REMOTE url), sorted in ascending version order.

tenv <tool> list-remote has a --descending, -d flag to sort in descending order.

tenv <tool> list-remote has a --stable, -s flag to display only stable version.

$ tenv <tool> list-remote
1.6.0-alpha1
1.6.0-alpha2
1.6.0-alpha3
1.6.0-alpha4
1.6.0-alpha5
1.6.0-beta1
1.6.0-beta2
1.6.0-beta3
1.6.0-beta4
1.6.0-beta5
1.6.0-rc1 (installed)
1.6.0 (installed)
tenv help [command]
Help about any command.

You can use --help -h flag instead.

$ tenv help tf detect
Display Terraform current version.

Usage:
  tenv tf detect [flags]

Flags:
  -f, --force-remote         force search on versions available at TFENV_REMOTE url
  -h, --help                 help for detect
  -k, --key-file string      local path to PGP public key file (replace check against remote one)
  -n, --no-install           disable installation of missing version
  -c, --remote-conf string   path to remote configuration file (advanced settings)
  -u, --remote-url string    remote url to install from

Global Flags:
  -r, --root-path string   local path to install versions of OpenTofu and Terraform (default "/home/nonroot/.tenv")
  -v, --verbose            verbose output

$ tenv tofu use -h
Switch the default OpenTofu version to use (set in .opentofu-version file in TOFUENV_ROOT)

Available parameter options:
- an exact Semver 2.0.0 version string to use
- a version constraint string (checked against version available in TOFUENV_ROOT directory)
- latest or latest-stable (checked against version available in TOFUENV_ROOT directory)
- latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

Usage:
  tenv tofu use version [flags]

Flags:
  -f, --force-remote          force search on versions available at TOFUENV_REMOTE url
  -t, --github-token string   GitHub token (increases GitHub REST API rate limits)
  -h, --help                  help for use
  -k, --key-file string       local path to PGP public key file (replace check against remote one)
  -n, --no-install            disable installation of missing version
  -c, --remote-conf string    path to remote configuration file (advanced settings)
  -u, --remote-url string     remote url to install from
  -w, --working-dir           create .opentofu-version file in working directory

Global Flags:
  -r, --root-path string   local path to install versions of OpenTofu and Terraform (default "/home/nonroot/.tenv")
  -v, --verbose            verbose output

Environment variables

tenv commands support multiple groups of environment variables, OpenTofu, Terraform and TerraGrunt.

OpenTofu environment variables

TOFUENV_AUTO_INSTALL
String (Default: true)

If set to true tenv will automatically install a missing OpenTofu version needed (fallback to latest-allowed strategy when no .opentofu-version files are found).

tenv subcommands detect and use support a --no-install, -n disabling flag version.

Example:

Use OpenTofu version 1.6.1 that is not installed, and auto installation is disabled. (-v flag is equivalent to TOFUENV_VERBOSE=true):

$ TOFUENV_AUTO_INSTALL=false tenv use -v 1.6.1
Write 1.6.1 in /home/dvaumoron/.tenv/.opentofu-version
Example:

Use OpenTofu version 1.6.0 that is not installed, and auto installation stay enabled.

$ tenv use -v 1.6.0
Installation of OpenTofu 1.6.0
Write 1.6.0 in /home/dvaumoron/.tenv/.opentofu-version
TOFUENV_FORCE_REMOTE
String (Default: false)

If set to true tenv detection of needed version will skip local check and verify compatibility on remote list.

tenv subcommands detect and use support a --force-remote, -f flag version.

TOFUENV_OPENTOFU_PGP_KEY
String (Default: "")

Allow to specify a local file path to OpenTofu PGP public key, if not present download https://get.opentofu.org/opentofu.asc.

tenv subcommands detect, ìnstall and use support a --key-file, -k flag version.

TOFUENV_REMOTE
String (Default: https://api.github.com/repos/opentofu/opentofu/releases)

To install OpenTofu from a remote other than the default (must comply with Github REST API).

tenv tf subcommands detect, install, list-remote and use support a --remote-url, -u flag version.

TOFUENV_ROOT

String (Default: ${HOME}/.tenv)

The path to a directory where the local OpenTofu versions, Terraform versions and tenv configuration files exist.

tenv support a --root-path, -r flag version.

TOFUENV_GITHUB_TOKEN
String (Default: "")

Allow to specify a GitHub token to increase GitHub Rate limits for the REST API. Useful because OpenTofu binares are downloaded from the OpenTofu GitHub repository.

tenv subcommands detect, install, list-remote and use support a --github-token, -t flag version.

TOFUENV_VERBOSE
String (Default: false)

Active the verbose display of tenv.

tenv support a --verbose, -v flag version.

TOFUENV_TOFU_VERSION
String (Default: "")

If not empty string, this variable overrides OpenTofu version, specified in .opentofu-version files. tenv subcommands install and detect also respects this variable.

e.g. with :

$ tofu version
OpenTofu v1.6.0
on linux_amd64

then :

$ TOFUENV_TOFU_VERSION=1.6.0-rc1 tofu version
OpenTofu v1.6.0-rc1
on linux_amd64

Terraform environment variables

TFENV_AUTO_INSTALL
String (Default: true)

If set to true tenv will automatically install a missing Terraform version needed (fallback to latest-allowed strategy when no .terraform-version files are found).

tenv tf subcommands detect and use support a --no-install, -n disabling flag version.

Example: Use Terraform version 1.6.0-rc1 that is not installed, and auto installation is disabled. (-v flag is equivalent to TFENV_VERBOSE=true)

$ TFENV_AUTO_INSTALL=false tenv tf use -v 1.6.0-rc1
Write 1.6.0-rc1 in /home/dvaumoron/.tenv/.terraform-version

Example: Use Terraform version 1.6.0-rc1 that is not installed, and auto installation stay enabled.

$ tenv tf use -v 1.6.0-rc1
Installation of Terraform 1.6.0-rc1
Write 1.6.0-rc1 in /home/dvaumoron/.tenv/.terraform-version
TFENV_FORCE_REMOTE
String (Default: false)

If set to true tenv detection of needed version will skip local check and verify compatibility on remote list.

tenv tf subcommands detect and use support a --force-remote, -f flag version.

TFENV_HASHICORP_PGP_KEY
String (Default: "")

Allow to specify a local file path to Hashicorp PGP public key, if not present download https://www.hashicorp.com/.well-known/pgp-key.txt.

tenv tf subcommands detect, ìnstall and use support a --key-file, -k flag version.

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

To install Terraform from a remote other than the default (must comply with Hashicorp Release API)

tenv tf subcommands detect, install, list-remote and use support a --remote-url, -u flag version.

TFENV_ROOT
Path (Default: `$HOME/.tenv`)

The path to a directory where the local Terraform versions, OpenTofu versions and tenv configuration files exist.

tenv tf support a --root-path, -r flag version.

TFENV_VERBOSE
String (Default: false)

Active the verbose display of tenv.

tenv tf support a --verbose, -v flag version.

TFENV_TERRAFORM_VERSION
String (Default: "")

If not empty string, this variable overrides Terraform version, specified in .terraform-version files. tenv tf subcommands install and detect also respects this variable.

e.g. with :

$ terraform version
Terraform v1.6.0
on linux_amd64

then :

$ TFENV_TERRAFORM_VERSION=1.6.0-rc1 terraform version
Terraform v1.6.0-rc1
on linux_amd64

Terragrunt environment variables

TG_REMOTE
String (Default: https://api.github.com/repos/gruntwork-io/terragrunt/releases)

To install Terragrunt from a remote other than the default (must comply with Github REST API)

tenv tg subcommands detect, install, list-remote and use support a --remote-url, -u flag version.

TG_VERSION
String (Default: "")

If not empty string, this variable overrides Terragrunt version, specified in .terragrunt-version files. tenv tg subcommands install and detect also respects this variable.

e.g. with :

$ terragrunt -v
terragrunt version v0.54.22

then :

$ TG_VERSION=0.54.1 terragrunt -v
terragrunt version v0.54.1

version files

.opentofu-version file

If you put a .opentofu-version file in the working directory, user home directory, or TOFUENV_ROOT directory, tenv detects it and uses the version written in it. Note, that TOFUENV_TOFU_VERSION can be used to override version specified by .opentofu-version file.

Recognized values (same as tenv use command):

  • an exact Semver 2.0.0 version string to use
  • a version constraint string (checked against versions available in TOFUENV_ROOT directory)
  • latest or latest-stable (checked against versions available in TOFUENV_ROOT directory)
  • latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

See required_version docs.

.terraform-version file

If you put a .terraform-version file in the working directory, user home directory, or TFENV_ROOT directory, tenv detects it and uses the version writtien in it. Note that TFENV_TERRAFORM_VERSION can be used to override version specified by .terraform-version file.

Recognized values (same as tenv use command):

  • an exact Semver 2.0.0 version string to use
  • a version constraint string (checked against versions available in TFENV_ROOT directory)
  • latest or latest-stable (checked against versions available in TFENV_ROOT directory)
  • latest-allowed or min-required to scan your Terraform files to detect which version is maximally allowed or minimally required.

See required_version docs.

.terragrunt-version file

TODO

.tfswitchrc file

TODO

.tgswitchrc file

TODO

.tgswitch.toml file

TODO

terragrunt.hcl file

or terragrunt.hcl.json TODO

.tf files

or .tf.json files TODO

required_version

Will scan through your IAC files and identify the latest allowed version as defined in the relevant files.

Currently the format for Terraform required_version and OpenTofu required_version are very similar, however this may change over time, always refer to docs for the latest format specification.

example:

version = ">= 1.2.0, < 2.0.0"

This would identify the latest version at or above 1.2.0 and below 2.0.0

Technical details

Project binaries

tofu

The tofu command in this project is a proxy to OpenTofu's tofu command managed by tenv. The default resolution strategy is latest-allowed (without TOFUENV_TOFU_VERSION environment variable or .opentofu-version file).

terraform

The terraform command in this project is a proxy to HashiCorp's terraform command managed by tenv. The default resolution strategy is latest-allowed (without TFENV_TERRAFORM_VERSION environment variable or .terraform-version file).

terragrunt

The terragrunt command in this project is a proxy to Gruntwork's terragrunt command managed by tenv. The default resolution strategy is latest-allowed (without TG_VERSION environment variable or .terragrunt-version file).

Terraform support

tenv relies on .terraform-version files, TFENV_HASHICORP_PGP_KEY, TFENV_REMOTE and TFENV_TERRAFORM_VERSION specifically to manage Terraform versions.

tenv tf have the same managing subcommands for Terraform versions (detect, install, list, list-remote, reset, uninstall and use).

tenv checks the Terraform PGP signature (there is no cosign signature available).

Terragrunt support

tenv relies on .terragrunt-version files, TG_REMOTE and TG_VERSION specifically to manage Terragrunt versions.

tenv tg have the same managing subcommands for Terragrunt versions (detect, install, list, list-remote, reset, uninstall and use).

tenv checks the sha256 checksum (there is no signature available).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

Community

Have questions or suggestions? Reach out to us via:

  • GitHub Issues
  • User/Developer Group: Join github community to get update of Harbor's news, features, releases, or to provide suggestion and feedback.
  • Slack: Join tofuutils's community for discussion and ask questions: OpenTofu, channel: #tofuutils

Authors

tenv is based on tofuenv and gotofuenv projects and supported by tofuutils team with help from these awesome contributors:

Star History Chart

LICENSE

The tenv project is distributed under the Apache 2.0 license. See LICENSE.

Directories

Path Synopsis
cmd
tenv
terraform
terragrunt
tofu
pkg
apimsg
check/cosign
check/pgp
check/sha256
download
github
htmlquery
reversecmp
zip
builder
proxy
retriever/html
retriever/terraform
retriever/terragrunt
retriever/tofu
semantic
semantic/finder
semantic/parser/flat
semantic/parser/terragrunt
semantic/parser/tf
semantic/parser/toml

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.