Custom Resource Definitions (CRDs)

Custom Resource Definitions (CRDs) allow you to extend the Kubernetes API with your own custom resource types. They enable you to define application-specific objects that can be managed using standard Kubernetes tools like kubectl, stored in etcd alongside built-in resources, and integrated with Kubernetes’ declarative management patterns.

What are Custom Resources?

A Custom Resource is an extension of the Kubernetes API that represents a customization of a particular Kubernetes installation. Custom Resources can appear and disappear in a running cluster through dynamic registration, and cluster admins can update Custom Resources independently of the cluster itself.

Why Use Custom Resources?

Custom Resources provide several key benefits:

Benefit	Description
API Consistency	Use the same API patterns and tools (`kubectl`, RBAC, etc.) for custom objects
Declarative Management	Leverage Kubernetes’ declarative approach for your custom resources
Integration	Seamlessly integrate with existing Kubernetes tooling and workflows
Versioning	Support multiple API versions with automatic conversion
Validation	Define schemas to validate custom resource specifications

Creating a Custom Resource Definition

A CRD defines the schema and behavior of a custom resource. Here’s a basic example of a Website CRD:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: websites.example.com
spec:
  group: example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              domain:
                type: string
                pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
              replicas:
                type: integer
                minimum: 1
                maximum: 100
              image:
                type: string
            required:
            - domain
            - image
          status:
            type: object
            properties:
              phase:
                type: string
                enum: ["Pending", "Running", "Failed"]
              message:
                type: string
  scope: Namespaced
  names:
    plural: websites
    singular: website
    kind: Website

Key Components of a CRD

Component	Description	Purpose
Group	API group for the custom resource	Organizes related resources (e.g., `example.com`)
Version	API version for the resource	Enables API evolution and compatibility
Kind	The type name of the custom resource	Used in YAML manifests (e.g., `Website`)
Scope	Whether the resource is namespaced or cluster-wide	Determines resource visibility and isolation
Schema	OpenAPI v3 schema for validation	Defines the structure and constraints of the resource

Working with Custom Resources

Once you’ve created a CRD, you can work with custom resources just like built-in Kubernetes resources.

Creating a Custom Resource Instance

apiVersion: example.com/v1
kind: Website
metadata:
  name: my-website
  namespace: default
spec:
  domain: myapp.example.com
  replicas: 3
  image: nginx:1.20

Managing Custom Resources with kubectl

# Create the CRD
kubectl apply -f website-crd.yaml

# Create a custom resource instance
kubectl apply -f my-website.yaml

# List all websites
kubectl get websites

# Describe a specific website
kubectl describe website my-website

# Delete a website
kubectl delete website my-website

Advanced CRD Features

Schema Validation

CRDs support comprehensive OpenAPI v3 schema validation. In the example below, we are inspecting the resources object to make sure that it contains cpu and memory fields as strings that match specific patterns:

cpu must be a string representing either an integer, an integer followed by “m” (for millicores), or a decimal number,
memory must be a string starting with an integer and optionally followed by valid memory units like “Ki”, “Mi”, or “Gi”.

schema:
  openAPIV3Schema:
    type: object
    properties:
      spec:
        type: object
        properties:
          resources:
            type: object
            properties:
              requests:
                type: object
                properties:
                  cpu:
                    type: string
                    pattern: '^(\d+m?|\d+\.\d+)$'
                  memory:
                    type: string
                    pattern: '^(\d+)(Ei|Pi|Ti|Gi|Mi|Ki|E|P|T|G|M|K)?$'
        required:
        - resources

Multiple Versions and Conversion

CRDs support multiple API versions with automatic conversion between versions:

spec:
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      # v1 schema
  - name: v1beta1
    served: true
    storage: false
    schema:
      # v1beta1 schema
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        service:
          name: example-conversion-webhook
          namespace: default

Subresources

CRDs can define subresources like /status and /scale:

spec:
  versions:
  - name: v1
    served: true
    storage: true
    subresources:
      status: {}
      scale:
        specReplicasPath: .spec.replicas
        statusReplicasPath: .status.replicas
        labelSelectorPath: .status.selector

Custom Resource Categories and Short Names

Make your custom resources easier to work with by defining categories and short names:

spec:
  names:
    plural: websites
    singular: website
    kind: Website
    shortNames:
    - ws
    categories:
    - all
    - mycompany

This allows users to run commands like:

kubectl get ws              # Using short name
kubectl get all             # Includes websites in "all" category
kubectl get mycompany       # Custom category

Best Practices for CRDs

Design Principles

When designing Custom Resource Definitions, follow these principles:

Principle	Implementation	Benefits
Single Responsibility	Each CRD should represent one concept	Easier to understand and maintain
Immutable Spec	Avoid changing spec fields after creation	Prevents configuration drift
Rich Status	Provide detailed status information	Enables better observability and debugging
Semantic Versioning	Use semantic versioning for API versions	Clear compatibility expectations
Comprehensive Validation	Define thorough schema validation	Prevents invalid configurations

Common Use Cases for CRDs

Custom Resource Definitions are particularly useful for:

Use Case	Example	Benefits
Application Configuration	Database schemas, API configurations	Declarative application management
Infrastructure as Code	Cloud resources, network policies	Kubernetes-native infrastructure management
Workflow Management	CI/CD pipelines, batch jobs	Integrated workflow orchestration
Policy Definition	Security policies, compliance rules	Centralized policy management
Integration Points	External service configurations	Unified configuration management