Eve library

Bellona Remote — Production AWS Deployment (180.C.25.09)

Other

Revision 1

On this page

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, and terraform fmt -check (all pass — AWS provider ~> 5.0). The live terraform apply is 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#

text
                     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 :4070 to 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 (secrets block, 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_domain in aws_region, DNS-validated (for auto-renewal). Paste its ARN into acm_certificate_arn.
  • The gateway image pushed to ECR (or another registry your account can pull).
  • A remote state backend (uncomment the backend "s3" block in versions.tf and pre-create the bucket + lock table — see deploy/terraform/backend-bootstrap).

2. Configure#

sh
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#

sh
terraform init
terraform plan
terraform apply

4. DNS#

Point gateway_domain at the ALB using the outputs:

sh
terraform output alb_dns_name   # CNAME target (or Route 53 alias → alb_zone_id)

5. Smoke test#

sh
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, and deletion_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 (retention log_retention_days); RDS exports postgresql logs 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 apply is not run here (account-gated, billable). The config is validated for syntax + consistency (terraform validate / fmt -check pass).
  • 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.