Why Run More Than One Keycloak Server?

A single Keycloak server, like any single piece of infrastructure, represents both a capacity limit and a single point of failure. Running several Keycloak instances together as a cluster lets an organization handle more simultaneous logins than one server could alone, and keeps authentication working even if one particular server instance goes down.

What Is a Session, in This Context?

When a user logs in, Keycloak creates a session — a piece of server-side state remembering that this user is currently authenticated, along with details needed to support things like Single Sign-On across multiple applications and eventual logout. The genuinely hard question a cluster has to answer is: when this same user makes their next request, and it happens to land on a different server than the one that created their session, how does that second server know the session even exists?

How It Works

With Sticky Sessions (also called session affinity), the Load Balancer is configured to remember which specific Node handled a given user’s very first request, and to route every subsequent request from that same user back to that exact same Node, for as long as their session remains active.

How the Load Balancer Remembers

This is commonly achieved through a cookie the Load Balancer itself sets, identifying which Node originally handled the request, or by examining a routing identifier already embedded in Keycloak’s own session cookie. Either way, the Load Balancer consults this marker on every incoming request and directs traffic accordingly.

The Genuine Appeal of This Approach

Because the Node handling a request already has the relevant session data close at hand, Sticky Sessions can avoid some of the network overhead and complexity involved in constantly synchronizing session data across every Node in a cluster — a real, tangible benefit that explains why this remains a common, practical starting point for many deployments.

A Reasonable Default for Traditional, Long-Lived Infrastructure

In an environment where individual servers are provisioned deliberately, run for extended periods without being casually replaced, and are only taken down for planned, well-communicated maintenance windows, the specific weakness covered in the next chapter is a genuinely rarer event to actually encounter in practice — which is part of why Sticky Sessions has historically been such a common, comfortable default in more traditional, non-containerized infrastructure setups.

What Happens When the Assigned Node Fails

If the specific Node a user has been “stuck” to crashes, is taken down for maintenance, or otherwise becomes unavailable, the Load Balancer has no choice but to route that user’s next request somewhere else. If that new Node has no way to see the original session data, the user’s session is effectively lost — from their perspective, they’ve been abruptly, unexpectedly logged out.

Why This Surprises Teams Who Tested Only the Happy Path

A deployment relying on pure Sticky Sessions can pass every ordinary functional test with flying colors, since those tests rarely simulate an actual Node disappearing mid-session. This particular failure mode tends to surface only once real production traffic meets a real, unplanned (or even routinely planned) Node outage — precisely the moment when a team least wants to be discovering a gap in their own architecture for the first time, which is exactly why the deliberate failover testing recommended in Chapter 14 matters so much more here than in a simpler, single-server deployment, and why it deserves a place in a team’s regular operational routine rather than being treated as a one-time, pre-launch checkbox.

What Infinispan Is

Infinispan is an open-source, distributed caching technology that Keycloak embeds internally to store session data, among other things. “Distributed” here means Infinispan is specifically designed to hold data that’s replicated or shared across multiple running instances, rather than living in only one place.

How Infinispan Enables Session Sharing Across Nodes

When Keycloak’s Nodes are configured to form an Infinispan cluster together, a session created on one Node is replicated to the others (or made discoverable across them, depending on the specific replication strategy configured), meaning a request landing on a different Node than the one that created a given session can still find and use that session’s data.

How It Works

Under Stateless Clustering, the Load Balancer makes no attempt to route a given user consistently to the same Node — any Node can handle any request from any user at any time. This works because every Node relies on Infinispan’s replication to access the same, consistent session data, regardless of which Node originally created it.

Why “Stateless” Can Be a Slightly Misleading Name

The name doesn’t mean Keycloak itself has no session state at all — it very much still does. It means the Load Balancer’s routing decision doesn’t need to depend on that state, since every Node is equally capable of retrieving it from the shared, replicated cache. The “statelessness” describes the Load Balancer’s own routing logic, not Keycloak’s actual session data.

Embedded Infinispan

By default, each Keycloak Node runs its own embedded Infinispan instance, and these instances directly discover and communicate with one another to form a cluster. This is the simpler, out-of-the-box configuration, requiring no separate infrastructure beyond the Keycloak Nodes themselves.

External Infinispan (or an Alternative Distributed Cache)

For larger or more demanding deployments, Keycloak can instead be configured to rely on an externally run, separately managed distributed caching cluster, decoupling the caching layer’s own scaling and resilience characteristics from the Keycloak Nodes themselves.

Decoupling Cache Lifecycle From Keycloak Node Lifecycle

A further, often underappreciated benefit of an external caching layer is that the cache’s own lifecycle becomes independent of any individual Keycloak Node’s lifecycle. Restarting or replacing a Keycloak Node no longer risks disturbing the cache cluster’s own internal stability, since the cache lives and is managed entirely separately — a meaningful operational simplification once a deployment reaches a scale where Keycloak Nodes themselves are being cycled frequently.

The Trade-off: Additional Infrastructure to Operate

This benefit doesn’t come free — an external caching cluster is itself a piece of infrastructure requiring its own monitoring, capacity planning, and operational ownership, distinct from the Keycloak Nodes it serves. For a smaller deployment, this added operational surface can outweigh the benefits described above, which is exactly why Keycloak’s simpler, embedded default remains the sensible starting point until an organization’s actual scale genuinely calls for something more.

Containerized and Cloud-Native Environments Assume Nodes Come and Go

