Skip to content

Terraform versions

When working with Terraform and Terrateam, you may have different requirements for the Terraform CLI version depending on your project’s needs, module compatibility, or provider constraints. Terrateam allows you to manage and specify Terraform versions at various levels, providing flexibility and control over the version used for each operation.

Specifying Terraform versions

Terrateam supports multiple ways to specify the Terraform CLI version for your operations. The versions are evaluated in the following order, with the first match being used:

1. .terraform-version file in the directory where Terraform is being executed

2. .terraform-version file in the root directory of the repository

3. Custom workflow configuration in .terrateam/config.yml

4. default_tf_version setting in .terrateam/config.yml

Directory-specific .terraform-version file

You can specify the Terraform version for a specific directory by creating a .terraform-version file within that directory. When Terraform is executed in that directory, Terrateam will use the version specified in the file.

For example, if you have a directory structure like this:


The .terraform-version file in the prod/ec2/ directory will determine the Terraform version used for operations in that directory.

Root-level .terraform-version file

If you want to set a default Terraform version for your entire repository, you can create a .terraform-version file in the root directory of your repository. This version will be used for all directories that don’t have a specific .terraform-version file.

Custom workflow configuration

Terrateam’s workflow feature allows you to define custom workflows for different sets of directories or tags. You can specify the Terraform version to be used for each workflow in the .terrateam/config.yml file.

Here’s an example workflow configuration that specifies different Terraform versions for different tag queries:

tags: [ec2, us-east-1, production]
tags: [ec2, us-west-1, production]
- tag_query: ec2 us-east-1 production
terraform_version: 1.2.2
- tag_query: ec2 us-west-1 production
terraform_version: 0.15.5

In this example, directories tagged with ec2, us-east-1, and production will use Terraform version 1.2.2, while directories tagged with ec2, us-west-1, and production will use Terraform version 0.15.5.

Default Terraform version

If none of the above methods specify a Terraform version for a particular directory or operation, Terrateam will fall back to the default_tf_version setting in the .terrateam/config.yml file. You can set the default Terraform version like this:

default_tf_version: 1.2.2

This version will be used for all operations that don’t have a specific version specified through other methods.

Best practices

When managing Terraform versions with Terrateam, consider the following best practices:

  • Explicitly specify a default Terraform version in your repository using the default_tf_version setting. This ensures consistency between runs and avoids unexpected version upgrades.
  • Use directory-specific or workflow-specific versions only when necessary, such as when dealing with version-dependent modules or providers.
We use cookies and similar technologies to provide certain features, enhance the user experience and deliver content that is relevant to your interests. Depending on their purpose, analysis and marketing cookies may be used in addition to technically necessary cookies. By clicking on "Agree and continue", you declare your consent to the use of the aforementioned cookies. Here you can make detailed settings or revoke your consent (in part if necessary) with effect for the future. For further information, please refer to our Privacy Policy .