Custom resources concept in Kubernetes - Commands & Configuration

Introduction

Sometimes Kubernetes does not have the exact resource type you need. Custom resources let you add your own resource types to extend Kubernetes with new features.

When you want to manage a new kind of application or service that Kubernetes does not support by default

When you need to store configuration or state specific to your application inside Kubernetes

When you want to build operators that automate tasks for your custom resource

When you want to create reusable APIs inside your Kubernetes cluster

When you want to integrate external systems with Kubernetes using custom resource definitions

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 custom resource type called Widget in the example.com group.

apiVersion and kind specify this is a CustomResourceDefinition.

metadata.name is the full name of the resource type.

spec.group is the API group for the resource.

spec.versions lists the versions of this resource, with schema validation.

spec.scope means the resource is namespaced.

spec.names defines how to refer to this resource in commands and manifests.

Commands

This command creates the CustomResourceDefinition in the cluster, registering the new resource type.

Terminal

kubectl apply -f my-crd.yaml

Expected Output

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

This command verifies that the custom resource definition was created and is available.

Terminal

kubectl get crd widgets.example.com

Expected Output

NAME                    CREATED AT

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

This command creates an instance of the custom resource Widget named my-widget with specified size and color.

Terminal

kubectl apply -f - <<EOF
apiVersion: example.com/v1
kind: Widget
metadata:
  name: my-widget
spec:
  size: large
  color: blue
EOF

Expected Output

widget.example.com/my-widget created

This command lists all Widget custom resources in the current namespace.

Terminal

kubectl get widgets

Expected Output

NAME        AGE

my-widget   10s

Key Concept

If you remember nothing else from this pattern, remember: Custom resources let you add new resource types to Kubernetes to manage your own application data.

Common Mistakes

Not applying the CustomResourceDefinition before creating custom resource instances

Kubernetes does not know about the new resource type yet, so it rejects the instance creation

Always apply the CRD manifest first and confirm it is created before creating custom resources

Using incorrect apiVersion or kind when creating custom resource instances

The API server will reject the resource because it does not match the registered CRD

Use the exact apiVersion and kind defined in the CRD for your custom resources

Summary

Create a CustomResourceDefinition YAML file to define your new resource type.

Apply the CRD to register the new resource type in Kubernetes.

Create instances of your custom resource using the new apiVersion and kind.

Use kubectl commands to verify the CRD and list your custom resources.