Terraform Best Practices: a free ebook on repository and module structure

What problem the Terraform Best Practices book addresses

Terraform does not force a directory layout. The README says the tool "allows developers to do a lot of things and does not restrict them from doing things in ways that will be hard to support or integrate with." That gap is what this repository fills. It is a book, not a linter, a module registry or a CLI. The audience is engineers and platform teams who already write HCL and now have to decide where files live, how modules are named, how environments are separated, and how much structure is enough before it becomes ceremony.

The README states the project started in Madrid in 2018 and is published free at terraform-best-practices.com. The repository holds the book's source: code-structure.md, code-styling.md, naming.md, key-concepts.md, writing-terraform-configurations.md, faq.md, examples.md, workshop.md, and a not-best-practices/ directory. That last one is the tell. The author writes that some material "may not seem like the best practices" and that hints and icons mark the maturity level of each subsection, so readers can separate settled practice from opinion. Most Terraform advice online blurs that line. This book tries not to.

How the book is organised and what the examples directory shows

The content is a set of Markdown chapters rendered through GitBook, with SUMMARY.md as the table of contents and .gitbook/ holding the build configuration. There is no runtime, no plugin system and no data flow to trace. Reading it means reading files.

The part worth studying closely is examples/. It contains three parallel layouts: examples/small-terraform/, examples/medium-terraform/ and examples/large-terraform/. Rather than describing one ideal structure in prose, the repository ships three concrete ones at different sizes, which lets you compare how the recommended split changes as a codebase grows. There are also examples/terraform/ and examples/terragrunt.md, so the same structural questions are answered for both plain Terraform and Terragrunt users.

That is the strongest design decision in the repository. A book about structure is only useful if the structure is visible, and a reader can open the three directories side by side and see what actually changes between a small and a large Terraform repository instead of taking a paragraph's word for it.

Reading the book locally and finding the structure for multiple environments

There is nothing to install and no package to add. The README points readers to https://www.terraform-best-practices.com/ for the rendered book, and the translations section lists GitBook links for Arabic, Bosnian, Brazilian Portuguese, French, Georgian, German, Greek, Hebrew, Hindi, Indonesian, Italian, Japanese, Kannada, Korean, Polish, Romanian, Simplified Chinese, Spanish, Turkish, Ukrainian and Urdu. If you want the source, clone the repository and read the Markdown directly.

git clone https://github.com/antonbabenko/terraform-best-practices.git
cd terraform-best-practices
ls

The listing should show the chapter files named above alongside examples/ and .gitbook/. From there, the two files most readers want first are code-structure.md, which covers repository layout, and examples.md, which introduces the sample directories. To see how the book handles multiple environments, read code-structure.md next to examples/medium-terraform/ and examples/large-terraform/ rather than in isolation.

ls examples
ls examples/large-terraform

The first command lists the small, medium and large sample trees plus the terraform and terragrunt example files. The second shows the file layout the book recommends once a repository has grown past the medium stage. Nothing here executes; these are directories to read.

Where the book stops being the right tool

The repository is documentation, so it cannot enforce anything. If two engineers disagree about module boundaries, the book will not settle it in CI. Tools that parse HCL and fail a build do that job, and this project does not attempt it.

The README is also explicit that the content is not uniformly authoritative. It says some information "may not seem like the best practices" and that the author marks maturity levels per subsection. That honesty has a cost: you cannot read the book as a specification and apply every recommendation without deciding, section by section, whether you agree. A team looking for a single canonical answer will find several answers instead.

Cloud coverage is another boundary. The related searches people run against this material include "terraform best practices aws" and "terraform best practices azure", but the repository is organised around Terraform itself: code structure, styling, naming, key concepts, module usage. Provider-specific patterns are not the organising principle of the chapters. If your question is how to lay out an AWS account structure, this book gives you the Terraform side and leaves the cloud side to other sources.

Finally, the book is a snapshot of written guidance. Its last push was on 2026-03-20, so it is not archived but it is also not a continuously changing codebase. Treat it as a reference document with a revision date, not a feed.

How this differs from Terraform's own documentation and from Terragrunt guides

The obvious alternative is HashiCorp's own Terraform documentation. Its job is to describe what each resource, function and command does. This book assumes you already know that and asks a different question: given that Terraform permits almost any layout, which ones hold up. The README frames the project exactly that way, as "an attempt to systematically describe best practices using Terraform and provide recommendations for the most frequent problems Terraform users experience." Official docs are reference material; this is argument.

A second alternative is a Terragrunt-first guide. Terragrunt exists to reduce repetition across environments and modules, and guides written around it tend to start from its own abstractions. This repository treats Terragrunt as one of two paths: examples/terraform/ and examples/terragrunt.md sit side by side, so the structural advice is presented for both. If your team has already standardised on Terragrunt, the Terragrunt material here is a comparison point rather than a replacement for a Terragrunt-specific reference.

The difference in approach matters most when you are choosing a layout. A tool guide tells you how to configure the tool. This book tells you what the resulting repository should look like, and then shows three sizes of it.

Maintenance, licensing and the cost of following along

The repository is not archived, and the last push was on 2026-03-20. That is roughly six months before the date of writing, which means the book is being revised but not frequently. Plan for reading it once when you set up a repository and again when you make a structural change, not for tracking it continuously.

Upgrade cost is close to zero in the software sense. There is no dependency to bump. The real cost is organisational: if you adopt a layout from examples/large-terraform/, moving an existing repository into it means moving files and updating module sources, which is a refactor with review overhead. The book reports no migration tooling for that, and the README does not document a rollback path for a layout change, because a layout change is a git operation rather than a feature of this project.

The licence is listed as NOASSERTION in the repository metadata, which means the licence file could not be matched to a standard identifier by tooling. LICENSE sits at the top level of the repository, so read that file directly before reusing or redistributing the text or the example configurations. Translations are hosted as separate GitBook spaces, and the README invites contact from people who want to translate the book into further languages, so translation work is coordinated rather than forked freely. None of this is legal advice; the file itself is the authority.

Editorial conclusion

Adopt this book if you are setting up a Terraform repository or module layout and want a written, opinionated reference that flags which recommendations are settled and which are one author's view. Skip it if you need provider-specific guidance for a single cloud, or if you want a tool that enforces rules rather than a document that argues for them. Before relying on it, open code-structure.md and the examples/ directory on master and check whether the layout they show matches the way your team already splits environments and modules.

Frequently asked questions

Official sources

1. antonbabenko/terraform-best-practices on GitHub
2. Issues
3. Project website
4. README