# Kubernetes Platform

Lilith runs AWS EKS across dev, staging, and production environments with the
same Terraform modules so every cluster shares networking, security, and
operational guardrails.

## Cluster Topology

The `modules/eks` stack provisions a control plane per environment, pins it to
the project VPC, and encrypts Kubernetes secrets with the shared KMS CMK. Public
access remains optional via `var.endpoint_public_access` while private API
access is always enabled. Node groups land in the private subnets exported by
the networking module and inherit environment labels and tagging so Argo CD/Helm
releases target the correct cluster.

Each node group describes instance types, capacity type (on-demand or spot), and
desired/min/max sizes, and the module enables core EKS addons (`vpc-cni`,
`kube-proxy`, `coredns`) to stay current with the managed releases. IAM Roles
for Service Accounts (IRSA) are prewired for the VPC CNI and any downstream
addons.

## Autoscaling Strategy

Horizontal compute elasticity is handled by `modules/autoscaling`, which
installs the Kubernetes Cluster Autoscaler via Helm, binds it to an IRSA-backed
IAM role, and exposes tunables such as scale-down delay/utilization thresholds.
The autoscaler discovers node groups through standard EKS tags, so scaling
decisions respect the desired ranges declared in the node group map.

## Multi-Region Failover

Global traffic management is coordinated by the optional `module "multi_region"`
block in `deploy/terraform/main.tf`. When `var.enable_multi_region` is true, the
stack provisions Route 53 health checks and weighted records that point to
secondary and tertiary regions, wiring per-region load balancer addresses and
database replicas. The module consumes VPC route tables, media buckets, and KMS
keys exported from the primary stack to guarantee consistent configuration
across regions.

## Deployment Workflow

`deploy/terraform/main.tf` composes networking → security/KMS → EKS →
autoscaling → service mesh/observability and, when enabled, the multi-region
module. Environment-specific values (cluster version, node group shapes, access
CIDRs) live in `deploy/terraform/terraform.tfvars` or per-environment overrides.
Promotion flows reuse the same Terraform code across dev → staging → prod to
keep drift minimal. Compliance coverage in
`tests/infra.kubernetes-platform.spec.ts` ensures documentation, modules, and
root wiring stay aligned.
