ADR-018: Management port separation - Keycloak 25+

Category: architecture Provenance: guided-ai

Decision

Require Keycloak 25.0.0 or later which supports separate management interface (port 9000). Use management port for health checks and metrics, port 8080 for user traffic.

Rationale

Security: Separates management endpoints from user traffic. Production ready: Management port is production best practice from Keycloak 25+. Health checks: Dedicated management port prevents health check impact on user traffic. Version enforcement: Ensures users run supported, modern Keycloak versions.

Agent Instructions

Enforce minimum Keycloak version 25.0.0. Health checks use management port (9000) for /health/ready and /health/live. User traffic on port 8080. Reject versions < 25.0.0. Update DEFAULT_KEYCLOAK_VERSION in src/keycloak_operator/constants.py when new stable versions release.