Read back custom-resource fields before accepting a manifest

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.

Source fact: documented behavior

The Extend the Kubernetes API with CustomResourceDefinitions documentation is the primary reference.

The 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.

What the source does not establish

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.

Applicability questions

• Which served CRD version and structural schema apply?
• Is each required field actually declared at the intended path?
• Which subtree deliberately preserves unknown values?
• What stored-object and controller observations will establish the requested result?

DSE recommendation: review schema paths and stored values together

DSE 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.

Identify 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.

Use 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.

Read 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.

Verification and evidence

Proposed 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.

Use 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.

Official references

• Extend the Kubernetes API with CustomResourceDefinitions — Kubernetes.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.