Mastering Kubernetes CRDs: How to Define and Use Custom Resources

What is a CRD

CRD stands for

CustomResourceDefinitions

, which allow users to define new resources in Kubernetes, extending its functionality beyond built‑in objects such as Pods, Deployments, and ReplicaSets.

CRDs let you add features without changing the Kubernetes source code; for example, Tencent Cloud TKE uses a CRD at

logcollectors.ccs.cloud.tencent.com

for log collection, and Istio heavily relies on CRDs.

Another extension method is

apiservice

, with the API

metrics.k8s.io

being a typical use case for custom HPA.

You can list all defined resources in a cluster with

kubectl api-resources

:

<code># 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
...</code>

From this output you can see that a CRD includes attributes such as:

NAME – plural name of the CRD

SHORTNAMES – CLI abbreviation

APIGROUP – API group name

NAMESPACED – whether it is namespaced

KIND – resource kind used in manifests

To make a CRD functional you also need a controller (e.g.,

kube-controller-manager

) that watches resource events and acts accordingly.

CRD Usage

In clusters newer than 1.7.0 you can access CRDs via

apiextensions.k8s.io/v1beta1

, and from 1.16.0 onward via

apiextensions.k8s.io/v1

.

Create a CRD

Example CRD manifest (crd-test.yml):

<code># 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</code>

Create the CRD:

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

Verify its existence:

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

After creation you can access the custom resource via its API endpoint, e.g.,

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

.

Create a Custom Object

Custom object manifest (crontab.yml):

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

Create the object:

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

List the custom objects:

<code># kubectl get crontab
NAME          AGE
new-crontab   28s</code>

Summary

CRDs enable custom resources, the most common way to extend Kubernetes.

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