{"id":29662,"date":"2025-09-09T14:34:42","date_gmt":"2025-09-09T09:04:42","guid":{"rendered":"https:\/\/opstree.com\/blog\/?p=29662"},"modified":"2025-09-09T14:43:25","modified_gmt":"2025-09-09T09:13:25","slug":"complete-guide-to-kubernetes-crds","status":"publish","type":"post","link":"https:\/\/opstree.com\/blog\/2025\/09\/09\/complete-guide-to-kubernetes-crds\/","title":{"rendered":"A Complete Guide to Kubernetes CRDs: Definition, Uses , Benefits, and Error Fixes"},"content":{"rendered":"<section class=\"section section--body\">\n<div class=\"section-divider\"><\/div>\n<div class=\"section-content\">\n<div class=\"section-inner sectionLayout--insetColumn\">\n<p class=\"graf graf--p\">Hi Everyone , Today we are trying to understand CRDs(Custom Resource Definitions) as I was working on one Observability project in OpsTree Global and suddenly found CRD errors and let me tell you, It was very Frustration. I will try to make you understand them in easy way, so that you don\u2019t need to make another doc of knowledge. Comment if you will have any doubts.<\/p>\n<\/div>\n<\/div>\n<\/section>\n<p><!--more--><\/p>\n<div style=\"border: 1px solid #ddd; padding: 10px; border-radius: 6px; background: #f9f9f9; margin: 15px 0;\">\n<h3><strong>Table of Contents<\/strong><\/h3>\n<ul style=\"margin: 8px 0; padding-left: 18px; font-size: 15px; line-height: 1.6;\">\n<li><a style=\"color: #0073e6; text-decoration: none;\" href=\"#what-are-crd\">What are CRD ?<\/a><\/li>\n<li><a style=\"color: #0073e6; text-decoration: none;\" href=\"#why-we-use-crd\">Why we use CRD ?<\/a><\/li>\n<li><a style=\"color: #0073e6; text-decoration: none;\" href=\"#how-does-it-help\">How does it help ?<\/a><\/li>\n<li><a style=\"color: #0073e6; text-decoration: none;\" href=\"#common-errors\">What error you will see and their Fixation ?<\/a><\/li>\n<li><a style=\"color: #0073e6; text-decoration: none;\" href=\"#faq\">FAQ<\/a><\/li>\n<\/ul>\n<\/div>\n<section class=\"section section--body\">\n<div class=\"section-content\">\n<div class=\"section-inner sectionLayout--insetColumn\">\n<h2 id=\"what-are-crd\" class=\"graf graf--h3\">What are CRD ?<\/h2>\n<p class=\"graf graf--p\">A CRD in Kubernetes is like teaching Kubernetes a new word. By Default Kubernetes only understands built-in resources like Pods\u00a0, Services, Deployments.<br \/>\nWith CRD you can add your own type of resource ( like <strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Pizza\u00a0, FoodOrder\u00a0, or <a href=\"https:\/\/opstree.com\/services\/middleware-database-and-data-engineering\/\">Database<\/a><\/em><\/strong> ) and then use it just like the build-in once with Kubectl.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"alignnone wp-image-29670 size-full\" src=\"https:\/\/opstree.com\/blog\/wp-content\/uploads\/2025\/09\/Subtitle-1.jpg\" alt=\"Kubernetes API\" width=\"800\" height=\"512\" srcset=\"https:\/\/opstree.com\/blog\/wp-content\/uploads\/2025\/09\/Subtitle-1.jpg 800w, https:\/\/opstree.com\/blog\/wp-content\/uploads\/2025\/09\/Subtitle-1-300x192.jpg 300w, https:\/\/opstree.com\/blog\/wp-content\/uploads\/2025\/09\/Subtitle-1-768x492.jpg 768w\" sizes=\"(max-width: 709px) 85vw, (max-width: 909px) 67vw, (max-width: 984px) 61vw, (max-width: 1362px) 45vw, 600px\" \/><\/p>\n<p class=\"graf graf--p\">Let\u2019s Try to Understand this Analogy with Example of <strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Zomato.<\/em><\/strong><\/p>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Think of your Phone<\/em><\/strong><br \/>\n-&gt;&gt; Your Phone already understands Contacts, Messages\u00a0, Photos ( like Kubernetes Knows Pods\u00a0, Services).<br \/>\n&#8211; \u200aBut then you Install the Zomato app \u2192 Now your Phone Understands a New Concept ( <strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">FoodOrder<\/em><\/strong>).<br \/>\n<strong class=\"markup--strong markup--p-strong\">Installing Zomato = Add a CRD ( new type = Food Order ).<br \/>\n&#8211; \u200a<\/strong>You Place a pizza order in Zomato \u2192 this a Custom Resource (an actual object of type <strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">FoodOrder.<\/em><br \/>\n&#8211; \u200a<em class=\"markup--em markup--p-em\">Zomato \u2019s<\/em> <\/strong>system ensures food is cooked and delivered \u2192 this is the Controller ( it makes sure your \u201corder\u201d is Fulfilled)<em class=\"markup--em markup--p-em\">.<\/em><\/p>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Let\u2019s See the YAML file to understand it better<\/em><\/strong><\/p>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Step 1\u00a0: Define CRD<\/em><\/strong><\/h4>\n<div style=\"border: 1px solid #ddd; border-radius: 6px; background: #1e1e1e; padding: 10px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.4;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">apiVersion: <\/span><span style=\"color: #dcdcaa;\">apiextensions.k8s.io\/v1<\/span>\r\n<span style=\"color: #569cd6;\">kind:<\/span>:<span style=\"color: #4ec9b0;\">CustomResourceDefinition<\/span>\r\n<span style=\"color: #569cd6;\">metadata:<\/span>:\r\n  <span style=\"color: #569cd6;\">name:<\/span>:<span style=\"color: #dcdcaa;\">foodorders.food.app<\/span>\r\n<span style=\"color: #569cd6;\">spec:<\/span>:\r\n  <span style=\"color: #569cd6;\">group:<\/span> <span style=\"color: #dcdcaa;\">food.app<\/span>\r\n  <span style=\"color: #569cd6;\">scope:<\/span> <span style=\"color: #dcdcaa;\">Namespaced<\/span>\r\n  <span style=\"color: #569cd6;\">names:<\/span>:\r\n    <span style=\"color: #569cd6;\">plural:<\/span> <span style=\"color: #dcdcaa;\">foodorders<\/span>\r\n    <span style=\"color: #569cd6;\">singular:<\/span> <span style=\"color: #dcdcaa;\">foodorder<\/span>\r\n    <span style=\"color: #569cd6;\">kind:<\/span> <span style=\"color: #4ec9b0;\">FoodOrder<\/span>\r\n  <span style=\"color: #569cd6;\">versions:<\/span>:\r\n    <span style=\"color: #569cd6;\">- name:<\/span> <span style=\"color: #dcdcaa;\">v1<\/span>\r\n      <span style=\"color: #569cd6;\">served:<\/span> <span style=\"color: #569cd6;\">true<\/span>\r\n      <span style=\"color: #569cd6;\">storage:<\/span> <span style=\"color: #569cd6;\">true<\/span>\r\n      <span style=\"color: #569cd6;\">schema:<\/span>:\r\n        <span style=\"color: #569cd6;\">openAPIV3Schema:<\/span>:\r\n          <span style=\"color: #569cd6;\">type:<\/span> <span style=\"color: #dcdcaa;\">object<\/span>\r\n          <span style=\"color: #569cd6;\">properties:<\/span>:\r\n            <span style=\"color: #569cd6;\">spec:<\/span>:\r\n              <span style=\"color: #569cd6;\">type:<\/span> <span style=\"color: #dcdcaa;\">object<\/span>\r\n              <span style=\"color: #569cd6;\">properties:<\/span>:\r\n                <span style=\"color: #569cd6;\">dish:<\/span>:\r\n                  <span style=\"color: #569cd6;\">type:<\/span> <span style=\"color: #dcdcaa;\">string<\/span>\r\n                <span style=\"color: #569cd6;\">quantity:<\/span>:\r\n                  <span style=\"color: #569cd6;\">type:<\/span> <span style=\"color: #b5cea8;\">integer<\/span><\/pre>\n<\/div>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Step 2\u00a0: Create Custom Resource ( Pizza Order )<\/em><\/strong><\/h4>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">apiVersion<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #dcdcaa;\">food.app\/v1<\/span>\r\n<span style=\"color: #569cd6;\">kind<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #4ec9b0;\">FoodOrder<\/span>\r\n<span style=\"color: #569cd6;\">metadata<\/span><span style=\"color: #569cd6;\">:<\/span>\r\n  <span style=\"color: #569cd6;\">name<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #dcdcaa;\">komal-pizza-order<\/span>\r\n<span style=\"color: #569cd6;\">spec<\/span><span style=\"color: #569cd6;\">:<\/span>\r\n  <span style=\"color: #569cd6;\">dish<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #ce9178;\">\"Pizza\"<\/span>\r\n  <span style=\"color: #569cd6;\">quantity<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #b5cea8;\">2<\/span><\/pre>\n<\/div>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Step 3: Run Below Commands to make the above CRD<\/em><\/strong><\/h4>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">get<\/span> <span style=\"color: #4ec9b0;\">foodorders<\/span>\r\n<span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">describe<\/span> <span style=\"color: #4ec9b0;\">foodorder<\/span> <span style=\"color: #ce9178;\">komal-pizza-order<\/span><\/pre>\n<\/div>\n<\/div>\n<\/div>\n<\/section>\n<section class=\"section section--body\">\n<div class=\"section-content\">\n<div class=\"section-inner sectionLayout--insetColumn\">\n<p><strong>[Drive Efficiency with <a href=\"https:\/\/opstree.com\/services\/devsecops-transformation-and-automation\/\" target=\"_blank\" rel=\"noopener\">DevSecOps Transformation &amp; Automation<\/a>]<\/strong><\/p>\n<h2 class=\"section-divider\"><span style=\"font-size: 28px; font-weight: 900;\">Why we use CRD ?<\/span><\/h2>\n<div class=\"section-content\">\n<div class=\"section-inner sectionLayout--insetColumn\">\n<p class=\"graf graf--p\"><em class=\"markup--em markup--p-em\">CRDs ( CustomResourceDefinitions) let us extend <a href=\"https:\/\/opstree.com\/blog\/2024\/11\/08\/modern-traffic-management-with-gateway-api-in-kubernetes\/\" target=\"_blank\" rel=\"noopener\">Kubernetes to support<\/a> our own Business or Application-specific resources.<\/em><\/p>\n<\/div>\n<\/div>\n<h4 class=\"graf graf--h4\"><strong class=\"markup--strong markup--h4-strong\">Reasons\u00a0<\/strong><\/h4>\n<ol class=\"postList\">\n<li class=\"graf graf--li\"><strong class=\"markup--strong markup--li-strong\">Add new resource types ( extended Kubernetes API )<\/strong><br \/>\n&#8211; E.g. Kubernetes doesn\u2019t know what a <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">Database<\/em><\/strong> is\u00a0.<br \/>\n&#8211; With a CRD, you can Define a <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">Database <\/em><\/strong>resource <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">Kubectl get databases <\/em><\/strong>just like we do <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">kubectl get pods.<\/em><\/strong><\/li>\n<li class=\"graf graf--li\"><strong class=\"markup--strong markup--li-strong\">Automate with Operators<br \/>\n<\/strong>CRDs allow you to automate tasks when used with a controller\/ operator.<br \/>\n<strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">\u200a- \u200aExample:<\/em><\/strong> A Database CRD might automatically provision a <a href=\"https:\/\/opstree.com\/blog\/2021\/10\/05\/percona-postgresql-through-awsesomeosm-ansible-role\/\" target=\"_blank\" rel=\"noopener\">PostgreSQL<\/a> Pod, set up storage and make backups.<\/li>\n<li class=\"graf graf--li\"><strong class=\"markup--strong markup--li-strong\">Consistency and Standardization<br \/>\n<\/strong>\u200a- \u200aIn the absence of CRDs, teams would work with scripts, or YAML hacks.<br \/>\n&#8211; \u200aIn CRDs everything is declarative and resides within Kubernetes a single API, a single workflow.<\/li>\n<li class=\"graf graf--li\"><strong class=\"markup--strong markup--li-strong\">Validation and Safety<br \/>\n<\/strong>CRDs may impose schema based rules.<br \/>\n&#8211; \u200aSuch as: a <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">BackupPolicy<\/em><\/strong> CRD may need\u00a0, frequency = daily\/weekly\/monthly. retention = integer between 1\u201330 This discourages invalid configs to be used.<\/li>\n<li class=\"graf graf--li\"><strong class=\"markup--strong markup--li-strong\">Versioning and Extensibility<br \/>\n&#8211; \u200a<\/strong>Your CRDs can just as much evolve with versions (v1alpha1, v1beta1, v1). This renders them stable and forward looking.<\/li>\n<\/ol>\n<p><strong><em>&#8221; Want to master your data initiatives? <a href=\"https:\/\/opstree.com\/ebooks\/ebook-ultimate-guide-to-delivering-end-to-end-data-strategy\/\" target=\"_blank\" rel=\"noopener\">Download our Ultimate Guide to Delivering End-to-End Data Strategy<\/a> &#8221; <\/em><\/strong><\/p>\n<h2 class=\"graf graf--h3\">What Error Will we see and it\u2019s Fixation?<\/h2>\n<h4 class=\"graf graf--h4\"><strong class=\"markup--strong markup--h4-strong\">1. CRD Not\u00a0Found<\/strong><\/h4>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Error Example:<\/em><\/strong><\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #f44747;\">error<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #dcdcaa;\">failed to identify but one recognizes key<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #ce9178;\">database.yaml<\/span> <span style=\"color: #dcdcaa;\">version<\/span> <span style=\"color: #ce9178;\">mycompany.com\/v1<\/span> <span style=\"color: #dcdcaa;\">with kind<\/span> <span style=\"color: #ce9178;\">Database<\/span> <span style=\"color: #dcdcaa;\">no matches<\/span> <span style=\"color: #dcdcaa;\">no matches are found in the query<\/span><span style=\"color: #569cd6;\">.<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Cause:<\/em><\/strong><\/p>\n<ul class=\"postList\">\n<li class=\"graf graf--li\">Before actually installing the CRD, you applied a CR (Custom Resource)<\/li>\n<li class=\"graf graf--li\">Incorrect <strong class=\"markup--strong markup--li-strong\"><em class=\"markup--em markup--li-em\">apiVersion<\/em><\/strong> or CRD name typo.<\/li>\n<\/ul>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Solution:<\/em><\/strong><\/p>\n<p>1. First install CRD:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">apply<\/span> <span style=\"color: #ce9178;\">-f crd-definition.yaml<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\">\u00a02. Then apply the CR:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">apply<\/span> <span style=\"color: #ce9178;\">database.yaml<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\">3. Verify CRDs:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">get<\/span> <span style=\"color: #4ec9b0;\">crd<\/span>\u00a0<span style=\"color: #569cd6;\">grep<\/span> <span style=\"color: #ce9178;\">database<\/span><\/pre>\n<\/div>\n<h4 class=\"graf graf--h4\">2. Schema Validation Errors<\/h4>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Error Example:<\/em><\/strong><\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #f44747;\">error<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">error during validation of<\/span> <span style=\"color: #ce9178;\">database.yaml<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">error during validation of data<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">ValidationError<\/span><span style=\"color: #569cd6;\">(<\/span><span style=\"color: #ce9178;\">Database.spec<\/span><span style=\"color: #569cd6;\">)<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">unknown field<\/span> <span style=\"color: #ce9178;\">\"storagge\"<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Cause:<\/em><\/strong><\/p>\n<p class=\"graf graf--p\">You specified a field (storagge) not present in CRD schema.<\/p>\n<p class=\"graf graf--p\">Solution:<\/p>\n<p>1. Check CRD schema using:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">kubectl<\/span> <span style=\"color: #dcdcaa;\">describe<\/span> <span style=\"color: #4ec9b0;\">databases.mycompany.com<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\">2. Fix the spelling the typo error \u200a- \u200astorage, not storagge.<\/p>\n<h4 class=\"graf graf--h4\">3. CRD Size Limit Exceeded (26625 KB\u00a0Issue)<\/h4>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Error Example:<\/em><\/strong><\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #f44747;\">etcdserver<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">mvcc<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">database space has reached<\/span> <span style=\"color: #b5cea8;\">(26625 kb growth)<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Cause:<\/em><\/strong><\/p>\n<ul class=\"postList\">\n<li class=\"graf graf--li\">Too many \/ large objects in CRD (particularly when storing logs, monitoring configs, Prometheus CRDs).<\/li>\n<li class=\"graf graf--li\">etcd is overwhelmed since CRDs place all information in etcd.<\/li>\n<\/ul>\n<p class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\"><em class=\"markup--em markup--p-em\">Solution:<\/em><\/strong><\/p>\n<p>1. Compact etcd database:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #f44747;\">etcdserver<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">mvcc<\/span><span style=\"color: #569cd6;\">:<\/span> <span style=\"color: #f44747;\">database space has reached<\/span> <span style=\"color: #b5cea8;\">(26625 kb growth)<\/span><\/pre>\n<\/div>\n<p class=\"graf graf--p\">2. Defragment etcd:<\/p>\n<div style=\"border: 1px solid #333; border-radius: 6px; background: #1e1e1e; padding: 12px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto; line-height: 1.5;\">\n<pre style=\"margin: 0; white-space: pre;\"><span style=\"color: #569cd6;\">ETCDCTL_API=3<\/span> <span style=\"color: #569cd6;\">etcdctl<\/span> <span style=\"color: #dcdcaa;\">defrag<\/span><\/pre>\n<\/div>\n<ul>\n<li class=\"graf graf--p\">\u200aCRD Use short names to decrease the size of objects.<\/li>\n<li class=\"graf graf--p\">\u200aDo not keep heavy configs in CRDs (use ConfigMap instead).<\/li>\n<\/ul>\n<p class=\"graf graf--p\">CRD Version Mismatch<\/p>\n<p class=\"graf graf--p\">Error Example:<\/p>\n<p class=\"graf graf--p\">no kind kind <a href=\"https:\/\/opstree.com\/blog\/2022\/10\/04\/prometheus-and-grafana-on-kubernetes\/\" target=\"_blank\" rel=\"noopener\">Prometheus<\/a> v1alpha1 monitoring.coreos.com no version available of monitoring.coreos.com\/v1alpha1<\/p>\n<p class=\"graf graf--p\">Cause:<\/p>\n<p class=\"graf graf--p\">You are operating a previous version of CRD (v1alpha1) yet the CR is in v1.<\/p>\n<p class=\"graf graf--p\">Solution:<\/p>\n<p class=\"graf graf--p\">Check supported versions:<\/p>\n<p class=\"graf graf--p\">kubectl get crd prometheuses.monitoring.coreos.com -o yaml grep served.<br \/>\nUpgrade CR YAML to version.<\/p>\n<p class=\"graf graf--p\">Ref: Operators Prometheus CRDs.<\/p>\n<p class=\"graf graf--p\">CRD Stalled in Terminating State.<\/p>\n<p class=\"graf graf--p\">Error Example:<\/p>\n<p class=\"graf graf--p\">customesourcedefinition.apiextensions.k8s.io databases.mycompany.com is deleted.<\/p>\n<p class=\"graf graf--p\">Cause:<\/p>\n<p class=\"graf graf--p\">CRD is deletion blocked.<br \/>\nCleanup hooks Finalizers ensure that CRD is not removed accidentally.<\/p>\n<p class=\"graf graf--p\">Solution:<\/p>\n<p class=\"graf graf--p\">Remove finalizers manually:<\/p>\n<p class=\"graf graf--p\">kubectl patch crd databases.mycompany.com -p consist of metadata finalizers:[]<\/p>\n<p class=\"graf graf--p\">Also, see Kubernetes Finalizers Docs.<\/p>\n<p class=\"graf graf--p\">CRDs Performance Problems.<\/p>\n<p class=\"graf graf--p\">Problem:<\/p>\n<p class=\"graf graf--p\">Excessive CR leads to the slowing of API server\/etcd.<br \/>\nExample: CRDs Prometheus ServiceMonitor are capable of flooding the cluster.<\/p>\n<p class=\"graf graf--p\">Solution:<\/p>\n<p class=\"graf graf--p\">Split resources with sharding (into multiple CRDs).<br \/>\nOptimize controllers to observe less objects.<br \/>\nPerformance kube-apiserver-use watch-cache flag.<\/p>\n<p class=\"graf graf--p\">Ref: CRDs and Kubernetes Scalability.<\/p>\n<p class=\"graf graf--p\">YAML Apply Issues<\/p>\n<p class=\"graf graf--p\">Error Example:<\/p>\n<p class=\"graf graf--p\">error: no resource mapping found that matches name: my-postgres namespace: none.<br \/>\nno matches of kind Database in database.yaml<\/p>\n<p class=\"graf graf--p\">Cause:<\/p>\n<p class=\"graf graf--p\">Namespace mismatch.<br \/>\nCR installed previous to CRD.<\/p>\n<p class=\"graf graf--p\">Solution:<\/p>\n<p class=\"graf graf--p\">Always install CRD first.<br \/>\nnamespace my-namespace in CR YAML.<\/p>\n<\/div>\n<\/div>\n<\/section>\n<section class=\"section section--body\">\n<div class=\"section-divider\"><\/div>\n<div class=\"section-content\">\n<div class=\"section-inner sectionLayout--insetColumn\">\n<h2 class=\"graf graf--h3\">FAQ<\/h2>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\">Q1: Which is the difference between CRDs and Kubernetes built-in resources?<\/strong><\/h4>\n<p class=\"graf graf--p\">A: CRDs are user extensions, which are defined to meet domain requirements, and built-in resources (Pods, Services, Deployments) are the resources that Kubernetes provides. CRDs are subject to the same patterns but model your business logic.<\/p>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\">Q2: Is a custom controller required per CRD?<\/strong><\/h4>\n<p class=\"graf graf--p\">A: Not necessarily. CRDs are able to store data without controllers, although controllers are required to apply business logic and respond to resource changes. CRDs may be simple configurations without any controllers.<\/p>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\">Q3: What do I do with CRD versioning in production?<\/strong><\/h4>\n<p class=\"graf graf--p\">A: Have versions in your CRD definition, do conversion webhook migrations when complicated, and have plans of depreciation. Test version migrations should first be made in non production environments.<\/p>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\">Q4: What is the behavior when I delete an active custom resource CRD?<\/strong><\/h4>\n<p class=\"graf graf--p\">A: Kubernetes will not allow to delete CRD when custom resources are there. You have to clean up all of the custom resources beforehand or gracefully clean up with finalizers.<\/p>\n<h4 class=\"graf graf--p\"><strong class=\"markup--strong markup--p-strong\">Q5: Do CRDs have the ability to affect Kubernetes cluster performance?<\/strong><\/h4>\n<p class=\"graf graf--p\">A: Well planned CRDs have very little effect. But badly constructed validation rules, too large custom resources, or ineffective controllers may have an impact. Track resource usage and take relevant limit.<\/p>\n<h2 class=\"graf graf--h3\">References<\/h2>\n<ul class=\"postList\">\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/kubernetes.io\/docs\/concepts\/extend-kubernetes\/api-extension\/custom-resources\/\" target=\"_blank\" rel=\"noopener\" data-href=\"https:\/\/kubernetes.io\/docs\/concepts\/extend-kubernetes\/api-extension\/custom-resources\/\" data->Kubernetes Official Documentation\u200a-\u200aCustom Resources<\/a>\u200a- \u200aOfficial Kubernetes documentation on custom resources and CRDs<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/kubernetes.io\/docs\/tasks\/extend-kubernetes\/custom-resources\/custom-resource-definitions\/\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/kubernetes.io\/docs\/tasks\/extend-kubernetes\/custom-resources\/custom-resource-definitions\/\" data->Kubernetes CustomResourceDefinitions Guide<\/a>\u200a- \u200aComprehensive guide to creating and managing CRDs<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/spacelift.io\/blog\/kubernetes-crd\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/spacelift.io\/blog\/kubernetes-crd\" data->Spacelift Kubernetes CRD Guide<\/a>\u200a- \u200aPractical guide with real-world examples and best practices<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/notes.kodekloud.com\/docs\/CKA-Certification-Course-Certified-Kubernetes-Administrator\/Security\/Custom-Resource-Definition-CRD-2025-Updates\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/notes.kodekloud.com\/docs\/CKA-Certification-Course-Certified-Kubernetes-Administrator\/Security\/Custom-Resource-Definition-CRD-2025-Updates\" data->KodeKloud CRD Course Materials<\/a>\u200a- \u200aUpdated CRD learning materials and examples<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/medium.com\/@muppedaanvesh\/a-hand-on-guide-to-kubernetes-custom-resource-definitions-crds-with-a-practical-example-%EF%B8%8F-84094861e90b\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/medium.com\/@muppedaanvesh\/a-hand-on-guide-to-kubernetes-custom-resource-definitions-crds-with-a-practical-example-%EF%B8%8F-84094861e90b\" data->Medium\u200a-Hands-On CRD Guide by Anvesh Muppeda<\/a>\u200a- \u200aPractical implementation examples<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/kubernetes.io\/blog\/2022\/09\/23\/crd-validation-rules-beta\/\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/kubernetes.io\/blog\/2022\/09\/23\/crd-validation-rules-beta\/\" data->Kubernetes Blog\u200a- CRD Validation Rules<\/a>\u200a- \u200aAdvanced validation techniques and best practices<\/li>\n<li class=\"graf graf--li\"><a class=\"markup--anchor markup--li-anchor\" href=\"https:\/\/helm.sh\/docs\/chart_best_practices\/custom_resource_definitions\/\" target=\"_blank\" rel=\"nofollow noopener\" data-href=\"https:\/\/helm.sh\/docs\/chart_best_practices\/custom_resource_definitions\/\" data->Helm CRD Best Practices<\/a>\u200a- \u200aBest practices for managing CRDs with Helm<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/section>\n","protected":false},"excerpt":{"rendered":"<p>Hi Everyone , Today we are trying to understand CRDs(Custom Resource Definitions) as I was working on one Observability project in OpsTree Global and suddenly found CRD errors and let me tell you, It was very Frustration. I will try to make you understand them in easy way, so that you don\u2019t need to make &hellip; <a href=\"https:\/\/opstree.com\/blog\/2025\/09\/09\/complete-guide-to-kubernetes-crds\/\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;A Complete Guide to Kubernetes CRDs: Definition, Uses , Benefits, and Error Fixes&#8221;<\/span><\/a><\/p>\n","protected":false},"author":244582682,"featured_media":29669,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_coblocks_attr":"","_coblocks_dimensions":"","_coblocks_responsive_height":"","_coblocks_accordion_ie_support":"","jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false},"version":2}},"categories":[768739351],"tags":[475,768739309,768739380,343865],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"https:\/\/opstree.com\/blog\/wp-content\/uploads\/2025\/09\/Kubernetes-1.jpg","jetpack_likes_enabled":false,"jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/pfDBOm-7Iq","jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/posts\/29662"}],"collection":[{"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/users\/244582682"}],"replies":[{"embeddable":true,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/comments?post=29662"}],"version-history":[{"count":9,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/posts\/29662\/revisions"}],"predecessor-version":[{"id":29673,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/posts\/29662\/revisions\/29673"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/media\/29669"}],"wp:attachment":[{"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/media?parent=29662"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/categories?post=29662"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/opstree.com\/blog\/wp-json\/wp\/v2\/tags?post=29662"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}