⌂ Home

Custom Resource Definitions

Interactive guide to extending the Kubernetes API with custom types, schema validation, and operator-driven reconciliation.

CRDs teach Kubernetes new resource types. They become truly useful when users create custom resources and optional controllers or operators act on those resources.

Core Model

Understand the Concept First

CRD defines a type

A CRD adds a new resource kind, names, version, and schema to the Kubernetes API.

CR is an instance

A Custom Resource is an actual object created from that new type.

Operator pattern

Controllers can watch custom resources and turn their desired state into action.

Lifecycle Flow

API Extension Flow

1. Define CRD YAML apiextensions.k8s.io/v1 Schema + Validation Names + Versions 2. Apply to Cluster kubectl apply -f API Server Registers New Resource Type 3. Create CR Instance kind: Website Stored in etcd Validated by Schema 4. Controller Pattern (Operator) WATCH RECONCILE Desired → Actual UPDATE Continuous Reconciliation Loop Legend API Extension Resource Instance Controller Logic
1

Create CRD

Define names, versions, scope, and schema validation.

2

Register with API server

The Kubernetes API now understands the new kind.

3

Create custom resources

Users apply CR instances just like built-in objects.

4

Validate object structure

OpenAPI schema checks whether the custom resource is valid.

5

Optional controller reconciles

An operator or controller watches CRs and implements behavior.

A CRD alone extends the API. A controller is what turns that custom type into an active platform feature.
YAML and Commands

Examples You Can Recognize Quickly

CRD Skeleton
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: websites.example.com
Useful Commands
kubectl get crds
kubectl api-resources
kubectl describe crd <name>
Decision Guide

CRD vs ConfigMap

Feature CRD ConfigMap
Purpose Define a new API resource type Store non-secret configuration data
Validation Schema-driven validation Limited built-in structure
Versioning Supports API versioning Single core object type
Typical use Operators and platform APIs Application configuration
Use a CRD when you want a new platform concept with API semantics, not just a bag of configuration values.
Use It Well

Practice and Real-World Thinking

Platform APIs

Define higher-level abstractions like Website, Application, or Database resources.

Operator learning

Understand the foundation behind tools such as Prometheus Operator or ArgoCD.

Schema enforcement

Use OpenAPI validation to make custom resources safer and more predictable.