Prove CRD storage migration before removing an old version

Bottom line: A response labeled with the new API version should not close a storage migration. Keep served representations, durable rewrites and removal of the old version as separate acceptance steps with an explicit recovery owner.

Source fact: documented behavior

The Versions in CustomResourceDefinitions documentation is the primary reference.

Changing the CRD storage version does not automatically convert existing stored objects; new or updated objects use the storage version current at their write. Reading an object through a different served version returns that representation without changing the stored object on disk. The documented manual upgrade rewrites all existing objects before removing the old entry from status.storedVersions; old-version removal requires migration of the stored data.

What the source does not establish

This article concerns durable migration acceptance for the manual workflow. It does not approve deleting objects, bypassing conversion, or merely editing status to make the evidence look complete. Automated migration-controller adoption, its release-specific maturity, encryption-at-rest changes and legacy CRD API migration need separate review. Obtain a suitable backup and recovery procedure before rewriting valuable resources.

Applicability questions

• Which version is served and which one is the current storage version?
• Which existing objects must the rewrite cover?
• How will conversion and application meaning be checked?
• What evidence must exist before old-version cleanup is authorized?

DSE recommendation: reconcile every object before cleanup

DSE recommends requiring a complete object-rewrite record before accepting old CRD storage-version cleanup.

Have the API owner inventory the relevant resource population and identify the supported conversion arrangement. Record the current and proposed served versions, storage designation and stored-version status. Keep the intended client migration alongside that record, without treating client adoption of a new endpoint as evidence that older stored objects were rewritten.

Prepare the supported manual rewrite procedure with a complete enumeration strategy, operation outcomes and an explicit treatment of concurrent activity. Obtain the required recovery reference and test the procedure on harmless objects first. Preserve each object’s identity and intended content so migration acceptance can assess meaning as well as a successful request.

Execute only the approved migration in its controlled window. Reconcile successes, failures and any population changes before requesting status cleanup. Investigate an omitted or failed object rather than excluding it from the completion count. Have the resource owner’s normal consumer verify representative converted content independently of the rewrite operation.

Authorize removal of old-version status and serving support only after the relevant prerequisites have been accepted. Keep the cleanup change separate in the record so a future reviewer can see what evidence existed before that decision.

Verification and evidence

Proposed verification, not performed: use a disposable CRD with two reviewed representations and harmless objects created before and after changing its storage designation. Compare served reads with the intended stored-version history without assuming those reads rewrite older objects.

Run the approved manual rewrite against the complete fixture population, retain every operation outcome and reconcile the population again. Include a deliberately withheld fixture in a desk review and require the reviewer to reject premature cleanup. Record the final accepted migration evidence and any separate cleanup operation. Do not apply the exercise to valuable production objects or claim that a cleared status list alone proves a complete migration.

Official references

• Versions in CustomResourceDefinitions — Kubernetes.

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