CustomResourceDefinitions

CustomResourceDefinitions (CRDs) are a Kubernetes mechanism for extending the API with new resource types. Introduced as part of the API extensions system, CRDs allow cluster operators to define and manage custom resources alongside built-in Kubernetes objects, without changing the core API server code. A CRD itself is a resource in the apiextensions.k8s.io API group that specifies how a new resource type should behave and be validated.

A CRD describes the target resource’s identity and schema. Core fields include spec.group (API group), spec.names (kind, plural, singular, shortNames, listKind, categories), and spec.scope (Namespaced or Cluster). The resource versions are defined in spec.versions, with attributes such as name, served, storage, and schema (for validation, typically using OpenAPI v3). CRDs may also declare subresources (for status and scaling) and additionalPrinterColumns to customize kubectl output.

When a CRD is created and established, users can create custom resources of the defined kind, using the specified API group and version. These custom resources are stored in etcd like native objects and can be observed, listed, and reconciled by controllers that watch for changes to the custom resources. CRDs enable operators and developers to model domain-specific data and workflow entities within Kubernetes, and to implement controller logic that enforces desired state.

CRDs support scope customization (Namespaced or Cluster), versioning with compatible schemas, and optional conversion webhooks for handling migrations between versions. They are commonly installed via YAML manifests or package managers and are central to Kubernetes extension patterns and ecosystem tooling.