Support .terraform-version for Terraform

[suzuki-shunsuke]

Feature Overview

Support .terraform-version for Terraform.

Why is the feature needed?

• To make it easy to migrate other version managers to aqua.
• To enable developers to use aqua and other version managers

.terraform-version is a common version file for Terraform.

Workaround

No response

Example Code

No response

Note

• Support getting package versions from other files #3061
• Support .node-version for Node.js #3183

[suzuki-shunsuke]

One of issues is where aqua gets the information about Terraform.
aqua usually gets it from registry, but .terraform-version doesn't have any reference to aqua registry.
There are some options.

1. Hardcode to aqua: If aqua-registry setting for Terraform is unstable, every time it is changed we need to release aqua. It's undesirable
2. Hardcode aqua-registry version in aqua: This is really same with the option 1
3. Use the latest installed aqua-registry : This is implicit and depends on the state of the machine. This is not declarative
4. Find aqua.yaml and get aqua-registry from it: This doesn't work if aqua.yaml isn't found

I guess many Terraform version managers don't have the concept registry and accept the option 1.
I think Terraform setting is stable and would not be changed so frequently.

But there are several version files like .terraform-version.

• .terraform-version
• .node-version
• .nvmrc
• etc

Do we need to hardcode all of them into aqua?
It's undesirable.

[suzuki-shunsuke]

• aqua i finds .terraform-version and install Terraform
• If terraform executes, aqua searches aqua.yaml and .terraform-version. If aqua finds .terraform-version first or Terraform isn'f found in aqua.yaml, aqua uses .terraform-version
• aqua list -i outputs terraform if .terraform-version exists

[suzuki-shunsuke]

⚠️ Problems

1. We don't want to force users to use aqua in projects where don't manage Terraform using aqua
2. .terraform-version is complicated. We don't want to support other than x.y.z

1. We don't want to force users to use aqua in projects where don't manage Terraform using aqua

Please see the document too.

For example, Project A manages Terraform using aqua and Project B manages Terraform using tfenv.
Note that we can replace tfenv with other tools which support .terraform-version.

aqua and tfenv requires the environment variable $PATH.

# tfenv
export PATH="$HOME/.tfenv/bin:$PATH"

# aqua
export PATH="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin:$PATH"

If people define PATH of tfenv first, they can't manage Terraform using aqua in Project A.
On the other hand, if they define PATH of aqua first, they can manage Terraform using tfenv in Project B because aqua searches tools in other $PATH if the tool isn't found in aqua.yaml.

This is the current behavior.

But if aqua supports .terraform-version, people can't manage Terraform using tfenv in Project B.
Some people and projects need to manage Terraform using other tools, so this situation is undesirable.

Solution

There are some solutions.

1. Enable users to disable aqua's .terraform-version support by the environment variable
2. Import .terraform-version in aqua.yaml
3. Add the setting to aqua.yaml

1. Enable users to disable aqua's .terraform-version support by the environment variable

e.g.

export AQUA_DISABLE_TERRAFORM_VERSION=true

The drawback is environment variables are global settings unless users use tools such as direnv, so they can't configure by project.

2. Import .terraform-version in aqua.yaml

• Support getting package versions from other files #3061

This is simple solution, but users need to create aqua.yaml.

3. Add the setting to aqua.yaml

e.g. This is just an example.

external_version_files:
  - type: .terraform-version
    enabled: true
packages:

aqua supports .terraform-version in the directory and sub directories where this aqua.yaml exists.

2. .terraform-version is complicated. We don't want to support other than x.y.z

Some tools support .terraform-version, but I guess the format of .terraform-version isn't standardized.

• https://github.com/asdf-community/asdf-hashicorp/blob/22eb1c4a16adcde39aaaf89fbb5d9404a1601fce/bin/parse-legacy-file
• https://github.com/tfutils/tfenv?tab=readme-ov-file#terraform-version

• x.y.z Semver 2.0.0 string specifying the exact version to install
• latest is a syntax to install latest version
• latest: is a syntax to install latest version matching regex (used by grep -e)
• latest-allowed is a syntax to scan your Terraform files to detect which version is maximally allowed.
• min-required is a syntax to scan your Terraform files to detect which version is minimally required.

Some values such as min-required requires to parse Terraform files.
We don't want to implement this.
Furthermore, aqua requires to specify versions strictly, so we don't want to support other than x.y.z.

[jdx]

Here is some insight from having supported some of this functionality in mise. What worked well and what did not.

export AQUA_DISABLE_TERRAFORM_VERSION=true

the rough mise equivalent of this is split between 2 settings:

• MISE_IDIOMATIC_VERSION_FILE=false - disables all idiomatic version files (so none of .node-version, .python-version, .terraform-version, etc
• MISE_IDIOMATIC_VERSION_FILE_DISABLE_TOOLS=terraform - provides a way to disable just one of these tools

these 2 settings has served us well. It works for users and they haven't needed more or had difficulty discovering and understanding them.

.terraform-version is complicated. We don't want to support other than x.y.z

This likely would be an issue. mise has never supported semver so you can't use ^1.0.0 in .terraform-version. However in mise you can use 1 as a "fuzzy-version" which effectively is the same thing. Other tools like .node-version and .python-version behave similarly. In mise I think not supporting semver is fine but that is because users can use an alternate but compatible syntax. Of course in aqua you don't want people to use anything other than full versions so it would be an issue where these files would not work in aqua even though they would work in other tools.

I think there are some ways to mitigate this. For example, in mise, if you define terraform = "1" in mise.toml then it will ignore the value in .terraform-version (so you can have mise-specific overriding). Also AQUA_DISABLE_TERRAFORM_VERSION would be another way people could have an "out".