ADR-035: Keycloak 25.0+ version support requirement

Category: architecture Provenance: human

Decision

Require Keycloak 25.0.0 or later. Operator validates Keycloak version and rejects unsupported versions. Default to latest stable Keycloak version (currently 26.4.x).

Rationale

Keycloak 25.0.0 introduced separate management interface (port 9000) which is required for proper health checks and metrics without impacting user traffic. Earlier versions lack this feature. Enforcing minimum version ensures consistent behavior and allows operator to depend on modern Keycloak features. Clear version requirement reduces support burden from incompatible configurations.

Agent Instructions

Enforce minimum Keycloak version 25.0.0 in operator code. Update DEFAULT_KEYCLOAK_VERSION in constants.py to track latest stable. Add version validation in reconcilers. Document version requirements clearly. Reject Keycloak instances with versions < 25.0.0 with clear error messages.

Rejected Alternatives

Support all Keycloak versions

Pre-25.0 lacks management port, forcing health checks on user-facing port. Different behavior paths increase complexity.

Support back to Keycloak 20.x

Significant API changes between versions. Supporting multiple API versions increases maintenance burden.