bin/kc.[sh|bat] update-compatibility metadata --file=/path/to/file.json --features=rolling-updates| This guide is describing a feature which is currently in preview. Please provide your feedback by joining this discussion while we’re continuing to work on this. |
|
While on preview stage, the feature |
The goal of this tool is to assist with modifying a Keycloak deployment, whether upgrading to a new version, enabling/disabling features, or changing configuration. The outcome will indicate whether a rolling upgrade is possible or if a recreate upgrade is required.
This has been designed to be fully scriptable, so an update procedure can adapt to a rolling or recreate strategy depending on the configuration or version change. It is also GitOps friendly as it allows storing the metadata of a currently running configuration in a file. This file can be used in a CI/CD run with the new configuration to determine if a rolling upgrade is possible or if a recreate upgrade is needed.
|
Rolling Upgrade
In the context of this guide, a rolling upgrade is an upgrade that can be performed with zero downtime for your deployment. Your Keycloak nodes must be updated one by one; in other words, shut down one of your old deployment nodes and start a new deployment node. Wait until the new node’s start-up probe returns success before proceeding to the next Keycloak node. See guide Enabling Keycloak Health checks for details on how to enable and use the start-up probe. |
|
Recreate Upgrade
A recreate upgrade is not compatible with zero-downtime and requires downtime to be applied. Shut down all nodes of the cluster running the old version before starting the nodes with the new version. |
The update compatibility tool involves two steps:
Generating the required metadata.
Checking the metadata to determine the possible upgrade type.
|
This command is under development. At the moment, it takes into consideration only the version of Keycloak and the embedded Infinispan to determine if a rolling update is possible. If those are unchanged, it reports that a rolling update is possible. The current version does not yet verify configuration changes and assumes all configuration changes are eligible for a rolling update. The same applies to changes to custom extensions and themes. A good use case when to use this is, for example, when you want to do a rolling update when you change the Keycloak theme or your custom extensions, and only want run recreate update when the version of Keycloak changes which does not yet allow a rolling update. While consumers of these commands should be aware of the limitations that exist today, they should not rely on the internal behavior or the structure of the metadata file as this is about to be enhanced in future versions.
Instead, they should rely only on the exit code of the |
To generate the metadata, execute the following command using the same Keycloak version and configuration options:
bin/kc.[sh|bat] update-compatibility metadata --file=/path/to/file.json --features=rolling-updatesThis command accepts all options used by the start command.
The metadata, in JSON format, is displayed in the console for debugging purposes.
The --file parameter allows you to save the metadata to a file.
This file is then used by the subsequent check command.
|
Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running the above command. Omitting any configuration options will result in incomplete metadata. |
This command checks the metadata generated by the previous command and compares it with the current configuration and Keycloak version. If you are upgrading to a new Keycloak version, this command must be executed with the new version.
bin/kc.[sh|bat] update-compatibility check --file=/path/to/file.json --features=rolling-updates
Failure to meet these requirements will result in an incorrect outcome. |
The command will print the result to the console. For example, if a rolling upgrade is possible, it will display:
[OK] Rolling Upgrade is available.Otherwise, the command will indicate that a rolling upgrade is not possible and, optionally, provide details about the incompatibility:
[Versions] Rolling Upgrade is not available. 'infinispan' is incompatible: Old=15.0.0.Final, New=15.0.11.Final (1)| 1 | In this example, the Infinispan version 15.0.0.Final is not compatible with version 15.0.11.Final and a rolling upgrade is not possible. |
Command exit code
To aid in the development of your automation and/or DevOps pipelines, the command’s exit code can be used to determine the upgrade type:
| Exit Code | Description |
|---|---|
|
Rolling Upgrade is possible. |
|
Unexpected error occurred (e.g., the metadata file is missing or corrupted). |
|
Invalid CLI option. |
|
Rolling Upgrade is not possible. The deployment must be shut down before applying the new configuration. |
|
Rolling Upgrade is not possible.
The feature |