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.
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
| Field | Description | Accepted Values | Schema | Default |
|---|---|---|---|---|
| name | The name of this datastore migration. Calico ignores a datastore migration with any other name than v1-to-v3. Required. | v1-to-v3 | string |
Spec
| Field | Description | Accepted Values | Schema | Default |
|---|---|---|---|---|
| type | The migration to run. Required. | APIServerToCRDs | string |
DatastoreMigrationProgress
Calico leaves out a counter when its value is zero.
| Field | Description | Accepted Values | Schema | Default |
|---|---|---|---|---|
| totalTypes | The number of resource kinds to migrate. | integer | ||
| completedTypes | The number of resource kinds that are done. | integer | ||
| typeProgress | A summary of completedTypes and totalTypes, such as 5 / 21. | Up to 64 characters. | string | |
| currentType | The resource kind that is being migrated now. | Up to 253 characters. | string | |
| total | The number of resources processed so far, across all kinds. | integer | ||
| migrated | The number of resources copied to the v3 CRDs. | integer | ||
| skipped | The number of resources that were already in the v3 CRDs with the same content. | integer | ||
| conflicts | The number of resources that were already in the v3 CRDs with different content. | integer | ||
| typeDetails | The result for each resource kind. | Up to 128 items. | list of TypeMigrationProgress |
TypeMigrationProgress
| Field | Description | Accepted Values | Schema | Default |
|---|---|---|---|---|
| kind | The resource kind, such as NetworkPolicy. Required. | Up to 253 characters. | string | |
| migrated | The number of resources of this kind copied to the v3 CRDs. | integer | ||
| skipped | The number of resources of this kind that were already in the v3 CRDs with the same content. | integer | ||
| conflicts | The number of resources of this kind that were already in the v3 CRDs with different content. | integer |
Status
Calico kube-controllers writes the status.
| Field | Description | Accepted Values | Schema | Default |
|---|---|---|---|---|
| phase | The phase of the migration. See Phases. | Pending, Migrating, WaitingForConflictResolution, Converged, Complete, Failed | string | |
| message | What the migration is doing now, or what it is waiting for. | Up to 1024 characters. | string | |
| datastoreLockedAt | The time when the migration locked the datastore. | date-time string | ||
| startedAt | The time when the phase became Migrating. | date-time string | ||
| completedAt | The time when the phase became Complete. | date-time string | ||
| progress | Counters for the migration as a whole and for each resource kind. | DatastoreMigrationProgress | ||
| conditions | Conflicts 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.
| Phase | What happens |
|---|---|
| Not set | Calico 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. |
Migrating | Calico copies resources to the v3 CRDs, one kind at a time. progress shows the kind and the counts. |
Converged | All 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. |
Complete | The migration is finished. |
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.