Kubernetes CRD Definitive Guide

March 14, 2024
min read

Kubernetes CRDs (custom resource definitions) are flexible building blocks that extend Kubernetes and enable administrators to manage Kubernetes resources and meet unique requirements more efficiently. If you've heard of Kubernetes CRDs or want to enhance your experience, you're in the right place.

This article will explore Kubernetes CRDs in depth, including benefits, real-world use cases, and best practices. By the end of this article, you'll be equipped to use CRDs in your Kubernetes projects.

Summary of key Kubernetes CRD concepts

The table below summarizes the Kubernetes CRD concepts this article will explore in more detail.

Concept Description
Introduction to Kubernetes CRDs Exploring the purpose and benefits of Kubernetes CRDs.
Anatomy of a custom resource definition Understanding the components and scope of CRDs.
Creating and managing custom resources Performing CRUD operations on CRDs in Kubernetes.
Extending functionality with controllers Enhancing CRD behavior using custom controllers.
Kubernetes CRD advanced topics Exploring advanced customization and access control for CRDs.
Real-world use cases for Kubernetes CRDs Case studies on practical applications of CRDs.
Kubernetes CRD challenges and limitations Addressing performance considerations and potential pitfalls.

Introduction to Kubernetes CRDs

Kubernetes CRDs is a powerful extension to the Kubernetes API that expands Kubernetes beyond its core resource types. CRDs allow administrators to introduce new, application-specific resources into Kubernetes clusters, tailoring the platform to unique requirements.

This purpose aligns with the need to bridge the gap between the general-purpose nature of Kubernetes and the specific needs of diverse applications.

Benefits of Kubernetes CRD

Kubernetes CRDs provide several benefits for Kubernetes administrators. By enabling the creation of custom resources, CRDs allow for abstraction and simplification of complex processes and streamline deployment and management tasks. These custom resources create modularity and reusability across projects, which reduces development time and improves efficiency.

Moreover, CRDs establish domain-specific APIs, enhancing communication between applications and the Kubernetes platform. The enforced schema ensures data integrity, reducing errors and promoting consistency across deployments, ultimately improving the overall efficiency and reliability of Kubernetes environments.

One example is the Istio VirtualService custom resource. In an Istio service mesh context, the VirtualService CRD empowers administrators to define complex traffic routing rules, apply weighted load balancing, enable fault injection, and enforce fine-grained security policies for microservices.

Anatomy of a Kubernetes CRD

Kubernetes CRDs empower administrators to go beyond the built-in resource types and introduce new domain-specific resources into their Kubernetes clusters. Let’s break down the components of a CRD to better understand how they work in practice.

Components of a CRD

A CRD is defined by four key components.

  • Group categorizes the CRD under a specific API group, helping to organize related resources.
  • Version represents the API version for the CRD, allowing for future iterations while maintaining backward compatibility.
  • Kind is the singular name of the custom resource.
  • Plural is its plural form, which aids in creating the resource's endpoint URL.

Here is an example of a CRD declaration:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
  name: uffizziclusters.uffizzi.com
  group: uffizzi.com
    kind: UffizziCluster
    listKind: UffizziClusterList
    plural: uffizziclusters
    - uc
    singular: uffizzicluster
# Custom resource attributes and configurations

Kubernetes CRD vs. CR: Scope and access level of CRDs

In Kubernetes CRDs, it's essential to differentiate between the CRD itself and the custom resources (CRs) it generates.

The CRD is a cluster-wide resource, always available across the entire cluster. However, the resulting custom resources can vary in scope and can be either Cluster or Namespaced.

When a CRD is defined as cluster-wide, any CR created from it can be accessed from any namespace.

Conversely, if the CRD is defined with a namespaced scope, the CR derived from it is confined to a specific namespace, limiting its accessibility to that namespace alone.

This distinction is crucial for administrators as they fine-tune the behavior and reach of their custom resources.

Creating and managing custom resources

Kubernetes CRDs empower administrators to tailor custom resources precisely to their applications, offering granular control over cluster behavior.

Instantiating custom resources from CRDs

Administrators instantiate custom resources from the defined CRDs to bring them to life. Here is an example of a CRD provided by Uffizzi (the end has been truncated for brevity; the full CRD can be viewed here):

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
  name: uffizziclusters.uffizzi.com
  group: uffizzi.com
    kind: UffizziCluster
    listKind: UffizziClusterList
    plural: uffizziclusters
    - uc
    singular: uffizzicluster
# Custom resource attributes and configurations

CRUD operations on custom resources

CRUD represents the fundamental operations used to manage resources within a system and serves as a basis for interacting with Kubernetes CRDs.

CRUD Description
Create Creating new instances of a resource.
Read Reading and retrieving details of instances.
Update Modifying attributes or properties of instances.
Delete Removing instances from the system.

Let's take a look at CRUD operations in practice.

First, create a file TestCluster.yaml with the content:

kind: UffizziCluster
apiVersion: uffizzi.com/v1alpha1
  name: TestCluster
  - chart:
      name: kubernetes-dashboard
      repo: https://kubernetes.github.io/dashboard/

Once instantiated, custom resources support CRUD operations.

Create a new instance:

kubectl create -f TestCluster.yaml

Read details of an instance:

kubectl get UffizziCluster TestCluster

Or, using the short name:

kubectl get uc TestCluster

Update attributes of an instance:

kkubectl edit uc TestCluster

