How To Upgrade: Keycloak chart

This page describes how to upgrade the Keycloak chart and the components it manages. Because the Keycloak Operator version and the Keycloak instance version are decoupled, upgrades follow specific procedures to minimise or eliminate downtime.

Upgrade strategy overview

The chart defaults to update.strategy: Auto in the Keycloak CR. The operator evaluates the type of change on each reconciliation and chooses the appropriate strategy:

Change type	Strategy	Downtime
Patch version bump (same major.minor)	Rolling update on the StatefulSet	None
Minor or major version bump	Recreate (scale to 0, then up)	Yes: expected for schema migrations
Operator image bump only	Operator pod restarts; StatefulSet untouched	None

Upgrade procedures

Patch version upgrade (Keycloak image only)

Update keycloak.image.tag in your values file and run helm upgrade. The running operator detects the CR change and performs a rolling StatefulSet update.

helm upgrade keycloak . \
  --namespace keycloak \
  -f my-keycloak-values.yaml \
  --set keycloak.image.tag=0.3.0-26.6.5-postgres

The operator pod is not restarted.

Operator version upgrade

Update operator.image.tag in a dedicated release, separate from any Keycloak image change. The operator pod restarts; the Keycloak StatefulSet is not modified.

helm upgrade keycloak . \
  --namespace keycloak \
  -f my-keycloak-values.yaml \
  --set operator.image.tag=26.6.5

Minor or major Keycloak version upgrade

1. Upgrade the operator version first (separate helm upgrade); the operator must support the target Keycloak version before the Keycloak image is changed.
2. Update keycloak.image.tag to the new version. The operator detects the incompatible change and uses the recreate strategy.
3. Keycloak is scaled down, applies database schema migrations, then scales back up.

Plan a maintenance window for minor and major upgrades.

Chart version migration notes

From 0.5.4 to 0.6.1 (Mia-Platform v15.0.1 to v15.1.0)

No manual action required: install the new chart version.

Also note:

• The new top-level mode value controls how Keycloak runs. The default, operator, keeps the current behaviour. With mode: manual the chart deploys Keycloak as a StatefulSet without the Keycloak Operator: only one instance is allowed, the realms entries are ignored, and the Keycloak Service is named <release fullname>-service instead of keycloak-service.
• You can override the logo, the favicon and the other image assets of the built-in Keycloak theme with keycloak.themeCustomization, which is disabled by default.
• The realms value is no longer required by the chart schema.

This chart is at its initial release (v0.x). No prior chart versions exist, so there are no migration notes at this time.

Future releases that require user action will include step-by-step migration instructions in this section, along with the minimum Helm and operator versions required. Always review the chart CHANGELOG.md before upgrading.