Skip to main content
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.
A presentation slide titled "CRDs — Extending Kubernetes With Custom APIs" showing four colored boxes: Schema Definition, API Extension, kubectl Integration, and Validation. Each box has a short caption about defining new resource types, creating custom endpoints, using standard Kubernetes tools, and built-in schema/OpenAPI validation.
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:
Notes on this CRD:
  • metadata.name must be <plural>.<group>, 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:
The controller/operator that owns PonyDatabase reads this spec and provisions the underlying resources (StatefulSets, Services, PVCs, backups, Secrets) — developers only declare intent.
A presentation slide titled "From Complex Infrastructure to Simple APIs" showing a four-level colored pyramid with labeled steps: Abstraction (1), Standardization (2), Empowerment (3), and Governance (4). The slide includes a small "© Copyright KodeKloud" note at the bottom left.

​
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.
A presentation slide titled "Built-In Validation and Documentation" showing five numbered, colored circles with corresponding boxes labeled as benefits. The listed benefits are Automatic validation, API documentation, kubectl describe, Error prevention, and Consistent resources.

​
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.
A slide titled "Team Collaboration on CRD Design" showing three team members — Swati (SRE), Alan (Infrastructure), and Phuong (Developer) — each with colored circular avatars. Swati handles monitoring/backup/reliability, Alan designs infrastructure templates, and Phuong provides feedback on developer experience.

​
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:
This enforces least privilege: teams can request databases but cannot directly change underlying Pods or cluster-level resources.
A presentation slide titled "Securing CRD Access With RBAC" outlining a "Security Strategy." It lists four key points: granular permissions, separation of concerns, least privilege principle, and team-based access control.
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.
Slide titled "Managing CRD Schema Changes" showing four pillars: Multiple Versions, Conversion, Migration, and Backward Compatibility, each with an icon and brief description. The slide is branded © KodeKloud.

​
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.
Slide titled "2025 CRD Capabilities" with two feature panels: "Subresources" listing status and scale subresources, separate status updates, horizontal scaling, and specialized endpoints, and "Custom Printers" mentioning kubectl output customization and formatted table output. The slide is branded © Copyright KodeKloud.
A presentation slide titled "2025 CRD Capabilities" showing two feature boxes labeled "Additional Printer Columns" and "Metrics." The left box lists enhanced kubectl output items (status summaries, resource metrics, custom data fields) and the right box lists Prometheus metrics integration items (controller performance, resource statistics, operational insights).

​
Choosing the right extension

Decide between simple config, schema-only extension, or schema+automation:
A slide titled "Choosing the Right Kubernetes Extension" showing a table that compares three extension types—ConfigMaps, CRDs, and Operators—by use case, complexity, and validation. It lists ConfigMaps as low-complexity for simple config, CRDs as medium with schema-based validation, and Operators as high-complexity with schema + 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.
A slide titled "CRD Design Best Practices" showing five pillars—User-Centric, Immutable Specs, Rich Status, Observability, and Security—each with a short guideline. Each pillar is illustrated with a colored circular icon and recommendations like "Design for developer experience" and "Validate all inputs, enforce policies."

​
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.
A slide titled "Platform Engineering CRD Patterns" showing four colored boxes labeled DatabaseClaim, Environment, Application, and Certificate. Each box has a short description of its purpose (request managed databases, provision complete environments, deploy applications, request TLS certificates).

​
Tools and local validation

Tools to accelerate CRD and controller development: Validate locally before applying:
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).
A slide titled "CRD Metrics and Monitoring" showing an "Observability Strategy" with four boxes: Controller Metrics, Resource Metrics, Performance, and Alerting. Each box lists examples like reconciliation success/failure rates, custom resource creation/deletion counts, reconciliation duration and queue depth, and alerts on controller failures or delays.

​
Real-world examples

Many CNCF projects use CRDs and operators in production:
A slide titled "CRDs in the CNCF Ecosystem" showing four colored cards for cert-manager, Zalando PostgreSQL Operator, Istio, and Prometheus Operator. Each card lists example CRDs (Certificate, PostgreSQL, VirtualService/DestinationRule, ServiceMonitor/PrometheusRule) with a short description of their purpose.

​
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.
A presentation slide titled "Key Takeaways – Custom Resources" showing three colored boxes labeled 01 API Extension, 02 Self-Service, and 03 Controllers with brief descriptions of each (CRDs extend Kubernetes; developers use simple APIs; controllers watch and reconcile resources). The slide has a clean white background and a small copyright notice for KodeKloud.

​
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.
A presentation slide titled "Key Takeaways – Custom Resources" showing four colored panels numbered 05–08 that list: RBAC Integration, Versioning, Best Practices, and Ecosystem with brief explanatory notes.
References and further reading:

Watch Video