OpsCanary
Back to daily brief
kubernetesoperatorsPractitioner

CustomResourceDefinitions: Extending Kubernetes for Your Needs

5 min read Kubernetes DocsApr 27, 2026
Share
PractitionerHands-on experience recommended

CustomResourceDefinitions (CRDs) exist to allow you to extend the Kubernetes API with your own custom resources. This capability is crucial for tailoring Kubernetes to meet the unique needs of your applications, enabling you to manage resources that are not natively supported by Kubernetes. By defining your own resources, you can enhance automation, improve resource management, and create a more cohesive operational environment.

When you create a new CRD, the Kubernetes API Server generates a new RESTful resource path for each version you specify. You can define whether your custom resource is namespaced or cluster-scoped using the spec.scope field. This flexibility allows you to organize resources according to your operational needs. Additionally, you can enforce validation on your custom resources using an OpenAPI v3.0 validation schema, ensuring that only valid configurations are accepted. For example, you might define a CronTab resource with specific fields like cronSpec, image, and replicas, which can be validated during creation and updates.

In production, you need to be aware of a few key points. First, ensure your Kubernetes server is version 1.16 or later to utilize CRDs. Also, remember that CRDs themselves are non-namespaced, meaning they are accessible across all namespaces. When you define a schema, unknown fields will be pruned before being stored, which can lead to confusion if you expect certain fields to persist. Always validate your CRD definitions and test them thoroughly in a staging environment before deploying them to production.

Key takeaways

  • Create a CustomResourceDefinition to extend the Kubernetes API with your own resources.
  • Specify whether your custom resource is namespaced or cluster-scoped using the `spec.scope` field.
  • Utilize OpenAPI v3.0 validation schemas to enforce field validation during resource creation.
  • Remember that unknown fields will be pruned before being persisted in the cluster.
  • Ensure your Kubernetes server is version 1.16 or later to use CRDs.

Why it matters

CustomResourceDefinitions enable you to tailor Kubernetes to your specific application needs, improving resource management and operational efficiency. This flexibility can significantly enhance automation and streamline workflows in complex environments.

Code examples

YAML
1apiVersion:apiextensions.k8s.io/v1
2kind:CustomResourceDefinition
3metadata:
4  name:crontabs.stable.example.com
5spec:
6  group:stable.example.com
7  versions:
8  - name:v1
9    served:true
10    storage:true
11    schema:
12      openAPIV3Schema:
13        type:object
14        properties:
15          spec:
16            type:object
17            properties:
18              cronSpec:
19                type:string
20              image:
21                type:string
22              replicas:
23                type:integer
24  scope:Namespaced
25  names:
26    plural:crontabs
27    singular:crontab
28    kind:CronTab
29    shortNames:
30    - ct
YAML
kubectl apply -f resourcedefinition.yaml
YAML
kubectl get crontab

When NOT to use this

The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.

Want the complete reference?

Read official docs

Test what you just learned

Quiz questions written from this article

Take the quiz →

Get the daily digest

One email. 5 articles. Every morning.

No spam. Unsubscribe anytime.