Naming Conventions

Global Variables

A "global variable" is any variable defined outside of a module. Global variable types should be defined in the root of the src directory in a file named variables.module_name.tf. Replace "module_name" with the name of the primary module that will use the variables. Use lowercase, singular names. For example, the variable used to define which load balancers should be built using aws_lb would be named lb and should be defined in a file named variables.lb.tf. If the variable being created doesn't directly relate to a module, use an intuitive name that aligns with our code practices or seek input from the team.

Module Blocks

A "module block" instructs Terraform to create resources defined in a module. Module blocks should be placed in the root of the src directory in a file named main.module_name.tf. Replace "module_name" with the name of the module being referenced. Use lowercase, singular names for module blocks. For example, the module block for aws_lb should be defined in a file named main.lb.tf.

Argument Names for variables that reference other keys

When naming argument variables that reference keys from other defined variables, use a name that won't cause confusion about the type of value that should be entered. For example, if an argument for a resource block is subnet_id, security_group_ids, or iam_role_arn use an argument named subnet, security_groups, or iam_role, respectively. This makes it clear that the expectation is not to supply ids or arns, but rather a key for a resource/variable defined elsewhere in our code. When our module looks up the actual resource id, name, arn, etc., the real name of the argument will be used in main.tf of the module in the resource or data block.

Modules

Module Names

Because our architecture requires most resources to be wrapped with their own module, each module name should reflect the resource it is being used to build. Module names should be all lowercase, singular and should match the resource name without the provider_ prefix. For example, the module for azurerm_virtual_network should be named virtual_network and the module for aws_vpc should be named vpc.

Module Variable Names

Module variables should be defined in a variables.tf file within the module directory. This file should define all input variables for the module. Each variable name should be lowercase, singular and prefixed with either var_ or mod_. mod_ should be used for the output of other modules passed into the module and var_ should be used for all others.

Module Variable Types

Most variable types are defined globally and passed into modules; therefore, type enforcement is handled outside of the module. The variable type for variables prefixed with mod_ should always be any because our modules output comes from both resource and data blocks. This prevents us from using map because all map values must be the same type. The any type should be avoided for other variables.

Module Local Blocks

Module local blocks should be defined in a file named locals.tf within the module directory.

Module Resource and Data Block Labels

When defining resource and data blocks within a module, they should be defined in main.tf within the module directory. Labels for each should be all lowercase, singular and should match the resource name without the provider_ prefix. (Same as the module name.) For example, an aws_lb resource block should use the label lb, and an aws_vpc data block should use the label vpc.

Module Output Blocks

Output blocks should be defined in a file named outputs.tf within the module directory. Output names should be all lowercase, singular and should match the resource name without the provider_ prefix. (Same as the module name.) For example, the lb module should use the output name lb, and the vpc module should use the output name vpc. If the module includes both data and resource blocks, the value of the output should be merged.