Production-ready Terraform for the Bellona Remote Gateway on AWS: an internet-facing Application Load Balancer, the gateway on ECS Fargate, RDS PostgreSQL, ElastiCache Redis, an S3 artifact bucket, CloudWatch logs/alarms, a coturn TURN relay on EC2, automated backups, and a smoke test.
Honesty note. This Terraform IS the deliverable and is validated with
terraform init,terraform validate, andterraform fmt -check(all pass — AWS provider~> 5.0). The liveterraform applyis account/credential-gated and is not run here — it would create real, billable AWS resources. After a real apply, run the smoke test against the ALB; it fails loud (exit non-zero) without a deployed URL and never fabricates a pass.
Topology#
internet
│ 80 → 301 → 443 (ACM cert)
▼
┌──────────────────┐ public subnets (2 AZ)
│ ALB (HTTPS/WSS) │
└─────────┬─────────┘
target group :4070 (IP targets, /health check, sticky)
▼
┌──────────────────┐ private subnets (2 AZ)
│ ECS Fargate │──┬─ RDS Postgres (multi-AZ, encrypted, backups)
│ gateway tasks x2 │ ├─ ElastiCache Redis (TLS, failover)
└──────────────────┘ └─ S3 artifacts (versioned, lifecycle)
│ secrets from Secrets Manager, logs → CloudWatch
│
┌──────────────────┐ EC2 + Elastic IP, public subnet
│ coturn TURN relay │ 3478/5349 + relay 49160-49200 (180.C.25.04)
└──────────────────┘
- ALB is the only public HTTP edge; it forwards
:4070to the gateway target group and only the ALB security group can reach the gateway. - Gateway runs as Fargate tasks in private subnets, egress via NAT.
- RDS and Redis accept connections only from the gateway security group.
- S3 blocks all public access; versioning + lifecycle are enabled.
- TURN runs on EC2 with a stable Elastic IP (Fargate can't host a wide UDP relay range well).
Files#
| File | Contents |
|---|---|
versions.tf |
Terraform + provider pins (aws ~> 5.0), S3 backend (commented). |
variables.tf |
All inputs (sizes, domain, secrets, retention). |
network.tf |
VPC, public/private subnets, IGW, NAT, route tables. |
security.tf |
SG-referenced rules (alb→gateway→rds/redis; turn public). |
data-plane.tf |
RDS Postgres, ElastiCache Redis, S3 bucket + versioning/lifecycle. |
gateway.tf |
ALB, target group, listeners, ECS cluster/service/task, IAM, logs. |
turn.tf |
coturn EC2 + Elastic IP + cloud-init. |
secrets.tf |
Secrets Manager secret + generated RDS password. |
monitoring.tf |
CloudWatch alarms (ALB/ECS/RDS/EC2) + SNS + dashboard. |
outputs.tf |
ALB DNS, gateway URL, TURN IP, endpoints, log group, SNS ARN. |
terraform.tfvars.example |
Example variables (copy → terraform.tfvars). |
Env wiring (mirrors the gateway config)#
The ECS task definition (gateway.tf) sets the gateway env from
apps/bellona/remote-gateway/src/config.ts:
- Non-secret env:
NODE_ENV,BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0,BELLONA_REMOTE_GATEWAY_PORT,…_LOG_LEVEL,…_HOST_TOKEN_TTL_MS, plus the S3/TURN coordinates. - Secrets (
secretsblock, from Secrets Manager — never plaintext):BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET,BELLONA_DATABASE_URL(…?sslmode=require),REDIS_URL(rediss://),BELLONA_TURN_STATIC_AUTH_SECRET.
HOST=0.0.0.0 is safe because the gateway SG only admits the ALB on :4070.
Deploy#
1. Prerequisites#
- An ACM public certificate for
gateway_domaininaws_region, DNS-validated (for auto-renewal). Paste its ARN intoacm_certificate_arn. - The gateway image pushed to ECR (or another registry your account can pull).
- A remote state backend (uncomment the
backend "s3"block inversions.tfand pre-create the bucket + lock table — seedeploy/terraform/backend-bootstrap).
2. Configure#
cd infra/bellona-remote/aws
cp terraform.tfvars.example terraform.tfvars # KEEP OUT OF GIT (.gitignore'd)
# Fill in: gateway_domain, acm_certificate_arn, gateway_image, and the two
# secrets. Generate secrets with: openssl rand -base64 48
$EDITOR terraform.tfvars
3. Plan + apply#
terraform init
terraform plan
terraform apply
4. DNS#
Point gateway_domain at the ALB using the outputs:
terraform output alb_dns_name # CNAME target (or Route 53 alias → alb_zone_id)
5. Smoke test#
BELLONA_SMOKE_BASE_URL="$(terraform output -raw gateway_base_url)" ../smoke/smoke-test.sh
Asserts /health, /ready, the /v1/pairing/exchange rejection, and
/v1/devices. Without BELLONA_SMOKE_BASE_URL it exits non-zero.
Backups#
- RDS: automated daily snapshots retained
postgres_backup_retention_days(default 14),copy_tags_to_snapshot, a final snapshot on delete, anddeletion_protection. Point-in-time restore is available within the window. - S3: versioning enabled + a lifecycle rule expiring prior versions after 90 days and aborting dangling multipart uploads after 7 days, so an overwritten/deleted artifact is recoverable.
- Redis: daily snapshots retained 7 days.
Monitoring & logs#
- Logs: the gateway logs to CloudWatch group
/bellona/<env>/remote-gateway(retentionlog_retention_days); RDS exportspostgresqllogs to CloudWatch. - Alarms (→ SNS
alarms_sns_topic_arn; subscribe email/PagerDuty): ALB no-healthy-hosts, ALB 5xx, ECS CPU, RDS CPU, RDS low storage, TURN EC2 status check. - Dashboard:
${name_prefix}-${environment}-gateway(ALB requests/5xx + healthy hosts).
TURN / TLS notes#
turn.tf cloud-init installs coturn with the shared static-auth-secret and the
instance's Elastic IP as external-ip. For TURN-over-TLS (:5349), install a
certificate for gateway_domain on the instance (ACM-exported or certbot) and
add cert=/pkey= lines, then restart coturn. The gateway derives short-lived
TURN credentials from the same turn_static_auth_secret, and the WebRTC
direct-vs-relay metric (180.C.25.04) records this server as the relay when a
session falls back to it.
Limitations (honest)#
terraform applyis not run here (account-gated, billable). The config is validated for syntax + consistency (terraform validate/fmt -checkpass).- The gateway ships a first-stage JSON store today; RDS/Redis/S3 are provisioned and wired (correct SGs, endpoints, secrets) ahead of the gateway's persistence/artifact code paths consuming them. On Fargate, that JSON store is per-task ephemeral until those paths land — run a single task, or front it with the RDS store, for durable state until then.
- TURN TLS requires a one-time cert install on the EC2 instance (documented above); the relay itself (STUN/TURN/UDP) works from cloud-init as written.
- A live WebRTC media-relay smoke (an actual relayed session through coturn)
needs real peers and is outside the smoke script; the metric classification it
feeds is unit-tested in
libs/bellona/remote-protocol/src/stream.test.ts.