Skip to main content
Calico Open Source 3.33 (latest) documentation

Datastore migration

A datastore migration resource (DatastoreMigration) represents one migration of Calico resources from crd.projectcalico.org/v1 CRDs to native projectcalico.org/v3 CRDs. You create the resource to start the migration, read its status to follow the migration, and delete it when the migration is complete. The only values you set are the name and spec.type. Calico sets every value in the status, and you only read them. DatastoreMigration is a cluster-scoped resource.

For the steps, see Migrate from API server to native CRDs.

This resource is in the migration.projectcalico.org API group, not in projectcalico.org. Its CRD is not part of a Calico installation. You install the CRD as a step in the migration. The current API version is migration.projectcalico.org/v1. The API still accepts migration.projectcalico.org/v1beta1, with a deprecation warning.

For kubectl commands, you can use the names datastoremigration, datastoremigrations, datastoremigration.migration.projectcalico.org, and datastoremigrations.migration.projectcalico.org. This resource is not supported in calicoctl.

Sample YAML​

This sample starts a migration from API server mode to native v3 CRDs.

apiVersion: migration.projectcalico.org/v1
kind: DatastoreMigration
metadata:
name: v1-to-v3
spec:
type: APIServerToCRDs

Definition​

Metadata​

FieldDescriptionAccepted ValuesSchemaDefault
nameThe name of this datastore migration. Calico ignores a datastore migration with any other name than v1-to-v3. Required.v1-to-v3string

Spec​

FieldDescriptionAccepted ValuesSchemaDefault
typeThe migration to run. Required.APIServerToCRDsstring

DatastoreMigrationProgress​

These fields are part of the status. You read them, and you don't set them. Calico leaves out a counter when its value is zero.

FieldDescriptionAccepted ValuesSchemaDefault
totalTypesThe number of resource kinds to migrate.integer
completedTypesThe number of resource kinds that are done.integer
typeProgressA summary of completedTypes and totalTypes, such as 5 / 21.Up to 64 characters.string
currentTypeThe resource kind that is being migrated now.Up to 253 characters.string
totalThe number of resources processed so far, across all kinds.integer
migratedThe number of resources copied to the v3 CRDs.integer
skippedThe number of resources that were already in the v3 CRDs with the same content.integer
conflictsThe number of resources that were already in the v3 CRDs with different content.integer
typeDetailsThe result for each resource kind.Up to 128 items.list of TypeMigrationProgress

TypeMigrationProgress​

These fields are part of the status. You read them, and you don't set them.

FieldDescriptionAccepted ValuesSchemaDefault
kindThe resource kind, such as NetworkPolicy. Required.Up to 253 characters.string
migratedThe number of resources of this kind copied to the v3 CRDs.integer
skippedThe number of resources of this kind that were already in the v3 CRDs with the same content.integer
conflictsThe number of resources of this kind that were already in the v3 CRDs with different content.integer

Status​

Calico kube-controllers writes the status. You read these fields, and you don't set them.

FieldDescriptionAccepted ValuesSchemaDefault
phaseThe phase of the migration. See Phases.Pending, Migrating, WaitingForConflictResolution, Converged, Complete, Failedstring
messageWhat the migration is doing now, or what it is waiting for.Up to 1024 characters.string
datastoreLockedAtThe time when the migration locked the datastore.date-time string
startedAtThe time when the phase became Migrating.date-time string
completedAtThe time when the phase became Complete.date-time string
progressCounters for the migration as a whole and for each resource kind.DatastoreMigrationProgress
conditionsConflicts and errors found during the migration. A migration with no conflicts or errors has no conditions.Up to 64 items.list of Condition

Phases​

A migration with no conflicts goes through these phases in order.

PhaseWhat happens
Not setCalico 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.
MigratingCalico copies resources to the v3 CRDs, one kind at a time. progress shows the kind and the counts.
ConvergedAll resources are copied. The migration waits for the Calico components to switch to the projectcalico.org/v3 API group. The message says what it is waiting for.
CompleteThe migration is finished.

Pending is an accepted value, but a migration with no conflicts doesn't show it. The phase is not set until it becomes Migrating.

For the WaitingForConflictResolution phase, see Resolve conflicts.

A migration that can't run has the phase Failed, and a condition of the type Failed with the reason MigrationError. For example, a datastore migration on a cluster that has no crd.projectcalico.org CRDs fails with the message no v1 CRDs (crd.projectcalico.org) found - nothing to migrate.

Deletion​

When you delete a datastore migration whose phase is Complete, Calico deletes all the crd.projectcalico.org CRDs and the data in them.

When you delete a datastore migration while the phase is not set, the migration stops and the crd.projectcalico.org CRDs stay. For deletion in other phases, see Abort a migration.

Additional resources​