ADR-033: Custom Resource Definitions as API

Category: architecture Provenance: human

Decision

Use Kubernetes Custom Resource Definitions (CRDs) as the API for managing Keycloak resources. All Keycloak configuration is declarative via CRD YAML manifests.

Rationale

CRDs are the Kubernetes-native way to extend the API. Provides declarative GitOps-friendly interface. kubectl works out of the box for managing resources. RBAC integrates natively. CRDs support validation, versioning, and schema evolution. Users already familiar with Kubernetes patterns. Eliminates need for custom API servers or CLIs. Works with all GitOps tools (ArgoCD, Flux) without special support.

Agent Instructions

Define all Keycloak resource types as CRDs with OpenAPI schemas. Users interact with operator exclusively through CRDs - no CLI, no API endpoints, no webhooks for configuration. CRDs are the single source of truth. Design CRD schemas to be intuitive and map closely to Keycloak's native concepts. Note that admission webhooks for validation (not configuration) are acceptable and encouraged for better UX - see ADR-040 for details.

Rejected Alternatives

REST API with custom API server

Additional infrastructure to maintain. Doesn't integrate with kubectl or RBAC. Not GitOps-friendly.

CLI tool for configuration

Not declarative, can't version control configurations easily. Doesn't fit GitOps workflows.