Migrate from API server to native CRDs

Big picture

Automatically migrate Calico resources from the aggregated API server's crd.projectcalico.org/v1 backing storage to native projectcalico.org/v3 CRDs, allowing you to remove the API server component.

Value

Newer Calico installations use native projectcalico.org/v3 CRDs directly, without the aggregated API server. This is simpler to operate, removes a component, and enables Kubernetes-native features like CEL validation rules. The DatastoreMigration controller provides an automated, in-place migration path for existing clusters that are still running the API server.

Concepts

How it works

The migration controller copies all Calico resources from the v1 CRDs (used as backing storage by the API server) to native v3 CRDs. During the migration window, the datastore is briefly locked (DatastoreReady=false) so components pause and retain their cached data plane state — existing workload connectivity is preserved throughout.

The migration proceeds through these phases:

Phase	Description
Pending	CR created, prerequisites are being validated
Migrating	Datastore locked, resources being copied from v1 to v3 CRDs
WaitingForConflictResolution	Conflicts found — user action needed (see resolving conflicts)
Converged	All resources migrated, datastore unlocked, waiting for components to switch to v3
Complete	All components running against v3 CRDs
Failed	Migration hit an unrecoverable error; delete the CR to roll back, then retry

What gets migrated

All Calico resource types are migrated: network policies, IP pools, BGP configuration, Felix configuration, IPAM blocks, and more. IPAM resources are migrated last to minimize the window where new IP allocations are blocked.

The controller handles policy name migration (removing the legacy default. prefix) automatically during the copy.

What happens during the migration window

• Components (Felix, Typha, kube-controllers) pause and retain cached data plane state
• Existing workload connectivity is preserved — no packet loss expected
• New pod scheduling and policy changes are blocked until migration completes
• IPAM allocations are blocked during the final phase of the migration

The locked window is typically short (seconds to a few minutes depending on cluster size), but you should plan for a maintenance window where no policy changes or new pod deployments are needed.

Before you begin

• Calico v3.32+ (or the release that includes the migration controller)
• Cluster is currently running in API server mode (the aggregated API server is deployed)
• Kubernetes 1.32 or later. Calico uses the MutatingAdmissionPolicy API for defaulting. On clusters where it is not enabled by default, enable the MutatingAdmissionPolicy feature gate on the API server.
• If using GitOps (ArgoCD, Flux): pause sync before starting the migration. These tools may interfere with the API group switchover. You'll update your manifests to use projectcalico.org/v3 after migration completes.

warning

Never delete the DatastoreMigration CRD while a DatastoreMigration CR still exists.

Deleting a CRD deletes every custom resource of that type, which runs the finalizer on the CR. If the CR is in Complete, that deletes all of your crd.projectcalico.org CRDs and the data stored in them. In any other phase, it rolls the migration back. Always delete the CR first, confirm that it is gone, and only then delete the CRD.

How to

Migrate to native CRDs

1. Install v3 CRDs.

   Apply the v3 CRD manifests from the Calico release. While the aggregated API service is active, Kubernetes ignores these CRDs, so this is safe to do ahead of time.

   If your cluster is based on Kubernetes 1.36 or later:

   kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org.yaml

   If your cluster is based on Kubernetes 1.34 or 1.35:

   kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org-v1beta1.yaml

2. Install the DatastoreMigration CRD.

   kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/migration.projectcalico.org_datastoremigrations.yaml

3. Create the DatastoreMigration CR.

   kubectl apply -f - <<EOF
   apiVersion: migration.projectcalico.org/v1
   kind: DatastoreMigration
   metadata:
     name: v1-to-v3
   spec:
     type: APIServerToCRDs
   EOF

4. Monitor progress.

   kubectl get datastoremigration v1-to-v3 -w

   You'll see phase transitions: Pending → Migrating → Converged → Complete.

   For more detail on per-resource-type progress:

   kubectl get datastoremigration v1-to-v3 -o yaml

5. Wait for completion.

   Operator-managed installs: The operator automatically detects when migration reaches Converged and switches all components to v3 CRD mode. It sets CALICO_API_GROUP=projectcalico.org/v3 on all components and triggers rolling updates. No manual action needed — just wait for the phase to reach Complete.

   Manifest-based installs: When the migration reaches Converged, you need to manually set CALICO_API_GROUP=projectcalico.org/v3 on all Calico components (calico-node, typha, kube-controllers) and trigger rolling updates. Update your helm values or manifests to disable the API server.

