antonbabenko/terraform-best-practices

Terraform Best Practices free ebook translated into 🇬🇧🇦🇪🇧🇦🇧🇷🇫🇷🇬🇪🇩🇪🇬🇷🇮🇱🇮🇳🇮🇩🇮🇹🇰🇷🇵🇱🇷🇴🇨🇳🇪🇸🇹🇷🇺🇦🇵🇰

Hi there, I'm Anton 👋

I am AWS Community Hero and a founder of Betajob - a company that helps build solutions using AWS and specializes in infrastructure as code, DevOps, and reusable infrastructure components.

I like

• Travel to share knowledge on conferences, meetups, podcasts, workshops, mentorship, etc.
• Figure out best&worst practices (by asking "Why?"), and publishing them as Terraform best practices and Terragrunt Reference Architecture
• Open-source, Terraform and AWS
• Making Terraform live streams and sending weekly newsletters is fun, too.

Some of my open-source projects

• serverless.tf - Doing serverless on AWS with Terraform.
• Terraform cost estimation - anonymized, secure, free.
• Terraform AWS modules which were provisioned more than 200 million times.
• pre-commit-terraform to keep Terraform projects clean and nice.
• Hide posts about certifications in your LinkedIn newsfeed - Chrome extension.
• Remember to give a star to terraform-aws-devops repository for a complete list of my projects and links.

Connect with me

terraform-best-practices's Issues

Allow to link to a specific version of the docs

Is your feature request related to a problem? Please describe.

When an organization defines the (coding) style that should be followed, it comes in handy to just reference a few URLs and say we adhere to this and done. However, this external resource can change.

Describe the solution you'd like

The version of the docs should be selectable and pinable. I am not familiar with GitBook. https://docs.jabref.org/ top right version selector would be a start.

Additionally, the project would need to start doing releases following some like https://semver.org/spec/v2.0.0.html. Or at least have stable branches like stable-2.0, stable-2.1.

Note that https://semver.org/ has exactly the same requirement so they offer URLs like https://semver.org/spec/v2.0.0.html to pin the version.

Another solution could be to mirror https://github.com/antonbabenko/terraform-best-practices, render the docs and then point to this fixed version. Then git can be used to update and diff changes.

Discuss quoting block labels

Is your feature request related to a problem? Please describe.

I'd like the book to discuss putting quotes around block labels. It's not required but they're typically quoted in documentation and the majority of modules. I believe this was cary over from a previous version of HCL that required them, but no longer does.

Terraform fmt and terraform validate do not raise no quotes as an error.

It doesn't seem like these quotes should be necessary and I'd love to see a discussion here or else where on this topic. IMO, the eventual goal should be that labels are no longer being quoted as the norm within the community.

Describe the solution you'd like

I'm referring to no longer quoting resources, modules, or provider "labels" like so:

GOOD

provider aws {
  ...
}

module iam_group_with_policies {
  ...
}

resource aws_waf_ipset whitelist_ipset {
  ...
}

BAD

provider "aws" {
  ...
}

module "iam_group_with_policies" {
  ...
}

resource "aws_waf_ipset" "whitelist_ipset" {
  ...
}

Would love to see this completed!

I saw a March 2018 goal to update and finish these. Poke!

Add resources for EC2 instances to code structure examples.

Examples of code structures describe only network topologies, it would be nice to add a simple examples for creating ec2 instances.

Thanks.

Add a section about providers versions/dependencies best practices

Add a section about providers versions/dependencies best practices

• Recommendation on implementing providers version constraints. How to implement the version_constraint in the required_providers block : version = "~> 1.0.0" or version = "= 1.0.0"

• Recommendation on implementing the lock file and why it can beneficial for security with the Checksum verification

• Recommendation on how to combine both version constraints and lock file to have reproducible builds

aws_security_group_list - typo?

Describe the bug

On line 51 of the Key Concepts page, what is aws_security_group_list? (I'm guessing it's a typo - maybe it should be aws_security_group_rule?)

Docs: What is the type in naming variables?

When I was reading about the naming convention I faced this line

Good structure for the name of output looks like {name}_{type}_{attribute} , where:
1. {name} is a resource or data source name without a provider prefix. {name} for aws_subnet is subnet, foraws_vpc it is vpc.
2. {type} is a type of a resource sources
3. {attribute} is an attribute returned by the output
4. See examples.

It's not clear what type is and how it can look. I was not able to understand it from the examples
https://www.terraform-best-practices.com/naming#code-examples-of-output

It seems the examples use {name}_{attribute} pattern

Can someone please explain to me what type is?

Add section dedicated to versions.tf

Handling of versions.tf is simple in a simple single directory/module project, but as a project becomes complex, starts using in-house as well as third-party modules, then versions.tf raise numerous questions on where those are needed, where recommended, etc.

@apparentlymart offered an excellent explanation in the How to set up versions.tf at root level of directory thread:

The key thing to note here is that the version constraints are a per-module idea and so should ideally be included in every directory that contains .tf files, describing which Terraform and provider versions each specific module is compatible with. There is no expectation that all of your modules would declare the same requirements, because each one will be using different features of Terraform and different provider features.

I think this deserves a place in any collection of Terraform best practices.

Terragrunt code example page empty

The Terragrunt code example page is broken. Page is empty.

https://www.terraform-best-practices.com/examples/terragrunt

`terraform.tfvars` only for composition?

