Kubernetes CRDs:
Expanding K8s Potential Beyond Standard Objects

Back to Glossary

Kubernetes was built to manage your fleet of clusters for you. It comes built-in with standard objects like Services, Deployments, and Ingresses to name a few. The typical flow of operations is the administrator defining key objects they need on the cluster, and Kubernetes making sure they always exist and are operational.

Try Traefik Hub: Publishing, Securing, & Managing APIs has Never Been Easier

This constant loop allows administrators to manage the desired states of their clusters in versioning systems like Git, and it gave birth to operational flows like GitOps, building on DevOps best practices.

Now, when administrators want Kubernetes to manage more objects than what is already available, they can define their own. These are called CRDs: Custom Resource Definitions.

What are Kubernetes Custom Resource Definitions (CRDs)

Kubernetes Custom Resource Definitions (CRDs) are definition files—structured data that describe objects (Custom Resources) and their desired state—that extend the scope of Kubernetes and leverage the existing K8s ecosystem.

Administrators manipulate these Custom Resources through the same available tools (e.g., kubectl) and secure them with the same role based access control. Once defined and added to the state of the cluster, these objects are available through the standard K8s API.

How are Kubernetes Custom Resources handled?

Since CRDs are definitions only, administrators need to add specific skills to Kubernetes so it can handle these new resources—the same way they install Ingress Controllers to manage the standard Ingress Objects.

Operators or controllers are the components responsible for managing custom resources in Kubernetes.

For example, Traefik extends the capabilities of the standard Ingress objects with the help of the IngressRoute CRD. Traefik, as the IngressRoute Controller, is responsible for managing these IngressRoute objects and allows requests to be dispatched leveraging fine-grained routing rules.

Kubernetes Administrators who add CRDs to their cluster will also add operators to manage these new resources.

Creating and Applying CRDs (With an Example)

Let's consider an example to illustrate the use of CRDs. Suppose you are managing a backup pipeline using Kubernetes.

In this system, each backup pipeline is a resource that needs to be managed. However, Kubernetes' built-in resources don't quite fit the concept of a backup pipeline. This is where CRDs can be very helpful.

Creating such a CRD in Kubernetes starts with defining the schema, using JSON Schema. This schema outlines the structure of your custom resource, and allows you to define acceptable values and structure.

Let’s then define a backup pipeline and its attributes. We’ll consider a pipeline to have 4 attributes:

  • appId—a unique identifier
  • Periodicity—a frequency of daily, weekly, or monthly
  • Copies—a number between 1 and 10 indicating how many copies of the backup the system should keep over time
  • Mode—either incremental or full

Only appId, periodicity, and mode are required fields.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
 name: bupipelines.traefik.io
 group: traefik.io
   plural: bupipelines
   singular: bupipeline
   kind: BUPipeLine
   - bupl
 scope: Namespaced
   - name: v1alpha1
     served: true
     storage: true
         type: object
             type: object
                 type: string

                 type: string
                 - daily
                 - weekly
                 - monthly

                 type: integer
                 minimum: 1
                 maximum: 10
                 type: string
                   - incremental
                   - full

             required: ["appId", "periodicity", "mode"]
         required: ["spec"]

To allow Kubernetes to handle this new CRD, use the command kubectl apply. In the following example, we saved the CRD in a file named backuppipeline.yaml.

kubectl apply -f backuppipeline.yaml
customresourcedefinition.apiextensions.k8s.io/bupipelines.traefik.io created

Using CRDs to Create and Manage Custom Resources

Once a CRD has been created, users can create custom resources of that type. These resources can be managed using the Kubernetes API, just like any other resource. They can be created, updated, deleted, and retrieved using the kubectl command-line tool or any other tool that interacts with the Kubernetes API.

Use the example given above, and define a BUPipeline:

apiVersion: traefik.io/v1alpha1
kind: BUPipeLine
 name: test-pipeline
 appId: daily-backup
 periodicity: daily
 mode: incremental
 copies: 5

Assuming the above content was saved to a file named bupipeline-std.yaml, you can apply it with kubectl apply -f bupipeline-std.yaml.

kubectl apply -f bupipeline-std.yaml
bupipeline.traefik.io/test-pipeline created

And if you tried with an incorrect value, K8s would refuse to apply the change. For example, if we tried to define 15 copies, we’d get the following error:

kubectl apply -f bupipeline-std.yaml
The BUPipeLine "test-pipeline" is invalid: spec.copies: Invalid value: 15: spec.copies in body should be less than or equal to 10

Benefits of Using CRDs

Custom Resource Definitions provide important benefits for anyone running their applications in Kubernetes at scale. The two most important benefits are:

  1. Extended Functionality—CRDs extend the functionality of the Kubernetes API, enabling it to manage more than its standard objects. This flexibility is one of the key reasons behind the popularity of Kubernetes.
  2. Adaptability—CRDs, when used in conjunction with Kubernetes operators, open up almost unlimited possibilities for adapting Kubernetes to manage every part of your infrastructure.


CRDs provide a way to extend the Kubernetes API beyond standard out-of-the-box functionality, allowing users to create custom resources that adapt to every unique environment. This makes Kubernetes more flexible, and a perfect fit in a wide range of scenarios.

If you’re managing company microservices and APIs in Kubernetes, know that Traefik Hub, the industry’s first Kubernets-native API management solution, takes full advantage of CRDs and introduces Custom Resources for the whole lifecycle of APIs. Request your free trial of Traefik Hub today.

Your APIs Deserve BetterTry Traefik Hub free for 14-days. Publishing, Securing, and Managing your APIs has never been easier.Request a Free Trial

References and further reading

Traefik Labs uses cookies to improve your experience. By continuing to browse the site you are agreeing to our use of cookies. Find out more in the Cookie Policy.