Skip to content

AWS Terraform Backend and Bootstrap Plan

Purpose

This document defines how to store Terraform state for the ECS migration and how to bootstrap the project-owned infrastructure without touching any central/shared state.

This is the practical follow-on from the project-specific state decision.

Decision Summary

  • Use an S3 backend for Terraform state.
  • Use separate state keys for staging and production.
  • Use state locking for concurrent safety.
  • Keep backend resources project-specific, not central/shared.
  • Bootstrap the empty staging account with a minimal initial step, then manage everything else from the project Terraform code.

Backend Choice

Use the Terraform S3 backend for remote state storage.

That gives us:

  • persistent shared state for team use
  • easy separation by environment
  • simple AWS-native storage
  • no dependence on the local filesystem for day-to-day operations

State Locking

Use locking for all applies.

If the chosen Terraform version and backend setup support S3 native locking in your workflow, use that. If the organisation standard is still to pair S3 state with a lock table, use that pattern.

The important requirement is that only one apply runs against a given state at a time.

State Layout

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

Use a project-specific bucket naming scheme in the account that owns the environment.

Examples:

  • staging state bucket in the staging account
  • production state bucket in the production account

Do not place this project’s state in a central/shared bucket unless the organisation explicitly requires that and ownership is documented.

Bootstrap Approach

Why Bootstrap Is Needed

Terraform cannot manage its own backend until the backend exists.

So the first step is to create only the minimum resources required for Terraform to run.

Bootstrap Scope

Create only:

  • the S3 bucket for state
  • locking support if required
  • backend access roles or policies if required

Do not mix the bootstrap layer with the application infrastructure layer.

  1. Create the backend bootstrap resources.
  2. Copy the backend template to a real backend.hcl file and configure Terraform to use it.
  3. Apply the project network and ECS foundation.
  4. Apply the service-specific resources.

Staging Backend File

For the staging stack, keep the backend settings in a local file that is not committed to the repo.

Recommended workflow:

  1. Copy infra/envs/staging/backend.hcl.example to infra/envs/staging/backend.hcl.
  2. Keep the real file out of version control.
  3. Run terraform -chdir=infra/envs/staging init -reconfigure -backend-config=backend.hcl.

Empty Staging Account Strategy

The empty staging account gives us room to keep the layout clean. Production already exists, so the production apply path may be additive rather than fully bootstrap-from-zero.

Recommended order:

  1. Backend bootstrap
  2. VPC and routing
  3. Security groups
  4. ECS cluster
  5. ALB and DNS
  6. Logs and alarms
  7. Secrets and parameters
  8. Database and Redis wiring
  9. ECS services
  10. Smoke tests

This order keeps dependencies moving in one direction and avoids circular infrastructure references.

Identity Center Note

IAM Identity Center is already configured and users already have access to the account they need.

That means this project does not need to design human access from scratch. It only needs to use the existing account access model when applying Terraform and operating the environment.