Mastering Kubernetes CRDs: Create, Manage, and Extend Custom Resources

What is a CRD

CRD stands for CustomResourceDefinitions, allowing users to define new resources in Kubernetes beyond built‑in ones such as Pod, Deployment, etc.

CRDs let you extend Kubernetes without modifying its source code; for example, Tencent Cloud TKE uses a CRD logcollectors.ccs.cloud.tencent.com to add log collection, and Istio heavily relies on CRDs.

Another extension method is apiservice, e.g., the metrics.k8s.io API for custom HPA.

You can list defined resources with kubectl api-resources.

# kubectl api-resources
NAME                              SHORTNAMES   APIGROUP                       NAMESPACED   KIND
configmaps                        cm                                          true         ConfigMap
endpoints                         ep                                          true         Endpoints
events                            ev                                          true         Event
namespaces                        ns                                          false        Namespace
persistentvolumes                 pv                                          false        PersistentVolume
pods                              po                                          true         Pod
podtemplates                                                                  true         PodTemplate
storageclasses                    sc           storage.k8s.io                 false        StorageClass
...

Key CRD attributes include:

NAME – plural name of the CRD

SHORTNAMES – CLI abbreviation

APIGROUP – API group name

NAMESPACED – whether it is namespaced

KIND – resource kind used in manifests

CRDs need a controller to act on them; the kube‑controller‑manager provides built‑in controllers such as cronjob, daemonset, deployment, namespace, etc., which watch resource events. Custom controllers can be written for CRDs.

Using CRDs

In clusters >1.7.0 you can access CRDs via apiextensions.k8s.io/v1beta1; in clusters >1.16.0 use apiextensions.k8s.io/v1.

Creating a CRD

Example CRD manifest (crd-test.yml):

# crd-test.yml
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: crontabs.staight.k8s.io
spec:
  group: staight.k8s.io
  versions:
    - name: v1
      served: true
      storage: true
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
    - ct
  preserveUnknownFields: false
  validation:
    openAPIV3Schema:
      type: object
      properties:
        spec:
          type: object
          properties:
            cronSpec:
              type: string
            image:
              type: string
            replicas:
              type: integer

Create the CRD:

# kubectl create -f crd-test.yml
customresourcedefinition.apiextensions.k8s.io/crontabs.staight.k8s.io created

Verify it:

# kubectl get crd crontabs.staight.k8s.io
NAME                      CREATED AT
crontabs.staight.k8s.io   2019-10-08T10:21:09Z

Access the custom resource via URL e.g.

https://169.254.128.15:60002/apis/staight.k8s.io/v1/namespaces/default/crontabs

.

Creating a custom object

After the CRD is created, you can create an instance:

# crontab.yml
apiVersion: "staight.k8s.io/v1"
kind: CronTab
metadata:
  name: new-crontab
spec:
  cronSpec: "* * * * *"
  image: new-image

Create the object:

# kubectl create -f crontab.yml
crontab.staight.k8s.io/new-crontab created

List the object:

# kubectl get crontab
NAME          AGE
new-crontab   28s

Summary

CRDs are the most common way to extend Kubernetes with custom resources.

Creating a CRD alone is insufficient; a controller is required to watch and act on resource changes.