1.2.4.1. Terraform Configuration File

Every Terraform module (including the root module) should contain a terraform block, which we declare in the terraform.tf file.

A typical terraform block looks like this:

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~>2.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~>4.0"
    }
  }
}

The required_version specifies the required version range of the Terraform program needed to run this module, while required_providers lists the required providers and their version ranges. The source field in required_providers is a string representing the provider's source address in the format <namespace>/<name>, such as hashicorp/azurerm. The version field is a string representing the provider's version range, for example ~>4.0 means versions greater than or equal to 4.0 but less than 5.0.

Of course, the terraform block follows the same conventions: required_version as an Argument at the top, and required_providers as a Nested Block below.

1.2.4.1.1. Constraining Provider Major Versions

Terraform and all its providers are required to follow the Semantic Versioning standard for version management. In simple terms:

Version format: MAJOR.MINOR.PATCH, with version increment rules as follows:

MAJOR: when you make incompatible API changes, MINOR: when you add functionality in a backward compatible manner, PATCH: when you make backward compatible bug fixes.

Major version updates often come with breaking changes, and all untested breaking changes are extremely dangerous. Therefore, when declaring provider version constraints, we must constrain the Major Version, for example:

• ~> 2.0
• >= 2.17, < 3.0

The following version constraints are inappropriate:

• >= 2.0 # Could potentially use v3.0 without testing
• =2.17, 2.17 # Overly strict constraints that make it difficult to use this module with other modules

We recommend starting with constraints like ~> 2.0, but once you introduce new functionality that was added in a specific provider version, you should change to a format like >= 2.17, < 3.0 or ~> 2.17, where the lower bound of the version constraint is the version where the new functionality was added.

1.2.4.1.2. Pay Close Attention to Updating the terraform Block

Please note that as module maintainers, we often receive requests from the community and customers to add various new features, new fields, or fix certain bugs. Our code changes sometimes require introducing functionality that wasn't there before. In such cases, we must check which provider version these features were added in, or whether we're using relatively new Terraform features. If so, we need to re-examine the version information defined in our terraform block to ensure it's accurate. Otherwise, it may cause very confusing errors, and users might be frightened by error messages indicating non-existent fields.