Kubernetes & Docker Deployment
LoomCache is fully cloud-native and designed to run inside Linux containers. Because nodes must persist state to Write-Ahead Logs (WAL) and establish stable network identities for Raft consensus, it is highly recommended to deploy using Kubernetes StatefulSets.
Kubernetes StatefulSet
Pod Auto-Discovery via Headless Service
Stateful Cluster Topologies
Section titled “Stateful Cluster Topologies”Unlike stateless microservices, LoomCache nodes form a cohesive, consistent hash ring. They require stable network identifiers so that clients can securely route packets to the correct partition leaders without constant DNS cache misses.
Auto-Discovery via Headless Services
Section titled “Auto-Discovery via Headless Services”When deploying to Kubernetes, nodes dynamically discover each other using a headless service. The DnsDiscovery or EnvironmentDiscovery strategies allow new pods to query the Kubernetes API:
- Pod-0 starts up and checks
loomcache-headless.default.svc.cluster.local. - As Pod-1 and Pod-2 spin up, they see the seed nodes and initiate Raft Pre-Vote and Leader Election.
- Once a majority (quorum of 2/3) is achieved, the cluster turns green and begins accepting writes.
Persistent Volumes (PVCs)
Section titled “Persistent Volumes (PVCs)”Every pod requires a Persistent Volume Claim (PVC) mounted to /var/lib/loomcache/wal. This directory holds the active .dat files for the Write-Ahead Log. Even if a pod crashes, Kubernetes will remount the exact same PVC to the new pod, allowing it to instantly replay the WAL from the last index and effortlessly rejoin the cluster.
Do not use emptyDir or ephemeral storage unless you are testing locally.
Health Probes & Circuit Breakers
Section titled “Health Probes & Circuit Breakers”By default, LoomCache provides an HTTP endpoint for Kubernetes Readiness and Liveness probes (/health).
However, intra-cluster detection is much faster. LoomCache natively implements Akka-style Phi-Accrual Failure Detectors via the DiscoveryHealthChecker. If a node experiences a sudden JVM crash or network partition, the remaining peers’ Circuit Breakers trigger to OPEN state, instantly re-routing traffic rather than suffering hanging TCP connections.