Update the CRD migration docs for DatastoreMigration v1 - #2907
Merged
caseydavenport merged 5 commits intoAug 6, 2026
Conversation
Adds the CRD cleanup step and a warning against deleting the CRD while a CR exists.
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Calico and Calico Enterprise documentation to reflect the DatastoreMigration CRD promotion to migration.projectcalico.org/v1 (with v1beta1 deprecated) and to document safer cleanup/upgrade guidance around CR/CRD deletion ordering.
Changes:
- Switch
DatastoreMigrationexample CRs frommigration.projectcalico.org/v1beta1tomigration.projectcalico.org/v1. - Add explicit warnings and cleanup steps to ensure the
DatastoreMigrationCR is deleted before deleting the CRD. - Add a Calico v3.32 → v3.33 upgrade section covering the new CRD versioning behavior and safe handling.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| calico/operations/crd-migration.mdx | Updates migration procedure to v1, adds CRD deletion warning/cleanup, clarifies abort behavior, and adds v3.32→v3.33 upgrade guidance. |
| calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx | Updates the on-prem migration walkthrough to use v1 and adds a post-migration CRD cleanup step/warning. |
| calico-enterprise/operations/crd-migration.mdx | Mirrors the v1 migration doc updates and adds the CRD deletion warning/cleanup plus abort clarification for Enterprise docs. |
Suppressed comments (2)
calico/operations/crd-migration.mdx:163
- This sentence is slightly ambiguous: “up to
Converged” can be read as including theConvergedphase, but the next sentence says aborting isn’t available fromConvergedonward. Reword to remove ambiguity.
calico-enterprise/operations/crd-migration.mdx:162 - This sentence is ambiguous: “up to
Converged” can be interpreted as includingConverged, but the next sentence says aborting isn’t available fromConvergedonward. Reword to remove ambiguity.
The controller refuses to start a new migration on a cluster that only serves the pre-GA CRD.
MichalFupso
approved these changes
Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Product Version(s): Calico v3.33 (
calico/), Calico Enterprise next (calico-enterprise/)Issue: https://tigera.atlassian.net/browse/CORE-12573
Link to docs preview:
The
DatastoreMigrationCRD is promoted frommigration.projectcalico.org/v1beta1tov1in v3.33. The v3.33 CRD serves both versions, withv1beta1deprecated andv1as storage, so applying it over the v3.32 CRD is a plain update. Calico-side changes are in projectcalico/calico#13383 and projectcalico/calico#13449.This supersedes #2888, which documented the earlier plan of deleting the v1beta1 CRD before applying the new one. That turned out to be dangerous: deleting the CRD cascades to the
DatastoreMigrationCR and runs its finalizer, which either deletes everycrd.projectcalico.orgCRD (CR inComplete) or rolls the migration back (any other phase).Changes:
migration.projectcalico.org/v1.v1beta1without a storage version migration.DatastoreMigrationCRD must never be deleted while a CR still exists.Converged, and there is nothing to abort back to on a cluster that already migrated.The same changes are mirrored on the unversioned Enterprise page, minus the upgrade section, since I don't know which Enterprise release picks this up.
SME review:
DOCS review: