Bottom line: Compare the stored custom resource with the intended configuration before declaring a manifest accepted. Make a missing or misspelled field a schema investigation instead of assuming that every submitted value reached the controller.
\nThe Extend the Kubernetes API with CustomResourceDefinitions documentation is the primary reference.
\nThe CRD guide says an API-server-unrecognized field is pruned before persistence under the documented schema behavior. Its example disables client validation to demonstrate server pruning; the published schema also lets kubectl reject unknown fields before sending the object. A structural schema can preserve an unknown-field subtree with x-kubernetes-preserve-unknown-fields: true, while pruning resumes for specified properties within that subtree.
This article concerns the documented structural-schema and pruning path. It does not approve preserving arbitrary data everywhere, migrate a legacy CRD or establish that the controller acted on a stored value. Keep schema compatibility and actual application reconciliation as separate acceptance questions.
\nDSE recommends a field map for the custom resource under review. Put each operationally required value beside its exact schema path and expected type. Have the API owner review spelling and nesting before treating a controller’s unexplained default behavior as an application defect.
\nIdentify any intentionally free-form subtree separately. Record why its flexibility is needed and which nested properties remain explicitly modeled. Do not turn off pruning broadly merely to make an unfamiliar field appear in a stored object. Keep the schema’s intended contract clear for other clients and controllers.
\nUse ordinary validation in the operational workflow. Keep the source’s validation-disabled demonstration confined to a disposable test case approved to examine server behavior. A rejected client request and an accepted object with a missing field need different explanations in the evidence record.
\nRead the object back through the approved API path and compare required values with the submitted manifest. Preserve the served schema and resource version used for that comparison. If a required field disappears, resolve the schema or manifest mismatch before widening the deployment. Review the controller’s subsequent behavior independently rather than equating persistence with successful application configuration.
\nProposed verification, not performed: create a disposable CRD and harmless objects patterned on the documentation. Include one declared field, one deliberately misspelled field and an explicitly preserved test subtree. Predict the client-validation and server-persistence results before exercising each approved case.
\nUse a separate fixture to examine a declared property inside the preserved subtree and compare its unknown sibling handling. Retain the schema, client options, submitted object, response and stored object for every case. Keep any validation bypass visibly labeled as a laboratory input. Do not apply the fixture to valuable custom resources or infer controller success from the stored representation alone.
\nSource review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.
\n", "content_text": "Bottom line: Compare the stored custom resource with the intended configuration before declaring a manifest accepted. Make a missing or misspelled field a schema investigation instead of assuming that every submitted value reached the controller.\nSource fact: documented behavior\nThe Extend the Kubernetes API with CustomResourceDefinitions documentation is the primary reference.\nThe CRD guide says an API-server-unrecognized field is pruned before persistence under the documented schema behavior. Its example disables client validation to demonstrate server pruning; the published schema also lets kubectl reject unknown fields before sending the object. A structural schema can preserve an unknown-field subtree with x-kubernetes-preserve-unknown-fields: true, while pruning resumes for specified properties within that subtree.\nWhat the source does not establish\nThis article concerns the documented structural-schema and pruning path. It does not approve preserving arbitrary data everywhere, migrate a legacy CRD or establish that the controller acted on a stored value. Keep schema compatibility and actual application reconciliation as separate acceptance questions.\nApplicability questions\n\nWhich served CRD version and structural schema apply?\nIs each required field actually declared at the intended path?\nWhich subtree deliberately preserves unknown values?\nWhat stored-object and controller observations will establish the requested result?\n\nDSE recommendation: review schema paths and stored values together\nDSE recommends a field map for the custom resource under review. Put each operationally required value beside its exact schema path and expected type. Have the API owner review spelling and nesting before treating a controller’s unexplained default behavior as an application defect.\nIdentify any intentionally free-form subtree separately. Record why its flexibility is needed and which nested properties remain explicitly modeled. Do not turn off pruning broadly merely to make an unfamiliar field appear in a stored object. Keep the schema’s intended contract clear for other clients and controllers.\nUse ordinary validation in the operational workflow. Keep the source’s validation-disabled demonstration confined to a disposable test case approved to examine server behavior. A rejected client request and an accepted object with a missing field need different explanations in the evidence record.\nRead the object back through the approved API path and compare required values with the submitted manifest. Preserve the served schema and resource version used for that comparison. If a required field disappears, resolve the schema or manifest mismatch before widening the deployment. Review the controller’s subsequent behavior independently rather than equating persistence with successful application configuration.\nVerification and evidence\nProposed verification, not performed: create a disposable CRD and harmless objects patterned on the documentation. Include one declared field, one deliberately misspelled field and an explicitly preserved test subtree. Predict the client-validation and server-persistence results before exercising each approved case.\nUse a separate fixture to examine a declared property inside the preserved subtree and compare its unknown sibling handling. Retain the schema, client options, submitted object, response and stored object for every case. Keep any validation bypass visibly labeled as a laboratory input. Do not apply the fixture to valuable custom resources or infer controller success from the stored representation alone.\nOfficial references\n\nExtend the Kubernetes API with CustomResourceDefinitions — Kubernetes.\n\nSource review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.", "content_markdown": "Bottom line: Compare the stored custom resource with the intended configuration before declaring a manifest accepted. Make a missing or misspelled field a schema investigation instead of assuming that every submitted value reached the controller.\n\n## Source fact: documented behavior\n\nThe [Extend the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) documentation is the primary reference.\n\nThe CRD guide says an API-server-unrecognized field is pruned before persistence under the documented schema behavior. Its example disables client validation to demonstrate server pruning; the published schema also lets kubectl reject unknown fields before sending the object. A structural schema can preserve an unknown-field subtree with x-kubernetes-preserve-unknown-fields: true, while pruning resumes for specified properties within that subtree.\n\n## What the source does not establish\n\nThis article concerns the documented structural-schema and pruning path. It does not approve preserving arbitrary data everywhere, migrate a legacy CRD or establish that the controller acted on a stored value. Keep schema compatibility and actual application reconciliation as separate acceptance questions.\n\n## Applicability questions\n\n- Which served CRD version and structural schema apply?\n\n- Is each required field actually declared at the intended path?\n\n- Which subtree deliberately preserves unknown values?\n\n- What stored-object and controller observations will establish the requested result?\n\n## DSE recommendation: review schema paths and stored values together\n\nDSE recommends a field map for the custom resource under review. Put each operationally required value beside its exact schema path and expected type. Have the API owner review spelling and nesting before treating a controller’s unexplained default behavior as an application defect.\n\nIdentify any intentionally free-form subtree separately. Record why its flexibility is needed and which nested properties remain explicitly modeled. Do not turn off pruning broadly merely to make an unfamiliar field appear in a stored object. Keep the schema’s intended contract clear for other clients and controllers.\n\nUse ordinary validation in the operational workflow. Keep the source’s validation-disabled demonstration confined to a disposable test case approved to examine server behavior. A rejected client request and an accepted object with a missing field need different explanations in the evidence record.\n\nRead the object back through the approved API path and compare required values with the submitted manifest. Preserve the served schema and resource version used for that comparison. If a required field disappears, resolve the schema or manifest mismatch before widening the deployment. Review the controller’s subsequent behavior independently rather than equating persistence with successful application configuration.\n\n## Verification and evidence\n\nProposed verification, not performed: create a disposable CRD and harmless objects patterned on the documentation. Include one declared field, one deliberately misspelled field and an explicitly preserved test subtree. Predict the client-validation and server-persistence results before exercising each approved case.\n\nUse a separate fixture to examine a declared property inside the preserved subtree and compare its unknown sibling handling. Retain the schema, client options, submitted object, response and stored object for every case. Keep any validation bypass visibly labeled as a laboratory input. Do not apply the fixture to valuable custom resources or infer controller success from the stored representation alone.\n\n## Official references\n\n- [Extend the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) — Kubernetes.\n\nSource review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change." }, "json_ld": { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://dsesecurity.com/#organization", "name": "Detection Systems & Engineering", "alternateName": "DSE Security", "url": "https://dsesecurity.com/", "logo": { "@type": "ImageObject", "url": "https://update.dsesecurity.com/assets/dse-logo-20260812.png?v=1.8.20" } }, { "@type": "Organization", "@id": "https://update.dsesecurity.com/#editorial-team", "name": "DSE Security Editorial Team", "url": "https://update.dsesecurity.com/", "parentOrganization": { "@id": "https://dsesecurity.com/#organization" } }, { "@type": "WebSite", "@id": "https://update.dsesecurity.com/#website", "name": "DSE Updates", "alternateName": "DSE Security Knowledge Hub", "url": "https://update.dsesecurity.com/", "inLanguage": "en-US", "publisher": { "@id": "https://dsesecurity.com/#organization" }, "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://update.dsesecurity.com/?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@type": "WebPage", "@id": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/", "url": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/", "isPartOf": { "@id": "https://update.dsesecurity.com/#website" }, "lastReviewed": "2026-10-29" }, { "@type": "BreadcrumbList", "@id": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/#breadcrumbs", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "DSE Updates", "item": "https://update.dsesecurity.com/" }, { "@type": "ListItem", "position": 2, "name": "IT", "item": "https://update.dsesecurity.com/topic/it/" }, { "@type": "ListItem", "position": 3, "name": "Read back custom-resource fields before accepting a manifest", "item": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/" } ] }, { "@type": [ "Article", "TechArticle" ], "@id": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/#article", "identifier": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/", "url": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/", "headline": "Read back custom-resource fields before accepting a manifest", "description": "An unknown custom-resource field can be removed before persistence, while client validation may reject it earlier.", "abstract": "An unknown custom-resource field can be removed before persistence, while client validation may reject it earlier. Review the structural schema and explicit preserved subtrees before trusting submitted data.", "articleBody": "Bottom line: Compare the stored custom resource with the intended configuration before declaring a manifest accepted. Make a missing or misspelled field a schema investigation instead of assuming that every submitted value reached the controller.\nSource fact: documented behavior\nThe Extend the Kubernetes API with CustomResourceDefinitions documentation is the primary reference.\nThe CRD guide says an API-server-unrecognized field is pruned before persistence under the documented schema behavior. Its example disables client validation to demonstrate server pruning; the published schema also lets kubectl reject unknown fields before sending the object. A structural schema can preserve an unknown-field subtree with x-kubernetes-preserve-unknown-fields: true, while pruning resumes for specified properties within that subtree.\nWhat the source does not establish\nThis article concerns the documented structural-schema and pruning path. It does not approve preserving arbitrary data everywhere, migrate a legacy CRD or establish that the controller acted on a stored value. Keep schema compatibility and actual application reconciliation as separate acceptance questions.\nApplicability questions\n\nWhich served CRD version and structural schema apply?\nIs each required field actually declared at the intended path?\nWhich subtree deliberately preserves unknown values?\nWhat stored-object and controller observations will establish the requested result?\n\nDSE recommendation: review schema paths and stored values together\nDSE recommends a field map for the custom resource under review. Put each operationally required value beside its exact schema path and expected type. Have the API owner review spelling and nesting before treating a controller’s unexplained default behavior as an application defect.\nIdentify any intentionally free-form subtree separately. Record why its flexibility is needed and which nested properties remain explicitly modeled. Do not turn off pruning broadly merely to make an unfamiliar field appear in a stored object. Keep the schema’s intended contract clear for other clients and controllers.\nUse ordinary validation in the operational workflow. Keep the source’s validation-disabled demonstration confined to a disposable test case approved to examine server behavior. A rejected client request and an accepted object with a missing field need different explanations in the evidence record.\nRead the object back through the approved API path and compare required values with the submitted manifest. Preserve the served schema and resource version used for that comparison. If a required field disappears, resolve the schema or manifest mismatch before widening the deployment. Review the controller’s subsequent behavior independently rather than equating persistence with successful application configuration.\nVerification and evidence\nProposed verification, not performed: create a disposable CRD and harmless objects patterned on the documentation. Include one declared field, one deliberately misspelled field and an explicitly preserved test subtree. Predict the client-validation and server-persistence results before exercising each approved case.\nUse a separate fixture to examine a declared property inside the preserved subtree and compare its unknown sibling handling. Retain the schema, client options, submitted object, response and stored object for every case. Keep any validation bypass visibly labeled as a laboratory input. Do not apply the fixture to valuable custom resources or infer controller success from the stored representation alone.\nOfficial references\n\nExtend the Kubernetes API with CustomResourceDefinitions — Kubernetes.\n\nSource review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.", "datePublished": "2026-10-29T19:49:24+00:00", "dateModified": "2026-10-29T19:50:09+00:00", "mainEntityOfPage": { "@id": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/" }, "inLanguage": "en-US", "isAccessibleForFree": true, "author": { "@type": "Organization", "name": "DSE Security Editorial Team", "url": "https://update.dsesecurity.com/#editorial-team" }, "publisher": { "@id": "https://dsesecurity.com/#organization" }, "image": { "@type": "ImageObject", "@id": "https://update.dsesecurity.com/updates/read-back-custom-resource-fields-before-accepting-a-manifest/#primaryimage", "url": "https://update.dsesecurity.com/assets/editorial/managed-it-social-v2.jpg?v=1.8.20", "contentUrl": "https://update.dsesecurity.com/assets/editorial/managed-it-social-v2.jpg?v=1.8.20", "width": 1200, "height": 630, "caption": "Read back custom-resource fields before accepting a manifest" }, "articleSection": [ "IT" ], "keywords": [ "IT", "Guide", "Advisory priority" ], "genre": "Guide", "about": [ { "@type": "Thing", "name": "IT", "url": "https://update.dsesecurity.com/topic/it/" } ], "wordCount": 519, "timeRequired": "PT3M", "publishingPrinciples": "https://update.dsesecurity.com/updates/dse-updates-editorial-methodology/", "usageInfo": "https://update.dsesecurity.com/usage/", "copyrightHolder": { "@id": "https://dsesecurity.com/#organization" }, "copyrightNotice": "Copyright © 2026 Detection Systems & Engineering. All rights reserved.", "citation": { "@type": "CreativeWork", "name": "Kubernetes — Extend the Kubernetes API with CustomResourceDefinitions", "url": "https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/" } } ] } }