See origin...ID: TFNFR6 - Category: Code Style - Resource & Data Order
For the definition of resources in the same file, the resources be depended on SHOULD come first, after them are the resources depending on others.
Resources that have dependencies SHOULD be defined close to each other.
See origin...ID: TFNFR7 - Category: Code Style - count & for_each Use
We can use count and for_each to deploy multiple resources, but the improper use of count can lead to anti pattern.
You can use count to create some kind of resources under certain conditions, for example:
resource "azapi_resource" "network_security_group" {
count = local.create_new_security_group ? 1 : 0
type = "Microsoft.Network/networkSecurityGroups@2023-11-01"
name = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
parent_id = var.parent_id
location = local.location
tags = var.new_network_security_group_tags
body = {
properties = {}
}
response_export_values = []
}
The module’s owners MUST use map(xxx) or set(xxx) as resource’s for_each collection, the map’s key or set’s element MUST be static literals.
Good example:
resource "azapi_resource" "subnet_pair" {
for_each = var.subnet_map // `map(string)`, when user call this module, it could be: `{ "subnet0": "subnet0" }`, or `{ "subnet0": azapi_resource.subnet0.name }`
type = "Microsoft.Network/virtualNetworks/subnets@2023-11-01"
name = "${each.value}-pair"
parent_id = azapi_resource.virtual_network.id
body = {
properties = {
addressPrefixes = ["10.0.1.0/24"]
}
}
response_export_values = []
}
Bad example:
resource "azapi_resource" "subnet_pair" {
for_each = var.subnet_name_set // `set(string)`, when user use `toset([azapi_resource.subnet0.name])`, it would cause an error.
type = "Microsoft.Network/virtualNetworks/subnets@2023-11-01"
name = "${each.value}-pair"
parent_id = azapi_resource.virtual_network.id
body = {
properties = {
addressPrefixes = ["10.0.1.0/24"]
}
}
response_export_values = []
}
See origin...ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders
There are 3 types of assignment statements in a resource or data block: argument, meta-argument and nested block. The argument assignment statement is a parameter followed by =:
location = azapi_resource.example.location
or:
tags = {
environment = "Production"
}
Nested block is a assignment statement of parameter followed by {} block:
subnet {
name = "subnet1"
address_prefix = "10.0.1.0/24"
}
Meta-arguments are assignment statements can be declared by all resource or data blocks. They are:
countdepends_onfor_eachlifecycleprovider
The order of declarations within resource or data blocks is:
All the meta-arguments SHOULD be declared on the top of resource or data blocks in the following order:
providercountfor_each
Then followed by:
- required arguments
- optional arguments
- required nested blocks
- optional nested blocks
All ranked in alphabetical order.
These meta-arguments SHOULD be declared at the bottom of a resource block with the following order:
depends_onlifecycle
The parameters of lifecycle block SHOULD show up in the following order:
create_before_destroyignore_changesprevent_destroy
parameters under depends_on and ignore_changes are ranked in alphabetical order.
Meta-arguments, arguments and nested blocked are separated by blank lines.
dynamic nested blocks are ranked by the name comes after dynamic, for example:
dynamic "linux_profile" {
for_each = var.admin_username == null ? [] : ["linux_profile"]
content {
admin_username = var.admin_username
ssh_key {
key_data = replace(coalesce(var.public_ssh_key, tls_private_key.ssh[0].public_key_openssh), "\n", "")
}
}
}
This dynamic block will be ranked as a block named linux_profile.
Code within a nested block will also be ranked following the rules above.
PS: You can use avmfix tool to reformat your code automatically.
See origin...ID: TFNFR9 - Category: Code Style - Module Block Order
The meta-arguments below SHOULD be declared on the top of a module block with the following order:
sourceversioncountfor_each
blank lines will be used to separate them.
After them will be required arguments, optional arguments, all ranked in alphabetical order.
These meta-arguments below SHOULD be declared on the bottom of a resource block in the following order:
depends_onproviders
Arguments and meta-arguments SHOULD be separated by blank lines.
See origin...ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes
The ignore_changes attribute MUST NOT be enclosed in double quotes.
Good example:
lifecycle {
ignore_changes = [
tags,
]
}
Bad example:
lifecycle {
ignore_changes = [
"tags",
]
}
See origin...ID: TFNFR11 - Category: Code Style - Null Comparison Toggle
Sometimes we need to ensure that the resources created are compliant to some rules at a minimum extent, for example a subnet has to be connected to at least one network_security_group. The user SHOULD pass in a security_group_id and ask us to make a connection to an existing security_group, or want us to create a new security group.
Intuitively, we will define it like this:
variable "security_group_id" {
type: string
}
resource "azapi_resource" "network_security_group" {
count = var.security_group_id == null ? 1 : 0
type = "Microsoft.Network/networkSecurityGroups@2023-11-01"
name = coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
parent_id = var.parent_id
location = local.location
tags = var.new_network_security_group_tags
body = {
properties = {}
}
response_export_values = []
}
The disadvantage of this approach is if the user create a security group directly in the root module and use the id as a variable of the module, the expression which determines the value of count will contain an attribute from another resource, the value of this very attribute is “known after apply” at plan stage. Terraform core will not be able to get an exact plan of deployment during the “plan” stage.
You can’t do this:
resource "azapi_resource" "foo" {
type = "Microsoft.Network/networkSecurityGroups@2023-11-01"
name = "example-nsg"
parent_id = "/subscriptions/.../resourceGroups/example-rg"
location = "eastus"
body = {
properties = {}
}
response_export_values = []
}
module "bar" {
source = "xxxx"
...
security_group_id = azapi_resource.foo.id
}
For this kind of parameters, wrapping with object type is RECOMMENDED:
variable "security_group" {
type: object({
id = string
})
default = null
}
The advantage of doing so is encapsulating the value which is “known after apply” in an object, and the object itself can be easily found out if it’s null or not. Since the id of a resource cannot be null, this approach can avoid the situation we are facing in the first example, like the following:
resource "azapi_resource" "foo" {
type = "Microsoft.Network/networkSecurityGroups@2023-11-01"
name = "example-nsg"
parent_id = "/subscriptions/.../resourceGroups/example-rg"
location = "eastus"
body = {
properties = {}
}
response_export_values = []
}
module "bar" {
source = "xxxx"
...
security_group = {
id = azapi_resource.foo.id
}
}
This technique SHOULD be used under this use case only.
See origin...ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects
An example using AzAPI:
resource "azapi_resource" "main" {
type = "Microsoft.ContainerService/managedClusters@2024-09-01"
name = var.name
parent_id = var.parent_id
location = var.location
body = {
properties = { ... }
}
dynamic "identity" {
for_each = var.client_id == "" || var.client_secret == "" ? [1] : []
content {
type = var.identity_type
identity_ids = var.user_assigned_identity_ids
}
}
response_export_values = []
}
Please refer to the coding style in the example. Nested blocks under conditions, MUST be declared as:
for_each = <condition> ? [<some_item>] : []
See origin...ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try
The following example shows how "${var.subnet_name}-nsg" SHOULD be used when var.new_network_security_group_name is null or ""
Good examples:
coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")
try(coalesce(var.new_network_security_group.name, "${var.subnet_name}-nsg"), "${var.subnet_name}-nsg")
Bad examples:
var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name)
See origin...ID: TFNFR16 - Category: Code Style - Variable Naming Rules
The naming of a variable SHOULD follow HashiCorp’s naming rule.
variable used as feature switches SHOULD apply a positive statement, use xxx_enabled instead of xxx_disabled. Avoid double negatives like !xxx_disabled.
Please use xxx_enabled instead of xxx_disabled as name of a variable.
See origin...ID: TFNFR17 - Category: Code Style - Variables with Descriptions
The target audience of description is the module users.
For a newly created variable (Eg. variable for switching dynamic block on-off), it’s description SHOULD precisely describe the input parameter’s purpose and the expected data type. description SHOULD NOT contain any information for module developers, this kind of information can only exist in code comments.
For object type variable, description can be composed in HEREDOC format:
variable "kubernetes_cluster_key_management_service" {
type: object({
key_vault_key_id = string
key_vault_network_access = optional(string)
})
default = null
description = <<DESCRIPTION
- `key_vault_key_id` - (Required) Identifier of Azure Key Vault key. See [key identifier format](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name) for more details. When Azure Key Vault key management service is enabled, this field is required and must be a valid key identifier. When `enabled` is `false`, leave the field empty.
- `key_vault_network_access` - (Optional) Network access of the key vault Network access of key vault. The possible values are `Public` and `Private`. `Public` means the key vault allows public access from all networks. `Private` means the key vault disables public access and enables private link. Defaults to `Public`.
DESCRIPTION
}
You MUST remove all trailing whitespace so that terraform-docs renders the readme properly.
See origin...ID: TFNFR18 - Category: Code Style - Variables with Types
type MUST be defined for every variable. type SHOULD be as precise as possible. Authors SHOULD NOT use any.
- Use
bool instead of string or number for true/false - Use
string for text - Use concrete
object instead of map(any)
See origin...ID: TFNFR19 - Category: Code Style - Sensitive Data Variables
If variable’s type is object and contains one or more fields that would be assigned to a sensitive argument, then this whole variable SHOULD be declared as sensitive = true, otherwise you SHOULD extract sensitive field into separated variable block with sensitive = true.
See origin...ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values
Nullable SHOULD be set to false for collection values (e.g. sets, maps, lists) when using them in loops. However for scalar values like string and number, a null value MAY have a semantic meaning and as such these values are allowed.
See origin...ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default
nullable = true MUST be avoided.
Variables MUST be declared with nullable = false whenever the variable’s type has a meaningful zero value ({} for objects/maps, [] for lists/sets, "" for strings where empty has the same meaning as absent, etc.). Consumers should signal “no value” by omitting the input, not by explicitly passing null.
A small, well-defined class of inputs MAY keep the implicit nullable = true (i.e. default = null) where null carries a distinct semantic meaning of “no override — use the underlying provider/AVM defaults”, and where representing that state with the type’s zero value would be ambiguous or wrong. Examples include:
var.retry and var.timeouts (per TFFR7) — null means “do not emit a retry/timeouts block; use the AzAPI provider defaults”.var.lock (per the AVM lock interface) — null means “do not create a management lock”.- Optional sub-objects that toggle whole feature blocks on/off, where
{} would be indistinguishable from “feature enabled with all defaults”.
Where this exception applies, the variable MUST:
- Use
default = null (the implicit nullable = true is permitted only for this purpose). - State explicitly in its
description what null means. - Be consumed with a
null-aware pattern (e.g. count = var.lock != null ? 1 : 0, or dynamic "timeouts" { for_each = var.timeouts == null ? [] : [var.timeouts] }).
This exception does not extend to required inputs, to collection-shaped inputs (TFNFR20), or to nested attributes inside an object — those MUST use nullable = false and the type’s zero value.
See origin...ID: TFNFR22 - Category: Code Style - Avoid sensitive = false
sensitive = false MUST be avoided.
See origin...ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions
A default value MUST NOT be set for a sensitive input, unless it is an empty collection value.
Good example:
variable "example_map" {
type = map(string)
default = {}
description = "An example map variable with an empty default value."
sensitive = true
}
Bad example:
variable "example_string" {
type = string
default = "sensitive_value"
description = "An example string variable with a sensitive default value."
sensitive = true
}
See origin...ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables
Sometimes we will find names for some variable are not suitable anymore, or a change SHOULD be made to the data type. We want to ensure forward compatibility within a major version, so direct changes are strictly forbidden. The right way to do this is move this variable to an independent deprecated_variables.tf file, then redefine the new parameter in variable.tf and make sure it’s compatible everywhere else.
Deprecated variable MUST be annotated as DEPRECATED at the beginning of the description, at the same time the replacement’s name SHOULD be declared. E.g.,
variable "enable_network_security_group" {
type = string
default = null
description = "DEPRECATED, use `network_security_group_enabled` instead; Whether to generate a network security group and assign it to the subnet. Changing this forces a new resource to be created."
}
A cleanup of deprecated_variables.tf SHOULD be performed during a major version release.
See origin...ID: TFNFR25 - Category: Code Style - Verified Modules Requirements
The terraform.tf file MUST only contain one terraform block.
The first line of the terraform block MUST define a required_version property for the Terraform CLI.
The required_version property MUST include a constraint on the minimum version of the Terraform CLI. Previous releases of the Terraform CLI can have unexpected behavior.
The required_version property MUST include a constraint on the maximum major version of the Terraform CLI. Major version releases of the Terraform CLI can introduce breaking changes and MUST be tested.
The required_version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.
Note: You can read more about Terraform version constraints in the documentation.
Example terraform.tf file:
terraform {
required_version = "~> 1.6"
required_providers {
azapi = {
source = "Azure/azapi"
version = "~> 2.9"
}
}
}
See origin...ID: TFNFR26 - Category: Code Style - Providers in required_providers
The terraform block in terraform.tf MUST contain the required_providers block.
Each provider used directly in the module MUST be specified with the source and version properties. Providers in the required_providers block SHOULD be sorted in alphabetical order.
Do not add providers to the required_providers block that are not directly required by this module. If submodules are used then each submodule SHOULD have its own versions.tf file.
The source property MUST be in the format of namespace/name. If this is not explicitly specified, it can cause failure.
The version property MUST include a constraint on the minimum version of the provider. Older provider versions may not work as expected.
The version property MUST include a constraint on the maximum major version. A provider major version release may introduce breaking change, so updates to the major version constraint for a provider MUST be tested.
The version property constraint SHOULD use the ~> #.# or the >= #.#.#, < #.#.# format.
Note: You can read more about Terraform version constraints in the documentation.
Good examples:
terraform {
required_version = "~> 1.6"
required_providers {
azapi = {
source = "Azure/azapi"
version = "~> 2.9"
}
}
}
terraform {
required_version = ">= 1.6.6, < 2.0.0"
required_providers {
azapi = {
source = "Azure/azapi"
version = ">= 2.9.0, < 3.0.0"
}
}
}
terraform {
required_version = ">= 1.6, < 2.0"
required_providers {
azapi = {
source = "Azure/azapi"
version = ">= 2.9, < 3.0"
}
}
}
Acceptable example (but not recommended):
terraform {
required_version = "1.6"
required_providers {
azapi = {
source = "Azure/azapi"
version = "2.9"
}
}
}
Bad example:
terraform {
required_version = ">= 1.6"
required_providers {
azapi = {
source = "Azure/azapi"
version = ">= 2.9"
}
}
}
See origin...ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules
By rules, in the module code provider MUST NOT be declared. The only exception is when the module indeed need different instances of the same kind of provider(Eg. manipulating resources across different locations or accounts), you MUST declare configuration_aliases in terraform.required_providers. See details in this document.
provider block declared in the module MUST only be used to differentiate instances used in resource and data. Declaration of fields other than alias in provider block is strictly forbidden. It could lead to module users unable to utilize count, for_each or depends_on. Configurations of the provider instance SHOULD be passed in by the module users.
Good examples:
In verified module:
terraform {
required_providers {
azapi = {
source = "Azure/azapi"
version = "~> 2.9"
configuration_aliases = [azapi.alternate]
}
}
}
In the root module where we call this verified module:
provider "azapi" {}
provider "azapi" {
alias = "alternate"
}
module "foo" {
source = "xxx"
providers = {
azapi = azapi
azapi.alternate = azapi.alternate
}
}
Bad example:
In verified module:
provider "azapi" {
# Configuration options
}
See origin...ID: TFNFR29 - Category: Code Style - Sensitive Data Outputs
An output block that contains confidential data MUST be declared with sensitive = true.
See origin...ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs
Sometimes we notice that the name of certain output is not appropriate anymore, however, since we have to ensure forward compatibility in the same major version, its name MUST NOT be changed directly. It MUST be moved to an independent deprecated_outputs.tf file, then redefine a new output in output.tf and make sure it’s compatible everywhere else in the module.
A cleanup SHOULD be performed to deprecated_outputs.tf and other logics related to compatibility during a major version upgrade.
See origin...ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only
In locals.tf, file we could declare multiple locals blocks, but only locals blocks are allowed.
You MAY declare locals blocks next to a resource block or data block for some advanced scenarios, like making a fake module to execute some light-weight tests aimed at the expressions.
See origin...ID: TFNFR33 - Category: Code Style - Precise Local Types
Precise local types SHOULD be used.
Good example:
{
name = "John"
age = 52
}
Bad example:
{
name = "John"
age = "52" # age should be number
}
See origin...ID: TFNFR34 - Category: Code Style - Using Feature Toggles
A toggle variable MUST be used to allow users to avoid the creation of a new resource block by default if it is added in a minor or patch version.
E.g., our previous release was v1.2.1 and next release would be v1.3.0, now we’d like to submit a pull request which contains such new resource:
resource "azapi_resource" "route_table" {
type = "Microsoft.Network/routeTables@2023-11-01"
name = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
parent_id = var.parent_id
location = local.location
body = {
properties = {}
}
response_export_values = []
}
A user who’s just upgraded the module’s version would be surprised to see a new resource to be created in a newly generated plan file.
A better approach is adding a feature toggle to be turned off by default:
variable "create_route_table" {
type = bool
default = false
nullable = false
}
resource "azapi_resource" "route_table" {
count = var.create_route_table ? 1 : 0
type = "Microsoft.Network/routeTables@2023-11-01"
name = coalesce(var.new_route_table_name, "${var.subnet_name}-rt")
parent_id = var.parent_id
location = local.location
body = {
properties = {}
}
response_export_values = []
}
See origin...ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes
Potential breaking(surprise) changes introduced by resource block
- Adding a new
resource without count or for_each for conditional creation, or creating by default - Adding a new argument assignment with a value other than the default value provided by the provider’s schema
- Adding a new nested block without making it
dynamic or omitting it by default - Renaming a
resource block without one or more corresponding moved blocks - Change
resource’s count to for_each, or vice versa
Terraform moved block could be your cure.
Potential breaking changes introduced by variable and output blocks
- Deleting(Renaming) a
variable - Changing
type in a variable block - Changing the
default value in a variable block - Changing
variable’s nullable to false - Changing
variable’s sensitive from false to true - Adding a new
variable without default - Deleting an
output - Changing an
output’s value - Changing an
output’s sensitive value
These changes do not necessarily trigger breaking changes, but they are very likely to, they MUST be reviewed with caution.
See origin...ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources (AzureRM only)
From Terraform AzureRM 3.0, the default value of prevent_deletion_if_contains_resources in provider block is true. This will lead to an unstable test because the test subscription has some policies applied, and they will add some extra resources during the run, which can cause failures during destroy of resource groups.
Since we cannot guarantee our testing environment won’t be applied some Azure Policy Remediation Tasks in the future, for a robust testing environment, prevent_deletion_if_contains_resources SHOULD be explicitly set to false.
See origin...newres is a command-line tool that generates Terraform configuration files for a specified resource type. It automates the process of creating variables.tf and main.tf files, making it easier to get started with Terraform and reducing the time spent on manual configuration.
Module owners MAY use newres when they’re trying to add new resource block, attribute, or nested block. They MAY generate the whole block along with the corresponding variable blocks in an empty folder, then copy-paste the parts they need with essential refactoring.
See origin...ID: TFNFR39 - Category: Code Style - Standard File Layout
Every Terraform AVM module (root module and every submodule) MUST organize its top-level Terraform code into the following files at the module’s root directory:
| File | Required | Contents |
|---|
terraform.tf | MUST | The single terraform { … } block — required_version, required_providers, and any backend configuration (root module only). Provider configuration blocks MUST NOT appear here. |
variables.tf | MUST | All variable blocks for the module. MAY be split into additional variables.<topic>.tf files (see below). |
outputs.tf | MUST | All output blocks for the module. MAY be split into additional outputs.<topic>.tf files (see below). |
main.tf | MUST | The module’s primary resource, data, and module blocks. MAY be split into additional main.<topic>.tf files (see below). |
locals.tf | SHOULD | All locals blocks. Required if the module declares any locals. MAY be split into additional locals.<topic>.tf files (see below). MAY be omitted only when the module has no locals at all. |
Splitting and naming additional files
For larger modules the contents of main.tf, variables.tf, outputs.tf, and locals.tf MAY each be split into multiple files along logical / topic lines. When this is done:
- Additional Terraform files MUST use the canonical filename (
main, variables, outputs, or locals) as the prefix, followed by a ., a short descriptive topic name, and the .tf extension — for example main.diagnostic_settings.tf, variables.diagnostic_settings.tf, outputs.diagnostic_settings.tf, locals.diagnostic_settings.tf. - The topic name MUST be
snake_case (per TFNFR3). - The same topic name SHOULD be used across the four file types when they describe the same logical concern, so that (for example)
main.private_endpoints.tf, variables.private_endpoints.tf, outputs.private_endpoints.tf, and locals.private_endpoints.tf all relate to the same feature. - Each split file MUST contain only the block kind matching its prefix:
main.<topic>.tf — only resource, data, and module blocks.variables.<topic>.tf — only variable blocks.outputs.<topic>.tf — only output blocks.locals.<topic>.tf — only locals blocks.
- The
terraform { … } block MUST appear exactly once per module, in terraform.tf. It MUST NOT be split.
Files that MUST NOT appear at the module root
- A
providers.tf file — provider requirements belong in terraform.tf; provider configurations belong only in the consumer’s root module, never in an AVM module (per SFR2). - A single monolithic
module.tf or everything.tf — the canonical filenames above MUST be used.
Rationale
Standardizing file layout means that any reviewer or consumer can find a module’s interface (variables.tf, outputs.tf), provider constraints (terraform.tf), and primary logic (main.tf / main.<topic>.tf) in the same place across every AVM Terraform module, without having to grep. It also makes the cascade rules in TFFR6, TFFR7, and TFRMNFR1 reviewable at a glance.
Notes
- Submodules (per TFRMNFR1) follow the same layout in their own root directory under
modules/<subresource>/. The submodule’s terraform.tf MUST declare the same set of required_providers it actually consumes. - Auto-generated documentation files (
README.md, _header.md, _footer.md) and tooling configuration files (.terraform-docs.yml, .tflint.hcl, etc.) are out of scope of this rule and follow their own specs.