ADR-0008 — Hazelcast clustering via Kubernetes DNS discovery; UI sessions via Ingress affinity¶
Date: 2026-09-01 · Status: accepted (validated by prototype 3)
Context¶
N GeoServer replicas with a variable count, no fixed IP address, configuration in the database (JDBCConfig/JDBCStore). Configuration changes must be propagated between nodes, the UI must remain usable behind a round-robin Service, and asynchronous WPS must be served from any node. Prior operational experience: Hazelcast discovery through the Kubernetes API without RBAC blocked startups for tens of minutes.
Decision¶
- Propagation:
gs-hz-clustermodule (Hazelcast 5.3.8, version pinned by GeoServer 3.0.1),sync_method=event, bundle resolved by Maven (ADR-0007). - Kubernetes discovery in DNS mode: headless Service with
publishNotReadyAddresses: true,service-dns, fixed port 5701; no RBAC, no IPs. The bootstrap checks DNS resolution before Tomcat and fails explicitly otherwise (measured: 3 s). - UI sessions: session affinity at the Ingress by default (cookie);
HZ_SESSION_SHARING=truevalidated as an alternative when affinity is not available. - WPS: status in the database + results on a shared RWX PVC.
PodDisruptionBudget minAvailable: 1, preferred anti-affinity, node identification (GEOSERVER_NODE_OPTS).
Measurements (test bench)¶
Propagation 3 s; scale 3→5→2→3: 0 errors / 95 requests; cold boot 0→3: ~55 s, a single cluster; discovery failure: shutdown in 3 s; sessions: affinity 10/10, bare round-robin 0/10, Hazelcast sharing 10/10; WPS and admin rotation across nodes OK.
Rejected alternatives¶
| Alternative | Why rejected |
|---|---|
JMS (gs-jms-*) + ActiveMQ |
A broker to operate; primary/replica model (replicas reject modifications) |
| Discovery through the Kubernetes API | RBAC required; blocking experienced on failure |
| Multicast / tcp-ip | Unavailable in Kubernetes / fixed IPs |
| Tomcat session replication (JDBC, Redis) | Not needed: two solutions validated without any extra component |
| No propagation | Cache divergence between replicas |
Consequences¶
- The replica count is free; every new pod joins the cluster via DNS. An HPA remains possible (to be worked out with metrics).
- RWX storage becomes a platform requirement for asynchronous WPS.
- Wicket sessions are not replicated by default: losing the hosting node logs the user out (acceptable for an administration UI).