> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Resources CRDs for Self Service APIs
> Overview of Kubernetes CustomResourceDefinitions for creating intent-based self-service APIs, covering schema validation, controllers and operators, RBAC, versioning, observability, patterns and best practices
CRDs (CustomResourceDefinitions) let platform teams extend the Kubernetes API with domain-specific resources and intent-based APIs. They are a core building block for platform engineering: expose simple, validated interfaces to developers while platform controllers handle the operational complexity.
CRDs are ideal when you need:
* Domain-specific abstractions (for example: PonyDatabase, Environment, SearchCluster).
* Intent-based APIs that hide low-level objects (Pods, Services, PVCs).
* Server-side validation, kubectl integration, discovery, and RBAC control.
Key capabilities of CRDs:
* Define new Kubernetes-like resource types with `kind`, `apiVersion`, and REST endpoints.
* Enforce validation using OpenAPI v3 schemas.
* Integrate with standard tooling (kubectl, API discovery) and RBAC.
* Serve as the contract that controllers use to reconcile desired state to actual cluster resources.
CRDs provide the API surface and validation. To make a CRD functional you normally implement a controller or operator that watches custom resources and performs provisioning, lifecycle management, and reconciliation.
## Basic CRD example
Below is a minimal, valid CRD that defines a namespaced `PonyDatabase` resource with a simple OpenAPI v3 validation that restricts the `size` field to `small | medium | large`:
```yaml theme={null}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: ponydatabases.platform.sparkleponyranch.com
spec:
group: platform.sparkleponyranch.com
names:
plural: ponydatabases
singular: ponydatabase
kind: PonyDatabase
shortNames:
- pdb
scope: Namespaced
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
size:
type: string
enum:
- small
- medium
- large
```
Notes on this CRD:
* `metadata.name` must be `.`, enabling API discovery.
* `names` controls how the resource appears to users and tools (`kind`, `plural`, `shortNames`).
* `scope: Namespaced` places objects inside namespaces — change to `Cluster` for cluster-scoped resources.
* `openAPIV3Schema` provides server-side validation for fields under `spec`, reducing misconfiguration.
### Example custom resource using that CRD
Once the CRD is installed, developers create resources like this to express intent:
```yaml theme={null}
apiVersion: platform.sparkleponyranch.com/v1
kind: PonyDatabase
metadata:
name: user-profiles-db
namespace: dev-team
spec:
size: "medium"
backupEnabled: true
team: "magical-creatures"
environment: "development"
```
The controller/operator that owns `PonyDatabase` reads this `spec` and provisions the underlying resources (StatefulSets, Services, PVCs, backups, Secrets) — developers only declare intent.
## Validation, documentation, and guardrails
CRDs provide built-in validation and generate machine-readable API documentation (OpenAPI v3). Use schemas to:
* Enforce required fields and allowed values (enums).
* Apply numeric constraints (minimum/maximum).
* Prevent unsupported configurations and enforce governance.
Benefits:
* Early detection of invalid manifests.
* Better developer UX: `kubectl explain` and generated API docs.
* Clear upgrade and governance paths via controlled schema changes.
## Designing CRDs collaboratively
CRD design sits at the intersection of product, infrastructure, and SRE. Collaborate early to choose fields, defaults, lifecycle semantics, and status reporting. Good collaboration reduces iteration and operational surprises.
## Controllers and the reconciliation loop
A CRD defines shape and rules; controllers implement behavior. Controllers:
* Watch custom resources and related objects.
* Compare desired (`spec`) vs actual cluster state.
* Plan and execute changes (create/update/delete dependent resources).
* Update `status` with progress and health.
Reconciliation is continuous. Typical loop:
1. Watch (event or periodic sync)
2. Validate current vs desired state
3. Plan changes
4. Execute (create/update/delete)
5. Observe and update `status`
6. Repeat
This level-driven approach ensures the cluster converges to the declared state.
## Securing CRD access with RBAC
CRDs integrate with Kubernetes RBAC so teams can be allowed to create and manage high-level resources without giving access to low-level primitives.
Example Role allowing a team to manage PonyDatabase objects and view Pods:
```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: pony-database-user
namespace: dev-team
rules:
- apiGroups:
- platform.sparkleponyranch.com
resources:
- ponydatabases
verbs:
- get
- list
- create
- update
- apiGroups:
- ""
resources:
- pods
verbs:
- get
- list
```
This enforces least privilege: teams can request databases but cannot directly change underlying Pods or cluster-level resources.
When granting permissions, prefer roles scoped to a namespace and use the least-privilege principle. Avoid giving broad cluster-level permissions unless strictly required.
## Evolving CRD schemas and API versions
CRDs support versioning and conversion. Best practices when evolving schemas:
* Make additive, backward-compatible changes where possible.
* Avoid removing fields; mark fields deprecated and provide migration paths.
* Use `conversion` webhooks or structural schemas for multi-version support.
## Developer experience features
CRDs offer UX features that make life easier for teams:
* Subresources (`status`, `scale`) enable safe status updates and HPA integration.
* Additional printer columns and custom printers improve `kubectl get` output.
* Controllers can expose Prometheus metrics for reconcilers, queue depth, and durations.
## Choosing the right extension
Decide between simple config, schema-only extension, or schema+automation:
| Extension Type | Use Case | Complexity | Validation |
| - | -: | -: | - |
| ConfigMaps | Simple key/value configuration | Low | None (client-side only) |
| CRDs | Domain-specific API with schema validation | Medium | OpenAPI v3 server-side validation |
| Operators | CRD plus controller/operator with orchestration logic | High | Schema + automation and lifecycle logic |
Operators are CRDs with controllers that encode operational knowledge, automated workflows, and domain logic. Choose an Operator when you need both schema and complex orchestration.
## CRD design best practices
* Design for developers: clear names, predictable defaults, and good docs.
* Prefer additive changes; mark fields deprecated before removal.
* Expose rich `status` for Day-2 operations (progress, conditions).
* Instrument controllers (metrics, events, logs).
* Validate and sanitize inputs; enforce policies via admission controllers or OPA/Gatekeeper.
## Common CRD patterns
Typical platform CRDs:
* DatabaseClaims — request a managed database.
* Environment — provision a dev/test/stage environment.
* Application — deploy an app with opinionated defaults.
* Certificate — request TLS certificates.
These intent-based CRDs map developer requests to platform-managed resources; add controllers when orchestration is required.
## Tools and local validation
Tools to accelerate CRD and controller development:
* controller-gen — generate CRD YAML & boilerplate from Go types: [https://github.com/kubernetes-sigs/controller-tools/tree/master/cmd/controller-gen](https://github.com/kubernetes-sigs/controller-tools/tree/master/cmd/controller-gen)
* Kubebuilder — scaffold CRDs and controllers: [https://book.kubebuilder.io/](https://book.kubebuilder.io/)
* Operator SDK — higher-level operator framework: [https://sdk.operatorframework.io/](https://sdk.operatorframework.io/)
Validate locally before applying:
```bash theme={null}
kubectl apply --dry-run=client -f my-crd.yaml
```
After installing a CRD, use `kubectl explain` to inspect fields and schema.
## Observability and metrics
Monitor controllers and CRDs:
* Controller metrics: reconciliation success/failure, durations, queue depth.
* Resource metrics: creation/deletion counts, resource sizes.
* Alerts: controller errors and excessive reconciliation delays.
* Correlate controller metrics with application and cluster-level observability (e.g. Prometheus).
## Real-world examples
Many CNCF projects use CRDs and operators in production:
* cert-manager — Certificate CRDs and lifecycle automation: [https://cert-manager.io/](https://cert-manager.io/)
* Zalando Postgres Operator — Postgres clusters: [https://github.com/zalando/postgres-operator](https://github.com/zalando/postgres-operator)
* Prometheus Operator — ServiceMonitor, PrometheusRule: [https://github.com/prometheus-operator/prometheus-operator](https://github.com/prometheus-operator/prometheus-operator)
* Istio — VirtualService, DestinationRule: [https://istio.io/](https://istio.io/)
## Key takeaways
* CRDs extend Kubernetes APIs to provide platform-specific, intent-based resources for self-service.
* Controllers/operators reconcile custom resources into real cluster objects (StatefulSets, Services, PVCs, Secrets).
* Use OpenAPI v3 schemas for server-side validation and documentation.
* Integrate CRDs with RBAC, versioning, conversion, and observability.
* Favor additive, backward-compatible changes and design APIs for a great developer experience.
## Additional reminders
* Use CRDs when you need a schema-backed, domain-specific API.
* Use Operators when you also need complex automation and orchestration logic.
* Keep developer-facing APIs simple and push complexity into platform controllers.
* Instrument controllers and CRDs for metrics, logs, events, and alerts.
References and further reading:
* Kubernetes CRD docs: [https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
* Kubebuilder book: [https://book.kubebuilder.io/](https://book.kubebuilder.io/)
* controller-tools / controller-gen: [https://github.com/kubernetes-sigs/controller-tools](https://github.com/kubernetes-sigs/controller-tools)
* Operator SDK: [https://sdk.operatorframework.io/](https://sdk.operatorframework.io/)
* Prometheus: [https://prometheus.io/](https://prometheus.io/)
* cert-manager: [https://cert-manager.io/](https://cert-manager.io/)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.