2025 Updates Custom Resource Definition CRD

This guide explains CustomResourceDefinitions (CRDs) in Kubernetes — how they extend the Kubernetes API, how objects are persisted, and how controllers act on those objects. It preserves the sequence of concepts and diagrams so you can follow the flow from built-in resources to custom resources and controllers.

How built-in Kubernetes resources work

When you create a built-in resource such as a Deployment, Kubernetes persists the object in etcd and a controller reconciles the cluster to match the desired state recorded in that object. You can manage these objects with kubectl. Example: a simple Deployment YAML and typical kubectl commands

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      type: front-end
  template:
    metadata:
      name: myapp-pod
      labels:
        type: front-end
    spec:
      containers:
        - image: nginx

$ kubectl create -f deployment.yml
deployment "myapp-deployment" created

$ kubectl get deployments
NAME                DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
myapp-deployment    3         3         3            3           21s

$ kubectl delete -f deployment.yml
deployment "myapp-deployment" deleted

Controllers are control-plane processes that watch objects and reconcile actual cluster state to the desired state. For example, the Deployment controller creates a ReplicaSet for the Deployment, and the ReplicaSet creates Pods. Small excerpt of what a controller looks like in Go (for illustration only):

package deployment

var controllerKind = apps.SchemeGroupVersion.WithKind("Deployment")

// Run begins watching and syncing.
func (dc *DeploymentController) Run(workers int, stopCh <-chan struct{})

// Add ReplicaSet
func (dc *DeploymentController) addReplicaSet(obj interface{})

We have many built-in resource types (ReplicaSets, Deployments, Jobs, CronJobs, StatefulSets, Namespaces, etc.), and each normally has a controller responsible for ensuring the cluster matches the desired state.

A simple diagram showing Kubernetes resources (ReplicaSet, Deployment, Job, CronJob, StatefulSet, Namespace) on the left and corresponding controllers on the right with ETCD depicted between them. It illustrates the relationship between resources, controllers, and the ETCD datastore.

Extending the Kubernetes API: custom resource example

You can extend the Kubernetes API to include your own resource types using a CustomResourceDefinition (CRD). For example, suppose you want to model flight bookings inside Kubernetes with a custom resource called FlightTicket. Desired FlightTicket manifest:

apiVersion: flights.com/v1
kind: FlightTicket
metadata:
  name: my-flight-ticket
spec:
  from: Mumbai
  to: London
  number: 2

Once a CRD is registered, kubectl should be able to create, list, and delete FlightTicket objects:

$ kubectl create -f flightticket.yml
flightticket "my-flight-ticket" created

$ kubectl get flighttickets
NAME               AGE
my-flight-ticket   10s

$ kubectl delete -f flightticket.yml
flightticket "my-flight-ticket" deleted

Important: creating the FlightTicket object only persists it in etcd via the API server. To perform side effects (for example, call an external booking service like bookflight.com/API when a FlightTicket is created), you must run a controller that watches FlightTicket objects and takes action. Illustrative snippet of a custom controller in Go:

package flightticket

var controllerKind = flights.SchemeGroupVersion.WithKind("FlightTicket")

// Run begins watching and syncing.
func (ftc *FlightTicketController) Run(workers int, stopCh <-chan struct{})

// When a FlightTicket is created, call the external booking API.
func (ftc *FlightTicketController) callBookFlightAPI(obj interface{})

If the cluster does not know about the FlightTicket resource type, kubectl will fail with the following error:

$ kubectl create -f flightticket.yml
error: unable to recognize "flightticket.yml": no matches for kind "FlightTicket" in version "flights.com/v1"

This error occurs because the API server has not been told about the new resource type. You register a new resource type with the API server using a CustomResourceDefinition.

What is a CustomResourceDefinition (CRD)?

A CRD is itself an API object (apiVersion: apiextensions.k8s.io/v1, kind: CustomResourceDefinition) that instructs the API server to accept a new resource type. The CRD defines:

API group and versions (for example, flights.com/v1)
resource names (kind, singular, plural, shortNames)
scope (Namespaced or Cluster)
OpenAPI v3 validation schema (openAPIV3Schema) for server-side validation
which version is served and which is storage

Example CRD (key parts):

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: flighttickets.flights.com
spec:
  group: flights.com
  scope: Namespaced
  names:
    kind: FlightTicket
    singular: flightticket
    plural: flighttickets
    shortNames:
      - ft
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                from:
                  type: string
                to:
                  type: string
                number:
                  type: integer
                  minimum: 1
                  maximum: 10

The openAPIV3Schema field lets the API server validate incoming objects. In this example, from and to are strings and number must be an integer between 1 and 10. If a user submits invalid data, the API server will reject the object according to this schema. Create the CRD and then the custom resource:

$ kubectl create -f flightticket-crd.yml
customresourcedefinition.apiextensions.k8s.io/flighttickets.flights.com created

$ kubectl create -f flightticket.yml
flightticket "my-flight-ticket" created

$ kubectl get flighttickets
NAME               AGE
my-flight-ticket   24m

$ kubectl delete -f flightticket.yml
flightticket "my-flight-ticket" deleted

Creating a CRD registers a new resource type with the Kubernetes API and enables persisted objects of that type. A CRD provides validation and API wiring but does not implement business logic — to make the resource trigger actions (for example, call an external booking API), you must deploy a controller that watches those custom objects and reconciles desired state to actual state.

Quick reference: CRD spec fields

Field	Purpose	Example
`group`	API group for the custom resource	`flights.com`
`names`	Names exposed by the API (`kind`, `plural`, `singular`, `shortNames`)	`kind: FlightTicket`, `plural: flighttickets`
`scope`	Whether resource is `Namespaced` or `Cluster` scoped	`Namespaced`
`versions`	API versions with `served` and `storage` flags	`- name: v1`, `served: true`, `storage: true`
`schema`	Server-side validation via OpenAPI v3	`openAPIV3Schema` with `spec` properties

Summary

CRDs extend the Kubernetes API by registering new resource types (for example, FlightTicket).
After a CRD is created, you can create, list, and delete custom resources using kubectl.
CRDs support OpenAPI v3 schemas for server-side validation of resource fields.
To make custom resources trigger real-world actions, implement and run a controller that watches the custom resources and reconciles them (e.g., call external APIs).

Links and references

Kubernetes Custom Resources and CRDs: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
etcd: https://etcd.io/
kubectl reference: https://kubernetes.io/docs/reference/kubectl/overview/
OpenAPI Specification (v3): https://spec.openapis.org/oas/latest

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

2025 Updates Custom Resource Definition CRD

How built-in Kubernetes resources work

Extending the Kubernetes API: custom resource example

What is a CustomResourceDefinition (CRD)?

Quick reference: CRD spec fields

Summary

Links and references

Watch Video

Practice Lab

​How built-in Kubernetes resources work

​Extending the Kubernetes API: custom resource example

​What is a CustomResourceDefinition (CRD)?

​Quick reference: CRD spec fields

​Summary

​Links and references

Watch Video

Practice Lab

How built-in Kubernetes resources work

Extending the Kubernetes API: custom resource example

What is a CustomResourceDefinition (CRD)?

Quick reference: CRD spec fields

Summary

Links and references