ADR-037: Support for operator-managed and external Keycloak instances

Category: architecture Provenance: human

Decision

Support both operator-managed Keycloak (deployed by operator) and external Keycloak instances (pre-existing, managed outside operator). Users choose via CRD configuration.

Rationale

Operator-managed Keycloak provides easy getting-started experience and full lifecycle management. External Keycloak supports existing deployments, migrations, and cases where Keycloak is managed separately (different team, external service). Flexibility increases adoption - users not forced to adopt operator's Keycloak management to use realm/client automation. Allows gradual migration: start with external, migrate to operator-managed later.

Agent Instructions

When designing Keycloak CRD, support both deployment modes. For operator-managed: include deployment spec (image, resources, database, etc.). For external: reference existing Keycloak via URL and credentials. Reconcilers must handle both cases. External Keycloak allows using existing instances without redeployment.

Rejected Alternatives

Only operator-managed Keycloak

Forces users to redeploy existing Keycloak instances. High migration barrier. Can't use with external Keycloak services.

Only external Keycloak

No getting-started path. Users must deploy Keycloak separately before using operator.