Custom Resource Definitions
A CustomResourceDefinition (CRD) lets you register an entirely new resource type—say, Database or CronTab—as a first-class citizen of the Kubernetes API, storable in etcd, listable and watchable through kubectl, and governable by RBAC exactly like a built-in Pod or Deployment. Once a CRD is applied, the API server dynamically creates a new RESTful endpoint for it without any code changes to Kubernetes itself, which is what makes CRDs the foundation of the entire operator and platform-engineering ecosystem.
Cricket analogy: The ICC formally recognizing a new format like The Hundred and giving it official status—rules, rankings, a governing body—mirrors how a CRD registers a brand-new resource type as a first-class citizen of the Kubernetes API.
Defining a CRD: Schema and Validation
Every CRD must declare an OpenAPI v3 schema under its versions that specifies required fields, types, defaults, and validation rules such as minimum/maximum values or regex patterns, and the API server rejects any custom resource that doesn't conform at admission time, exactly as it validates built-in types. Structural schemas—where every field is typed and pruning removes unknown fields—are mandatory in modern Kubernetes, which prevents typos or stale fields from silently persisting in etcd and keeps custom resources as strict as native ones.
Cricket analogy: Match officials reject a scorecard submission that's missing the required overs-bowled field or has an impossible run total, just as the API server rejects a custom resource that violates its CRD's required fields or validation rules.
Versioning and Conversion
A CRD can serve multiple versions simultaneously, such as v1alpha1, v1beta1, and v1, with exactly one marked as the storage version that determines how objects are actually persisted in etcd, while the others are served through automatic or webhook-based conversion. Trivial version bumps that only add fields can rely on Kubernetes' automatic conversion, but any change that restructures the schema requires a conversion webhook that the API server calls to translate objects between versions on read and write, which is the same mechanism built-in types like Ingress used when migrating between API groups.
Cricket analogy: The DRS system has evolved through several rule revisions over the years, but historical decisions are still stored and interpretable under whichever version was in force, mirroring a CRD's storage version with conversion between served versions.
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: databases.db.example.com
spec:
group: db.example.com
scope: Namespaced
names:
plural: databases
singular: database
kind: Database
shortNames: ["db"]
versions:
- name: v1
served: true
storage: true
subresources:
status: {}
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required: ["engine", "storageSize"]
properties:
engine:
type: string
enum: ["postgres", "mysql"]
version:
type: string
storageSize:
type: string
pattern: '^[0-9]+Gi$'
replicas:
type: integer
minimum: 1
maximum: 7
status:
type: object
properties:
phase:
type: string
readyReplicas:
type: integerOnce a CRD is registered, kubectl explain database.spec and kubectl explain database.spec.replicas work exactly like they do for built-in resources, because kubectl reads the same OpenAPI v3 schema the API server generated from the CRD's validation block.
Subresources, Scope, and Working with Custom Resources
Subresources like /status and /scale can be enabled on a CRD so that, for example, a controller can update status without needing write permission to the spec, mirroring how Deployments separate spec updates from status updates and enabling RBAC to grant narrower permissions. A CRD's scope is either Namespaced or Cluster, chosen once at creation and not changeable afterward, and while a CRD alone only gives you storage and API surface, it does nothing on its own—the resource only becomes useful once a controller (commonly built with a framework like Kubebuilder or Operator SDK) watches it and reconciles real infrastructure or application state to match.
Cricket analogy: A scorer updates the live score independently from the match officials setting the format and rules before the toss, mirroring how the /status subresource lets controllers update state without touching spec.
A CRD's scope field (Namespaced vs Cluster) cannot be changed after creation — migrating requires creating a brand-new CRD under a different name or group and writing a one-time migration script to recreate existing custom resources under it.
- A CRD registers a new resource type as a first-class citizen of the Kubernetes API without modifying Kubernetes code.
- Every CRD must declare an OpenAPI v3 schema; structural schemas are mandatory and enable field pruning.
- A CRD can serve multiple versions with exactly one designated as the storage version.
- Non-trivial schema changes across versions require a conversion webhook.
- Subresources like /status and /scale allow finer-grained RBAC control.
- A CRD's scope (Namespaced or Cluster) is fixed at creation and cannot be changed later.
- A CRD alone provides only storage and API surface; a controller is needed to make it do anything.
Practice what you learned
1. What does applying a CRD to a cluster do?
2. What is required for every CRD in modern Kubernetes?
3. When is a conversion webhook required for a multi-version CRD?
4. What does the /status subresource enable?
5. Can a CRD's scope be changed from Namespaced to Cluster after creation?
Was this page helpful?
You May Also Like
Kubernetes Operators Explained
What a Kubernetes Operator is, how it combines a CustomResourceDefinition with a controller to automate operational knowledge, and patterns for building one reliably.
The Kubernetes API Server
How kube-apiserver authenticates, authorizes, validates, and persists every cluster change, and why it sits at the center of every Kubernetes operation.
The Kubernetes Control Plane In Depth
A deep dive into the components that make up the Kubernetes control plane—kube-apiserver, etcd, scheduler, and controller manager—and how they work together to reconcile cluster state.