RFC: Multi-cluster support & central orchestration patterns

[vriesdemichael]

Summary

Add an RFC and implementation plan for multi-cluster support and central orchestration patterns for the Keycloak operator.

Motivation

Large organizations require recommended, opinionated patterns to operate Keycloak across multiple clusters: fleet management, recommended GitOps repo layout, monitoring/alert aggregation, failover and DR patterns for CNPG, and test strategies for fleet validation.

Proposed deliverables

• ADR describing recommended multi-cluster patterns (central GitOps, per-cluster operators, repo layout, security implications)
• Docs: step-by-step guide for deploying and operating at fleet scale
• Example repo layout and ArgoCD/Flux application-of-apps patterns
• Runbook: cross-cluster failure scenarios and CNPG failover guidance
• Integration test plan and at least one example harness or tests (simulated fleet)
• Monitoring guidance for fleet-level aggregation: label conventions, Prometheus federation, Grafana fleet dashboards

Acceptance Criteria

• ADR merged and docs added under docs/ with examples and recommended patterns
• Example repo layout and at least one sample application-of-apps repository in examples/ or docs/
• Integration test(s) validating the recommended flow (or documented test harness)

Notes

Start as RFC broad issue; split into implementation tasks (docs, ADR, tests, examples) once agreed.

[vriesdemichael]

An approach might be to have a mechanism for a remotely owned realm (in a different cluster) but have permission to create a client for it.

If we skip the possibility for a single realm for multiple clusters we can just prefix everything in keycloak.

An alternative approach is have the secrets only replicated to different clusters, for instance by ESO with PushSecret.
That way the management is split, can still be gitops but replicated across clusters for usage in applications. The keycloak instance, operator, realm and client then still have their same parent scope.

Other options are federated approaches for entire CRs + secrets with tools such as karmada, admiralty or clusterpedia