Keycloak Operator 26.6 turns a routine rollback into a CRD migration problem
Red Hat says moving back to 26.4 can fail after Kubernetes records v2beta1 as a stored version, so operators need a tested rollback path before upgrading.
Red Hat has documented a rollback trap in the Red Hat build of Keycloak Operator 26.6.x: after installing the newer operator, an attempt to return to a 26.4.x release can fail because the older custom resource definitions do not include an API version Kubernetes now records as stored.
The public portion of Red Hat’s verified solution shows the API server refusing updates to both keycloaks.k8s.keycloak.org and keycloakrealmimports.k8s.keycloak.org. The message warns that the replacement CRD would remove v2beta1 while that version remains listed as stored. This is a protective refusal, not evidence that Keycloak has already lost realm data.
Why 26.6 changes the rollback boundary
The 26.6 release notes explain the other half of the failure. That release adds v2beta1 for the Keycloak and KeycloakRealmImport resources, while retaining the previous v2alpha1 version as served but deprecated. Red Hat says the schemas are currently identical and recommends changing relevant apiVersion references to v2beta1.
That forward migration looks small at the manifest level, but it changes cluster state. Once Kubernetes has persisted the new version, applying an older operator bundle whose CRDs omit it is no longer equivalent to replacing one controller image with another. The API server blocks the CRD change described by Red Hat because it would drop a version still represented in the CRD’s stored-version history.
Who should act
Platform teams running Red Hat build of Keycloak Operator 26.4.x and planning an upgrade to 26.6.x should treat rollback as a separate migration procedure. The same applies to teams that use automated operator rollback as part of an incident playbook: reinstalling the previous catalog version is not, by itself, a complete recovery test.
Before production rollout, verify the Keycloak and KeycloakRealmImport CRDs in a representative cluster, exercise the rollback path in a non-production environment, and preserve the resource and database backups required by the organization’s existing Keycloak recovery plan. Red Hat’s public solution identifies the failure and affected versions, but its remediation content is subscriber-only; customers should use that verified procedure or open a support case rather than editing CRD status fields ad hoc.
The practical lesson is narrow but important: 26.6’s v2beta1 transition is schema-compatible in the forward direction, yet it creates state that an older operator definition may not accept on the way back. Upgrade reviews should therefore include the CRD storage-version boundary, not only Keycloak application and database compatibility.
sources
comments · 0