Stateless Keycloak moves multi-site failover onto the database and load balancer

Red Hat has documented a two-site OpenShift proof of concept for a stateless Red Hat build of Keycloak architecture. The lab kept OpenID Connect logins and token refreshes working while either Keycloak site was deliberately taken offline.

The design changes where cross-site consistency lives. Instead of replicating session state between embedded Infinispan caches, each site keeps its cache local and persists cross-site session data in a synchronously replicated PostgreSQL database. An external HAProxy instance presents one issuer hostname, probes each site’s /lb-check endpoint and moves traffic away from a failed deployment.

What Red Hat tested

The proof of concept used two Red Hat OpenShift Local environments in one LAN. One ran on Linux with the primary PostgreSQL instance; the other ran on Windows 11 with a synchronous standby. PostgreSQL ran in Podman containers, while HAProxy listened outside the clusters and routed both sites behind a shared hostname.

A single-page application repeatedly authenticated, refreshed tokens and called a protected API. The author simulated site failures by scaling each Keycloak StatefulSet to zero. The published results show authorization-code flow with PKCE and the standard RFC 8693 token-exchange flow continuing after either site disappeared. When both sites were down, HAProxy returned an HTTP 503 as expected.

That is a more useful test than simply showing two healthy clusters. It exercises issuer continuity, pre-existing tokens and the load balancer’s ability to stop sending requests to an unavailable site.

The operational trade

Removing cross-site cache replication does not remove coordination. It moves the hardest consistency requirement to the database and makes the external load balancer part of the authentication control plane. The shared issuer hostname must match at both sites, custom ports must appear in Keycloak’s hostname configuration, and OpenShift route stickiness must not fight the external load balancer.

The lab also retains a low-latency requirement and synchronous database replication. Teams should test network partitions, database promotion and recovery separately rather than treating a clean application-site failover as proof of full disaster recovery.

What teams should do

Red Hat says multi-site support expanded with Red Hat build of Keycloak 26.4 for certain on-premises and non-AWS topologies. The newer stateless behavior discussed here is tied to upstream Keycloak 26.7 preview work, so operators should distinguish the supported product architecture from the experimental feature being validated.

For a trial, reproduce the shared issuer and health-check path, disable conflicting router stickiness, then test authorization, refresh and token exchange with each failure domain removed in turn. Production adoption should wait for an explicit support statement covering the exact Keycloak version, database topology, OpenShift layout and load-balancing design.