Custom Resource Definitions (CRDs): Extending the Soul of Kubernetes

Kubernetes is often called a "Platform for building Platforms." Why? Because it doesn't just limit you to the built-in objects like Pods, Services, and Deployments. If those objects don't fit your needs, you can simply Create Your Own.

Imagine you are building an AI company. You want your developers to be able to say: "Give me an AI Model named llama-3-research with 1 GPU and a temperature of 0.7." Currently, there is no kind: AIModel in Kubernetes. But with Custom Resource Definitions (CRDs), you can add it. Once defined, your new AIModel becomes a first-class citizen—you can use kubectl get aimodels, you can use RBAC to secure them, and you can manage them in GitOps like everything else.

In this lesson, we will master the CRD Architecture, learn the OpenAPI v3 Schema syntax for validation, and understand how to transform Kubernetes into a domain-specific operating system for your specific business needs.

1. What is a CRD? (The "Schema" for K8s)

A CRD is a "Contract" that points the Kubernetes API Server to a new type of resource. It tells the API:

Group: The domain (e.g., ai.shshell.com).
Version: The release (e.g., v1alpha1).
Kind: The name (e.g., AIModel).
Schema: What fields are allowed inside the object (e.g., gpuCount must be an integer).

2. Anatomy of a CRD Manifest

Let's define our proprietary AIModel resource.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: aimodels.ai.shshell.com # Format: <plural>.<group>
spec:
  group: ai.shshell.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                modelName:
                  type: string
                temperature:
                  type: number
                  minimum: 0
                  maximum: 1
                gpuCount:
                  type: integer
  scope: Namespaced
  names:
    plural: aimodels
    singular: aimodel
    kind: AIModel
    shortNames:
    - ai

3. Using Your New Resource

Once you apply the CRD, you can create a "Custom Resource" (the actual instance).

apiVersion: ai.shshell.com/v1
kind: AIModel
metadata:
  name: research-agent
spec:
  modelName: "claude-3-opus"
  temperature: 0.5
  gpuCount: 1

Run kubectl get ai. It works! You have successfully extended the Kubernetes API.

4. Visualizing the CRD Extension

graph TD
    User["Developer (kubectl)"] -- "Create AIModel" --> API["API Server"]
    
    subgraph "Control Plane"
        API -- "Is this a core object?" --> Core{Core?}
        Core -- "No" --> CRD_Store["Check CRD Registry"]
        CRD_Store -- "Found ai.shshell.com" --> ETCD["Store in etcd"]
    end
    
    ETCD -- "Status Update" --> API
    API -- "Success" --> User

5. Scope: Namespaced vs. Cluster

Namespaced: The most common. Your resource lives inside a namespace (like a Pod).
Cluster: The resource is global (like a Node or a Namespace). Use this for infrastructure-wide settings like a GlobalConfig or BackupPolicy.

6. The "Empty Soul" Problem

A CRD by itself is just Data in a Database. If you create an AIModel resource, nothing actually happens. No pods are created, no GPUs are allocated. Kubernetes just says "Okay, I've stored your request in etcd."

To make the resource "Do" something, you need a Controller or an Operator. The Operator is a piece of code that watches the API for new AIModel objects and then runs the actual commands to spin up the pods and download the weights.

7. AI Implementation: Templating Model Versions

One of the biggest benefits of CRDs in AI is Versioning.

The Enterprise AI Setup:

Instead of hundreds of messy ConfigMaps, you create an AIModel CRD.

You can have v1-stable, v2-testing, and v3-emergency-fix all clearly visible in kubectl get ai.
You can add custom "Status" fields to your CRD, like status.accuracyScore or status.driftDetected.
This allows your Monitoring dashboard (Module 9.2) to query the Kubernetes API directly to see the "Health" of your AI models, separate from the health of the pods.

8. Summary and Key Takeaways

CRD: Extending the Kubernetes API with custom types.
OpenAPI v3: used for validating the input to ensure data quality.
Group/Version/Kind: The unique triplet that identifies your resource.
Namespaced: Keeps your resources isolated.
First-Class Citizen: CRDs gain all the benefits of K8s (RBAC, Audit Logs, CLI).
The Next Step: CRDs define the "What"; Operators define the "How."

In the next lesson, we will look at the intelligence behind these resources: The Operator Pattern.

9. SEO Metadata & Keywords

Focus Keywords: Kubernetes Custom Resource Definition tutorial, creating K8s CRD example, extend Kubernetes API with custom objects, OpenAPI v3 schema K8s validation, CRD vs ConfigMap, building an internal AI platform with CRDs.

Meta Description: Take full control of your infrastructure. Learn how to use Custom Resource Definitions (CRDs) to extend the Kubernetes API, allowing you to manage proprietary resources like AI models and database clusters as native, first-class K8s objects.