Skip to content

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}:

stage-euc1-core-ecs-cluster
prod-euc1-vault-clickhouse
stage-euc1-atrax-atrax-api

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-stage and cookiehub-prod (IAM Identity Center federated to Entra ID; the ~/.aws/config snippet is in the infra README). Access requires the sec-infra Entra group.
  • Terraform >= 1.6.0 installed
  • Optional: direnv. environments/<env>/.envrc exports the right profile and runs scripts/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-consent and the log-destination buckets. Referenced by data sources or by ARN where a module needs them. Stage is fully declared in its s3.tf except the three legacy atrax-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 cs150p and its MariaDB, and the old atrax Postgres in eu-west-1.
  • cookiehub.com DNS — a Cloudflare zone, not Route53.
  • SSM Quick Setup StackSets and Audit Manager — service-owned; nothing to manage.