First of all, thanks for providing this great book!

The Getting started with structuring of Terraform configurations section states that terraform.tfvars files should exclusively be used with composition:

terraform.tfvars should not be used anywhere except composition.

In turn, the Composition section defines composition as follows:

Composition is a collection of infrastructure modules, [...]

However, the example for small-size infrastructures doesn't have any module but nevertheless uses a terraform.tfvars file.

I'm wondering who's wrong here - the code structure section or the code example?

Add naming convention for modules arguments and examples

Possible order of arguments:

1. source
2. version

Possible code:

module "vpc" {
 count              = 2

 source             = "terraform-aws-modules/vpc/aws"
 version            = "3.11.0"

 name               = "my-vpc-${count.index + 1}"
 cidr               = "10.0.0.0/16"
 azs                = ["us-east-1a", "us-east-1b", "us-east-1c"]
 private_subnets    = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
 public_subnets     = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
 enable_nat_gateway = true
 enable_vpn_gateway = true

 tags               = {
   Terraform = "true"
 }
}

Not a good place for providers

terraform-best-practices/examples/large-terraform/stage/main.tf

Line 1 in fdc2894

provider "aws" {

If you have to specify many aws regions as aliases, you will get lost with where the actual work is (the modules down below).

Reconsider where to put the provider blocks; eg, new file called providers.tf

Certificate error while accessing the website ?

Describe the bug

I am prompted with a security error caused by the certificate that I am given when I try to access the website.
https://www.terraform-best-practices.com/

Expected change

A secure access to the website.

Please consider changing the name recommendation of "this"

The terraform naming conventions currently recommends "this" as a default resource name. While I agree with the majority of what you have written I think using "main" as a default name would be a better recommendation.

in many software languages where "this" is a formal feature it is used as a token only for private references from within the component to its self. Using "this" for other components to refer to each other seems strange. The term "main" is more general and would work in this context.

How do you feel about making the change? If you agree, I can draft a pull request to update the documentation.

Links in examples are broken

Describe the bug

Some of the links in the terraform-best-practices/examples folder are broken (e.g. https://github.com/antonbabenko/terraform-best-practices/blob/master/examples/terraform/terraform.md#terraform-small).

Expected change

The links should lead to the correct folders, e.g. https://github.com/antonbabenko/terraform-best-practices/tree/master/examples/small-terraform .

Adding Infracost to the FAQ

I was talking to a user today who referred to the best practices website, and said Infracost should be listed in the 'tools to be aware of' (https://www.terraform-best-practices.com/faq#what-are-the-tools-i-should-be-aware-of-and-consider-using). I thought that would be cool to add :)

Happy to send a PR if that's easier too <3

Naming conventions - possible mistake

Describe the bug

I started reading the book and reached the following page:
https://www.terraform-best-practices.com/naming

The following tip caught my eye:

To make inverted conditions don't introduce another variable unless really necessary, use 1 - boolean value instead. For example, count = "${1 - var.create_public_subnets}"

Shouldn't the count statement be the opposite? Meaning that if I pass "1" as the variable named "create_public_subnets", then the result of the mathematical operation would be "1-1=0", meaning count=0: don't create the resource. I would expect that passing var.create_public_subnets=1 will create the resource.

Link is broken

Describe the bug

Link "AWS VPC Terraform module " on page https://www.terraform-best-practices.com/key-concepts is broken

How to manage dependencies?

I saw you touch on dependencies in https://github.com/antonbabenko/terraform-best-practices/blob/master/not-best-practices/faq.md but I was wondering if you could point to a resource for how to manage terraform dependencies..

My current organization does something that feels wrong, and requires lots of manual rebuilds.. When a terraform module depends on another module, it is fetched into the 'build' directory, with the dependent module name as a folder in the top level structure of the built module. It is then 'vendored' into the .tar that we produce and push to our artifact repository (across environments), and then exported from the artifact repo into each different environments git repo with an appropriate version tag.

We use terragrunt to fetch the version of the repo with all of it's dependencies vendored into it.;

What is the 'right' way to have multiple module dependency resolved in terragrunt? We already have a top level module_versions.yaml file that is used to index the version, but you can't just update dependent_module in that file and get it pulled in, unless the toplevel_module gets rebuilt, and pulls that version in.

Are there any good resources showing how to create/reference/build the right module structure and it's references? I guess what I want to find is what you would put in https://www.terraform-best-practices.com/examples/terragrunt, but it currently appears empty!

Gitbook Dark Mode Toggle

Hey @antonbabenko!

Is there anyway you would be able to add the dark mode toggle for the Gitbook site?

Why having the exact copy of main files (main.tf) in two different folders (prod/stage) is the best practice?

I am trying to find the best practice for the Terraform folder structure. I found this page https://www.terraform-best-practices.com/examples/terraform/medium-size-infrastructure.

But I don't understand why it's the best practice to have the exact copy of mains in two different folders (prod, stage). Maybe I might be missing something. Please let me know what I miss. Thanks.

curious about the layout of this repo....

I was referred to your repo from a colleague of mine who spoke very highly of you. The main thing i question is having both your prod and staging environments in one repo, while also having embedded modules. Would it not be better to have one repo, your modules in separate repos, and both prod and staging using this repo while leveraging workspaces and pulling modules from their own repos (even better, using a registry)? I'm sure you have reasons for doing it this way, just curious as to what they are. Thanks for entertaining me, hope you're well.