What are Custom Resource Definitions (CRDs)?
☸ Kubernetes · 5 min read
Kubernetes lets you define your own resource types. Here's what that means and when you'd actually use it.
⏱ 5 min read 🎯 Beginner 📦 K8s Extensibility
What is a CRD?
Kubernetes ships with a set of built-in resource types — things like Pod, Deployment, Service, and ConfigMap. These cover most common use cases.
But sometimes you need Kubernetes to understand something it doesn't know about yet — like a Database, a BackupPolicy, or a TLSCertificate. That's exactly what a Custom Resource Definition (CRD) solves.
A CRD is a way to extend Kubernetes by teaching it a brand new resource type. Once you register a CRD, Kubernetes treats your new resource just like a built-in one — you can kubectl apply it, kubectl get it, set permissions on it, and so on.
💡 Simple Analogy
Think of Kubernetes like a spreadsheet app. It comes with built-in column types — text, number, date. A CRD is like creating your own custom column type called "Database" that the app now understands and validates natively.
Why Do CRDs Exist?
Kubernetes was designed to be extensible from the start. The core team couldn't predict every use case, so they built a way for anyone — teams, companies, open source projects — to add their own resource types without touching the Kubernetes source code.
🧩 Flexibility — Every team has unique needs. CRDs let you model your infrastructure in a way that makes sense for your specific use case.
🔁 Consistency — Instead of writing custom scripts or using separate tools, you manage everything through the same kubectl workflow you already know.
🏗️ Ecosystem — Tools like cert-manager, Argo CD, and Istio ship their own CRDs so they feel native to Kubernetes rather than bolted on from outside.
When Do You Use CRDs?
You'll use (or encounter) CRDs in three situations:
1. When you install a Kubernetes tool
Most popular Kubernetes tools automatically install CRDs when you deploy them. You're already using CRDs without realising it every time you install something like Argo CD or Prometheus Operator.
🔐cert-manager adds Certificate, Issuer, ClusterIssuer — so you can describe TLS certs declaratively
🚀 Argo CD adds Application — so you can describe a GitOps deployment as a Kubernetes resource
📊 Prometheus Operator adds ServiceMonitor — so you can define what to scrape without editing config files
🌐 Istio adds VirtualService, DestinationRule — so you can manage traffic routing natively in Kubernetes
2. When you're building an internal platform
Platform teams often create CRDs to give developers a simpler, opinionated interface. Instead of making developers write 200-line YAML for a full app deployment, they create a simple AppDeployment CRD where devs just say what image they want and what size — the platform handles the rest.
🧑💻 Example: A developer applies a kind: AppDeployment with 5 fields. Behind the scenes, the platform automatically wires up a Deployment, HPA, Service, Ingress, and PodDisruptionBudget. The developer never sees any of that complexity.
3. When you're building a Kubernetes Operator
An Operator is an advanced pattern where you automate the management of a complex piece of software — like a database cluster, a message queue, or a caching layer. The Operator watches your custom resource and reacts to changes automatically.
⚙️ Example: You apply a kind: PostgresCluster resource. The Postgres Operator sees it, spins up the right pods, configures replication, sets up backups — all automatically. You just described what you want, it figured out how.
What a CRD Is NOT
A common beginner confusion — a CRD by itself doesn't do anything. It's just a schema. It tells Kubernetes "this resource type exists and here's what it looks like." Nothing actually happens when you create a custom resource unless there's a controller watching it and taking action.
⚠️ Think of a CRD as a form and a controller as the person who processes the form. The form defines what fields exist. Without someone reading and acting on it, nothing moves forward.
❌ A CRD alone does not spin up pods, create storage, or call external APIs
❌ A CRD alone does not replace built-in resources like Deployments or Services
✅ A CRD + a Controller together form what's called an Operator — that's where the real power comes from
// Quick Recap
→ CRD = a new resource type you teach Kubernetes to understand
→ Works just like built-in resources — kubectl apply, get, describe all work
→ You use them when you install tools like Argo CD, cert-manager, Istio
→ Platform teams use them to simplify developer experience
→ CRD alone = just storage. Add a Controller to make things happen
Final Thoughts
CRDs are one of the most powerful features in Kubernetes — but also one of the most misunderstood.
At first, they just look like “extra YAML.” But once you understand them, you realize something important:
👉 Kubernetes is not just a container platform — it’s a platform you can extend.
With CRDs, you’re not limited to Pods and Deployments anymore. You can define your own concepts, your own abstractions, and even your own platform experience.
Installing tools? → You’re already using CRDs
Building platforms? → You simplify life for developers
Writing Operators? → You automate complex systems
And the most important takeaway:
👉 CRDs define what you want. Controllers make it happen.
Once this clicks, a lot of Kubernetes suddenly starts making sense.
