What is a Rolling Upgrade Strategy in Keycloak?
Upgrading the identity system every single login depends on sounds terrifying — until you learn how to swap the engine while the plane keeps flying, one part at a time.
Imagine a busy hospital that needs to replace every light fixture in its emergency room — but can never turn all the lights off at once, because patients are being treated around the clock. The only sane approach is to replace one fixture at a time, confirm it works, and move to the next, so the room is never fully dark. Upgrading a production Keycloak deployment faces exactly this problem: Keycloak is usually the single front door every application in an organization logs users in through, so taking it fully offline to upgrade it isn’t an option most businesses can accept. A Rolling Upgrade Strategy is how organizations replace an old version of Keycloak with a new one, one server at a time, keeping the overall system continuously available throughout. This guide explains why upgrading Keycloak is trickier than upgrading a typical stateless application, how a rolling upgrade actually works step by step, what happens internally to a cluster during the process, and how real teams plan and execute one safely. No prior background in clustered systems is assumed.
1Core Concepts
Why does Keycloak usually run as a cluster?
A single Keycloak server is a single point of failure — if it crashes or needs maintenance, every application relying on it for login suddenly can’t authenticate anyone. To avoid this, production deployments typically run several Keycloak server instances, called nodes, working together as a cluster, usually placed behind a load balancer that spreads incoming login requests across them. If one node goes down, the others keep serving requests, and users never notice.
What is a rolling upgrade, specifically?
A rolling upgrade takes advantage of exactly this multi-node setup. Instead of stopping every node at once to install a new version — which would mean a real outage — nodes are upgraded one at a time (or in small batches): take one node out of the load balancer’s rotation, stop it, upgrade it to the new version, start it back up, verify it’s healthy, and put it back into rotation, before moving on to the next node. At every single moment during this process, the majority of the cluster is still running and serving real user logins, just on a mix of old and new versions temporarily.
Think of repaving a busy multi-lane highway. Closing every lane at once would stop all traffic completely. Instead, road crews close one lane at a time, redirect traffic into the remaining open lanes, finish that section, reopen it, and move to the next lane. Traffic never stops entirely — it just flows through a temporarily reduced, and briefly mixed, set of lanes while the work happens.
Why can’t you just treat a Keycloak upgrade like any other stateless web app?
Many modern applications are “stateless” — any server can handle any request, with no memory of past interactions, making rolling upgrades relatively simple. Keycloak is different: it holds meaningful state — active user sessions, cached data, and a database schema that itself sometimes needs to change between versions. A rolling upgrade has to account for the fact that, temporarily, some nodes are running old code while others run new code, all potentially reading from and writing to the same shared session store and database at once.
Any organization running Keycloak in a production Kubernetes cluster, a set of load-balanced virtual machines, or any other multi-node deployment needs a rolling upgrade strategy the moment they can’t accept a scheduled full outage every time a new Keycloak version needs to be applied.
Key vocabulary, explained simply
Node
One individual running instance of the Keycloak server, one of potentially several working together as a cluster.
Load Balancer
The component that distributes incoming requests across all healthy nodes, and can be told to temporarily stop sending traffic to a specific node during its upgrade.
Mixed-Version Cluster
The temporary state during a rolling upgrade where some nodes run the old Keycloak version and others already run the new one, simultaneously.
Database Schema Migration
Structural changes to the underlying database that a new Keycloak version may require, which must be handled carefully during an upgrade involving mixed versions.
Health Check
An automated check confirming a freshly upgraded node is actually working correctly before it’s allowed back into the load balancer’s rotation.
Rollback
The process of reverting an upgraded node (or the whole cluster) back to the previous version if something goes wrong during or after the upgrade.
2Architecture & Components
graph TB
LB[Load Balancer] --> N1[Node 1
Old Version]
LB --> N2[Node 2
Old Version]
LB --> N3[Node 3
Old Version]
N1 --> DB[(Shared Database)]
N2 --> DB
N3 --> DB
N1 --> SESS[Shared/Distributed
Session Store]
N2 --> SESS
N3 --> SESS
UPG["Upgrade Process:
drain → stop → upgrade →
start → health check → rejoin"] -.-> N2
Component breakdown
Load Balancer Configuration
Must support gracefully removing and re-adding individual nodes from rotation, ideally based on automated health checks rather than manual intervention alone.
Shared Database
Every node in a cluster typically reads from and writes to the same underlying database, meaning any schema change introduced by the new version must be compatible with nodes still running the old version during the transition.
Distributed Session/Cache Layer
Keycloak’s clustering relies on a distributed cache to share session information across nodes; this layer must continue functioning correctly even while some nodes run a different version than others.
Deployment Orchestration Tooling
In modern deployments, this is often a container orchestration platform (like Kubernetes) that can automate the drain-upgrade-verify-rejoin sequence node by node, rather than requiring fully manual execution.
Where planning decisions get made
Before touching any actual server, administrators review the specific release notes for the target Keycloak version, paying particular attention to any called-out breaking changes, required database migration steps, or explicit guidance on rolling-upgrade compatibility between the current and target versions. This upfront research shapes exactly how the rolling upgrade sequence needs to be structured for that specific version jump.
A common real setup
A company running a three-node Keycloak cluster behind a load balancer plans an upgrade during a low-traffic maintenance window, even though a full outage isn’t strictly required. They first upgrade a non-production, staging environment with an identical configuration, verify it works correctly end to end, and only then apply the same rolling sequence to production, one node at a time, monitoring each step before proceeding to the next.
Why does the database matter so much here?
Unlike application code, which each node runs independently, the database is a single, shared resource every node touches. If the new Keycloak version requires a database schema change that the old version’s code cannot understand or work correctly against, running old and new nodes simultaneously against the same, already-migrated database becomes a serious risk. This is precisely why Keycloak’s own upgrade guidance for each version explicitly addresses whether, and how, a rolling upgrade is safely supported for that specific version transition.
3Internal Working
Handling database schema changes safely
When a new Keycloak version needs to change the database schema, the migration is generally designed, where possible, to be backward compatible for the duration of the rolling upgrade — meaning the old version’s code can still function correctly against the updated schema, even though it doesn’t yet know about or use whatever new capability the schema change enables. Keycloak’s official upgrade documentation for each release specifies exactly what kind of schema changes are involved and whether a rolling upgrade is supported for that particular version jump, which is why checking this documentation before starting is essential rather than optional.
How a mixed-version cluster actually behaves during the transition
For the period during which some nodes run the old version and others run the new one, both sets of nodes continue serving live user traffic side by side. A user’s login request might land on an old-version node one moment and, on their next request, land on an already-upgraded node — ideally with no visible difference in behavior from the user’s perspective, assuming the version transition is designed to be compatible in this mixed state. This is why release notes calling out “not safe for rolling upgrade” for a specific version jump matter so much — they signal that this assumption of safe mixed operation does not hold for that particular transition.
The drain-upgrade-verify-rejoin cycle for each node
For each individual node being upgraded, the same basic cycle repeats: the node is first drained — the load balancer stops sending it new requests, while letting its current in-flight requests finish naturally. Once drained, the node is stopped, upgraded to the new version, and restarted. Before rejoining the load balancer’s rotation, the newly upgraded node is checked against health checks to confirm it’s genuinely functioning correctly — only then does it start receiving live traffic again, at which point the next node in the sequence begins its own cycle.
Skipping the drain step and simply stopping a node abruptly can interrupt in-flight requests that were already being processed by that node, causing a small number of failed logins or API calls right at the moment of interruption — a proper drain avoids this entirely by letting existing work finish first.
Step-by-step: a full rolling upgrade across a cluster
Preparation and testing
Release notes are reviewed, and the exact upgrade sequence is tested against a staging environment matching production as closely as possible.
Database migration (if required)
Any necessary, backward-compatible schema changes are applied, following the specific version’s documented migration process.
First node drained and upgraded
One node is removed from rotation, stopped, upgraded, restarted, and health-checked before rejoining.
Mixed-version operation monitored
With one node upgraded and others still on the old version, the cluster’s behavior is closely watched for any signs of trouble.
Remaining nodes upgraded in sequence
Each remaining node goes through the same drain-upgrade-verify-rejoin cycle, one at a time or in small batches.
Full cluster verification
Once every node runs the new version, the cluster is verified as a whole to confirm the upgrade completed successfully.
4Data Flow & Lifecycle
sequenceDiagram
participant User
participant LB as Load Balancer
participant N1 as Node 1
participant N2 as Node 2 (upgrading)
participant DB as Shared Database
User->>LB: Login request
LB->>N1: Routes to healthy node
N1->>DB: Reads/writes session data
N1-->>User: Successful login
Note over N2: Drained, stopped, upgraded,
restarted, health-checked
User->>LB: Another login request
LB->>N2: Routes to now-upgraded, healthy node
N2->>DB: Reads/writes session data
N2-->>User: Successful login, no visible difference
Notice that from the user’s point of view in that diagram, nothing looks different at all — one login happened to be served by an old-version node, the next by an already-upgraded one, and both worked exactly the same way. This seamless continuity, invisible to the end user, is the entire measure of success for a well-executed rolling upgrade.
The lifecycle of a full rolling upgrade effort
Planning
Release notes, compatibility guidance, and rollback plans are reviewed and documented before any production change begins.
Staging validation
The exact planned sequence is rehearsed against a non-production environment closely mirroring production.
Production execution
Nodes are upgraded one at a time in production, following the drain-upgrade-verify-rejoin cycle, with active monitoring throughout.
Post-upgrade verification
Once every node is upgraded, the team confirms overall system health, checks for any lingering issues, and formally closes out the upgrade.
Rollback readiness (if needed)
If a serious problem is discovered, a documented rollback plan is executed to return affected nodes, or the whole cluster, to the previous known-good version.
Rolling back a database schema change is often significantly harder than rolling back application code alone, which is why many teams treat any required schema migration as a one-way decision point deserving extra caution and testing before it’s applied, even within an otherwise reversible rolling upgrade.
5Advantages, Disadvantages & Trade-offs
Advantages
- Avoids a full-system outage, keeping login capability available throughout the entire upgrade process
- Allows problems to be caught early, on a single node, before they’ve affected the whole cluster
- Fits naturally into modern orchestration platforms that already support automated node draining and health checking
- Reduces the pressure of a single, high-stakes maintenance window, spreading risk across a more gradual process
Disadvantages & Trade-offs
- Takes meaningfully longer to complete than simply stopping everything, upgrading, and restarting all at once
- Requires the cluster to correctly tolerate running mixed versions simultaneously, which isn’t guaranteed for every version transition
- Adds real operational complexity — health checks, drain logic, and careful sequencing all need to be correctly implemented
- Database schema changes that aren’t backward compatible can force a full-cluster stop anyway, limiting when a rolling approach is actually usable
Repainting a ship’s hull while it’s still sailing, one section at a time, keeps the ship moving throughout — but it takes considerably longer than simply pulling the ship into dry dock and repainting the whole thing at once while nobody needs it to sail. Which approach makes sense depends entirely on whether the ship — or in this case, the login system — can actually afford to stop moving for a while.
6Security
Why staying current matters for security
Keycloak, like any actively maintained software, periodically receives security patches addressing newly discovered vulnerabilities. A rolling upgrade strategy that makes upgrades routine and low-risk to perform directly supports an organization’s ability to apply security patches promptly, rather than delaying them out of fear of a disruptive, all-at-once outage.
Context
Organizations sometimes delay applying security patches to a critical system like Keycloak specifically because the upgrade process feels risky or disruptive, leaving known vulnerabilities unpatched for longer than necessary.
Decision
Invest in a well-tested, reliable rolling upgrade process specifically so that applying security patches becomes routine and low-risk, rather than a rare, high-anxiety event.
Consequence
Security patches can be applied promptly after release, meaningfully reducing the window during which a known vulnerability remains unaddressed in production.
Securing the upgrade process itself
The credentials and access used to perform an upgrade — whether through an orchestration platform, a deployment script, or direct server access — deserve the same access-control discipline as any other privileged administrative action, since an upgrade process with weak access controls becomes an attractive target in its own right.
Treating a rolling upgrade as purely an operational, non-security concern, and skipping a review of the new version’s own security-relevant changes — including any changes to default settings that might need explicit reconfiguration to maintain a previously established security posture.
Verifying integrity of upgrade artifacts
Whatever mechanism delivers the new Keycloak version to production — a container image, a downloaded package — should be verified against official checksums or signatures where available, ensuring the artifact being deployed is genuinely the intended, unmodified release rather than something tampered with in transit or storage.
7Monitoring, Logging & Metrics
Per-node health check status
Closely tracking each node’s health check results immediately after it rejoins the cluster, before considering that step of the upgrade fully successful.
Login success/failure rate during the upgrade window
Comparing login success rates during the rolling upgrade against normal baseline levels, to catch any subtle degradation the health checks alone might miss.
Database connection and query error rates
Watching for any unusual database-related errors specifically during the mixed-version period, which could indicate a schema compatibility issue.
Upgrade duration per node and overall
Tracking how long each node’s upgrade cycle takes, useful both for planning future maintenance windows and for spotting a node that’s taking unusually long, which might indicate a problem.
A practical monitoring habit
Teams performing rolling upgrades often keep a dedicated, real-time dashboard open throughout the entire process, specifically tracking login success rate, error rate, and per-node health status side by side, so that any deviation from expected behavior at any point in the sequence is caught within moments, well before it could affect a meaningful number of real users.
8Design Patterns & Anti-patterns
Proven patterns
Staging environment parity
Maintain a staging environment configured as closely as possible to production, specifically so upgrade rehearsals catch real issues before they reach live traffic.
Automated health-gated rollout
Use orchestration tooling that automatically halts the upgrade sequence if a newly upgraded node fails its health check, rather than blindly proceeding to the next node regardless.
Documented, tested rollback plan
Prepare and actually test a rollback procedure before starting the upgrade, rather than figuring it out under pressure if something goes wrong mid-process.
Incremental version steps for large jumps
For upgrades spanning several major versions, upgrade through intermediate versions in sequence rather than attempting one large, potentially unsupported jump directly to the latest release.
Anti-patterns to avoid
Anti-pattern
- Skipping staging validation entirely and testing a new version’s behavior for the first time directly in production
- Upgrading all nodes simultaneously “to save time,” reintroducing the full-outage risk the rolling approach was meant to avoid
- Proceeding to the next node’s upgrade before properly confirming the previous one is genuinely healthy
- Attempting a large, multi-version jump without checking whether that specific transition is documented as rolling-upgrade safe
Instead, do this
- Always rehearse the exact planned upgrade sequence against a representative staging environment first
- Upgrade nodes incrementally, never all at once, to preserve continuous availability
- Wait for confirmed health checks before proceeding to each subsequent node
- Consult official upgrade guidance for the specific version transition, stepping through intermediate versions when recommended
9Best Practices & Common Mistakes
Best practices
Always read the specific version’s release and upgrade notes
Never assume a rolling upgrade is automatically safe for a given version jump — confirm it explicitly in the official documentation for that specific transition.
Back up before any schema-affecting change
Take a full database backup immediately before applying any migration step, regardless of how confident the team is in the process.
Schedule upgrades during lower-traffic periods when possible
Even though a rolling upgrade avoids a full outage, performing it during lower-traffic windows reduces the potential impact of any unexpected issue.
Keep the whole team informed during the process
Ensure relevant stakeholders know an upgrade is in progress, so any unrelated issue reported during that window is correctly investigated with the upgrade in mind as a possible factor.
Common mistakes
Assuming every Keycloak version upgrade automatically supports a rolling approach, without checking the specific release’s own documented guidance, which occasionally calls for a full-cluster stop instead for certain version transitions.
Rushing through the process without adequate monitoring, only discovering a subtle mixed-version compatibility issue well after the upgrade completed, when it’s much harder to trace back to the upgrade itself.
Not testing the rollback procedure ahead of time, discovering during an actual incident that reverting isn’t as straightforward as assumed, especially once a database migration has already been applied.
10Real-world & Industry Examples
Cloud-native platform teams
Organizations running Keycloak on Kubernetes commonly rely on the platform’s built-in rolling deployment capabilities, combined with readiness and liveness health checks, to automate much of the drain-upgrade-verify-rejoin cycle.
Financial services and always-on systems
Banking and trading platforms, where even brief authentication outages carry significant business impact, treat rolling upgrade discipline as a core operational requirement rather than a nice-to-have.
Managed identity service providers
Organizations offering Keycloak-based identity services to many customers rely heavily on well-tested rolling upgrade automation to apply updates across their fleet without any individual customer experiencing a noticeable outage.
Global, follow-the-sun operations
Companies operating across many time zones, where there’s effectively no universally “quiet” maintenance window, depend on rolling upgrades specifically because a scheduled full outage would inevitably disrupt some region’s active business hours.
A representative scenario
A global e-commerce company running a five-node Keycloak cluster needed to apply an important security patch as quickly as possible after its release. Because they had already invested in a well-tested rolling upgrade pipeline integrated with their container orchestration platform, the entire five-node cluster was upgraded within an hour, node by node, with automated health checks gating each step — all without a single noticeable login disruption for customers actively shopping on the platform at the time, across every time zone the business operated in.
11FAQ
12Summary and Key Takeaways
Key Takeaways
- A Rolling Upgrade Strategy upgrades a clustered Keycloak deployment one node at a time, keeping the overall system continuously available rather than requiring a full outage.
- It relies on a cluster running multiple nodes behind a load balancer, allowing individual nodes to be drained, upgraded, and verified independently.
- Success depends on the cluster correctly tolerating a mixed-version state temporarily, where old and new nodes serve traffic side by side against the same shared database.
- Database schema changes are the trickiest part of a rolling upgrade — they must generally remain backward compatible for the transition period, and not every version jump supports this cleanly.
- Each node follows a drain-upgrade-verify-rejoin cycle, with health checks gating whether it’s safe to move on to the next node.
- Staying current through routine, low-risk rolling upgrades directly supports applying security patches promptly, rather than delaying them out of fear of disruption.
- Thorough staging rehearsal, monitoring during the process, and a tested rollback plan are what separate a smooth rolling upgrade from a risky one.
- Not every version transition is automatically rolling-upgrade safe — always consult the specific release’s official upgrade guidance before assuming this approach applies.