Kubernetes provides an extension mechanism that allows you to add custom API resources to your cluster without modifying the core Kubernetes codebase. Custom Resource Definitions (CRDs) form the foundation of this extensibility, enabling you to define your own resource types that behave like native Kubernetes objects.

In this guide, we'll explore CRDs, providing some practical examples that will help you to understand it better.

What Are Custom Resource Definitions?

Custom Resource Definitions serve as the schema that defines a new resource type in Kubernetes. When you create a CRD, you're essentially teaching the Kubernetes API server about a new kind of object that can be managed using standard kubectl commands and stored in etcd alongside native resources like Pods and Services.

A CRD consists of three main components:

The API Group and Version: Every CRD belongs to an API group (such as stable.devoriales.com) and has one or more versions (like v1, v2alpha1). This structure follows the same versioning pattern as built-in Kubernetes resources.

The Resource Names: Each CRD defines plural and singular forms of the resource name (crontabs and crontab), a Kind (CronTab), and optional short names (ct) for convenient kubectl usage.

The Schema: The OpenAPI v3 validation schema specifies what fields your custom resource can contain, their types, and validation rules. This schema ensures that instances of your custom resource meet your specifications.

The Purpose and Goals of CRDs

CRDs accomplish several objectives in Kubernetes:

API Extension Without Code Modification: CRDs allow you to extend the Kubernetes API declaratively. You define new resource types using YAML manifests rather than writing Go code and compiling custom API servers.

Native Kubernetes Integration: Resources created from CRDs integrate with the Kubernetes. You can use kubectl to create, read, update, and delete custom resources. Role-Based Access Control (RBAC) rules apply to custom resources just as they do to native resources.

Persistence and Lifecycle Management: Custom resources are stored in etcd, the same distributed key-value store that holds all Kubernetes cluster data. They participate in the standard Kubernetes object lifecycle, including garbage collection and owner references.

Validation and Defaulting: CRDs support OpenAPI v3 validation schemas that enforce constraints on field values. You can specify required fields, set minimum and maximum values, define regular expression patterns, and provide default values.

How Kubernetes Handles CRDs

When you create a CustomResourceDefinition object in Kubernetes, several processes occur:

