DevOps Blog

Kubernetes Custom Resource Definition (CRDs) Explained

3 minute read
Toye Idowu

In this post, we are going to talk about Custom Resource Definitions (CRDs). We will go over:

  • What CRDs are
  • How they are used
  • How to create them
  • A few tips and tricks

To follow along, I assume you have prior knowledge of Kubernetes, kubectl, and have minikube running.

(This article is part of our Kubernetes Guide. Use the right-hand menu to navigate.)

CRD concepts in K8S

To begin to understand what CRD is, we must go over a couple of concepts in Kubernetes:

  • A resource is an endpoint in k8s API that allow you to store an API object of any kind.
  • A custom resource allows you to create your own API objects and define your own kind just like Pod, Deployment, ReplicaSet, etc.

Custom Resource allows you to extend Kubernetes capabilities by adding any kind of API object useful for your application. Custom Resource Definition is what you use to define a Custom Resource. This is a powerful way to extend Kubernetes capabilities beyond the default installation.

How to create a CRD

The manifest below shows an example CRD crd.yaml

kind: CustomResourceDefinition
- name: v1
served: true
storage: true
scope: Namespaced
plural: appconfigs
singular: appconfig
kind: AppConfig
- ac

Let’s explain what the CRD above will create:

  • The first two lines defines what the apiversion is and we are saying we want to create a custom resource definition.
  • The metadata field helps us define what the name of the resource is. In our case appconfigs (plural).
  • Spec group help us define what the group name will be.
  • Spec version helps us define the version. We are saying it is v1, and we want this version to be our storage version.
  • As you can see, we can define a version of our CRD and only one version can be a storage version at a time, so keep that in mind. We then made sure that this CRD is a namespaced and not cluster wide. This allow us to create the CRD for either just a specific namespace or for the whole cluster.
  • Next, we defined what the singular and plural name of our CRD will be.
  • Lastly we defined the kind name and the short name. We can then create it with “kubectl create -f crd.yaml”. The new namespaced RESTful API endpoint for our CRD will be found at /apis/*/appconfigs/

So we are probably wondering ok this is good but how is this useful? To use, the CRD above, we create a manifest using the kind we created with the CRD. For example we have my-kind.yaml

apiVersion: ""
kind: AppConfig
name: demo-appconfig
uri: "some uri"
Command: "some command"
image: my-image

As you can see, we are using the kind we defined in our CRD, then we defined the fields we want our kind object to have. Here we want to define, the uri, command and image for our app. Now if we run “kubectl create -f my-kind.yaml” our application can consume the data we created with the manifest above. To see what is going on we can run “kubectl get ac -o yaml”, we can see detailed info on what we just created. Notice how we are using the short name (ac) we defined in our CRD.

How to delete a CRD

To delete the CRD and resources we created, simply run kubectl delete just like with any other resources. It is important to know that the above CRD is just data which can be stored and retrieved therefore, it doesn’t give us a fully declarative API. The way to make this resource fully declarative is to add a custom controller, whose job is to make sure that the current state and the desired state are always in sync. An example is something like a replication controller.

CRDs expand Kubernetes

CRD is a way to extend kubernetes allowing us to create a custom resource of our choice and making it declarative with the help of a custom controller.

Additional resources

For more on Kubernetes, explore these resources:

Beginning Kubernetes: Knowledge & Tutorials for Getting Started

In this comprehensive e-book, we take a deep dive into the distributed computing platform Kubernetes, also known as K8s.

These postings are my own and do not necessarily represent BMC's position, strategies, or opinion.

See an error or have a suggestion? Please let us know by emailing

Business, Faster than Humanly Possible

BMC works with 86% of the Forbes Global 50 and customers and partners around the world to create their future. With our history of innovation, industry-leading automation, operations, and service management solutions, combined with unmatched flexibility, we help organizations free up time and space to become an Autonomous Digital Enterprise that conquers the opportunities ahead.
Learn more about BMC ›

About the author

Toye Idowu

Olatoye is a Certified Kubernetes Administrator and experienced DevOps/Platform engineering Consultant with a demonstrated history of working in the Information Technology and Services industry.