Eve library

Kubernetes Platform

Guide

Revision 1

On this page

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.