Hostzero-GmbH/keycloak-operator

This release focuses on cutting redundant write traffic against the Keycloak Admin API: every controller now diffs against the live representation and only PUTs when something actually changed. It also adds a new KeycloakIdentityProviderMapper CRD, fixes a handful of long-standing reconcile bugs (auth-flow execution order on Keycloak 25/26, KeycloakRole composites being silently dropped, firstBrokerLoginFlow deferred-binding crashes, public client secrets), and bumps to controller-runtime v0.24 / Kubernetes v0.36.

Highlights

• Cross-controller drift detection — every reconciler used to call Update<Resource> on every pass, regardless of whether the CR had drifted from Keycloak's stored state. On larger realms this drove significant write load (a ~120-client realm saw ~100/120 clients "updated" every 5-minute sync because Keycloak returns array/map fields in non-deterministic order and the JSON-string compare always reported drift). A new definitionsMatch comparator handles the three Keycloak-specific quirks — unordered string arrays (redirectUris, webOrigins, …), subset semantics for attributes-style maps, and name-keyed object arrays (protocolMappers) — and is wired into KeycloakClient, KeycloakRealm, ClusterKeycloakRealm, KeycloakUser, KeycloakRoleMapping, KeycloakIdentityProvider and KeycloakIdentityProviderMapper. In-sync resources log already in sync, skipping update at V(1) and issue zero writes. Special-cases config.clientSecret on IdPs and smtpServer.password on realms (Keycloak returns ********** on GET) so masked fields don't loop forever. (#71, #74, follow-ups — huge thanks to @NerdySoftPaw!)
• New KeycloakIdentityProviderMapper CRD — manage IdP mappers as standalone resources, mirroring the KeycloakProtocolMapper pattern. Each mapper references its parent KeycloakIdentityProvider by name and inherits realm/instance from it. Works around the Keycloak API limitation where mappers embedded in an IdentityProviderRepresentation or KeycloakRealm import are silently dropped on update. Ships with controller, client CRUD, RBAC, Helm wiring, export support, sample, docs, unit and e2e tests. (#68)
• Kubernetes Secret materialised for public KeycloakClients — public OAuth clients (publicClient: true) have no client_secret, so previously the operator wrote no Secret at all and every consumer chart had to special-case them. The operator now still creates/updates the Secret for public clients, emitting only the client-id key (honouring ClientSecretRefSpec.ClientIdKey). Matches the behaviour of the legacy legacy.k8s.keycloak.org operator and lets consumer charts inject the client-id via envFrom/secretKeyRef uniformly across public and confidential clients. (#72, thanks again @NerdySoftPaw!)
• Ready condition on every resource — all CRDs now expose a consistent Ready status condition, making it straightforward to gate downstream automation on resource readiness. (#69)

Bug fixes

• Auth flow execution order on Keycloak 25/26 — newly added flow executions all default to priority 0 (keycloak/keycloak#35765), so the previous raise-priority bubble-sort silently no-oped and the live order depended on Keycloak's storage order. The controller now sets explicit, monotonically increasing priorities via PUT (supported since Keycloak 25, keycloak/keycloak#27751) so the live tree matches the spec deterministically. Also drops the observedGeneration short-circuit so external drift (admin UI reorders, kcadm scripts, realm re-imports) is repaired on the next reconcile, with two new e2e regressions pinning the behaviour. (#78, fixes #76)
• KeycloakRole composites silently dropped — the role create/update endpoints in the Keycloak Admin API ignore the composites field of a RoleRepresentation, so a role declared with composite: true ended up as a plain non-composite role and membership changes were never reconciled. Mirroring the client-scope handling pattern, the operator now strips composites from the payload and reconciles membership via /roles/{role}/composites (and the client-role variant) by diffing the desired set against what Keycloak returns. (fixes #73)
• KeycloakRealm crash on deferred firstBrokerLoginFlow — referencing a not-yet-created firstBrokerLoginFlow made Keycloak crash on import with an NPE in RealmAdapter.setFirstBrokerLoginFlow, because the field was missing from realmFlowBindingFields and never deferred. Added to the strip list, covered by unit tests for every documented binding and an e2e regression. (fixes #70)
• Realm SMTP password reconcile loop — smtpSecretRef triggered drift on every reconcile because Keycloak masks smtpServer.password as ********** on GET. A dedicated realmDefinitionsMatch wrapper strips the password from both sides only when the live state shows the mask, so the first PUT still pushes the real value but subsequent reconciles converge cleanly.
• Orphan protocolMappers not removed — the object-array branch in valuesMatch matched desired against current by name and subset-compared their fields, but did not check array lengths. Orphan protocol mappers present in Keycloak but absent from the CR therefore failed to surface as drift. Equal-length is now required before the name-match loop so removals reconcile.
• KeycloakRoleMapping group mappings hammered on every reconcile — the reconciler skipped the already-mapped check for groups with a comment claiming no GetGroupRoleMappings methods existed; in practice the client has GetGroupRealmRoleMappings and GetGroupClientRoleMappings. Extended the check so group mappings stop hitting Add… on every pass.

Build, CI & dependencies

• Bump sigs.k8s.io/controller-runtime to v0.24.1 and k8s.io/api / k8s.io/apimachinery / k8s.io/client-go to v0.36.1.
• Replace the deprecated scheme.Builder with a local equivalent in api/v1beta1 to silence the SA1019 staticcheck warning.

Documentation

• Document the KeycloakRequiredAction CRD.
• Document the public-client Secret materialisation behaviour.
• De-duplicate the Supported Resources section.

Upgrade Guide

Helm Upgrade

helm upgrade keycloak-operator oci://ghcr.io/hostzero-gmbh/charts/keycloak-operator \
  --namespace keycloak-operator \
  --version 0.8.0

New contributors

• @NerdySoftPaw made their first contributions in #71 (drift detection across controllers) and #72 (public client secret materialisation).

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.7.0...v0.8.0

What's Changed

• chore(deps): bump sigs.k8s.io/controller-runtime from 0.23.3 to 0.24.0 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/66
• Add keycloakidentityprovidermapper crd for managing idp mappers by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/68
• Add drift-detection across all controllers to skip redundant updates by @NerdySoftPaw in https://github.com/Hostzero-GmbH/keycloak-operator/pull/71
• Materialize Kubernetes Secret with client-id for public KeycloakClients by @NerdySoftPaw in https://github.com/Hostzero-GmbH/keycloak-operator/pull/72
• fix(idp-mapper): skip update when in sync to avoid reconcile storms by @NerdySoftPaw in https://github.com/Hostzero-GmbH/keycloak-operator/pull/74
• Enforce auth flow execution order and detect drift, fixes #76 by @pehlert in https://github.com/Hostzero-GmbH/keycloak-operator/pull/78
• chore(deps): bump k8s.io/apimachinery from 0.36.0 to 0.36.1 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/82
• chore(deps): bump k8s.io/api from 0.36.0 to 0.36.1 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/81
• chore(deps): bump sigs.k8s.io/controller-runtime from 0.24.0 to 0.24.1 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/80
• chore(deps): bump k8s.io/client-go from 0.36.0 to 0.36.1 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/79

New Contributors

• @NerdySoftPaw made their first contribution in https://github.com/Hostzero-GmbH/keycloak-operator/pull/71

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.7.0...v0.8.0