Following on from my last post My Terraform Development Workflow, I felt it might be a good idea to talk a little about the standards that I employ when writing Terraform. I will break this post up into a few sections:
Naming
Naming is a highly touchy subject for many people, especially when it comes to naming cloud resources. This won't delve into the naming of the resultant resources provisioned by the Terraform code, only the names of blocks etc., within Terraform itself. The best way to do this is to lay them out as rules that can be looked through; this will help guide you to the right choice.
- When naming a Resource/Data Source/Input Variable/Output Value/Local Valuethe name MUST use Snake Case. Doing so ensures that visually the names align with how Terraform represents its internal names.
- Names MUST be lowercase.
- If there is only a single instance of a given Resource or Data Source, then it SHOULD be named
this. This means that you do not have to think of a descriptive name for the resource, as the resource type itself should be descriptive enough. In the event that your code grows to include multiple instances of resource that cannot be within a loop you SHOULD give subsequent resources a descriptive name. - When there are multiple instances of a given Resource or Data Source, the name SHOULD describe its function or domain.
- The name MUST not include information that is already present in the Resource/Data Source type name.
Input Variables
Input Variables or Variables or IVs are the most straightforward way to get information into your Terraform code. These are the pieces of information that instruct the Terraform code on what to build. As such, they are essential to get right, not only for you but for anyone consuming them!
The following is an example of what I would call a good IV, have a look at it, and we will deconstruct why it is good below.
variable "environment" {
type = string
description = <<EOT
(Optional) The name of the environment where the resources will be deployed.
Options:
- dev
- uat
- test
- prod
Default: dev
EOT
default = "dev"
validation {
condition = can(regex("dev|uat|test|prod"), var.environment)
error_message = "Err: environment name is not valid."
}
}
- The
typeMUST be explicit. - The
descriptionMUST be, as it says, descriptive. - The
defaultSHOULD be set sparingly; consumers should be explicit about what they are passing in. - If the variable has any specific requirements,
validationMUST be set. This prevents invalid data from entering the Terraform code and ensures that it will error sooner rather than later. - If you're passing in a known data structure, you SHOULD favour the
object()type, and this SHOULD be coupled withvalidationblocks.
If these rules are followed, it makes understanding what an Input Variable does and any requirements might have been easy.
Local Values
When you want to do some transformation of data based on Input Variables, or there is a piece of data you wish to pass around to multiple places Local Values is a fantastic option.
- If a file contains a
localsblock, it SHOULD be at the very top of the file. - If a
localsblock is transforming a specific piece of data and only used a single time it SHOULD be directly above the Resource that is doing the transformation for. - Nesting and/or creating complex objects within
- If you have
localsthat are global and your code is split across domain based files then you SHOULD put thoselocalswithin alocals.tffile.
Constraints
Constraints can be put in three places in Terraform; on the version of Terraform to use, on the version of the provider to use, and finally, on the version of a module to use.
- The version constraint SHOULD be applied to all three of these areas.
- You SHOULD use the pessimistic constraint operator on the minor version. Doing so will allow minor versions to increment and keep your code up to date without letting any breaking changes come through.
module "important_resources" {
version = "~> 1.0"
}
The above will allow the use of 1.1.0, 1.0.1 and 1.1.1 but will not allow the use of 2.x.x.
There are a 5 types of meta-arguments within the Terraform configuration language:
I will group count and for_each into a category called loops, as that is what they're predominately used for.
Loops
If the Resource, Data Source or Module requires more than one instance of itself then a loop is used.
- If the configuration of each instance of the resource is identical, then a
countSHOULD be used. - If the resource is required to be turned on or off like a feature flag, then a
countSHOULDbe used. - If the order of the resources is not going to change, then a
countSHOULD be used. - If the order of the resources is a concern, then
for_eachSHOULD be used. - If the configuration of each instance of the resource will change or depend on a value provided by the loop, then
for_eachSHOULD be used. - If you are unsure which loop type to use, then a
for_eachSHOULD be used.
I prefer to use a for_each loop in nearly all circumstances. You have a lot more control over them and if you're looking to reference the instances they produce, it is much easier to do so with a key provided by for_each rather than an index provided by count.
Depends On
Whilst Terraform will implicitly depend on other Resources or Data Sources when other resources reference them. It is sometimes necessary to do this explicitly. This is done via the depends_on meta-argument. This meta-argument allows you to explicitly depend on one or more other resources and data sources.
There are also instances where errors can occur on destruction or modification if you do not explicitly depend on a resource down the chain. I generally adopt an implicit dependency is okay model and change to explicit as required.
Provider
The provider meta-argument is extremely important when you're working with Terraform configuration that requires the use of multiple instances of the same type of provider.
- If you're writing a module, you SHOULD NOT use the
providermeta-argument. - The alias attributed to the
providermeta-argument MUST be descriptive.
There is not much more to say about this one, other than think carefully about when and if you need to use it. The more instances of a provider you have, the more complex the code become. It is currently not possible to loop/iterate over instances of providers; thus, this meta-argument MUSTbe used any time you wish to use a different provider instance.
Lifecycle
The lifecycle meta-argument is dangerous, be sure you know what
you're doing!!
lifecycle is very powerful as it allows you to manipulate the lifecycle of the Resources or Data Sources that you declare. I seldom use this meta-argument, the only time I find it necessary is when auto-scaling is applied to resources or the resource is modified out of Terraform and cannot be controlled through Terraform. An instance of this would be if your cloud platform applies a change to a resource, and you cannot prevent it.
I highly recommend reading through the lifecycle meta-argument documentation here. This might be a topic that I dedicate a post to in the future.
Code Structure
The code structure is fundamental; it determines how readable and clear our code is not only to us but to those wanting to consume and contribute. It is a good idea to make sure that you have a consistent approach to code structure. I follow the below set of rules whenever I write Terraform.
- You SHOULD use a single file for each of the following:
outputs.tfvariables.tfproviders.tfbackend.tfversions.tf
- You SHOULD start with a single
main.tffile and expand as required. (Refer to my previous post) localsblocks SHOULD be declared at the top of yourmain.tf.- Data Sources that are going to be used globally SHOULD be declared at the top of the
main.tfunder thelocals. - Data Sources and
localsthat are specific to a particular resource or set of resources SHOULD be declared above them if they are only being used in that place. - Any loops SHOULD be declared at the top of a resource, and a line of whitespace between it and any configuration for the resource.
- The
depends_onmeta-argument SHOULD be the last thing declared within a resource or data source and SHOULD be preceded with a single newline. - The
lifecyclemeta-argument SHOULD be at the bottom of a resource or data source but above thedepends_onif present. - The
providermeta-argument SHOULD be at the top of a resource or data source but below loops if they're present.
Closing Out
Hopefully, this post gives you some ideas on how to structure your Terraform code and implement some standards that you can use to improve your code. I am always keen to hear how others deal with the standards side of Terraform as it can be pretty contentious. HashiCorpcertainly never want to get involved in the religious war that is Terraform standards/best practices!