apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
update:
strategy: RecreateOnImageChange|Auto|Explicit (1)
revision: "abc" (2)
By default, the Keycloak Operator will perform rolling updates on configuration changes without downtime, and recreate updates with downtime when the image name or tag changes.
This guide describes how to minimize downtimes by configuring the Keycloak Operator to perform rolling updates of Keycloak automatically where possible, and how to override automatic detection for rolling updates.
Use it, for example, to avoid downtimes when rolling out an update to a theme, provider or build time configuration in a custom or optimized image.
The Operator supports the following update strategies:
Update the StatefulSet in a rolling fashion, avoiding a downtime when at least two replicas are running.
Scale down the StatefulSet before applying updates, causing temporary downtime.
Specify the update strategy within the spec
section of the Keycloak CR YAML definition:
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
update:
strategy: RecreateOnImageChange|Auto|Explicit (1)
revision: "abc" (2)
1 | Set the desired update strategy here. |
2 | Revision value for Explicit strategy.
Ignored by the other strategies. |
Value | Downtime? | Description |
---|---|---|
|
On image name or tag change |
Mimics Keycloak 26.1 or older behavior. When the image field changes, the Operator scales down the StatefulSet before applying the new image. |
|
On incompatible changes |
The Keycloak Operator detects if a rolling or recreate update is possible. In the current version, Keycloak performs rolling update if the Keycloak version is the same for the old and the new image. Future versions of Keycloak will change that behavior and use additional information from the configuration, the image and the version to determine if a rolling update is possible to reduce downtimes. |
|
Only the |
The Keycloak Operator checks the |
Auto
and Explicit
Update StrategiesWhen using the Auto
update strategy, the Keycloak Operator automatically starts a Job to assess the feasibility of a rolling update.
Read more about the process in the Checking if rolling updates are possible guide.
This process consumes cluster resources for the time of the check and introduces a slight delay before the StatefulSet update begins.
The Explicit
update strategy delegates the update decision to the user.
The revision
field acts as a user-controlled trigger.
While the Keycloak Operator does not interpret the revision
value itself, any change to the Custom Resource (CR) while the revision
remains unchanged will prompt a rolling update.
Exercise caution when using this with automatic Operator upgrades.
The Operator Lifecycle Manager (OLM) may upgrade the Keycloak Operator, and if the Explicit
update strategy is in use, this could lead to unexpected behavior or deployment failures as the Operator would attempt a rolling update when this is actually not supported.
If you are using the Explicit
update strategy, thorough testing in a non-production environment is highly recommended before upgrading.
The Keycloak CR status of RecreateUpdateUsed
indicates the update strategy employed during the last update operation.
The lastTransitionTime
field indicates when the last update occurred.
Use this information to observe actions and decisions taken by the Operator.
Status | Description |
---|---|
|
The initial state. It means no update has taken place. |
|
The Operator applied the rolling update strategy in the last update. |
|
The Operator applied the recreate update strategy in the last update.
The |