ADR-062: One Keycloak instance per operator deployment¶
Category: architecture Provenance: human
Decision¶
Each operator deployment manages exactly one Keycloak instance. Default Helm chart deploys managed Keycloak alongside operator in same namespace. External Keycloak instances supported as alternative.
Rationale¶
One-to-one mapping simplifies operator configuration and reduces complexity. Operator maintains single admin connection, single rate limiter, single health check target. Multi-Keycloak support would require connection pooling, per-instance rate limiting, complex failover logic. Users needing multiple Keycloak instances deploy multiple operators (horizontal scaling per decision 045). Managed Keycloak in same namespace enables quick start - single Helm install gets working system. External Keycloak supports production deployments where Keycloak managed separately. Clear 1:1 relationship simplifies troubleshooting and RBAC. Operator namespace contains everything for that Keycloak instance - clean isolation.
Agent Instructions¶
Operator manages one Keycloak instance only. Chart default (keycloak.enabled=false in charts/keycloak-operator/values.yaml line 240) deploys operator without managed Keycloak - expects external instance. Set keycloak.enabled=true to deploy managed Keycloak in operator namespace. Realms and Clients reference their Keycloak instance via keycloak_instance field (src/keycloak_operator/models/realm.py line 718, client.py line 517). Multiple Keycloak instances require multiple operator deployments. Decision 037 covers external vs managed Keycloak. Decision 047 covers managed Keycloak for quick start.
Rejected Alternatives¶
One operator manages multiple Keycloak instances¶
Complex connection management. Rate limiter shared across instances or per-instance complexity. Health checks for N instances. Configuration explosion.
Global operator manages all Keycloak instances cluster-wide¶
Single point of failure. No isolation between Keycloak instances. RBAC and security boundaries unclear. Scaling bottleneck.
Always require managed Keycloak (no external option)¶
Doesn't support existing Keycloak deployments. Forces specific deployment pattern. Reduces flexibility.
Never deploy managed Keycloak (external only)¶
No quick start path. Users must deploy Keycloak separately before using operator. Higher barrier to entry.