Understanding and building Kubernetes Custom Resource Definitions (CRDs)

Understanding and building Kubernetes Custom Resource Definitions (CRDs)


So, let’s say you had a service or application that was built on an orchestration platform such as Kubernetes. In doing so, you must also address an overflowing array of architectural issues, including security, multi-tenancy, API gateways, CLI, configuration management, and logging.

Wouldn’t you like to save some manpower and development time and focus on creating something unique to your problem?

Well, it just so happens that your solution lies in what’s called a Custom Resource Definition, or CRD. The CRD enables engineers to plug in your own Object and application as if they were a native Kubernetes component. This is extremely powerful in creating tool and services built on Kubernetes

By doing this, you can build out the custom resources for your application as well as use Kubernetes RBAC to provide security and authentication to your application. These custom resources will be stored in the integrated etcd repository with replication and proper lifecycle management. They will also leverage all the built-in cluster management features which come with Kubernetes.

Why do I need a CRD?

The easiest way to answer this is that you might not! It really depends on your specific project and needs. The Kubernetes Docs answer this question like so:

Use a ConfigMap if any of the following apply:

  • There is an existing, well-documented config file format, such as a mysql.cnf or pom.xml.
  • You want to put the entire config file into one key of a ConfigMap.
  • The main use of the config file is for a program running in a Pod on your cluster to consume the file to configure itself.
  • Consumers of the file prefer to consume file via a Pod or an environment variable in a Pod, rather than the Kubernetes API.
  • You want to perform rolling updates via Deployment, etc., when the file is updated.

Note: Use a secret for sensitive data, which is similar to a ConfigMap but more secure.

Use a Custom Resource Definition (CRD or Aggregated API) if most of the following apply:

  • You want to use Kubernetes client libraries and CLIs to create and update a new resource.
  • You want top-level support from kubectl (for example: kubectl get my-object object-name).
  • You want to build new automation that watches for updates on the new object, and then CRUD other objects, or vice versa.
  • You want to write automation that handles updates to the object.
  • You want to use Kubernetes API conventions like .spec, .status, and .metadata.
  • You want the object to be an abstraction over a collection of controlled resources or a summation of other resources.

Everyone has different goals in mind and context surrounding those goals, however if your project needs a flexible way to extend Kubernetes and is trying to stick heavily to the “Kubernetes-native” way of doing things then CRDs are right up your alley. You might be asking now, what are some typical CRDs? I’m glad you asked!

Githook example CRD

This CRD is called GitHook. It defines git webhook events and a build pipeline. GitHook controller will subscribe webhook events to git repo and when the events happen, it will run a build pipeline as defined in the CRD.

GitHook CRD controller’s job is:

  1. Make sure that webhook is registered to git repo with correct information.
  2. Make sure that there is a service running and wait for the webhook events. It uses Knative service to receive that webhook since it is easy to implement and can scale to 0 when it is not in use.

With a little work and a good team, you could string some CRDs like this together and have a startup like CircleCI or Gitlab!

Final thoughts

So in closing, CRDs are really amazing extensions of the Kubernetes API and allow a lot of flexibility in the creation of K8s native applications.  Hope this helps you wrap your head around CRDs and their uses a bit more, thanks for reading!

Subscribe to our newsletter

Stay informed about the latest updates, news, and insights.