6. Clean up v1 CRDs.

   Once you're confident everything is working on the new CRDs, delete the DatastoreMigration CR. The finalizer on the CR deletes all crd.projectcalico.org CRDs and their stored data.

   kubectl delete datastoremigration v1-to-v3

7. Delete the DatastoreMigration CRD.

   Only after the CR from the previous step is gone. The CRD is not part of a Calico install and has no reason to outlive the migration. Removing it also means a future release can drop the deprecated v1beta1 version without you having to run a storage version migration.

   kubectl get datastoremigration
   kubectl delete crd datastoremigrations.migration.projectcalico.org

8. Resume GitOps sync (if applicable). Update your manifests to use projectcalico.org/v3 API versions and resume sync.

Resolve conflicts

If the migration encounters a v3 resource that already exists with a different spec than the v1 source, it reports a conflict. The phase changes to WaitingForConflictResolution and the migration pauses.

To see which resources have conflicts:

kubectl get datastoremigration v1-to-v3 -o jsonpath='{.status.conditions}' | jq .

Each conflict condition includes the resource name and a description of the mismatch. To resolve:

• Delete the conflicting v3 resource if it was created accidentally or is stale. The migration will recreate it from the v1 source on the next reconcile.
• Update the v3 resource to match the v1 source if you want to keep the v3 version.

After resolving all conflicts, the migration controller automatically resumes on its next reconcile cycle.

Abort a migration

If something goes wrong, delete the DatastoreMigration CR before the migration reaches Converged:

kubectl delete datastoremigration v1-to-v3

The finalizer handles rollback:

• Cleans up any partial v3 resources that were created during migration
• Restores the aggregated APIService so components go back to reading v1 CRDs
• Components resume normal operation as if the migration never happened

The v1 data is never modified during migration, so it remains authoritative after an abort.

Aborting is only possible up to Converged. From Converged onwards the resources are already in the v3 CRDs and the components are switching over to them, so let the migration run through to Complete.

On a cluster that has already completed a migration there is nothing to abort back to, and once the v1 CRDs are deleted the v1 data is gone. Do not create a second DatastoreMigration CR on such a cluster.

Upgrade from v3.32 to v3.33

In v3.33, the DatastoreMigration CRD moves from migration.projectcalico.org/v1beta1 to v1. The CRD serves both versions, with v1beta1 deprecated, so applying the v3.33 CRD over the v3.32 one is a plain update. Do not delete the old CRD to make room for it.

From v3.33 a migration is only driven at migration.projectcalico.org/v1. A migration that was already in flight when you upgraded still runs through to completion, but a cluster that serves only the pre-GA v1beta1 CRD refuses to start a new one and reports that the v1 CRD needs applying.

The migration CRD is not part of a Calico install, so for most clusters there is nothing to do here. If you did install it on v3.32, what to do depends on the state of the DatastoreMigration CR:

State on v3.32	Before you upgrade
Migration CRD never installed	Nothing. Upgrade normally.
CRD installed, no CR left	Nothing required. Deleting the CRD is optional tidy-up, and only once you have confirmed that no CR exists.
CR in Complete, still present	Run the cleanup steps from Migrate to native CRDs: delete the CR, then the CRD. Then upgrade.
CR in Pending, Migrating, or WaitingForConflictResolution	Do not upgrade. Finish or abort the migration first.
CR in Converged	Do not upgrade. Wait for Complete; abort is not available from this phase.
CR in Failed	Delete the CR to roll back, confirm that the cluster is healthy on v1, then upgrade.
Migration finished and the v1 CRDs already deleted	Nothing to do, and never create another DatastoreMigration CR on this cluster.

Known limitations

OwnerReferences from non-Calico resources. The migration remaps OwnerReference UIDs on Calico resources, but does not scan non-Calico resources (ConfigMaps, Secrets, custom resources from other projects) for OwnerReferences pointing to Calico objects. If you have non-Calico resources with OwnerReferences to Calico resources, those references will become stale after migration because the Calico resource UIDs change. You'll need to update those references manually after migration completes. This is expected to be rare.