Delete an instance:

kubectl delete uc TestCluster

Viewing and querying custom resources in kubectl

Administrators can use kubectl to interact with custom resources. Here are some practical examples of kubectl commands.

List all instances:

kubectl get uc

Describe a specific instance:

kubectl describe uc TestCluster

Extending functionality with controllers

Kubernetes CRDs lay the foundation for custom resources, and controllers further extend their capabilities by automating resource management and maintaining desired states.

Introduction to controllers

Controllers are Kubernetes components designed to manage and maintain the lifecycle of resources, including custom resources defined by CRDs. Their primary role is to ensure that resources align with the state specified in the CRD instances. Controllers continuously monitor the cluster, detect changes, and take action to reconcile the current state with the desired state, ensuring system reliability and predictability.

Developing a controller for a CRD

Creating a controller for a CRD involves developing custom logic to handle the resource's lifecycle. This logic includes handling resource creation, modification, and deletion events. Controllers can be implemented in various programming languages like Go, Python, or Java. The controller for UffizziCluster, which reconciles the CRD from the previous section, is implemented in Go.

Kubernetes provides libraries and tools to facilitate controller development, streamlining the process of building resilient and efficient controllers.

Reconciliation loop and maintaining the desired state

The core concept of a controller's functionality revolves around the reconciliation loop. This loop continuously compares the current state of resources with their desired state, as specified in the CRD instances. If discrepancies are detected, the controller takes corrective actions to return the resource to the desired state. This loop ensures that resources remain in sync with the intent of administrators and the specifications outlined in CRD instances, contributing to stable and self-healing Kubernetes environments.


Kubernetes CRD advanced topic

Kubernetes CRDs unlock advanced possibilities that span microservices deployment management, custom storage solutions, and fine-tuned application configuration. Below, we’ll explore three advanced Kubernetes CRD topics.

CRDs for application-specific configuration management

CRDs shine in managing application-specific configurations. Administrators can design custom resources that capture intricate application settings and configurations.

These CRDs facilitate the uniform deployment of applications across environments, enforcing best practices and reducing configuration drift. With CRDs, administrators maintain control over application behavior while simplifying deployment complexity. That is exactly the case for the UffizziCluster CRD.

Case study: Using CRDs for managing microservice deployments

CRDs are instrumental in orchestrating microservice deployments. Administrators can streamline deployments by defining custom resources.

CRDs can enable administrators to manage the lifecycle of microservices, including scaling, updates, and rollback, ensuring efficient orchestration of complex distributed applications. Argo Rollouts are a great example of this capability.

Implementing custom storage solutions with CRDs

CRDs extend their influence to managing custom storage solutions. Administrators can define CRDs to represent storage classes, persistent volumes, and claims tailored to their application requirements.

This flexibility allows for the creation of storage solutions that align with the specific needs of applications, optimizing data management and storage utilization. Postresql cluster is a popular example of this capability.

Kubernetes CRD challenges and limitations

While Kubernetes CRDs empower administrators with flexibility, they also come with challenges and limitations that warrant consideration for optimal implementation.

Performance considerations with a large number of CRDs

As the number of CRDs increases, performance can be affected. Each CRD introduces additional load on the Kubernetes API server and etcd,  both of which could impact cluster responsiveness. Administrators need to monitor resource usage carefully, especially in scenarios with numerous CRDs, and implement strategies to mitigate performance bottlenecks.

Best practices to mitigate Kubernetes CRD limitations and pitfalls

CRD implementation can fall prey to common pitfalls, such as incorrect schema design, lack of validation, and insufficient testing. To address these challenges, administrators should adhere to best practices. Crafting well-defined schemas, enforcing data validation, and thorough testing ensure the stability and reliability of CRDs. Additionally, maintaining effective communication between development and operations teams enhances collaboration and leads to successful CRD adoption.

Kubernetes CRD best practices and recommendations

Kubernetes CRDs provide a canvas for customization, but adhering to best practices and considering various factors is essential for a successful implementation that harmonizes with the broader Kubernetes ecosystem. The three best practices and recommendations below can help administrators get the most out of their use of Kubernetes CRDs.

Design for stability and scalability

Craft CRDs with careful consideration of their structure, schema, and relationships to ensure stability and scalability. Well-defined schemas prevent data inconsistencies, while proper resource categorization and naming conventions facilitate easy discovery. Scale testing is crucial, especially for CRDs that may accumulate over time, to ensure they can handle larger workloads without compromising cluster performance.

Thoroughly test to ensure CRD quality and reliability

Thorough testing is paramount to avoid potential issues. Implement unit testing to verify CRD behavior individually and integration testing to validate their interaction with other resources. Continuous testing and validation pipelines ensure ongoing compatibility with Kubernetes updates and changes, safeguarding against unintended consequences.

Manage and abstract complexity with CRDs

CRDs are catalysts for building solutions of heightened complexity within Kubernetes environments. This level of granularity goes beyond traditional Kubernetes resources, allowing it to craft solutions like virtual clusters, multi-tier application deployments, and environments as a service.



Kubernetes CRDs are like the building blocks that help you extend what Kubernetes can do, allowing you to create customized tools that seamlessly fit your apps, making them more adaptable and versatile. Administrators using CRDs effectively can significantly improve development efficiency, quality, and scalability while meeting unique application requirements.

Like this article?

Subscribe to our LinkedIn Newsletter to receive more useful content.

Subscribe now