Skip to content

Kubernetes CRD

A CRD (Custom Resource Definition) is a powerful feature in Kubernetes that allows you to extend the Kubernetes API by defining your own custom resource types.

Think of it this way: Kubernetes comes with a set of built-in resource types like Pods, Deployments, Services, ConfigMaps, etc. These are the nouns of the Kubernetes API. CRDs let you add your own nouns to this vocabulary, tailored to your specific application or domain.

Here’s a breakdown:

  1. What is a Custom Resource Definition (CRD)?

    • A CRD is itself a Kubernetes resource (you create it using a YAML manifest, just like a Pod).
    • When you create a CRD, you are telling the Kubernetes API server about a new kind of object you want to manage.
    • The CRD specifies the name of your new resource (e.g., MyDatabase, BackupJob, MlModel), its API group, version, and scope (namespaced or cluster-wide).
    • Crucially, the CRD also defines the schema for your custom resource, using OpenAPI v3 schema. This schema dictates what fields your custom resource can have (e.g., spec.username, spec.version, status.currentState) and their data types, validation rules, etc.

  2. What is a Custom Resource (CR)?

    • Once a CRD is defined and registered with the API server, you can then create Custom Resources (CRs) of that new kind.
    • A CR is an instance of your custom resource type.
    • You manage CRs using kubectl just like any built-in resource (kubectl get mydatabases, kubectl apply -f mydatabase-instance.yaml).
    • The CRs will have spec (desired state) and status (actual state) fields, as defined in your CRD’s schema.

  3. Why use CRDs?

    • Extensibility: To model and manage application-specific or domain-specific concepts directly within Kubernetes.
    • Declarative APIs: You can manage your custom components using the same declarative kubectl apply -f ... workflow as standard Kubernetes resources.
    • Automation (Operators): CRDs are the foundation of the Operator Pattern. An Operator is a custom controller that watches for CRs of a particular kind and then takes action to reconcile the current state of the system with the desired state declared in the CR’s spec. For example, an EtcdCluster CRD might be managed by an Etcd Operator that automatically provisions, manages, backs up, and scales Etcd clusters.
    • Abstraction: Hide complex implementation details behind a simple, high-level custom API.

  4. CRD vs. Controller:

    • CRD: Defines the API and data structure for your custom object. It tells Kubernetes “this new kind of object exists, and this is what it looks like.”
    • Controller (Operator): Contains the logic that acts upon those custom objects. It watches for changes to CRs and performs actions to achieve the desired state.
    • Creating a CRD makes Kubernetes aware of your new resource type, but without a controller, creating instances (CRs) of that type won’t do anything beyond storing their definition in etcd (Kubernetes’s database). The controller brings them to life.

Example:

Let’s say you want to manage a custom type of application deployment called WebApp.

  1. Define the CRD (WebApp CRD):

    yaml apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: webapps.mycompany.com # Name of the CRD spec: group: mycompany.com # API group versions: - name: v1alpha1 served: true storage: true schema: openAPIV3Schema: type: object properties: spec: type: object properties: image: type: string replicas: type: integer minimum: 1 port: type: integer status: # Status fields are typically updated by the controller type: object properties: availableReplicas: type: integer url: type: string scope: Namespaced # Can be Namespaced or Cluster names: plural: webapps singular: webapp kind: WebApp # Kind used in manifests shortNames: - wa

  2. Create an instance (a WebApp CR):

    yaml apiVersion: mycompany.com/v1alpha1 # Matches group and version from CRD kind: WebApp # Matches kind from CRD metadata: name: my-sample-app namespace: default spec: image: "nginx:latest" replicas: 3 port: 80

  3. Write a Controller (Operator) for WebApp:

    • This controller would watch for WebApp resources.
    • When a WebApp CR is created or updated, the controller might:
      • Create a Kubernetes Deployment with the specified image and replicas.
      • Create a Kubernetes Service exposing the specified port.
      • Optionally, create an Ingress if needed.
      • Update the status field of the WebApp CR (e.g., with the availableReplicas or a publicly accessible url).

In summary, CRDs allow you to teach Kubernetes new tricks by defining custom object types, making Kubernetes more adaptable to a wider range of applications and operational needs, especially when combined with custom controllers (Operators).

Page last modified: 2025-05-21 11:17:19