Terraform for AWS

Status: reference, not yet verified; community contributions welcome. CI runs terraform fmt -check, terraform validate and terraform test (a plan against a mocked AWS provider). Nobody has run terraform apply with it against a real AWS account yet. If you do, please open an issue or a pull request with what worked and what did not. See CONTRIBUTING.md.

This is the AWS guide, option A, as Terraform: the same architecture, security groups, task definitions and hardening, so read the guide first. The guide explains the choices; this file only explains how to use the module.

Why ECS on Fargate, not EKS#

• Nothing to run below the tasks. No cluster nodes, AMIs or Kubernetes upgrades to keep up with; a security team reviews task definitions, two ALBs and RDS.
• No model volume. The guard-spec-gateway-full image carries the L2 and L3 models, so every task starts with L1 + L2 + L3 and there is no EFS.
• EKS users already have a path. The Helm chart covers Kubernetes, including EKS (guide, option B). A Terraform module for EKS would mostly wrap that chart.

What it creates#

It does not create the VPC, subnets, NAT gateway, ACM certificates, DNS records, a WAF or a state backend. Bring your own and pass their IDs.

Variables you will set#

The full list with descriptions is in variables.tf; a filled example is terraform.tfvars.example.

Use#

You need Terraform 1.6 or newer and AWS credentials for the target account. Configure a backend first (S3 with locking); the state holds no secret values but does hold your network layout.

1. First apply, no tasks.

cd deploy/terraform/aws
cp terraform.tfvars.example terraform.tfvars   # fill in; keep both desired counts at 0
terraform init
terraform plan -out tfplan
terraform apply tfplan

2. Put the secret values in (from a shell with access to the account):

put() { aws secretsmanager put-secret-value --secret-id "guard-spec/$1" --secret-string "$2" >/dev/null; }
put app-password   "$(openssl rand -hex 32)"
put jwt-secret     "$(openssl rand -hex 32)"
put mfa-enc-key    "$(openssl rand -base64 32)"
put admin-password "$(openssl rand -hex 16)"
put upstream-llm-key '<your-upstream-key>'        # only with upstream_llm_url

Copy mfa-enc-key to an offline vault now and keep it with your RDS snapshots: without it nobody with 2FA can log in, and there is no re-encryption step, so never rotate it automatically.

3. Migrations and the application password. Terraform does not run them. From a host inside the VPC with Docker and a checkout of the release tag, follow Migrations and the application password, with DB_HOST and OWNER_SECRET_ARN from terraform output db_address and terraform output db_owner_secret_arn. Give that host's security group in migration_host_security_group_id (or add the rule yourself).

4. Start the services. Set gateway_desired_count and control_plane_desired_count (for example 2 and 1) and apply again. Then point DNS at the outputs gateway_alb_dns_name and control_plane_alb_dns_name (a private zone for the admin host) and check:

curl -s https://<gateway-host>/readyz | jq .detector
# {"layers":["l1","l2","l3"],"degraded":false,"onnx":true,...}

Upgrade#

Take an RDS snapshot, run the migrations of the new tag (step 3), then set image_tag (or the digests) and apply. A failing deployment rolls back to the previous task definition by itself; a schema change does not roll back, so restore the snapshot (with its mfa-enc-key) if you must go back. See the guide's Upgrade and rollback.

Known gaps#

• Not applied against a real account yet (see the status above).
• No migration task: migrations run from a host in the VPC, as in the guide.
• No metrics collector, alarms, WAF, ALB access logs or VPC endpoints. The guide's Observability and Hardening checklist list what to add.
• No SSO (OIDC_SECRET_*), named upstream (UPSTREAM_KEY_*) or alert channel secrets. Add a secret per value and extend gateway_secrets / control_plane_secrets in ecs.tf and the execution role policies in iam.tf.

Checks#

terraform fmt -check -recursive
terraform init -backend=false
terraform validate
terraform test     # plans against a mocked AWS provider; no credentials needed

Source: deploy/terraform/aws/README.md @ ca69dad29f02