Custom Resource Definitions (CRDs) in Kubernetes - Commands & Configuration

Introduction

Sometimes you need Kubernetes to understand new types of objects beyond the built-in ones. Custom Resource Definitions (CRDs) let you teach Kubernetes about your own resource types so you can manage them like native objects.

When you want to store and manage application-specific settings inside Kubernetes.

When you need to extend Kubernetes with new resource types for your custom controllers or operators.

When you want to create reusable APIs for your team that behave like built-in Kubernetes resources.

When you want to track the state of external systems inside Kubernetes using custom objects.

When you want to automate workflows by defining new resource types that trigger actions.

Config File - my-crd.yaml

my-crd.yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: widgets.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                size:
                  type: string
                color:
                  type: string
  scope: Namespaced
  names:
    plural: widgets
    singular: widget
    kind: Widget
    shortNames:
      - wdgt

This file defines a new resource type called Widget under the group example.com.

apiVersion and kind specify this is a CRD.

metadata.name is the full name of the CRD.

spec.group is the API group for the new resource.

spec.versions lists versions; here only v1 is served and stored.

spec.versions.schema defines the shape of the resource, here with spec.size and spec.color as strings.

spec.scope means the resource is namespaced.

spec.names defines how the resource is called in plural, singular, kind, and short names.

Commands

This command creates the Custom Resource Definition in the Kubernetes cluster, so Kubernetes learns about the new resource type Widget.

Terminal

kubectl apply -f my-crd.yaml

Expected Output

customresourcedefinition.apiextensions.k8s.io/widgets.example.com created

This command checks that the CRD was created and shows its details.

Terminal

kubectl get crd widgets.example.com

Expected Output

NAME                    CREATED AT

widgets.example.com      2024-06-01T12:00:00Z

This command lists all Custom Resource Definitions installed in the cluster, including the new Widget CRD.

Terminal

kubectl get crds

Expected Output

NAME                    CREATED AT

widgets.example.com      2024-06-01T12:00:00Z

othercrd.example.com     2024-05-20T09:30:00Z

This command shows the schema and documentation of the new Widget resource, helping you understand its fields.

Terminal

kubectl explain widget

Expected Output

KIND:     Widget

VERSION:  example.com/v1



DESCRIPTION:

     Widget is a custom resource for managing widgets.



FIELDS:

   apiVersion   <string>

   kind         <string>

   metadata     <Object>

   spec         <Object>

       size     <string>

       color    <string>

Key Concept

If you remember nothing else from this pattern, remember: CRDs let you add your own resource types to Kubernetes so you can manage custom objects like built-in ones.

Common Mistakes

Not applying the CRD file before creating custom resources of that type.

Kubernetes won't recognize the custom resource type and will reject the resource creation.

Always apply the CRD first with kubectl apply -f before creating any custom resources.

Using incorrect apiVersion or kind in the CRD file.

The CRD will fail to create or behave unexpectedly because Kubernetes expects specific apiVersion and kind values.

Use apiVersion apiextensions.k8s.io/v1 and kind CustomResourceDefinition exactly as shown.

Not defining the schema under spec.versions.schema.openAPIV3Schema.

Without a schema, Kubernetes cannot validate your custom resource objects, leading to potential errors or acceptance of invalid data.

Always define a proper OpenAPI v3 schema for your CRD version.

Summary

Create a CRD YAML file that defines your new resource type with group, versions, schema, and names.

Apply the CRD to the cluster using kubectl apply -f to register the new resource type.

Verify the CRD is installed with kubectl get crd and explore its schema with kubectl explain.