Demystifying Kubernetes CRDs: Extending the Platform with Custom Resources

CRD (CustomResourceDefinition) is a built‑in Kubernetes resource type that lets you define new custom resources. You can list CRDs in a cluster with kubectl get.

NAME                         CREATED AT
apps.app.o0w0o.cn            2019-07-25T07:02:47Z
microservices.app.o0w0o.cn   2019-07-25T07:02:47Z

When discussing CRDs, several common misunderstandings arise:

In Kubernetes, everything is a resource, as indicated by the kind field in YAML.

Beyond built‑in resources like Deployments, users can define their own resources (CR).

A CRD is not the custom resource itself but the definition of that resource, describing its schema.

Essentially, a CRD is an OpenAPI schema that registers a new resource with the API server, ensuring the YAML representation is valid.

Controller Pattern

Before diving deeper into CRDs, it helps to understand the controller model. For example, a Deployment manages ReplicaSets, which in turn manage Pods—this is the controller pattern.

The controller pattern allows higher‑order controllers to be built on existing resources, enabling more complex functionality.

What CRDs Can Do

By defining a CRD, you create a new controller that can implement functionality not natively supported by Kubernetes.

In a concrete example, a simple CRD was created using Kubebuilder to manage micro‑services within a cluster. Two custom resources were defined: App – manages the lifecycle of an entire application. MicroService – manages the lifecycle of individual micro‑services.

Logical structure:

The App can manage multiple MicroService instances, each supporting multiple versions. Thanks to the controller model, each version can have its own Deployment, allowing simultaneous deployment of several versions.

If deployment is simple, a MicroService can also create a Service and an Ingress to provide both layer‑4 and layer‑7 load balancing.

When load balancing is enabled, each version gets its own Service (SVC). Thus, a service has n + 1 SVCs: one per version plus a stable SVC that always points to the current version, simplifying blue‑green deployments.

Beyond services, MicroService leverages the NGINX Ingress controller for canary releases, adjusting traffic via headers, cookies, or scaling.

In this example, neither App nor MicroService introduces new capabilities; they compose existing Kubernetes resources to achieve new functionality.

Additional value includes standardizing management: product‑specific concepts can be mapped to Kubernetes resources, allowing teams to work with familiar terminology while the underlying resources handle the implementation.

Summary

From a simple demo, two key capabilities of CRDs emerge:

CRDs turn existing Kubernetes resources into Lego‑like building blocks, enabling extensions beyond native capabilities.

They let product teams define their own concepts as custom resources, aligning product terminology with Kubernetes primitives and focusing on solving domain‑specific problems.