docs: operational risk profile for the keycloak-operator

[vriesdemichael]

Context

This issue was created as a companion to #94 (threat model documentation). During the threat modelling planning session it became clear that security risk and operational risk are distinct concerns aimed at different audiences and decision types:

• Threat model (docs: Create security threat model and mitigation documentation #94): Given I'm deploying this — who can attack me and how? (security teams, auditors)
• Operational risk (this issue): Should I deploy this at all, and what am I signing up for? (architects, platform leads, CTOs signing off)

Purpose

Create docs/operations/operational-risk.md — a frank risk profile for decision makers evaluating this operator.

Topics to cover

Blast radius vs manual management

Compare the risk profile of:

• Operator compromise (full Keycloak admin access across all realms)
• Manual admin access (per-person, potentially more accounts, harder to audit)
• The trade-off: operator consolidates blast radius but also consolidates audit trail

Dependency risk

Enumerate hard runtime dependencies and their failure modes:

• Kopf (operator framework) — pin strategy, upgrade path (ADR-083)
• CNPG (database) — not strictly required but first-class supported (ADR-015)
• cert-manager — required for webhook TLS (ADR-065)
• Keycloak version lock — single major version supported at a time (ADR-058/059)
• Python ecosystem — uv-managed, reproducible

GitOps fidelity vs drift window

• Periodic reconciliation means out-of-band Keycloak changes are not immediately corrected
• Manual Keycloak admin access is the primary drift source
• Drift is detectable (admin events) and should be treated as a security event
• Document the configurable interval and its security implications

Support posture

Be honest:

• OSS, unfunded, maintained by a single maintainer in their free time
• No SLA, no guaranteed response time for security disclosures
• No CVE process currently defined
• Suitable for: organizations with internal Kubernetes/Python expertise who can own the operator
• Less suitable for: teams that need vendor-backed support or who cannot contribute upstream fixes

When to use this operator vs alternatives

Scenario	Recommendation
Multi-tenant SaaS, strong GitOps requirement	This operator
Single-tenant, manual Keycloak management acceptable	Official operator or manual
Regulated environment needing vendor support	Evaluate Red Hat RHSSO/upstream with enterprise support
Need to manage users (not just realms/clients)	Out of scope for this operator

Operational ownership requirements

What a team needs to have in place to safely run this:

• Kubernetes RBAC expertise to correctly scope operator permissions
• Monitoring of operator metrics and alerts on reconciliation failures
• Secret rotation process for the Keycloak admin credential
• Network policy enforcement at the platform level (operator does not ship them — ADR-076)
• Encryption at rest for etcd Secrets (platform responsibility)
• Regular image updates / Dependabot monitoring

Acceptance criteria

• Document lives at docs/operations/operational-risk.md
• Linked from docs/operations/ index and from docs/concepts/security.md
• Covers all topics above
• Tone is honest and direct — avoids marketing language
• References relevant ADRs for each design decision discussed

Priority

Medium — Valuable for enterprise adoption decisions, but non-blocking for core functionality.

References

• docs: Create security threat model and mitigation documentation #94 — threat model documentation (companion issue)
• ADR-003: Least privilege everywhere
• ADR-056: No opinionated backup or secret management
• ADR-073: Security and multi-tenancy model
• ADR-076: No network policies in Helm chart
• ADR-083: Kopf version pin