docs-terraform-guidelines

IaC Guidelines

Guidelines to work with Terraform and Terragrunt

• IaC Guidelines
  • 🎯 Our purpose
  • 🤖 AI Agent Plugin
  • 🤖 GitHub Copilot Integration
  • Why IaC ?
  • 🌟 Standards 🌟
    • The 3 gold standards for your infrastructure codebase
    • The standards for layers
    • The standards for modules
    • The standard naming convention
  • 🚀 Guidelines
    • 🛗 Patterns
    • 🔄 Lifecycle operations
    • 🎓 Standards
      • Terraform
      • Terragrunt
    • 🚩 Red flags
    • 🛠️ Tooling
  • License

🎯 Our purpose

This documentation is provided by the Theodo Cloud IaC Guild. Its purpose is to present guidelines and best practices about terraform/terragrunt development.

You do not have to see these guidelines as an absolute truth, but more as a proposition to answer frequently asked questions and avoid issues you will often face in your projects.

🤖 AI Agent Plugin

Install the iac-guidelines plugin from this repository’s theodo-iac marketplace to use these guidelines with Claude Code, GitHub Copilot CLI and Codex CLI. It provides five skills (guidelines, read-only audit, C4 and architecture diagrams, version upgrade) and two agents (iac-developer, read-only iac-auditor; Codex has skills only).

claude plugin marketplace add padok-team/docs-terraform-guidelines
claude plugin install iac-guidelines@theodo-iac

For IDEs that do not load plugins (e.g. Codex IDE), copy the skills/ folders and the guideline folders they reference into your project.

See the installation and compatibility guide for marketplace commands, local installation, invocation examples and maintenance instructions.

🤖 GitHub Copilot Integration

To leverage these guidelines in your own IaC projects, we provide comprehensive GitHub Copilot instructions that help generate standards-compliant Terraform and Terragrunt code.

Copy the GitHub Copilot instructions to your project’s .github/copilot-instructions.md to enable Copilot to:

• Generate code following our WYSIWYG and Context patterns
• Apply proper naming conventions and versioning standards
• Suggest appropriate module structures and layer designs
• Avoid common anti-patterns and red flags
• Reference internal library modules correctly

These instructions encapsulate all the best practices from this documentation into actionable guidance for GitHub Copilot, making it easier to maintain consistency across your infrastructure codebase.

🔍 IaC Audit Prompt

For existing codebases, use the iac-audit skill of the plugin to evaluate compliance with these standards:

/iac-audit

This prompt provides comprehensive analysis including:

• Project structure and pattern compliance assessment
• Naming conventions and versioning standards evaluation
• Security and code quality scoring (1-10 scale)
• Detailed recommendations for improvement
• Prioritized action items for standards compliance

Why IaC ?

Infrastructure as Code (IaC) is a key practice in modern software development that allows teams to manage and provision infrastructure through code, rather than manual processes. This approach brings several benefits:

• Consistency: IaC ensures that infrastructure is provisioned consistently, reducing the risk of human error and configuration drift.
• Version Control: Infrastructure code can be versioned, allowing teams to track changes,
• Automation: IaC enables automation of infrastructure provisioning, scaling, and management, leading to faster deployments and reduced operational overhead.
• Collaboration: Teams can collaborate on infrastructure changes using the same tools and processes they use for application code, fostering better communication and alignment.
• Scalability: IaC allows for easy scaling of infrastructure resources, enabling teams to adapt to changing demands quickly.

🌟 Standards 🌟

The 3 gold standards for your infrastructure codebase

• Your layer design reflects a business need
• Only one team contributes has ownership of a layer (you have a clear vision of contribution & ownership)
• Your state refresh time is acceptable for a contribution purpose

The standards for layers

• You can rebuild your infrastructure without the -target flag
• You do not have any cyclical dependencies between resources
• You use data blocks only in layers

The standards for modules

• A module should be created
  • To abstract complexity
  • If you have to reuse it frequently (More than twice)
• You should not create a module to be a flat pass between resources
• Your module’s dependencies are provided by the caller
• You use remote modules to avoid repetition between your different projects

The standard naming convention

• The name of the file or folder should reflect what you are creating
• Adapt your codebase to your client needs and standards
• Avoid stuttering when naming Terraform resources.
• Use snake_case convention

We recommend everyone to follow the WYSIWYG pattern for vanilla terraform and the Context pattern for Terragrunt.

🚀 Guidelines

You’ll find below details of the standards to follow when working with Terraform and Terragrunt.

🛗 Patterns

Reusable solution to a commonly occurring problem within a given context

• WYSIWYG pattern
• Context pattern aka the Terragrunt implementation

🔄 Lifecycle operations

• Choosing the right IaC structure
• Refactoring

🎓 Standards

Standards help to avoid waste and ensure that we deliver value

Terraform

• Distant values references
• Versioning
• Naming
• Pre-commits
• Iterate on your resources
• Optional attributes
• Handling secrets
• Gitignore recommendations

Terragrunt

• Why Terragrunt (ADR)
• Context Pattern
• Distant values references

🚩 Red flags

Red flag is something that you must pay attention about. This is an advice or recommendation, not a requirement.

• Dont’s
• Child modules depth limit

🛠️ Tooling

• Useful tooling for Terragrunt/Terraform
• Terraform pre-commits
• TFLint configuration

License

This site is open source. Improve this page.