Rolling Upgrade

A rolling upgrade applies changes or updates to your Keycloak cluster while keeping it operational. At Cloud-IAM, this process is managed by our technical team, but it also applies when you make configuration changes directly from the Cloud-IAM console.

Rolling upgrades ensure that end users stay connected without interruption, reduce the risk of cluster-wide failures by updating nodes sequentially, and maintain operational resilience by keeping applications that depend on Keycloak available throughout the process.

When is a rolling upgrade applied?

A rolling upgrade is triggered whenever changes need to be applied to your Keycloak deployment. This includes actions such as adding, updating, or removing custom extensions, changing configuration settings like environment variables or allow lists, and other customizations or configurations made through the Cloud-IAM console. To apply these changes to your Keycloak deployment, you must select Save and Redeploy, this action triggers the rolling upgrade.

How does the rolling upgrade work?

During the process, nodes in your Keycloak cluster are updated one by one:

1. A node is taken offline.
2. The new version or configuration is applied.
3. The node rejoins the cluster.

This cycle repeats until all nodes are updated.

Because upgrades are sequential:

• Only a small subset of nodes is offline at any time.
• Other nodes continue serving user requests.
• The cluster may briefly run a mixed-version state (old and new nodes together).

Cloud-IAM Console - Rolling Upgrade Schema

Zero downtime on your Keycloak

Rolling upgrades are designed to ensure zero downtime: your applications and services remain available during updates. This is possible thanks to redundancy: while one node is updated, others stay online to handle traffic.

Zero downtime improves service quality, as users do not experience interruptions during maintenance.

Note: Rolling upgrade is not the same as hot reload that lets developers instantly apply code changes without restarting an app. Rolling upgrades ensure production availability, not developer convenience.

Important Considerations

Behavior for versions prior to v25

For Keycloak versions before v25, users may be prompted to log in again after a restart.

This is due to the "persistent-user-sessions" feature available from Keycloak v25, which stores user sessions in the database. If a session is not found in memory, it is loaded from the database, allowing the user to continue their session without needing to re-authenticate.

Operations and Keycloak Upgrades

Certain deployment maintenance tasks or Keycloak updates may require a full cluster restart.
In such cases, the Cloud-IAM technical team will notify you in advance and explain the potential impacts.

For detailed guidance on upgrade procedures and best practices, see the Keycloak Upgrade Reference.