Modern deployment environments, particularly container orchestration platforms, are built around the assumption that individual server instances are disposable and can be replaced, rescheduled, or scaled up and down frequently and automatically. Sticky Sessions’ reliance on a stable, consistent mapping between a user and one specific Node sits awkwardly against this assumption, since a Node might be replaced by the orchestration platform at any moment for reasons entirely unrelated to any deliberate maintenance action.

True High Availability Requires Surviving a Node’s Failure Gracefully

As covered in Chapter 4, Sticky Sessions alone doesn’t provide real resilience against a Node actually failing — and a genuine production deployment’s high-availability goals generally require exactly this kind of resilience. Stateless Clustering directly delivers it, as its core, defining property.

Session Creation. A user logs in, and Keycloak creates a session on whichever Node happened to handle that specific login request.

Initial Replication. Regardless of the clustering approach chosen, the new session is generally written into the shared Infinispan cache, though how quickly and how reliably other Nodes are actually kept in sync can vary by configuration.

Ongoing Requests. Under Sticky Sessions, subsequent requests are routed back to the originating Node, which can serve them from its own local, already-current view of the session. Under Stateless Clustering, subsequent requests may land on any Node, each retrieving the session fresh from the shared cache.

Node Failure (if it occurs). Under Stateless Clustering, this is a routine, gracefully handled event. Under pure Sticky Sessions without adequate replication, this is where active sessions are actually lost, as covered in Chapter 4.

Session Expiry or Logout. Eventually, the session ends, either through explicit logout or reaching its configured expiration, and is cleaned up from the shared cache across the cluster.

graph LR
    A["Session Created
on Originating Node"] --> B["Replicated to
Shared Infinispan Cache"]
    B --> C{"Node Serving Next Request"}
    C -->|"Sticky Sessions"| D["Same Node,
Local Data"]
    C -->|"Stateless Clustering"| E["Any Node,
Fetched From Cache"]
    D --> F["Session Ends
(Expiry or Logout)"]
    E --> F
    

Cross-Node Replication Traffic Deserves Its Own Protection

Because session data — including details tied to an authenticated user’s identity — travels between Nodes as part of Infinispan’s replication under Stateless Clustering, this internal, Node-to-Node traffic deserves the same network-level protection (isolation, encryption where appropriate) as any other channel carrying sensitive authentication data, rather than being assumed safe simply because it stays within an internal network.

Load Balancer Session Cookies Need Their Own Security Review

Under Sticky Sessions, the cookie a Load Balancer uses to remember routing decisions is itself a piece of state worth reviewing for proper security attributes (such as being marked secure and appropriately scoped), exactly like any other cookie covered elsewhere in this series’ discussion of browser security headers.

A Compromised Node Under Each Approach

It’s worth considering what a single compromised Node can actually see under each approach. Under Sticky Sessions, a compromised Node primarily has direct, local access to the sessions of the specific users currently routed to it — a narrower, if still serious, exposure. Under Stateless Clustering, because every Node participates fully in the shared replicated cache, a compromised Node potentially has access to session data for any user across the entire cluster, not merely those it happened to serve directly. This doesn’t argue against Stateless Clustering’s real availability benefits, but it does mean the security hardening of each individual Node deserves consistent, uniform attention across the whole cluster, since a weakness in any single Node’s defenses has cluster-wide reach rather than being contained to that Node’s own directly served traffic.

Detecting a Silent Network Partition

One of the more insidious failure modes in a clustered deployment is a network partition — a situation where a subset of Nodes can no longer communicate with the rest of the cluster, yet each remains individually up and appears healthy on its own. Without dedicated cluster-membership monitoring specifically watching for this condition, a partition like this can persist for an extended period entirely unnoticed, quietly degrading the very resilience the cluster was built to provide, since replication across the partition boundary has effectively stopped even though no individual Node has actually crashed.

Alerting on Sustained, Not Momentary, Anomalies

As with the signature-verification monitoring covered elsewhere in this series, a brief, momentary blip in replication latency or per-Node load is often normal background noise in any sufficiently active distributed system. Effective alerting distinguishes this ordinary variability from a sustained, worsening trend that genuinely warrants investigation, keeping the operations team’s attention focused on real, emerging problems rather than routine fluctuation.

Good Patterns

• Choose deliberately, based on actual availability requirements, rather than defaulting to whichever approach happened to be easiest to configure initially
• Test failover explicitly and regularly, rather than assuming a chosen configuration provides the resilience it’s intended to
• Monitor Infinispan cluster health continuously, since a silently degraded cache undermines the whole architecture without necessarily producing an obvious, immediate symptom
• Favor Stateless Clustering for containerized or cloud-native deployments, where Nodes are expected to come and go dynamically

Anti-patterns to Avoid

Neither approach is a permanent architectural commitment carved in stone the moment it’s chosen — both are configuration decisions that can, and sometimes should, be revisited as a deployment’s scale, infrastructure, and availability expectations genuinely evolve over time. What matters most is that the choice is made deliberately, with its real trade-offs clearly understood, and verified through actual testing rather than assumed from the configuration screen alone.

Ultimately, the right choice here isn’t a question of which approach is objectively superior in the abstract, but which one actually matches a specific deployment’s real availability requirements, its deployment environment’s own assumptions about Node stability, and the operational maturity a team can realistically sustain around a continuously replicated cache. A deployment that outgrows its original choice as its scale or requirements shift isn’t a sign anything was done wrong initially — it’s simply a natural point to revisit this same trade-off with fresh, current information, exactly as any other piece of foundational infrastructure occasionally deserves.