terraform-code-standards

Table of Contents

• Overview
  • Directory Structure
  • Domain Specific Files
  • Naming Conventions
  • Resource and State Management
  • Modules
  • Variables and Outputs
  • Version Control
  • Documentation
  • Testing and Validation

Documentation

• Comprehensive Documentation: Document all modules, variables, and outputs using Markdown files or inline comments. Well-documented code is crucial for maintaining clarity and ensuring that the purpose and functionality of each module are easily understood. Clear documentation helps onboard new team members, facilitates code reviews, and simplifies maintenance.

• Automated Documentation with Terraform Docs:
  • Use Terraform Docs (tfdocs) to automatically generate documentation for your Terraform modules. This tool extracts information about resources, variables, outputs, and other elements directly from your Terraform files and formats them into a Markdown file.
  • Benefits of Terraform Docs:
    • Consistency: Automatically generate consistent documentation across all modules.
    • Up-to-date Information: Ensure your documentation reflects the latest changes in your Terraform configuration, reducing the risk of outdated or incomplete information.
    • Ease of Use: tfdocs is simple to integrate into your CI/CD pipeline, allowing for automated updates to your documentation whenever changes are made to your Terraform codebase.
• README for Each Module: Provide a README.md file for each module explaining its purpose, inputs, and outputs. This README should include:
  • Module Overview: A brief description of the module’s purpose and the problem it solves.
  • Inputs: A detailed list of input variables, including types, default values, and descriptions.
  • Outputs: A summary of the module’s outputs, detailing what each output represents and how it can be used.
  • Examples: Include examples of how to use the module, with example configurations to guide users in implementing the module in their environments.
• Best Practices:
  • Use Inline Comments: Where appropriate, include inline comments within your Terraform code to explain complex logic or decisions. This helps maintainers and collaborators understand the reasoning behind certain configurations.
  • Version Control Your Documentation: Store all documentation alongside your Terraform code in version control (e.g., Git). This practice ensures that your documentation is always in sync with the code and provides a historical record of changes.
• Integrating Documentation in CI/CD:
  • Consider integrating tfdocs into your CI/CD pipeline to automatically update documentation whenever a change is made to your Terraform files. This approach ensures that your documentation is always up-to-date and reflects the current state of your infrastructure code.

For more information on how to set up and use Terraform Docs, visit the official Terraform Docs User Guide.

[^ table of contents ^](#table-of-contents)

This site is open source. Improve this page.