Deleting a CustomResourceDefinition deletes every custom object stored under it. The Kubernetes docs say the server will uninstall the REST endpoint and delete all custom objects stored in it. Recreating the same CRD starts out empty, so export the resources first.
What gets removed
A CRD defines an API path such as /apis/GROUP/VERSION/PLURAL. When you delete the CRD, that path goes away and so does the data behind it. Requests for the type then return a NotFound error.
Scope matters too. CRDs themselves are not namespaced, so one delete affects every namespace. Custom objects follow their own scope setting, and deleting a namespace deletes the custom objects in it, just like built-in objects.
Why this is a supply chain concern
Operators and add-ons ship CRDs. Removing an operator the careless way, or letting a tool prune what it thinks is unused, can take out database clusters, certificates or policies defined as custom resources. Whoever can delete CRDs holds a cluster-wide destructive permission, so it deserves the same care as cluster-admin.
Steps before you remove a CRD
- List who depends on it:
kubectl get CRDNAME --all-namespaces. - Export every object to files and store them outside the cluster.
- Remove the operator or controller first, so nothing recreates objects while you work.
- Check for finalizers on the custom objects, because cleanup logic may live in the controller you just removed.
- Delete the CRD only when the export is verified.
A worked example
Say a team installed a certificate or database operator two years ago and a new engineer sees an unfamiliar CRD during a cleanup. The CRD list shows a type with a plural name and a group they do not recognise, and nothing in the namespace they work in uses it. They delete it. In the same moment the API path disappears and every object of that type, in every namespace, is removed. Workloads that depended on those objects keep running for a while, then fail at the next renewal or restart.
The fix is procedural, not technical. Make CRD deletion a reviewed change with a named owner, and require the export step in the ticket.
Safer ways to retire a type
If you only want a type to stop being used, you do not have to delete it. The Kubernetes docs describe a served flag on each version of a CRD. Turning a version off in a controlled way, after you have migrated objects to a newer version, is gentler than deleting the whole definition. Plan the migration first, and check the full versioning section of the docs for the exact behavior of your Kubernetes release.
Who should be allowed to do it
Restrict create, update and delete on customresourcedefinitions to a small admin group. A role that can edit CRDs can change validation schemas and conversion settings for a whole API group. Audit it the way you audit RBAC mistakes that lead to cluster-admin.
Helm will not remove CRDs on uninstall, which is the safe default. See does helm upgrade update CRDs for how that plays out.
Quick check
Is there an undo for deleting a CRD?
Not inside Kubernetes. The docs say a recreated CRD starts out empty, so recovery means restoring objects from your own exports or backups.
Does deleting a namespace delete custom objects in it?
Yes. The docs say deleting a namespace deletes all custom objects in that namespace, as with built-in objects.
Safeguard asset discovery builds an inventory of what you run, which is a useful starting point before any cleanup.
Sources
- Kubernetes: Extend the API with CustomResourceDefinitions
- Helm: Custom Resource Definitions best practices
Last reviewed: 19 October 2026.
