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

SUPERSEDED - See ADR-059 for current multi-version support (24.x+). This ADR is kept for historical context only.

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.