# Service Mesh

Lilith standardizes on Istio for zero-trust networking, traffic management, and
resilience across dev, staging, and production clusters. The Terraform
`modules/service-mesh` package installs the mesh alongside opinionated defaults
for mTLS, retries, timeouts, and circuit breaking.

## Installation & Topology

The service mesh module rolls out the Istio base CRDs, `istiod` control plane,
and an optional ingress gateway via Helm charts sourced from the official Istio
repository. Deployments land in `istio-system` (control plane) and
`istio-ingress` (gateway) namespaces, with resource limits, HPA settings, and
mesh IDs configurable per environment. The root stack gates installation behind
`var.enable_service_mesh`, allowing lower environments to toggle the mesh
independently while still using the same Terraform code.

## mTLS & Zero Trust

Strict mutual TLS is enabled through default `DestinationRule` and
`PeerAuthentication` manifests that enforce `ISTIO_MUTUAL` traffic policies
across the application namespace. When `var.enable_strict_mtls` is true, a
namespace-wide `PeerAuthentication` sets the mTLS mode to `STRICT`, ensuring
every workload participates in the authenticated mesh. Certificates are rotated
automatically by Istio, backed by the same KMS-protected secret stores
provisioned elsewhere in the stack.

## Traffic Management (Retries & Timeouts)

Intelligent routing primitives are provided via programmable `VirtualService`
definitions. By default the module configures exemplar HTTP routing with
deterministic timeouts (`30s`) and retry budgets (three attempts, 10-second
per-try deadlines) while leaving room for per-service overrides through GitOps
manifests. Gateway API support can be enabled when advanced ingress policies are
required.

## Circuit Breaking & Resilience

A shared `DestinationRule` applies connection pool limits, outlier detection,
and max-ejection percentages across the application namespace to shed unhealthy
instances quickly. These guardrails ensure downstream failures remain isolated
and prevent cascading outages when upstream services misbehave.

## Operations & Tooling

Kiali is deployed (optional via `var.enable_kiali`) for service graph
visualization, leveraging the Prometheus/Grafana stack from the observability
module. Outputs from `modules/service-mesh` expose whether the mesh is enabled,
mTLS mode, ingress gateway namespaces, and Kiali endpoints so CI/CD pipelines
and GitOps tooling can surface topology metadata. Compliance coverage in
`tests/infra.service-mesh.spec.ts` locks the documentation and Terraform module
together.
