ADR-018: Management port separation - Keycloak 25+

Category: architecture Provenance: guided-ai

Decision

Use the separate management interface (port 9000) for health checks and metrics when available (Keycloak 25.0.0+). For Keycloak 24.x, fall back to port 8080 for health checks since the management interface is not available. User traffic always uses port 8080.

Rationale

Security: Separates management endpoints from user traffic when possible (25.x+). Backward compatibility: Supports 24.x users who need the operator but cannot upgrade. Production ready: Management port is production best practice from Keycloak 25+. Health checks: Dedicated management port prevents health check impact on user traffic.

Agent Instructions

Health check port is version-dependent: - Keycloak 25.x+: Use management port 9000 for /health/ready and /health/live - Keycloak 24.x: Use main HTTP port 8080 for health checks (no management interface) Use supports_management_port() and get_health_port() from keycloak_operator.utils.validation to determine correct port at runtime. User traffic always on port 8080. See ADR-059 for multi-version support architecture.