Understanding Kubernetes Custom Resource Definitions (CRDs) and Their Controllers

In Kubernetes, the API programming paradigm is embodied by Custom Resource Definitions (CRDs), which allow users to define their own resources that behave like native objects such as Pods and Deployments.

Why Custom Resources Exist

As Kubernetes adoption grows, the need for user-defined resources increases because built‑in aggregation of sub‑resources cannot meet all use cases. CRDs let users create native, first‑class resources stored in etcd, manageable via kubectl and RBAC, and enable custom controllers to react to changes.

Basic CRD Example

A CRD introduced in Kubernetes 1.7 lets users add custom objects. These objects share the same API server handling as native resources. The example defines a CRD with fields such as apiVersion, kind, metadata.name, and spec specifying group and version. Important fields include:

group: samplecontroller.k8s.io version: v1alpha1 names.kind: Foo plural: a short nickname for the resource

scope: Namespaced or Cluster The corresponding custom object instance shows how apiVersion, kind, metadata.name, and a free‑form spec are populated.

CRD with Validation

Adding an openAPIV3Schema enables field validation. For example, the replicas field can be constrained to integers between 1 and 10. Invalid values cause the API server to reject the object with an error.

CRD with Status Sub‑resource

Since Kubernetes 1.12, CRDs can include a status sub‑resource, allowing controllers to update status without triggering a new reconciliation loop. This is useful for reporting deployment health, replica counts, and version information.

Hands‑On Demonstration

Two YAML files are used: crd.yaml defining the schema and example-foo.yaml creating an instance. Commands: kubectl create -f crd.yaml – registers the CRD. kubectl get crd – verifies creation. kubectl create -f example-foo.yaml – creates a custom Foo object. kubectl get foo example-foo -o yaml – inspects the stored object.

The custom object behaves like native resources, with similar kubectl interactions.

Controller Overview

A CRD alone does nothing; a controller implements the desired behavior. Controllers watch the API server via Informers, which use ListFunc (e.g., kubectl get pods) and WatchFunc to receive events. Events are placed in a FIFO queue keyed by namespace/name, processed by workers that invoke Add/Update/Delete handlers.

If processing succeeds, the key is removed; on error, the event is re‑queued and an event is logged.

Summary

CRDs let users extend Kubernetes with native‑like resources.

CRDs support RBAC, validation, and status sub‑resources.

Controllers interpret CRDs and reconcile desired state, using Informer‑driven event loops.