AWS deployment design (Terraform not shipped)

The BitzOrcas repository does not currently ship a versioned, production-supported AWS Terraform module. This page defines deployment constraints, not copy-and-run infrastructure. Teams may implement their own module from it, with separate review, testing, and ownership.

Service mapping

Terraform acceptance line

A module should cover private networking, security groups, encryption, secret injection, logs and metrics, backups, remote state locking, and environment boundaries. Decide SQL Server versus PostgreSQL and ECS versus EKS during design; this guide deliberately does not choose for every deployment.

Before the first production release, rehearse failover, database restore, Redis key-ring restore, and message-backlog recovery. Call a module “supported” only after those checks pass.

Make irreversible choices first

ECS and EKS both run containers; they differ in control-plane, networking, upgrades, scaling, and operations ownership. A team without Kubernetes operations should not select EKS merely to standardize YAML.

SQL Server versus PostgreSQL affects provider support, migration, collation/time, backups, authorization, and parity evidence. Confirm production adapters and tests before provisioning RDS.

Amazon MQ needs CAP, TLS, topology permission, retry, and backlog evidence. ElastiCache may carry coordination and Data Protection state as well as caches, so “flush at any time” is not universal.

Suggested module boundaries

# ① Root composition consumes stable interfaces from owned submodules.
module "database" {
  source              = "./modules/database"
  environment         = var.environment
  subnet_ids          = module.network.private_subnet_ids
  deletion_protection = var.environment == "production"
}

module "api" {
  source         = "./modules/container-service"
  image_digest   = var.api_image_digest
  subnet_ids     = module.network.private_subnet_ids
  secret_arns    = module.secrets.api_secret_arns
  readiness_path = "/health/ready"
  liveness_path  = "/health/live"
}

This illustrates interfaces and immutable digests, not a repository module. Production IaC also needs provider locks, encrypted remote state and locking, tag policy, retention, and organization guardrails.

Network and identity

• run API/JobHost in private subnets and expose only API through ingress;
• allow database, MQ, and Redis only from owner task security groups;
• use task roles/IRSA for S3, Secrets Manager, KMS, and telemetry;
• prohibit long-lived keys in task definitions, tfvars, and CI logs;
• control egress through NAT/VPC endpoints with documented data flows;
• align ALB forwarding, TLS, and WebSockets with Forwarded Headers.

Secrets and configuration

# ② References only; the platform resolves real values from Secrets Manager.
environment:
  # Non-sensitive environment identity stays in ordinary variables.
  ASPNETCORE_ENVIRONMENT: Production
  OTEL_SERVICE_NAME: BitzOrcas.Api
  OTEL_DEPLOYMENT_ENVIRONMENT: production
secrets:
  # Store ARN references only; task startup resolves the values.
  ConnectionStrings__Default: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/db-credentials
  RabbitMq__Password: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/rabbitmq-password
  Licensing__Runtime__TrustedPublicKeys__0: arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:bitzorcas/license-public-key

License DeploymentId/cache and the Data Protection key ring need persistence across task replacement with restricted identity access. Ephemeral storage changes identity and breaks cookie/token compatibility during rollout.

Release and migration

1. Generate plans only in a protected environment with a readable summary.
2. Complete backup, VERIFYONLY, and expand migrations first.
3. Start candidates without traffic and validate startup guards plus readiness.
4. Canary immutable digests while watching error budget, queues, and database.
5. Roll back task definitions at stop conditions; forward-fix schema.
6. Contract schema and clean resources only after observation.

State, drift, and destroy protection

Encrypt, version, lock, and restrict production state. CI runs format, validate, security policy, and approved plans. Periodic refresh-only plans detect console drift.

Enable deletion protection or retain policy for RDS, S3, backup vaults, KMS keys, and logs. Destruction needs separate approval and never runs from an ordinary PR.

Observability and recovery

CloudWatch resource metrics do not replace application OTel. API/JobHost still emit service name, version, environment, traces, and business meters with runbook-linked alerts.

Drills restore RDS into isolation, attach object copies, recover Redis/key rings, control RabbitMQ replay, and execute tenancy, file, workflow, and audit smoke.

Delivery checklist

• an ADR records ECS/EKS, database, and region choices;
• images use digests and providers/modules are version-locked;
• network, IAM, KMS, secrets, and egress follow least privilege;
• real ALB tests cover startup guards, live/ready, and termination;
• migration, backup, restore, rollback, and region failure are drilled;
• cost, capacity, retention, and residency have owners;
• Terraform has versions, upgrade notes, tests, and support matrix;
• until then, material retains “planned/not delivered.”

See also

• Deployment overview
• Production security checklist