Terraform¶
Overview¶
Infrastructure is managed with Terraform (>= 1.6.0) using the AWS provider (~> 6.0, since September 2026). State is stored remotely in S3 with file-based locking and encryption.
Each environment lives in its own AWS account and has its own state file. CI runs terraform fmt -check and
terraform validate on every pull request and those checks are required on main; applies are still run locally
after review.
Repository Structure¶
infra/
├── environments/
│ ├── prod/
│ │ ├── eu-central-1/ # Production core, admin-portal, vault, edge, atrax-api,
│ │ │ # security baseline (also manages eu-west-2 / us-east-1
│ │ │ # GuardDuty and EBS defaults via provider aliases)
│ │ └── eu-west-1/ # Production atrax-node (region-isolated)
│ └── stage/
│ ├── eu-central-1/ # Staging core, admin-portal, dash, vault, edge, atrax-api
│ └── eu-west-1/ # Staging atrax-node
└── modules/
├── core/ # Core-group services
│ ├── core-api/
│ ├── admin-portal/ # staff admin (Next.js), core cluster
│ ├── atrax-api/ # atrax controller, lives on the core cluster
│ ├── ecr/ # core-group ECR repos
│ └── ecs/ # core ECS cluster
├── atrax/ # atrax-node only (region-isolated workers)
│ ├── ecr/ # atrax-node ECR repo (eu-west-1)
│ ├── ecs/ # atrax-node cluster: fixed EC2s + per-host EIPs
│ └── node/ # atrax-node ECS service / task def
├── dash/ # legacy dashboard host (iam, portal)
├── edge/ # cdn (stage-only CloudFront + Lambda@Edge), consent-queue,
│ # ecr, ecs, edge-api
├── monitoring/ # CloudWatch alarm modules (alb, ec2-asg, ec2-instance,
│ # ecs-cluster, ecs-service, grafana, rds-postgres, sqs-queue)
├── network/ # client-vpn (Entra-federated Client VPN)
├── security/ # account security baseline: config-recorder, guardduty,
│ # inspector, securityhub, vpc-flow-logs
└── vault/ # Vault analytics pipeline
├── clickhouse/
├── ecr/
├── ecs/
├── etl/ # shared ETL base + one module per service
└── vault-api/
Each environments/<env>/<region>/ directory is an independent root module with its own backend configuration. You run
terraform init and terraform plan from within that directory; terraform apply is run only by the person who
applies infrastructure state (see Who applies).
State Backend¶
State is stored in per-account S3 buckets with encryption and locking:
| Environment | Region | Bucket | Key |
|---|---|---|---|
| prod | eu-central-1 | cookiehub-terraform-state-prod-759286286879 |
prod/eu-central-1/terraform.tfstate |
| prod | eu-west-1 | cookiehub-terraform-state-prod-759286286879 |
prod/eu-west-1/terraform.tfstate |
| stage | eu-central-1 | cookiehub-terraform-state-stage-258618559895 |
stage/eu-central-1/terraform.tfstate |
| stage | eu-west-1 | cookiehub-terraform-state-stage-258618559895 |
stage/eu-west-1/terraform.tfstate |
The state buckets themselves both live in eu-central-1 regardless of which region's resources they describe — one bucket per environment, multiple state keys for multi-region environments.
Both use use_lockfile = true and encrypt = true (AES256).
Naming Convention¶
All resource names follow the pattern {env}-{region_short}-{group}-{component}:
This is generated from locals.tf in each root module:
locals {
region_short = {
eu-central-1 = "euc1"
eu-west-1 = "euw1"
}
name_prefix = "${var.environment}-${local.region_short}-${var.group}"
base_tags = {
Environment = var.environment
Region = var.region
Group = var.group
ManagedBy = "terraform"
}
}
The name_prefix and base_tags are passed down to every module.
Module Conventions¶
Each module follows a standard file layout:
| File | Purpose |
|---|---|
main.tf |
Resource definitions |
variables.tf |
Input variables |
outputs.tf |
Output values |
versions.tf |
Provider constraints |
data.tf |
Data sources (when needed) |
Modules are small and purpose-specific. A typical service module manages:
- ECS task definition (with SSM secrets)
- ALB target group and listener rules
- Route53 DNS record
- IAM roles and security group
- CloudWatch log group
All modules receive common variables: name_prefix, environment, region, group, vpc_id, subnet_ids, and
base_tags.
How to Apply Changes¶
Prerequisites¶
- AWS CLI v2 with the two SSO profiles
cookiehub-stageandcookiehub-prod(IAM Identity Center federated to Entra ID; the~/.aws/configsnippet is in the infra README). Access requires thesec-infraEntra group. - Terraform >= 1.6.0 installed
- Optional:
direnv.environments/<env>/.envrcexports the right profile and runsscripts/check-aws-account.sh, which refuses to continue if the active account is not the expected one.
Workflow¶
# 1. Sign in and select the profile (sessions last 8 hours)
aws sso login --profile cookiehub-stage # or cookiehub-prod
export AWS_PROFILE=cookiehub-stage # or cookiehub-prod
# 2. Navigate to the environment
cd environments/stage/eu-central-1
# 3. Initialize (first time or after adding modules)
terraform init
# 4. Review changes
terraform plan
# 5. Apply: Ástþór only, after the pull request is reviewed (see below)
terraform apply
Manual applies only
CI formats and validates every pull request, but nothing applies automatically. All changes are applied
locally after the PR is reviewed. Always run terraform plan first and read the output before applying;
for imports of existing resources the plan should show imports and, at most, tag additions.
Who applies¶
Ástþór applies Terraform, through an Infrastructure & Security issue and a pull request he reviews. Nobody else
applies, and never an assistant. Everyone else's part is the pull request: write the change, run terraform plan
and put the output on the PR, and let CI format and validate it.
Environment Differences¶
| Production | Stage | |
|---|---|---|
| AWS Account | 759286286879 | 258618559895 |
| Regions | eu-central-1 + eu-west-1 (atrax-node); GuardDuty also in eu-west-2, us-east-1 | eu-central-1 + eu-west-1 (atrax-node) |
| Vault services | Yes (2 × c7i.xlarge ECS hosts, m7i.xlarge ClickHouse) | Yes (1 × t3.medium ECS host, t3.medium ClickHouse) |
| Atrax services | api on the core cluster; 2 × r6a.xlarge nodes in eu-west-1 | api on the core cluster; 1 × t3.medium node |
| Core API (Hono) | Module deployed, service at 0 tasks — live core API is still Laravel on the legacy host | Yes |
| Admin Portal | Yes (cha.cookiehub.net) |
Yes (cha.stage.cookiehub.net) |
| Edge API | Yes, 2 tasks on a c7i.large edge cluster, behind edge.cookiehub.net CloudFront |
Yes, 1 × t3.small edge cluster, edge-api.stage.cookiehub.net |
| Edge CDN module | No — Live CDN is console-managed (IS-66) | Yes (modules/edge/cdn, Lambda@Edge + Logging v2) |
| Public ALB hosts | atrax-api, core-api, cha, edge, edge-origin, consent-eu, region-eu | atrax-api, core-api, cha, dash, dash-next, edge-api, edge-origin |
| Internal ALB | vault-api.internal.cookiehub.net |
vault-api.internal.stage.cookiehub.net |
| Core ECS hosts | 2 × t3.small | 2 × t3.small |
| Security baseline | GuardDuty, Security Hub, Config, CloudTrail, Inspector, flow logs (all Terraform-managed) | Inspector only |
Security Baseline¶
Since September 2026 (IS-67) the account controls live in modules/security/ and are applied from
environments/prod/eu-central-1:
| Control | Module / file | Where |
|---|---|---|
| VPC flow logs | modules/security/vpc-flow-logs |
prod eu-central-1 and eu-west-1 |
| Inspector + VM-01..05 suppression rules | modules/security/inspector |
both prod regions and both stage regions |
| GuardDuty detectors, features, IS-111 noise filters | modules/security/guardduty |
all four prod regions |
| AWS Config recorder | modules/security/config-recorder |
prod eu-central-1 and eu-west-1 |
| Security Hub (AFSBP, disabled controls, aggregator, automation rules) | modules/security/securityhub, securityhub.tf |
prod eu-central-1 and eu-west-1 |
| CloudTrail, IAM password policy, EBS defaults, Access Analyzer | cloudtrail.tf, iam_account.tf, ec2_account.tf |
prod eu-central-1 |
environments/prod/eu-central-1/security_baseline.tf is the decision log: what is managed, what is deliberately
left out and why (for example the account-level S3 Block Public Access, which two public-by-design buckets prevent).
Security Hub standards are not pinned; AWS's AFSBP revisions are followed and controls that do not apply are
disabled with a reason.
Console-created resources are adopted with import blocks in a temporary imports.tf, planned to zero diff,
applied, and the blocks removed afterwards.
What's Not in Terraform¶
Created by hand and still unmanaged, each for a reason recorded in security_baseline.tf or the referencing file:
- Prod S3 buckets other than the atrax, flow-log, Config and CloudTrail buckets — 16 of 23, including
cookiehub-cdn,cookiehub-release,cookiehub-consentand the log-destination buckets. Referenced bydatasources or by ARN where a module needs them. Stage is fully declared in itss3.tfexcept the three legacyatrax-stage-*buckets. - The Live CDN and Consent-log CloudFront distributions (
cookiehub.net,consent.is,consent.cookiehub.net) and the Lambda@Edge functions behind them in us-east-1 — being retired as edge-api takes over their paths (IS-60, IS-66). - Legacy hosts: the Laravel dashboard host
cs150pand its MariaDB, and the old atrax Postgres in eu-west-1. cookiehub.comDNS — a Cloudflare zone, not Route53.- SSM Quick Setup StackSets and Audit Manager — service-owned; nothing to manage.