Custom Resource Definitions (CRDs): Teach Kubernetes New Tricks

Why it exists

Kubernetes ships with core resources like Pods and Deployments, but real-world systems need to manage more, like databases, message queues, or backup jobs. CRDs were created to extend the Kubernetes API to manage these application-specific components as native objects.

The mental model

A CRD is like adding a new noun to the Kubernetes vocabulary. You're teaching the API server a new concept, like a PostgresCluster or a ScheduledBackup. Once defined, you can interact with these new objects using standard tools like kubectl get mycustomresource.

How it works

You apply a YAML file that defines the CRD itself. This file specifies the new resource's name (e.g., crontabs.stable.example.com), its scope (namespaced or cluster-wide), and a schema for its spec and status fields. Once the CRD is registered, the Kubernetes API server automatically creates a new RESTful endpoint for your resource type. You can then create, read, update, and delete instances of this new object.

When to use it

Use CRDs when you want to manage a resource declaratively using Kubernetes-native tools. This is the foundation of the Operator Pattern, where a custom controller automates the lifecycle of a complex application defined by one or more CRDs. For example, the Prometheus Operator uses a ServiceMonitor CRD to automatically configure scraping targets.

When not to use it

If you only need to store configuration data, a ConfigMap or Secret is much simpler. If your desired API doesn't follow the declarative, CRUD-style model of Kubernetes resources, a CRD might be a poor fit. For very complex extensions that need custom validation or subresources, a more advanced (and much harder) pattern called an Aggregated API Server might be necessary.

One canonical example

A classic example is creating a CronTab resource. The CRD defines what a CronTab object looks like: it has a spec with a schedule (e.g., "/1 *") and a job template. A separate, custom controller watches for CronTab objects. When a new one is created, the controller creates Kubernetes Job resources on the specified schedule. The CRD itself does nothing but define the schema; the controller provides the behavior.