Custom Resource Definitions

Analogy categoryAnalogies

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.

yaml

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: integer

Once 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.