Skip to content

DOCS-3101: Add the datastore migration resource reference - #3227

Open
ctauchen wants to merge 2 commits into
tigera:mainfrom
ctauchen:DOCS-3101-datastoremigration
Open

ctauchen wants to merge 2 commits into
tigera:mainfrom
ctauchen:DOCS-3101-datastoremigration

Conversation

@ctauchen

@ctauchen ctauchen commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Copilot AI lite review requested due to automatic review settings November 17, 2026 07:43
@netlify

netlify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for calico-docs-preview-next ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit ae3051d
🔍 Latest deploy log https://app.netlify.com/projects/calico-docs-preview-next/deploys/6afc99180149db91f5c80262
😎 Deploy Preview https://deploy-preview-3227--calico-docs-preview-next.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify

netlify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

❌ Deploy Preview for tigera failed. Why did it fail? →

Built without sensitive environment variables

Name Link
🔨 Latest commit ae3051d
🔍 Latest deploy log https://app.netlify.com/projects/tigera/deploys/6afc99184db4093e75793978

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The migration reference tables in all three affected files incorrectly replace the documented initial Pending phase with Not set, which could mislead readers about the normal migration sequence.

3 open issues
What changed in this PR

Adds a Calico Open Source DatastoreMigration resource reference for the next, 3.33, and 3.32 documentation trees, and links migration procedures to the new reference.

Changes:

  • Adds field, status, phase, deletion, and example YAML documentation for DatastoreMigration.
  • Registers the new reference in resource overviews and Calico sidebars.
  • Links migration instructions in the CRD migration and on-premises installation guides to the reference.
File Description
sidebars-calico.js Adds the DatastoreMigration resource reference to the next-version sidebar.
calico/​reference/​resources/​overview.mdx Lists DatastoreMigration in the next-version resource overview.
calico/​reference/​resources/​datastoremigration.mdx Adds the next-version DatastoreMigration resource reference and documentation.
calico/​operations/​crd-migration.mdx Links migration status instructions to the new resource reference.
calico/​getting-started/​kubernetes/​self-managed-onprem/​onpremises.mdx Links the migration setup instructions to the new resource reference.
calico_versioned_sidebars/​version-3.33-sidebars.json Adds the resource reference to the 3.33 sidebar.
calico_versioned_sidebars/​version-3.32-sidebars.json Adds the resource reference to the 3.32 sidebar.
calico_versioned_docs/​version-3.33/​reference/​resources/​overview.mdx Lists DatastoreMigration in the 3.33 resource overview.
calico_versioned_docs/​version-3.33/​reference/​resources/​datastoremigration.mdx Adds the 3.33 DatastoreMigration resource reference and documentation.
calico_versioned_docs/​version-3.33/​operations/​crd-migration.mdx Links 3.33 migration status instructions to the resource reference.
calico_versioned_docs/​version-3.33/​getting-started/​kubernetes/​self-managed-onprem/​onpremises.mdx Links the 3.33 migration setup instructions to the resource reference.
calico_versioned_docs/​version-3.32/​reference/​resources/​overview.mdx Lists DatastoreMigration in the 3.32 resource overview.
calico_versioned_docs/​version-3.32/​reference/​resources/​datastoremigration.mdx Adds the 3.32 DatastoreMigration resource reference and documentation.
calico_versioned_docs/​version-3.32/​operations/​crd-migration.mdx Links 3.32 migration status instructions to the resource reference.
calico_versioned_docs/​version-3.32/​getting-started/​kubernetes/​self-managed-onprem/​onpremises.mdx Links the 3.32 migration setup instructions to the resource reference.

Review effort: Lite


| Phase | What happens |
| ----- | ------------ |
| Not set | $[prodname] adds the finalizer `migration.projectcalico.org/v1-crd-cleanup` to the resource and locks the datastore. The message is `Waiting for in-flight datastore writes to drain`. |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm keeping "Not set" here.
On kind clusters at v3.33.1 and v3.32.4, a migration with no conflicts never shows Pending.
The phase is empty while the controller adds the finalizer and locks the datastore.
Then it goes to Migrating, Converged, and Complete.
A watch showed the same on every run.

In ae3051d I added a sentence that says Pending is an accepted value, but a migration with no conflicts doesn't show it.
The procedure pages still say Pending comes first. That needs a separate fix.

PTAL @caseydavenport, and thanks!


| Phase | What happens |
| ----- | ------------ |
| Not set | $[prodname] adds the finalizer `migration.projectcalico.org/v1-crd-cleanup` to the resource and locks the datastore. The message is `Waiting for in-flight datastore writes to drain`. |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm keeping "Not set" here.
On kind clusters at v3.33.1 and v3.32.4, a migration with no conflicts never shows Pending.
The phase is empty while the controller adds the finalizer and locks the datastore.
Then it goes to Migrating, Converged, and Complete.
A watch showed the same on every run.

In ae3051d I added a sentence that says Pending is an accepted value, but a migration with no conflicts doesn't show it.
The procedure pages still say Pending comes first. That needs a separate fix.

PTAL @caseydavenport, and thanks!


| Phase | What happens |
| ----- | ------------ |
| Not set | $[prodname] adds the finalizer `migration.projectcalico.org/v1-crd-cleanup` to the resource and locks the datastore. The message is `Waiting for in-flight datastore writes to drain`. |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm keeping "Not set" here.
On kind clusters at v3.33.1 and v3.32.4, a migration with no conflicts never shows Pending.
The phase is empty while the controller adds the finalizer and locks the datastore.
Then it goes to Migrating, Converged, and Complete.
A watch showed the same on every run.

In ae3051d I added a sentence that says Pending is an accepted value, but a migration with no conflicts doesn't show it.
The procedure pages still say Pending comes first. That needs a separate fix.

PTAL @caseydavenport, and thanks!

@ctauchen ctauchen left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Find ways to make it clearer that you don't set the values in this resource.

@ctauchen
ctauchen marked this pull request as ready for review November 17, 2026 14:44
@ctauchen
ctauchen requested a review from a team as a code owner November 17, 2026 14:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants