Extending Kubernetes with CRDs and Operators

A CustomResourceDefinition (CRD) registers a brand-new kind of object with the Kubernetes API, under apiextensions.k8s.io/v1 — the older v1beta1 version stopped being served as of Kubernetes v1.22, with v1 available since v1.16. Once a CRD is registered, instances of that kind — custom resources — can be created, read, updated and deleted with kubectl exactly like any built-in object, validated against the schema the CRD declares, and stored in etcd the same way.

On its own, that's all a CRD does: define a schema and a place to store structured data. Nothing watches it, and nothing acts on it — creating a custom resource with no controller behind its CRD just stores data, with no operational effect whatsoever.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: backupschedules.example.com
spec:
  group: example.com
  scope: Namespaced
  names:
    plural: backupschedules
    singular: backupschedule
    kind: BackupSchedule
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                schedule:
                  type: string

An Operator is a custom controller that watches instances of a CRD and reconciles real state to match what they declare — a database operator, for example, watching BackupSchedule objects and actually creating the Jobs, volumes or external API calls needed to make backups happen on that schedule. The CRD defines what — the shape of the data. The operator's controller defines what to do about it. A CRD without a controller is inert data; the operator is what turns a custom resource into something that actually does something in the cluster.