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:

prod/
  ec2/
    .terraform-version
    main.tf

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:

dirs:
  ec2/us-east-1/production:
    tags: [ec2, us-east-1, production]
  ec2/us-west-1/production:
    tags: [ec2, us-west-1, production]
workflows:
  - 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.