Keycloak zero-downtime patch upgrades

A Keycloak patch release can look like a low-risk change, but it may still alter the database that every node shares. By default, Keycloak migrates its database schema automatically at startup. The first node that starts on the new version can therefore apply schema changes before the rest of the cluster has been upgraded. The database becomes a shared change that every node depends on. Before the maintenance plan is written, the team should confirm from the upgrade documentation for the exact target version whether that patch includes schema changes at all. The answer shapes every later decision in the runbook.

Keycloak also supports manual migration, in which administrators apply the schema SQL themselves before starting nodes on the new version. The upgrading guide suggests this approach for large deployments. It moves the schema change into a step the team can review, schedule and hand to a database administrator, and it keeps the change out of the first node's startup sequence. The cost is more operational work. The team has to obtain the correct script for the target version, run it against the production database in a planned window, and confirm the result before any node starts. Ask whether the target version's script is documented for manual application and what the documentation says about reversing it if the rollout fails.

The harder question is whether old and new nodes can run side by side. A rolling restart replaces nodes one at a time, so for a period the cluster serves requests from both versions against the same database. If the new version changed the schema or the data it writes, an old node may fail to read it, or a new node may expect data that an old node has not written. The team must confirm from the release notes for the specific release whether mixed-version operation is supported. The patch number alone does not establish that support. If the notes do not state it, the rolling plan is not safe as written, and the team should plan a window in which all nodes stop and restart together.

Turn these points into three checks before the change request is approved. First, read the release notes and upgrade notes for the exact target version and record whether the release changes the schema, whether migration runs at startup, and whether mixed-version operation is supported. Second, rehearse the upgrade on a copy of the production database and observe the startup of the first node, since that node is where automatic migration would run. Third, if the team uses the Keycloak Operator, keep manual approval mode for operator updates, which the Operator documentation strongly recommends, so that a new version is applied only when the team chooses. Record each answer in the runbook so the approver can see which path was chosen and why.

A rolling restart keeps users signed in only when the load balancer continues to send each existing browser session to a node that stays up, and when the session state that session needs is held somewhere other than the node being restarted. With sticky sessions, the load balancer pins each browser to one Keycloak node, usually through a routing cookie or a similar affinity mechanism. While one node restarts, requests from browsers pinned to the other nodes continue normally. Browsers pinned to the restarting node lose their affinity target for the length of the restart, and whether those users stay signed in depends on whether another node holds their session data. Confirm the affinity mechanism your load balancer uses and how Keycloak encodes node identity in its cookies in the upgrade documentation for your target release.

Session state is distributed through the Infinispan caches that Keycloak uses in its high availability architectures. Keycloak documents three designs: a single cluster optionally spread across availability zones, multi-cluster deployments (v2) without an external Infinispan cluster, and the deprecated multi-cluster v1, which used a separate Infinispan cluster per site. For a single cluster across zones, check how many nodes hold a replica of each session, how the cluster forms across zones, and what happens when a zone or node leaves. For multi-cluster v2, confirm how sessions reach the other site and what a restart in one site does to sessions that were pinned there. Do not assume a single node restart is safe until replication has been verified in a test environment that matches your topology.

Both supported high availability designs need a synchronously replicated database, and this requirement matters during rolling restarts. Each restarting node reads and writes the same user, session and schema state as the nodes that remain, so a database that lags behind its primary can hand a node stale data after a failover. Keycloak migrates its database schema automatically at startup by default, which means a patched node that starts while another node is still working against the old schema is a risk to plan for. For large deployments, the upgrading guide suggests manual migration, where administrators apply the SQL themselves before any node restarts. Confirm which migration approach and ordering your patch release requires in its upgrade notes.

If you run Keycloak on Kubernetes with the Keycloak Operator, the rolling behavior depends on the Operator's rolling update strategy along with your readiness probes and disruption settings, not on Keycloak alone. Verify that strategy against the Keycloak version you run before you rely on it, because the Operator's behavior can differ between releases. The Operator is installed through Operator Lifecycle Manager (the recommended method), with kubectl, or with an experimental Helm chart. The Operator documentation strongly recommends manual approval mode for operator updates, which keeps an upgrade from starting until your team has reviewed the target release.

Before you schedule a production patch, run a rehearsal on a copy of your topology. Sign in several test users so that sessions are pinned to each node, restart nodes one at a time in the order your rollout will use, and record which sessions survive each step. Confirm the exact rolling behavior for the target patch in the upgrade documentation and through this test, not from the general description on this page. Agree with your load balancer and database owners on the rollback point and the criteria for pausing the rollout before the first production node restarts.

Start the test plan with the sign-in paths your applications depend on, because a patch can start cleanly and still break a token exchange. Run a scripted smoke test for each client in the realm: OpenID Connect and OAuth 2.0 clients through their configured flows, and SAML 2.0 service providers through their SSO bindings. Sign in as a test user, confirm that the ID token or SAML assertion carries the expected claims and audience, and confirm that token refresh and logout still work. Include the admin console and the Administration REST API, using a service account with the same permissions and token lifetimes as production. Record each result in a form you can compare between the current and target versions, so a failure points to one flow.

Next, test the identity sources and factors that sit outside the core login path. For LDAP or Active Directory user federation, authenticate a directory test account, confirm group and role mappings, and check that scheduled synchronization completes. For each brokered identity provider, whether OIDC, OAuth or SAML, complete a login and confirm that first-login account linking behaves as configured. Repeat the check for any social providers you have enabled. For MFA, test OTP enrollment and verification, WebAuthn security keys, passkeys in both conditional and modal UI, and recovery code use. Passkey and WebAuthn behavior depends on the origin, so run these tests against the exact public hostname your users sign in through.

Email and metrics need their own checks because both can change silently after a patch. Keycloak 26.8 enforces SMTP StartTLS without plaintext fallback, according to the upgrade notes, so any realm whose mail relay was reached without encryption will fail to send password reset, verification or notification messages. Send a test message from each realm that mails users, using the production SMTP host and port, and confirm that the relay certificate validates. Ask your mail team to confirm that the relay offers STARTTLS on that port. If you scrape Prometheus metrics, start the target version with --metrics-enabled=true on the management interface and confirm that /metrics returns the series your dashboards and alerts query, including any HTTP or cache histograms you enabled.

Rollback is the step teams most often underestimate. Keycloak migrates its database schema automatically at startup by default, and a newer release may write a schema that the previous release cannot read. Once the migration has run, returning to the old binary may not work without restoring a database backup taken before the upgrade. Define the rollback point before the first node starts against the migrated database, and write down who can authorize the restore. Consider manual migration, where administrators apply the SQL themselves. The upgrading guide suggests this for large deployments, and it gives you a reviewed script and a deliberate pause before the schema changes. Take a database backup immediately before the migration, and rehearse restoring it into a scratch environment so you know how long the restore takes.

Confirm the rollback procedure for the specific target version in the Keycloak upgrading documentation before you schedule the window. A downgrade path documented for one minor release should not be assumed to apply to another. If you run the Red Hat build of Keycloak, confirm the procedure with Red Hat support as well. Ask whether any changes in the target release, such as login failures persisted to the database by default in 26.8, would be lost in a restore, and plan how you will handle sessions and audit records created between the backup and the rollback. Assign one owner for the go or no-go decision and agree on the failure conditions in advance, such as any failed flow from the test plan, so the team does not improvise under pressure.