terraform.yaml

# Terraform Code Review Guidelines
# Comprehensive rules for Terraform security, state management, and best practices

name: Terraform Code Review Guidelines
description: Guidelines for reviewing Terraform configurations covering security, state management, code quality, and drift prevention
globs:
  - "**/*.tf"
  - "**/*.tfvars"
  - "**/*.tfvars.json"
  - "**/terraform.tfstate"
  - "**/terraform.tfstate.backup"
  - "**/.terraform.lock.hcl"

areas:
  - name: security
    description: Security rules for Terraform configurations
    rules:
      - name: mark-sensitive-variables
        description: Mark variables containing secrets with sensitive = true. This prevents values from appearing in logs and plan output. Always use sensitive for passwords, API keys, tokens, and certificates.
        severity: high

      - name: no-hardcoded-credentials
        description: Never hardcode credentials in Terraform files. Use environment variables, secret management systems, or data sources to retrieve sensitive values. Check .tfvars files are in .gitignore.
        severity: high

      - name: use-provider-authentication-properly
        description: Configure provider credentials through environment variables or instance profiles, not in code. Use assume_role for cross-account access. Enable provider credential rotation.
        severity: high

      - name: encrypt-remote-state
        description: Enable encryption for remote state storage. Use SSE-S3 or KMS for S3 backends, encryption for GCS. Remote state may contain sensitive data from resource attributes.
        severity: high

      - name: restrict-state-access
        description: Implement strict IAM policies for state bucket access. Use separate state files per environment. Enable versioning and MFA delete protection on state buckets.
        severity: high

      - name: sanitize-outputs
        description: Mark sensitive outputs with sensitive = true. Review all outputs to ensure they don't expose secrets. Outputs are visible in state files and logs.
        severity: medium

  - name: state_management
    description: Remote state backend and locking configuration
    rules:
      - name: use-remote-backend
        description: Always use a remote backend (S3, GCS, Azure Blob, Terraform Cloud) for team environments. Local state files should only be used for testing. Remote backends enable collaboration and state protection.
        severity: high

      - name: enable-state-locking
        description: Enable state locking to prevent concurrent modifications. Use DynamoDB for S3 backend, native locking for GCS/Azure. Never disable locking in production environments.
        severity: high

      - name: use-workspaces-appropriately
        description: Use workspaces for environment separation only when resource configurations are identical. Prefer separate state files for significantly different environments. Don't use default workspace in production.
        severity: medium

      - name: implement-state-backup
        description: Enable versioning on state buckets for point-in-time recovery. Configure lifecycle policies for version retention. Test state recovery procedures regularly.
        severity: medium

  - name: code_quality
    description: Code formatting, documentation, and naming conventions
    rules:
      - name: format-code-consistently
        description: Run terraform fmt to ensure consistent formatting. Enable format checks in CI/CD pipelines. Consistent formatting improves readability and reduces diff noise.
        severity: low

      - name: document-variables-outputs
        description: Add descriptions to all variables and outputs. Document type constraints, validation rules, and expected values. Good documentation enables self-service infrastructure.
        severity: medium

      - name: use-consistent-naming
        description: Follow consistent naming conventions for resources, variables, and outputs. Use snake_case for Terraform identifiers. Include environment and purpose in resource names.
        severity: low

      - name: pin-provider-versions
        description: Pin provider versions using version constraints in required_providers. Use pessimistic constraint operator (~>) for minor version updates. This ensures reproducible applies across environments.
        severity: high

      - name: pin-module-versions
        description: Pin module versions when using external modules. Never reference main/master branch directly. Use semantic versioning or commit SHAs for stability.
        severity: high

      - name: validate-variable-inputs
        description: Add validation blocks to variables for input validation. Check string formats, numeric ranges, and allowed values. Fail fast with clear error messages for invalid inputs.
        severity: medium

  - name: best_practices
    description: Terraform best practices for maintainable infrastructure
    rules:
      - name: use-modules-for-reuse
        description: Create modules for reusable infrastructure patterns. Modules should be focused and composable. Use input variables for customization and outputs for integration.
        severity: medium

      - name: use-data-sources
        description: Use data sources to reference existing resources instead of hardcoding IDs. Data sources ensure references are valid and up-to-date. They also document external dependencies.
        severity: medium

      - name: implement-resource-tagging
        description: Apply consistent tags to all resources for cost allocation and organization. Use default_tags in provider configuration. Include environment, owner, project, and cost center tags.
        severity: medium

      - name: use-locals-for-computed-values
        description: Use locals blocks for computed values and complex expressions. This improves readability and reduces duplication. Name locals descriptively to document their purpose.
        severity: low

  - name: resource_management
    description: Resource lifecycle and dependency management
    rules:
      - name: use-prevent-destroy-wisely
        description: Add lifecycle prevent_destroy = true to critical resources like databases and storage. This prevents accidental deletion. Remove the flag only when intentionally destroying resources.
        severity: medium

      - name: configure-lifecycle-rules
        description: Use create_before_destroy for zero-downtime replacements. Configure ignore_changes for attributes managed outside Terraform. Understand lifecycle implications for each resource type.
        severity: medium

      - name: explicit-dependencies
        description: Use depends_on only when implicit dependencies are insufficient. Prefer reference-based implicit dependencies. Explicit depends_on should be documented with comments explaining why.
        severity: low

      - name: use-count-and-for-each
        description: Use count for conditional resource creation and for_each for creating multiple similar resources. Prefer for_each over count when resources have unique identifiers to prevent recreation on changes.
        severity: medium

  - name: drift_prevention
    description: Change management and drift detection
    rules:
      - name: review-plan-output
        description: Always review terraform plan output before applying. Check for unexpected changes or destroys. Use -detailed-exitcode in CI to detect changes.
        severity: high

      - name: implement-apply-approval
        description: Require manual approval for terraform apply in production. Use Terraform Cloud/Enterprise or CI/CD gates for approval workflows. Never auto-apply to production.
        severity: high

      - name: detect-configuration-drift
        description: Regularly run terraform plan to detect drift. Investigate and resolve drift promptly. Configure drift detection in CI/CD or use Terraform Cloud drift detection.
        severity: medium

      - name: import-existing-resources
        description: Use terraform import to bring existing resources under management. Document imports and verify state accuracy. Consider using import blocks (Terraform 1.5+) for declarative imports.
        severity: medium