Best Practices

July 11, 2025 · View on GitHub

This document outlines the best practices for developing and maintaining Terraform modules in this repository.

📋 New Module Pattern: For detailed information about our standardized module development pattern, see Module Development Pattern

Module Design

General Principles

  1. Single Responsibility

    • Each module should do one thing well
    • Keep modules focused and composable
    • Avoid creating "kitchen sink" modules

  2. Reusability

    • Design modules to be reusable across projects
    • Use variables for customization
    • Avoid hardcoding values

  3. Composability

    • Make modules work well together
    • Use consistent naming conventions
    • Design for composition from the start

Input Variables

  1. Naming

    • Use clear, descriptive names
    • Follow consistent naming patterns
    • Use snake_case for variable names

  2. Types

    • Always specify variable types
    • Use complex types when appropriate
    • Validate input with type constraints

  3. Defaults

    • Provide sensible defaults
    • Document default values
    • Make defaults secure by default

  4. Validation

    • Add validation rules
    • Use custom validation blocks
    • Validate security-related inputs

Outputs

  1. Completeness

    • Output all useful attributes
    • Include computed values
    • Output resource IDs and ARNs

  2. Naming

    • Use consistent naming
    • Make names descriptive
    • Follow the same pattern as inputs

  3. Documentation

    • Document all outputs
    • Include usage examples
    • Explain computed values

Security

General Security

  1. Least Privilege

    • Use minimal IAM permissions
    • Follow security best practices
    • Document security requirements

  2. Encryption

    • Enable encryption by default
    • Use KMS for sensitive data
    • Document encryption settings

  3. Network Security

    • Use security groups properly
    • Implement network isolation
    • Document network requirements

AWS-Specific

  1. IAM

    • Use IAM roles and policies
    • Follow AWS best practices
    • Document IAM requirements

  2. VPC

    • Use private subnets
    • Implement proper routing
    • Document network architecture

  3. Secrets

    • Use AWS Secrets Manager
    • Never hardcode secrets
    • Document secret management

Tagging

AWS Resources

  1. Required Tags

    • Environment (dev, staging, prod)
    • Project/Application name
    • Owner/Team
    • Cost Center
    • Managed By (Terraform)

  2. Optional Tags

    • Version
    • Description
    • Compliance requirements
    • Backup requirements

  3. Tagging Strategy

    • Consistent across resources
    • Automated tagging
    • Document tagging requirements

Testing

Module Testing

  1. Unit Tests

    • Test variable validation
    • Test output values
    • Test error conditions

  2. Integration Tests

    • Test with real providers
    • Test module composition
    • Test error handling

  3. Security Tests

    • Run tfsec
    • Check IAM permissions
    • Validate encryption

Documentation

Module Documentation

  1. README.md

    • Clear description
    • Usage examples
    • Input/output documentation
    • Requirements

  2. Examples

    • Basic usage
    • Common scenarios
    • Security configurations
    • Integration examples

  3. Comments

    • Document complex logic
    • Explain design decisions
    • Reference external docs

Versioning

Semantic Versioning

  1. Major Version

    • Breaking changes
    • Incompatible updates
    • Major feature changes

  2. Minor Version

    • New features
    • Backward compatible
    • Minor improvements

  3. Patch Version

    • Bug fixes
    • Security updates
    • Documentation updates

References