Mastering Kubernetes CRDs: Define and Use Custom Resources

What is a CRD

CRD stands for CustomResourceDefinitions, which allows users to define new resources in Kubernetes, extending its built‑in objects such as Pod, Deployment, and ReplicaSet.

CRDs let you add functionality without modifying the Kubernetes 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, with the metrics.k8s.io API being a typical use case for custom HPA.

You can list defined resources in a cluster with kubectl api-resources:

# kubectl api-resources
NAME          SHORTNAMES   APIGROUP               NAMESPACED   KIND
configmaps    cm                              true   ConfigMap
endpoints      ep                              true   Endpoints
... (output truncated)

From the output, a CRD includes at least the following fields:

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 require a controller to give them meaning. The built‑in kube-controller-manager provides controllers such as cronjob, daemonset, deployment, and namespace, which watch resource events and act accordingly. You can also write custom controllers for your CRDs.

Using CRDs

In Kubernetes, a CRD itself is a resource. Clusters version > 1.7.0 can use the apiextensions.k8s.io/v1beta1 API, and version > 1.16.0 can 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 exists:

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

The CRD can now be accessed 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 of the custom resource. Example manifest (crontab.yml):

# 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 custom objects:

# kubectl get crontab
NAME          AGE
new-crontab   28s

Summary

CRDs are the primary way to extend Kubernetes with custom resources.

Creating a CRD alone is not enough; a controller is needed to watch and act on resource changes.