Skip to content

AWS Terraform State Ownership and Project Layout

Purpose

This document answers the question of whether this migration should use project-specific Terraform and whether it should interact with any central/shared Terraform state.

The short answer is:

  • yes, Terraform can be the right tool for this project
  • no, this migration should not write to or depend on central/shared state unless there is no alternative

Decision Summary

  • Keep this project in its own Terraform root configuration.
  • Keep this project in its own Terraform state for staging.
  • Keep this project in its own Terraform state for production.
  • Do not modify any central/shared Terraform state as part of this migration.
  • Share reusable modules only if needed, but keep state ownership project-specific.
  • Use separate backends or state keys per environment.

Ownership Model

Project Scope

This migration should own:

  • the project VPCs
  • subnets
  • route tables
  • security groups
  • ECS clusters and services
  • ALBs and target groups
  • Route 53 records for this project
  • Secrets Manager and Parameter Store entries for this project
  • CloudWatch log groups and alarms for this project
  • task roles and execution roles for this project

Not Project Scope

This migration should not own:

  • organization-wide AWS platform resources
  • shared network foundations for unrelated projects
  • central identity or account bootstrap state
  • resources managed by other teams unless there is a clear handoff agreement

State Layout

Use a project-specific layout such as:

infra/
  modules/
    alb/
    ecs-service/
    iam/
    redis/
    rds/
    vpc/
  envs/
    staging/
    prod/

Each environment should point at its own backend state key.

Example State Separation

  • tracker-restapi/staging
  • tracker-restapi/prod

If the organisation uses a remote backend, the exact backend type can vary, but the state must remain separate by environment.

Central State Rule

Do Not Touch Central State

Do not add this project’s resources to a shared “central” Terraform state.

That creates avoidable coupling and makes review, rollback, and ownership harder.

Why

Keeping the project out of central state gives us:

  • cleaner ownership
  • narrower plan/apply scope
  • safer rollback
  • less chance of accidental cross-project changes
  • easier migration sequencing

Module Strategy

Shared Modules

Shared modules are acceptable if they are versioned and owned clearly.

Use them when they reduce duplication, but do not let shared modules hide the actual project ownership.

Avoid

  • giant central modules that configure multiple unrelated projects
  • hidden dependencies on outputs from other project states
  • cross-state write operations

Operational Rule

If a resource belongs to this migration, it lives in this project’s Terraform code and state.

If a resource belongs to the platform or another project, it stays out of this migration unless there is a documented dependency and ownership agreement.