# Terraform Foundation

Lilith's infrastructure-as-code stack is organized as composable Terraform
modules layered around the AWS control plane. The goal is to build a repeatable,
auditable baseline that the delivery platform can promote through dev → staging
→ prod without retooling the primitives.

## VPC & Subnet Topology

The `networking` module provisions a deterministic CIDR plan per environment:

- Creates an IPv4 VPC with DNS hostnames/support enabled and project/environment
  tags.
- Carves `/20` public and private subnets per Availability Zone, exposing public
  subnets for ingress controllers and reserving private subnets for workloads.
- Attaches an Internet Gateway, configures per-subnet route tables, and wires
  security groups for the EKS control plane and node pools.
- Exports VPC identifiers, subnet IDs/CIDRs, NAT gateway IDs, and route table
  IDs so downstream modules (EKS, multi-region DNS) can reuse the topology.

## NAT & Egress Strategy

The module supports either a single shared NAT gateway or one per AZ. Elastic
IPs are created alongside NAT gateways and associated with the public subnets.
Dedicated private route tables point default routes to the NAT layer to maintain
deterministic egress without exposing workloads publicly.

## DNS & TLS Certificates

DNS is handled by the `multi-region` module via a managed Route 53 hosted zone,
health checks, and weighted failover records for primary/secondary (and optional
tertiary) regions. Public TLS is managed by the `security` module, which
provisions ACM certificates (public and wildcard/internal), automates DNS
validation records, and exposes ARNs for ingress controllers and load balancers.

## KMS & Vault Integration

Centralized secret management relies on a dedicated KMS CMK from the `security`
module; the key encrypts S3 media, EKS secrets, and Vault storage. The `vault`
module deploys HashiCorp Vault via Helm with TLS material stored in Kubernetes
secrets, an IAM role bound through IRSA, and bootstrap configuration referencing
the shared KMS key. Module outputs surface Vault endpoints, service account
details, and secret engine paths for downstream automation.

## Verification & Usage

The root Terraform stack (`deploy/terraform/main.tf`) composes these modules and
exports their outputs. Compliance coverage in
`tests/infra.terraform-foundation.spec.ts` ensures the documentation and modules
stay in lockstep. Run `terraform init` / `terraform plan` from
`deploy/terraform/` after providing provider credentials and
environment-specific variables.
