ADR-058: Single Keycloak version support (26.x)

Category: architecture Provenance: human

Decision

Operator supports only Keycloak 26.x (currently 26.4.1). Multiple version support is planned but not implemented. Users must use the same Keycloak version as defined in DEFAULT_KEYCLOAK_IMAGE constant.

Rationale

Single version support simplifies development - no API compatibility matrix, no feature detection, no version-specific code paths. Keycloak API relatively stable within major versions but changes between majors. Supporting multiple versions requires testing each Keycloak version, maintaining compatibility shims, detecting feature availability. Resources better spent on core features now. Users can pin operator version matching their Keycloak version. When multi-version support added, it will be a planned feature (decision 008 feature parity). Current approach: stay on latest Keycloak version, update operator when Keycloak updates.

Agent Instructions

Current supported version: 26.4.1 (see DEFAULT_KEYCLOAK_IMAGE in src/keycloak_operator/constants.py). Minimum version: 25.0.0 for management port (decision 018). Operator assumes 26.x API and features. When Keycloak releases new versions, update DEFAULT_KEYCLOAK_IMAGE constant. Test against new version before updating. Multiple version support planned but blocked by API compatibility testing and feature detection needs. Reject version mismatches with clear error messages. Document supported version in README and Helm chart.

Rejected Alternatives

Support all Keycloak versions 25.0+

Requires extensive compatibility testing. API differences between versions need conditional code. Feature detection complexity.

No version enforcement

Silent failures when API changes. Confusing error messages. Operator assumes features present.

Support only latest major (27.x when it releases)

Forces users to upgrade Keycloak before operator. Breaking for existing deployments.