Terraform roots

Atlas keeps reusable infrastructure logic in shared modules and instantiates that logic from three environment roots.

Root inventory

Root file	Purpose
backend.tf	S3 backend and DynamoDB locking configuration
providers.tf	AWS provider configuration
versions.tf	Terraform and provider version constraints
data.tf	environment-level data sources such as availability zones
locals.tf	name prefixes, common tags, and secret templates
variables.tf	root inputs and validation
main.tf	module wiring and any root-level listener rules
monitoring.tf	SNS topics, alarms, dashboard resources, and budget notifications
outputs.tf	operator-facing outputs and integration values

Root roles

Root	Role
terraform/staging	primary staging root that owns the shared staging VPC, subnets, security groups, MSK cluster, application ECR repositories, and the first workload plane
terraform/staging2	second staging workload root with its own state key that reuses the shared foundation exported by terraform/staging
terraform/prod	production root with its own independent foundation and workload plane

What the full-foundation roots instantiate

terraform/staging and terraform/prod both instantiate:

• events_ecr
• dashboard_ecr
• scoring_ecr
• vpc
• events_secret
• dashboard_secret
• scoring_secret
• camunda_secret
• msk
• optional sink buckets and msk_s3_sink
• alb
• optional newrelic_aws_pull_integration, enabled in staging and disabled in prod
• New Relic dashboards for non-events ECS services, RDS, and MSK
• events_service
• dashboard_backend
• scoring
• camunda
• elasticache_valkey
• dashboard_db
• camunda_db
• kafka_ui
• environment_operations, enabled in staging and disabled in prod, with a separate toggle to keep Scheduler entries suspended
• optional slack_alarm_delivery through monitoring.tf when Slack alert forwarding is enabled

What staging2 instantiates

terraform/staging2 keeps the same root file structure but intentionally omits the foundation resources already owned by terraform/staging.

It creates:

• events_secret
• dashboard_secret
• scoring_secret
• camunda_secret
• alb
• events_service
• dashboard_backend
• scoring
• camunda
• elasticache_valkey
• dashboard_db
• camunda_db
• kafka_ui

It reuses from terraform/staging remote state and AWS data lookups:

• VPC and public/private subnets
• approved shared security groups
• MSK cluster ARN and TLS bootstrap brokers
• application ECR repositories

Why the roots exist separately

• separate state files and lock scopes
• separate backend resources and keys
• nearly the same module graph with environment-specific values
• a clear migration path from the current staging deployment to a harder production posture

staging2 is the deliberate exception to “same module graph”: it keeps state isolation while consuming the shared staging foundation instead of minting a second copy of that foundation.

Read order for operators

1. Confirm the correct state backend, hostnames, ACM certificate, and access settings for the target root.
2. Read main.tf to verify which modules and listener rules are active in the root.
3. Inspect outputs.tf after apply to locate hostnames, internal service endpoints, repository URLs, secret names, and database connection details.

For staging2, also confirm that terraform/staging has already been applied with the latest shared outputs before planning.