Defining Custom Resource Definitions

Create and configure Kubernetes Custom Resource Definitions to represent the desired state of your managed application components.

In this lesson, you will learn how to extend the Kubernetes API by defining your own Custom Resource Definitions (CRDs) to model application-specific components.

Extending the Kubernetes API

While Kubernetes comes with standard resources like Pod and Service, real-world applications often require specialized abstractions. A CRD allows you to define a "custom type" that Kubernetes treats as a first-class citizen. By creating a CRD, you teach the cluster how to validate, store, and track the state of your unique business logic, such as a DatabaseCluster or a MessageQueue.

Defining Your First CRD

A CRD is simply a YAML manifest that tells the API server about your new resource. The critical components are the group, version, and kind.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    plural: databases
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                size:
                  type: integer
                  minimum: 1

In this example, we define a Database resource. By including the openAPIV3Schema block, we ensure that anyone creating a Database object must provide an integer for the size field. If a user attempts to apply a configuration that violates this structure, the API server will reject the request, ensuring that your custom objects are always valid before they reach your controller logic.

Why this matters

Defining a CRD is the foundation of the Operator pattern. Once you register this structure with the cluster, you have a formal "desired state" definition. Your automation tools can then watch for these resources and perform the heavy lifting—like provisioning cloud infrastructure or configuring backups—automatically. By strictly defining your schema, you reduce configuration drift and provide a consistent interface for your DevOps workflows.

Key Takeaway: Custom Resource Definitions act as the contract between your application’s requirements and the Kubernetes API, enabling you to manage complex components with the same native tooling used for standard pods and services.