mirror of
https://github.com/keycloak/keycloak.git
synced 2026-01-25 16:42:34 +00:00
137 lines
6.4 KiB
Plaintext
137 lines
6.4 KiB
Plaintext
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
<#import "/templates/links.adoc" as links>
|
|
|
|
<@tmpl.guide
|
|
title="Checking if rolling updates are possible"
|
|
summary="Execute the update compatibility command to check if {project_name} supports a rolling update for a change in your deployment."
|
|
>
|
|
|
|
Use the update compatibility command to determine if you can update your deployment with a rolling update strategy when enabling or disabling features or changing the {project_name} version, configurations or providers and themes.
|
|
The outcome shows whether a rolling update is possible or if a recreate update is required.
|
|
|
|
In its current version, it shows that a rolling update is possible when the {project_name} version is the same for the old and the new version.
|
|
Future versions of {project_name} might change that behavior to use additional information from the configuration, the image and the version to determine if a rolling update is possible.
|
|
|
|
This is fully scriptable, so your update procedure can use that information to perform a rolling or recreate strategy depending on the change performed.
|
|
It is also GitOps friendly, as it allows storing the metadata of the previous configuration in a file. Use this file in a CI/CD pipeline with the new configuration to determine if a rolling update is possible or if a recreate update is needed.
|
|
|
|
If you are using the {project_name} Operator, continue to the <@links.operator id="rolling-updates" /> {section} and the `Auto` strategy for more information.
|
|
|
|
== Supported update strategies
|
|
|
|
Rolling Update::
|
|
In this guide, a rolling update is an update that can be performed with zero downtime for your deployment, which consists of at least two nodes.
|
|
Update your {project_name} one by one; 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 {project_name} node. See {section} <@links.observability id="health"/> for details on how to enable and use the start-up probe.
|
|
|
|
Recreate Update::
|
|
A recreate update 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.
|
|
|
|
== Determining the update strategy for an updated configuration
|
|
|
|
To determine if a rolling update is possible, run the update compatibility command:
|
|
|
|
1. Generate the required metadata with the old configuration.
|
|
2. Check the metadata with the new configuration to determine the update strategy.
|
|
|
|
[WARNING]
|
|
====
|
|
This command currently offers only a limited functionality. At the moment, it takes into consideration only the version of {project_name} 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 {project_name} theme or your custom extensions, and only want run recreate update when the version of {project_name} changes which does not yet allow a rolling update.
|
|
|
|
While consumers of these commands should know the limitations that exist today, they should not rely on the internal behavior or the structure of the metadata file.
|
|
Instead, they should rely only on the exit code of the `check` command to benefit from future enhancements on the internal logic to determine when a rolling update is possible.
|
|
====
|
|
|
|
=== Generating the Metadata
|
|
|
|
To generate the metadata, execute the following command using the same {project_name} version and configuration options:
|
|
|
|
.Generate and save the metadata from the current deployment.
|
|
<@kc.updatecompatibility parameters="metadata --file=/path/to/file.json"/>
|
|
|
|
This command accepts all options used by the `start` command.
|
|
The command displays the metadata, in JSON format, in the console for debugging purposes.
|
|
The `--file` parameter allows you to save the metadata to a file.
|
|
Use this file with the subsequent `check` command.
|
|
|
|
[WARNING]
|
|
====
|
|
Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running the above command.
|
|
|
|
Omitting any configuration options results in incomplete metadata, and could lead to a wrong reported result in the next step.
|
|
====
|
|
|
|
=== Checking the Metadata
|
|
|
|
This command checks the metadata generated by the previous command and compares it with the current configuration and {project_name} version.
|
|
If you are upgrading to a new {project_name} version, this command must be executed with the new version.
|
|
|
|
.Check the metadata from a previous deployment.
|
|
<@kc.updatecompatibility parameters="check --file=/path/to/file.json"/>
|
|
|
|
[WARNING]
|
|
====
|
|
* Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running this command.
|
|
|
|
* Verify that the correct {project_name} version is used.
|
|
|
|
Failure to meet these requirements results in an incorrect outcome.
|
|
====
|
|
|
|
The command prints the result to the console.
|
|
For example, if a rolling update is possible, it displays:
|
|
|
|
.Rolling Update possible message
|
|
[source,bash]
|
|
----
|
|
[OK] Rolling Update is available.
|
|
----
|
|
|
|
If no rolling update is possible, the command provides details about the incompatibility:
|
|
|
|
.Rolling Update not possible message
|
|
[source,bash]
|
|
----
|
|
[keycloak] Rolling Update is not available. 'keycloak.version' is incompatible: 26.2.0 -> 26.2.1 #<1>
|
|
----
|
|
<1> In this example, the Keycloak version `26.2.0` is not compatible with version `26.2.1` and a rolling update is not possible.
|
|
|
|
*Command exit code*
|
|
|
|
Use the command's exit code to determine the update type in your automation pipeline:
|
|
|
|
|===
|
|
|Exit Code |Description
|
|
|
|
m|0
|
|
|Rolling Update is possible.
|
|
|
|
m|1
|
|
|Unexpected error occurred (such as the metadata file is missing or corrupted).
|
|
|
|
m|2
|
|
|Invalid CLI option.
|
|
|
|
m|3
|
|
|Rolling Update is not possible.
|
|
The deployment must be shut down before applying the new configuration.
|
|
|
|
m|4
|
|
|Rolling Update is not possible.
|
|
The feature `rolling-updates` is disabled.
|
|
|===
|
|
|
|
== Further reading
|
|
|
|
The {project_name} Operator uses the functionality described above to determine if a rolling update is possible. See the <@links.operator id="rolling-updates" /> {section} and the `Auto` strategy for more information.
|
|
|
|
</@tmpl.guide>
|