I've been working with Terraform for a while now, and I've noticed that there are a few things that people keep asking me about. I thought it would be helpful to write a blog post about some of the most common questions I get asked and share some of the things I've learned along the way. This is not an exhaustive list, and, if you have any feedback or suggestions, please let me know!

File Conventions

Terraform offers great flexibility in its configuration language, making it easy to write code and organize directories according to your preferences. This adaptability ensures that your code remains readable, scalable, and maintainable. A well-organized codebase makes it easier to manage and scale your infrastructure. Here's a standard file structure I recommend to get started:

• main.tf: The core file where you define your resources, data sources, and modules.
• data.tf: I like to put data sources here.
• variables.tf: Where you declare all the variables your configuration will use.
• outputs.tf: Defines the outputs from your resources, making data available to other parts of your configuration.
• provider.tf: Providers are initialized in this file.
• versions.tf: Specifies the required versions of Terraform and its providers.
• terraform.tfvars: Contains variable values that override the default values set in variables.tf. This file is often environment-specific and should not be checked into version control.

Naming Conventions

Consistency in naming makes your Terraform code easier to read and maintain. Here are some key guidelines:

• Use underscores (_) instead of dashes (-) in resource names, data source names, variable names, and outputs.
• Stick to lowercase letters and numbers.
• Avoid repeating the resource type in names. For example, use resource "aws_vpc" "main" {} or resource "aws_vpc" "this" {} instead of resource "aws_vpc" "main_vpc" {}.
• Use singular nouns for resource names.
• For arguments values that will be exposed to humans (like DNS names), use dashes.

Using Data Sources

Data sources allow you to query existing resources in your infrastructure. This can be incredibly powerful for dynamically retrieving information and avoiding hardcoding values in your configuration.

Example of using a data source:

data "aws_ami" "latest" {
  most_recent = true
  owners      = ["self"]
 
  filter {
    name   = "name"
    values = ["my-custom-ami-*"]
  }
}
 
resource "aws_instance" "example" {
  ami           = data.aws_ami.latest.id
  instance_type = "t2.micro"
 
  tags = {
    Name = "example-instance"
  }
}

Configuring and Handling State

Managing state is a critical aspect of using Terraform effectively. The state file keeps track of the resources Terraform manages, so it's important to store it securely and make it accessible to your team. Here are some best practices:

• Remote State Storage: Use a remote backend like AWS S3, Azure Storage, or Terraform Cloud to store your state files. This ensures that your state is not lost and can be accessed by your team members.
• State Locking: Enable state locking to prevent multiple users from making concurrent changes. AWS S3 with DynamoDB, for example, supports state locking.
• Do not forget to review resources periodically, restrict state file access, and carefully remove unnecessary resources.
• Never store sensitive information in state files or in your Terraform configuration (use environment variables or data sources and a secrets management tool). I wrote a whole post about How to Safely Store Secrets in Terraform Using Cloud KMS - check it out!
• Do not edit state files manually. If you need to make changes, use Terraform commands like terraform state mv, terraform state rm, or terraform import (but if you can avoid it, do so).

Using Terraform Workspaces

Terraform workspaces are incredibly useful for managing and isolating different state files within a single project, especially when dealing with multiple environments. They allow you to deploy multiple resources based on different inputs. With workspaces, you can use the same configuration for various environments like development, staging, and production. Each workspace maintains its own state file, making it easier to handle multiple environments efficiently.

Terraform Workspaces are an excellent way to manage multiple environments (e.g., dev, staging, production) within the same configuration. Workspaces allow you to use a single Terraform configuration for different environments, with separate state files for each workspace. After creating a new workspace with terraform workspace new, you can switch between workspaces using terraform workspace select. You can then reference the current workspace in your Terraform code to differentiate configurations or resource names, like so:

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  tags = {
    Name = "${terraform.workspace}-example-instance"
  }
}

I wrote another blog post about How to Use Terraform Workspaces to Manage Environment-based Configuration - check this one out too!

Terraform provides pretty much everything you need to manage your infrastructure out-of-the-box. However, there are some additional tools that can help you work more efficiently and maintain code quality.

Using Formatters and Linters

Formatters are tools that automatically format your code according to a specific style guide. Terraform provides the terraform fmt command to format your code based on the HashiCorp style guide. Linters help maintain code quality by enforcing style guidelines and catching potential errors. To maintain code quality and consistency, you can use TFLint as a linter. It helps identify errors and best practice violations in your Terraform configurations.

If you are using GitHub Actions as your CI/CD pipeline (do it!), you can use the terraform-linters/setup-tflint action from the marketplace to set up and run TFLint in your workflow.

Terratest and Terragrunt

Terratest and Terragrunt are two tools for testing and managing your Terraform configurations. They are built by Gruntwork, a company that specializes in DevOps and infrastructure as code.

Terratest is a Go library that provides patterns and helper functions for testing your infrastructure code. It allows you to write automated tests for your Terraform configurations to ensure they work as expected, just like you would test your application code.

Example of a simple test in Go with Terratest:

package test
 
import (
  "testing"
  "github.com/gruntwork-io/terratest/modules/terraform"
)
 
func TestTerraformExample(t *testing.T) {
  opts := &terraform.Options{
    TerraformDir: "../examples/terraform-aws-example",
  }
  defer terraform.Destroy(t, opts)
  terraform.InitAndApply(t, opts)
}

Terragrunt instead is a thin wrapper for Terraform that provides extra tools for keeping your configurations DRY (Don't Repeat Yourself). It is especially useful for managing multiple environments and handling dependencies between modules.

Conclusion

I worked with Terraform for a while now, and I've learned a few things along the way. I find myself mentioning these best practices and tools to people who are new to Terraform or looking to improve their existing workflows. I hope this post helps you get started with Terraform and provides some useful tips for working with it effectively!

By following these best practices for file conventions, naming conventions, using data sources, configuring and handling state and workspaces, leveraging linters and other tools like Terratest and Terragrunt you'll ensure your infrastructure-as-code configuration is robust, maintainable, and scalable.

Happy Terraforming!