API Endpoint Creation: The API server automatically creates RESTful API endpoints for your custom resource. For a namespaced CRD with group stable.devoriales.com and version v1, the endpoint becomes /apis/stable.devoriales.com/v1/namespaces/*/crontabs/....

Schema Registration: The API server registers your OpenAPI schema and begins validating incoming custom resource objects against it. Any attempt to create or update a custom resource that violates the schema is rejected with detailed error messages.

Storage in etcd: Custom resources are persisted in etcd using the same mechanisms as native resources. The API server handles serialization, versioning, and retrieval.

Field Pruning: By default, the API server removes (prunes) any fields in a custom resource that aren't defined in the schema. This prevents unexpected data from being stored and ensures schema compliance.

Do You Need an Operator?

The answer depends on what you want to accomplish with your custom resources.

CRDs Alone: A CRD by itself only extends the Kubernetes API with a new resource type. You can create, read, update, and delete instances of your custom resource using kubectl, but these objects don't do anything by themselves. They're simply stored in etcd.

Adding Behavior with Controllers: To make your custom resources functional, you need a controller (often called an operator when it manages complex applications). The controller watches for changes to your custom resources and takes actions to reconcile the desired state with the actual state.

For example, you might create a CRD for a CronTab resource that specifies a schedule and a container image. Without a controller, this is just data. With a controller, you can write code that:

• Watches for new CronTab objects
• Creates Kubernetes CronJobs based on the specifications
• Updates those CronJobs when the CronTab object changes
• Cleans up resources when a CronTab is deleted

You need to understand how to create and manage CRDs themselves which this article is about. You should be comfortable with CRD creation, validation, and basic troubleshooting.

❗In this article, we'll focus on CRDs themselves and cover how to write an operator in another article or video.

kubectl get customresourcedefinitions # or use short name crd

You can also describe an existing CRD like in the following example:

kubectl describe crd traefikservices.traefik.containo.us

Working Example: Creating a CronTab CRD

Let's build a complete example that demonstrates CRD creation and usage. This example appears frequently in Kubernetes documentation and provides a solid foundation for understanding CRDs.

The user story:

You, a platform engineer at DevOriales, manage dozens of scheduled backup and maintenance jobs across multiple namespaces. Your team uses native Kubernetes CronJobs, but creating them requires writing lengthy YAML manifests with numerous fields. Developers frequently make mistakes with the cron syntax or forget to set resource limits.

The Solution:

You need to create a CronTab CRD that simplifies scheduled job creation. Instead of dealing with complex CronJob specifications, developers only need to provide three essential fields:

The Benefits:

• Validation built-in: The CRD enforces valid cron patterns through regex validation
• Safe defaults: Replica count must be between 1-10, preventing resource issues
• Simplified interface: Developers only specify what matters: schedule, image, and scale
• Consistent naming: Using stable.devoriales.com makes it clear these are custom company resources

The Controller (to be built):

Your team will develop a controller that watches for CronTab resources and automatically creates properly configured Kubernetes CronJobs with:

• Resource limits (memory, CPU)
• Monitoring labels
• Alert configurations
• Backup retention policies

Now developers can create scheduled jobs in seconds instead of copying and modifying complex templates.

Step 1: Define the CustomResourceDefinition

Create a file named crontab-crd.yaml:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.devoriales.com
spec:
  group: stable.devoriales.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              cronSpec:
                type: string
                pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$'
              image:
                type: string
              replicas:
                type: integer
                minimum: 1
                maximum: 10
            required:
            - cronSpec
            - image
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
    - ct

Understanding the Schema:

The group field (stable.devoriales.com) defines the API group. In production, use a domain you control.

The versions array supports multiple API versions. Each version has a served flag (whether the API server exposes this version) and a storage flag (which version is stored in etcd).

The openAPIV3Schema defines the structure of your custom resource. In this example:

• cronSpec must be a string matching a cron pattern (validated with a regular expression)
• image is a string field for the container image
• replicas is an integer between 1 and 10

The scope can be either Namespaced or Cluster. Namespaced resources belong to a specific namespace, while cluster-scoped resources are global.

The names section defines how you'll refer to this resource. You can use kubectl get crontabs, kubectl get crontab, or kubectl get ct.

Step 2: Create the CRD

Apply the CustomResourceDefinition to your cluster:

kubectl apply -f crontab-crd.yaml

Verify the CRD was created:

kubectl get crd crontabs.stable.devoriales.com

You should see output indicating the CRD exists and when it was created.

Step 3: Create Custom Resource Instances

Now that the CRD exists, you can create instances of your custom resource.

Create a file named my-crontab.yaml:

apiVersion: stable.devoriales.com/v1
kind: CronTab
metadata:
  name: backup-crontab
spec:
  cronSpec: "0 2 * * *"
  image: backup-utility:v1.0
  replicas: 3

Apply this custom resource:

kubectl apply -f my-crontab.yaml

# List all crontabs
kubectl get crontabs

# Get detailed information
kubectl get crontab backup-crontab -o yaml

# Use the short name
kubectl get ct

# Describe the resource
kubectl describe crontab backup-crontab

# Delete the resource
kubectl delete crontab backup-crontab

apiVersion: stable.devoriales.com/v1
kind: CronTab
metadata:
  name: invalid-crontab
spec:
  cronSpec: "invalid cron pattern"
  image: test-image:latest
  replicas: 15

kubectl apply -f invalid-crontab.yaml

spec:
  versions:
  - name: v1
    served: true
    storage: true
    subresources:
      status: {}
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              replicas:
                type: integer
          status:
            type: object
            properties:
              availableReplicas:
                type: integer

subresources:
  scale:
    specReplicasPath: .spec.replicas
    statusReplicasPath: .status.replicas
    labelSelectorPath: .status.labelSelector

kubectl scale crontab backup-crontab --replicas=5

openAPIV3Schema:
  type: object
  properties:
    spec:
      type: object
      x-kubernetes-validations:
      - rule: "self.minReplicas <= self.replicas"
        message: "replicas must be greater than or equal to minReplicas"
      - rule: "self.replicas <= self.maxReplicas"
        message: "replicas must be less than or equal to maxReplicas"
      properties:
        minReplicas:
          type: integer
        replicas:
          type: integer
        maxReplicas:
          type: integer

spec:
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        # v1 schema
  - name: v1beta1
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        # v1beta1 schema

versions:
- name: v1
  served: true
  storage: true
  additionalPrinterColumns:
  - name: Schedule
    type: string
    description: The cron schedule
    jsonPath: .spec.cronSpec
  - name: Replicas
    type: integer
    description: The number of replicas
    jsonPath: .spec.replicas
  - name: Age
    type: date
    jsonPath: .metadata.creationTimestamp