Narrative

Currently Keycloak is unable to provide any guarantees of runtime compatibility between different patch releases on a given release stream. In order for a user to be able to upgrade Keycloak safely, it's necessary for the Keycloak cluster to be gracefully shutdown and restarted with the new Keycloak version. This applies to individual Keycloak clusters and multi-site "HA" environments.

UPDATE:

• This is available as a preview feature in Keycloak 26.3
• This will probably stay a preview feature until Keycloak 27.0 until we switch to Infinispan 16 which has built-in backwards compatibility.

Value proposition

Allowing users to upgrade Keycloak for patch releases without downtime will significantly improve the user experience as they don't need to plan for services outages which adds an additional barrier to upgrading.

While Keycloak has patch releases every two to four weeks, there are minor releases only every three months. After this change, a Keycloak community user would have four downtimes a year instead of 10-20.

Goals

• Roll out of a patch release will succeed and all nodes with the next patch release can join the cluster
• Start log-in flow with version A, finish with version B (at least OIDC)
• Log-in with version A, refresh / token introspection / user info / logout with version B (at least OIDC)
• Account and admin console will work 'best effort', and I might need to refreshing the browser when I see a descriptive error message (or account and admin console might be disabled during upgrades)

TODOs

• Document to use sticky sessions to avoid switching between instances too often for the login flow and the admin/account UI
• Document that during a patch release version change in the backend, an error message in the account or admin UI can occur and the application would then need to be reloaded (see Smoke test the account/admin UI functionality during upgrades #38886 for the screenshots)
• Possibly unify the displayed error message in account and admin UI (see Smoke test the account/admin UI functionality during upgrades #38886 for the screenshots)