Defining Custom Resource Definitions

Custom Resource Definitions (CRDs) let you extend the Kubernetes API with your own resource types. Once a CRD is registered, you can create, read, update, and delete custom resources using kubectl just like built-in resources.

CRD YAML Structure

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.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
      additionalPrinterColumns:
        - name: Schedule
          type: string
          jsonPath: .spec.cronSpec
        - name: Replicas
          type: integer
          jsonPath: .spec.replicas
        - name: Age
          type: date
          jsonPath: .metadata.creationTimestamp
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
      - ct

Key Sections Explained

• group and versions -- define the API group and supported versions
• schema -- validates custom resource fields using OpenAPI v3 schema; Kubernetes rejects resources that do not match
• additionalPrinterColumns -- controls what columns appear when you run kubectl get
• names -- defines the plural, singular, kind, and optional short names

Creating and Verifying a CRD

# Apply the CRD
kubectl apply -f crontab-crd.yaml

# Verify it was registered
kubectl get crd crontabs.stable.example.com

# You can now use the new resource type
kubectl get crontabs
kubectl get ct

Key Takeaways

• CRDs extend the Kubernetes API without modifying the API server
• Schema validation enforces the structure of custom resources
• additionalPrinterColumns makes kubectl get output useful for custom types