Cluster Extensions

Upgrade an installed extension

Upgrades the extension to its latest available version. Returns 409 Conflict if the extension is already at the latest version (upgrade_available is false).

The upgrade is processed asynchronously; poll until status is active or failed.

Required scope: clusters:extensions:write

post/clusters/{cluster_id}/extensions/{extension_id}/upgrade

Request

  • Base URL: http://localhost:8000
  • URL: http://localhost:8000/clusters/{cluster_id}/extensions/{extension_id}/upgrade
  • Auth: API key in header API-Key

Path parameters

cluster_idstring uuid required
extension_idstring uuid required

Headers

API-Version'2026-06-01.beta' required

Response

Returned for async operations. Poll the Location URL to track completion.

extension_idstring uuid required
extension_namestring required
extension_source'platform' | 'custom' required
status'installing' | 'active' | 'failed' | 'removing' required
installed_versionstring required

Version currently running on the cluster. For platform extensions this is the upstream release string of the installed build (not necessarily semver, for example 1.4.1-SNAPSHOT), or unknown when it cannot be determined. For custom extensions it is the uploader-supplied version.

available_versionstring nullable required

Version the cluster would get by upgrading now. For platform extensions it is the build published for the cluster's Keycloak version (unknown when that build states no version), and null when no build supports the cluster's Keycloak version. For custom extensions it is the latest uploaded version.

upgrade_availableboolean required

Whether upgrading would install a different build. For platform extensions it compares the installed build with the one published for the cluster's Keycloak version, so republishing an unchanged catalog never sets it. For custom extensions it is set when a version was published after the install. Always false when the install is not active or is pinned by Skycloak support.

parametersobject required

Current parameter values. Values for sensitive parameters are omitted (null).

installed_atstring date-time required
last_status_change_atstring date-time nullable required

When the installation status last changed.

Example response

{
  "extension_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "extension_name": "Social Login Bundle",
  "extension_source": "platform",
  "status": "active",
  "installed_version": "3.0.0",
  "available_version": "3.1.0",
  "upgrade_available": true,
  "parameters": {},
  "installed_at": "2025-02-01T09:00:00Z",
  "last_status_change_at": "2025-02-01T09:05:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.