From 5aa5d078cc964b77c46eb4d5429cd801d8bdccea Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Wed, 29 Jul 2026 07:24:06 -0700 Subject: [PATCH 1/3] Update CRD migration docs for DatastoreMigration v1 Bumps the example apiVersion and adds a note that an existing v1beta1 CRD has to be deleted first, since Kubernetes rejects dropping a version that's still in storedVersions. --- calico-enterprise/operations/crd-migration.mdx | 18 +++++++++++++++++- calico/operations/crd-migration.mdx | 18 +++++++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/calico-enterprise/operations/crd-migration.mdx b/calico-enterprise/operations/crd-migration.mdx index da05c9203f..a87967ade8 100644 --- a/calico-enterprise/operations/crd-migration.mdx +++ b/calico-enterprise/operations/crd-migration.mdx @@ -67,11 +67,27 @@ The locked window is typically short (seconds to a few minutes depending on clus kubectl apply -f $[manifestsUrl]/manifests/migration.projectcalico.org_datastoremigrations.yaml ``` + :::note + + If you installed the DatastoreMigration CRD on an earlier release, delete it before + applying this one: + + ```bash + kubectl delete crd datastoremigrations.migration.projectcalico.org + ``` + + The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a + version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails + with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration + resource, so only do this if no migration is in progress. + + ::: + 3. **Create the DatastoreMigration CR.** ```bash kubectl apply -f - < Date: Wed, 29 Jul 2026 07:28:56 -0700 Subject: [PATCH 2/3] Fix manifest-based migration steps in onpremises.mdx Same v1 bump and delete-old-CRD note as crd-migration.mdx, plus the DatastoreMigration CRD path needs to point at manifests/ instead of the in-tree kube-controllers path, which is going away. --- .../self-managed-onprem/onpremises.mdx | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx index a461e1605f..e9659b8e7a 100644 --- a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx +++ b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx @@ -241,14 +241,30 @@ If you have an existing manifest-based $[prodname] install using the legacy `crd 1. Install the DatastoreMigration CRD. ```bash - kubectl apply --server-side -f $[manifestsUrl]/kube-controllers/pkg/controllers/migration/crd/migration.projectcalico.org_datastoremigrations.yaml + kubectl apply --server-side -f $[manifestsUrl]/manifests/migration.projectcalico.org_datastoremigrations.yaml ``` + :::note + + If you installed the DatastoreMigration CRD on an earlier release, delete it before + applying this one: + + ```bash + kubectl delete crd datastoremigrations.migration.projectcalico.org + ``` + + The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a + version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails + with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration + resource, so only do this if no migration is in progress. + + ::: + 1. Create a DatastoreMigration resource to start the migration. The migration controller copies all Calico resources from v1 CRDs to v3 CRDs. ```bash kubectl apply -f - < Date: Wed, 29 Jul 2026 07:32:21 -0700 Subject: [PATCH 3/3] Unwrap the migration CRD note to match the rest of the docs --- calico-enterprise/operations/crd-migration.mdx | 8 ++------ .../kubernetes/self-managed-onprem/onpremises.mdx | 8 ++------ calico/operations/crd-migration.mdx | 8 ++------ 3 files changed, 6 insertions(+), 18 deletions(-) diff --git a/calico-enterprise/operations/crd-migration.mdx b/calico-enterprise/operations/crd-migration.mdx index a87967ade8..e6ceafe9f7 100644 --- a/calico-enterprise/operations/crd-migration.mdx +++ b/calico-enterprise/operations/crd-migration.mdx @@ -69,17 +69,13 @@ The locked window is typically short (seconds to a few minutes depending on clus :::note - If you installed the DatastoreMigration CRD on an earlier release, delete it before - applying this one: + If you installed the DatastoreMigration CRD on an earlier release, delete it before applying this one: ```bash kubectl delete crd datastoremigrations.migration.projectcalico.org ``` - The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a - version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails - with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration - resource, so only do this if no migration is in progress. + The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration resource, so only do this if no migration is in progress. ::: diff --git a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx index e9659b8e7a..d730796285 100644 --- a/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx +++ b/calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx @@ -246,17 +246,13 @@ If you have an existing manifest-based $[prodname] install using the legacy `crd :::note - If you installed the DatastoreMigration CRD on an earlier release, delete it before - applying this one: + If you installed the DatastoreMigration CRD on an earlier release, delete it before applying this one: ```bash kubectl delete crd datastoremigrations.migration.projectcalico.org ``` - The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a - version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails - with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration - resource, so only do this if no migration is in progress. + The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration resource, so only do this if no migration is in progress. ::: diff --git a/calico/operations/crd-migration.mdx b/calico/operations/crd-migration.mdx index 0fda569e77..411eb206ad 100644 --- a/calico/operations/crd-migration.mdx +++ b/calico/operations/crd-migration.mdx @@ -70,17 +70,13 @@ The locked window is typically short (seconds to a few minutes depending on clus :::note - If you installed the DatastoreMigration CRD on an earlier release, delete it before - applying this one: + If you installed the DatastoreMigration CRD on an earlier release, delete it before applying this one: ```bash kubectl delete crd datastoremigrations.migration.projectcalico.org ``` - The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a - version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails - with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration - resource, so only do this if no migration is in progress. + The CRD moved from `v1beta1` to `v1`. Kubernetes rejects an update that drops a version still listed in the CRD's `status.storedVersions`, so `kubectl apply` fails with a confusing error otherwise. Deleting the CRD also deletes any DatastoreMigration resource, so only do this if no migration is in progress. :::