autojanet/skills/terrashark/references/do-dont-patterns.md

Do and Don't Patterns

Use this guide as a fast checklist for safe Terraform/OpenTofu output.

Identity and iteration

Do:

• use for_each with stable, business-meaningful keys
• keep identity keys separate from mutable attributes
• add moved blocks when renaming resources or module addresses

Don't:

• use list index as long-lived identity
• derive identity from a computed attribute
• delete/rename addresses without an explicit migration plan

Secrets and sensitive data

Do:

• mark secret outputs as sensitive = true
• use secret managers and data sources for runtime injection
• avoid logging sensitive values in locals or output

Don't:

• put secrets in default values or .tfvars committed to VCS
• echo secrets in provisioner commands
• rely on sensitive alone to protect state contents

State boundaries and blast radius

Do:

• keep production in isolated state backends or workspaces
• split large stacks by lifecycle and ownership
• use environment protection and approvals for apply

Don't:

• mix unrelated systems in a single root state
• apply directly to production from unreviewed branches
• use one monolithic stack for all environments

Module contracts

Do:

• expose typed inputs and explicit outputs
• use optional() for evolution-friendly contracts
• validate invariants with validation and precondition

Don't:

• accept untyped map(any) for core interfaces
• expose entire provider objects as outputs
• push environment-specific policy into primitive modules

Providers and versions

Do:

• pin runtime and providers with bounded constraints
• commit .terraform.lock.hcl intentionally
• pass provider aliases explicitly to child modules

Don't:

• float provider versions
• rely on implicit provider inheritance in multi-region setups
• mix upgrades with functional changes in the same PR

Data sources and dependencies

Do:

• use data sources for read-only integration
• model dependencies via input/output wiring
• keep depends_on for real ordering requirements only

Don't:

• use depends_on to paper over missing interfaces
• use data sources for identity fields that can change
• create hidden ordering between unrelated resources

CI/CD and policy

Do:

• separate plan and apply
• keep an auditable reviewed plan artifact
• run policy and cost checks on every plan

Don't:

• allow direct apply from arbitrary branches
• skip policy checks for production changes
• delete plan artifacts before approval

Testing

Do:

• run terraform test / tofu test for module-level checks
• use Terratest for workflow or integration validation
• tier tests by risk and cost

Don't:

• rely on plan-only validation for runtime-only attributes
• run destructive tests without isolation and cleanup
• treat mocked provider tests as full integration coverage

Migration and refactors

Do:

• include moved or import strategy in the same change
• run a reviewed plan before any apply
• document rollback steps for destructive changes

Don't:

• rename resources without preserving state identity
• apply refactors without plan review
• remove resources without lifecycle transition