Upgrade On Demand

What is upgrade on demand?

Upgrade On Demand is a feature that allows you to upgrade by yourself your Keycloak deployment to a newer version directly from Cloud-IAM console.

This gives you more control over your environment, allowing you to access new Keycloak features and security patches directly or on the next maintenance window.

Cloud-IAM's upgrade on demand process

To ensure upgrades are safe and reliable, Cloud-IAM follows a strict process to minimize any risk or downtime:

Automatic Backup - Before the upgrade begins, a full backup of your Keycloak deployment is created. This ensures our technical team can safely roll back if needed.
Rolling Upgrade - When downtime is not required, the upgrade is performed on one instance at a time. Once validated, it proceeds to the next instance, minimizing risk and preventing system-wide corruption. More information on Rolling upgrade process.

These safeguards ensure your upgrade experience is stable, secure, and fully reversible if needed.

How to use upgrade on demand?

Follow these steps to upgrade on demand your Keycloak:

⚠️ Keycloak deployments with custom extensions

Upgrading without proper validation may cause incident with customized functionality. If your deployment includes custom extensions, we recommend the following before performing an upgrade:

-> Verify compatibility with the target Keycloak version

If you're unsure or need changes, contact Cloud-IAM Support our team can help validate, or manage your extensions as needed.

Step 1 - Access feature and configure the upgrade

Open Cloud-IAM console
Select the Keycloak deployment you want to upgrade.
Click on Pilot
Select Upgrade
From the dropdown list select the target version to upgrade
Select the schedule of your upgrade
- As Soon As Possible - For immediately upgrade
- Next maintenance window - For scheduling upgrade with maintenance window feature
Then click Next Steps

Cloud-IAM Console - Upgrade On Demand Access

Step 2 - Confirmation upgrade

Review the selected Keycloak version and scheduled upgrade time
Confirm that the upgrade may cause temporary service interruption
Confirm that any custom extensions on your Keycloak may require updates
Then click Apply to proceed

The upgrade process typically takes 15–20 minutes. Once complete, your deployment will run on the selected Keycloak version.

Cloud-IAM Console - Upgrade On Demand confirmation

How to upgrade with the Cloud-IAM API

The upgrade can also be triggered programmatically, for instance from a CI/CD pipeline. All the calls below use a Service Account access token, see Cloud-IAM REST API to obtain one.

Step 1 - List the Keycloak versions

The available Keycloak versions are returned by the marketplace endpoint, with the organization id of your account:

bash

curl -s -X GET "https://api.cloud-iam.com/marketplace/organizations/{organizationId}/keycloak-versions" \
  -H "Authorization: Bearer $TOKEN"

json

{
  "keycloakVersions": [
    { "id": "26.5-quarkus", "name": "Keycloak 26.5" }
  ]
}

Step 2 - Trigger the upgrade

bash

curl -s -X PUT "https://api.cloud-iam.com/deployments/{deploymentId}/upgrade?when=MAINTENANCE_NOW&version=26.5-quarkus" \
  -H "Authorization: Bearer $TOKEN"

Parameter	Value
`version`	The target Keycloak version, given either as its `id` (`26.5-quarkus`) or as its `name` (`Keycloak 26.5`)
`when`	`MAINTENANCE_NOW` for an immediate upgrade, `MAINTENANCE_NEXT_WINDOW` to wait for your maintenance window

The deployment is upgraded to the latest image of the target version, so no patch level has to be provided.

Possible responses:

202 Accepted with the target image, the upgrade is scheduled
200 OK with {"message": "UPDATE_NOT_REQUIRED"}, the deployment already runs that image
400 Bad Request, the version is unknown (the message lists the accepted values) or an installed extension is not compatible with it
409 Conflict, an upgrade is already scheduled or in progress for this deployment

Step 3 - Follow the upgrade

bash

curl -s -X GET "https://api.cloud-iam.com/deployments/{deploymentId}/maintenance-upgrade" \
  -H "Authorization: Bearer $TOKEN"

The response is the status of the upgrade maintenance, and an empty body once no upgrade is pending anymore.

Which versions can I upgrade to?

The versions endpoint lists every Keycloak version known to Cloud-IAM, including the one you already run. Version jumping rules still apply, see Keycloak version jumping.