Decision Records

This section contains Architecture Decision Records (ADRs) documenting significant architectural and design decisions made during the development of the Keycloak Operator.

Browse by Category

Architecture Decisions (34 records)

Core design decisions affecting system structure, behavior, and runtime characteristics.

Development Decisions (34 records)

Tooling, processes, testing strategies, and development workflow decisions.

About ADRs

Architecture Decision Records capture important architectural decisions along with their context and consequences. Each ADR documents:

• Decision: What was decided
• Context: Why the decision was needed
• Rationale: Why this particular solution was chosen
• Consequences: Expected positive and negative outcomes
• Alternatives: Other options considered and why they were rejected

Key Decision Records

Here are some particularly important ADRs for understanding the system:

• ADR-017: Kubernetes RBAC over Keycloak security
• ADR-063: Namespace grant list authorization (current model)
• ADR-040: Admission webhooks for validation
• ADR-019: Drift detection
• ADR-001: Kopf as operator framework

Architecture Decisions

• ADR-001: Kopf as operator framework
• ADR-003: Least privilege everywhere
• ADR-008: Feature parity with self-managed Keycloak
• ADR-012: Async API with rate limiting and retries
• ADR-013: Pydantic models for Keycloak API
• ADR-014: Separate Helm charts per resource type
• ADR-015: CloudNativePG as first-class database
• ADR-016: Multi-namespace operation by default
• ADR-017: Kubernetes RBAC over Keycloak security
• ADR-018: Management port separation - Keycloak 25+
• ADR-019: Drift detection and continuous reconciliation
• ADR-025: Realm and Client as primary CRD resource types
• ADR-026: Three-layer responsibility system with token delegation
• ADR-032: Minimal RBAC with namespaced service accounts
• ADR-033: Custom Resource Definitions as API
• ADR-035: Keycloak 25.0+ version support requirement
• ADR-037: Support for operator-managed and external Keycloak instances
• ADR-039: Token rotation and bootstrap flows
• ADR-040: Admission Webhooks for Resource Validation
• ADR-045: Active-standby HA using Kopf peering
• ADR-046: Multiple operator support with explicit references
• ADR-047: Managed Keycloak for quick start
• ADR-048: Prometheus metrics exposure
• ADR-049: Horizontal scaling via multiple operator deployments (realm sharding)
• ADR-053: Error categorization - temporary vs permanent
• ADR-054: Namespace watch scope requires cluster-wide RBAC
• ADR-056: No opinionated backup or secret management
• ADR-058: Single Keycloak version support (26.x)
• ADR-059: No managed Keycloak upgrades
• ADR-060: Cascading deletes for dependent resources
• ADR-062: One Keycloak instance per operator deployment
• ADR-063: Namespace grant list authorization for clients
• ADR-065: Webhook certificate management with cert-manager
• ADR-066: Centralized settings management with pydantic-settings

Development Decisions

• ADR-002: uv for dependency management
• ADR-004: Everything must be GitOpsable
• ADR-005: No plaintext secrets
• ADR-006: All functionality must be tested with pytest
• ADR-007: Integration tests in Kind clusters
• ADR-009: AI agents as first-class developers
• ADR-010: Semantic versioning for all artifacts
• ADR-011: Conventional commits for all development
• ADR-020: Real Kubernetes for integration testing
• ADR-021: Pre-commit hooks with strict validation
• ADR-022: Type annotations with ty for type checking
• ADR-023: Make for development automation
• ADR-024: Helm as deployment mechanism
• ADR-027: JSON schemas published to GitHub Pages
• ADR-028: Documentation published to GitHub Pages
• ADR-029: Versioned documentation with mike
• ADR-030: Helm charts published to GitHub Pages OCI registry
• ADR-031: Automated releases with release-please
• ADR-034: GitHub Actions for CI and artifact publication
• ADR-036: Automated dependency updates with Dependabot and custom workflows
• ADR-040: Ruff for formatting and linting
• ADR-041: Shared operator fixture in tests
• ADR-042: pytest-xdist for parallel integration tests
• ADR-043: Wait helpers with debug logging in tests
• ADR-044: Extra manifests support in Helm charts
• ADR-050: Structured JSON logging
• ADR-051: Multi-stage Docker builds for minimal images
• ADR-052: Optimized Keycloak container for tests
• ADR-055: Container image registry and tagging strategy
• ADR-057: CR data must be validated with Pydantic models
• ADR-061: GitHub Issues for planned work with AI agent instructions
• ADR-064: No force-delete annotation for finalizers
• ADR-067: Integration test coverage collection via SIGUSR1 signal
• ADR-068: Always recreate test cluster