shoc-backend/terraform/README.md

# Terraform deployment infrastructure

Terraform adopts the environment-owned Sea Haven backend infrastructure while
keeping shared and Elastic Beanstalk-generated resources outside state.

## Roots

- `live/dev/` imports the existing dev environment-owned resources.
- `live/staging/` imports the existing staging environment-owned resources.

Shared RDS, application, VPC, subnet, service-role, shared-certificate, and
Elastic Beanstalk-generated inventory remains data-only or provider-managed.
Secret metadata is managed, but secret values are never authored in Terraform
configuration. Elastic Beanstalk receives secret values through
`environmentsecrets` ARN/key references.

The Sentry DSN is public ingestion configuration, not a secret: each root passes
it through the required `sentry_dsn` module variable as the plain
`SENTRY_DSN` environment setting. `SENTRY_ENVIRONMENT` is `development` for the
dev root and the root environment name otherwise. Production has no Terraform
root yet; production Sentry wiring will reuse the same variable when one is
added.

## HCP credentials

Org-baseline CloudFormation owns the HCP Terraform plan/apply roles and their
manager tags. The retired `shoc-backend-bootstrap` workspace and backend
bootstrap root were removed after the four dev/staging roles transferred
without replacement.

## Environment adoption

Follow [`live/README.md`](live/README.md). For each dev/staging adoption, the
first plan must import the environment-owned resources with zero create,
update, delete, or replacement actions. The second reviewed phase may update
only explicitly allowlisted ownership metadata and the narrowed dev deploy S3
policy.

The GitHub Environment **variable** `DEPLOY_ROLE_ARN` is the OIDC role used
by application CD. Environment secrets `TF_API_TOKEN` and
`AWS_DEPLOY_ROLE_ARN` were removed at cutover.

## Local validation

```bash
terraform fmt -check -recursive terraform
terraform -chdir=terraform/live/dev init -backend=false
terraform -chdir=terraform/live/dev validate
terraform -chdir=terraform/live/staging init -backend=false
terraform -chdir=terraform/live/staging validate
python scripts/test-terraform-import-plan-check.py
python3 scripts/test_next_release_tag.py
python3 scripts/test_require_commit_checks.py
python3 scripts/test_check_app_terraform_isolation.py
```