---
title: "Datastore migration"
description: "Reference for the DatastoreMigration resource in Calico Open Source that starts a migration from API server mode to native v3 CRDs and reports its progress."
product: "Calico Open Source"
version: "3.33 (latest)"
section: "Reference"
canonical_url: "https://docs.tigera.io/calico/latest/reference/resources/datastoremigration"
---

# 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](https://docs.tigera.io/calico/latest/operations/crd-migration.md).

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.

```yaml
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

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.

| 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) |         |

### TypeMigrationProgress

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

| 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. You read these fields, and you don't set them.

| Field             | Description                                                                                                 | Accepted Values                                                                           | Schema                                                                                                      | Default |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
| phase             | The phase of the migration. See [Phases](#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](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#condition-v1-meta) |         |

## 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.                                                                                                                                                        |

`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](https://docs.tigera.io/calico/latest/operations/crd-migration.md#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](https://docs.tigera.io/calico/latest/operations/crd-migration.md#abort-a-migration).

## Additional resources

- [Migrate from API server to native CRDs](https://docs.tigera.io/calico/latest/operations/crd-migration.md)
- [Native v3 CRDs](https://docs.tigera.io/calico/latest/operations/native-v3-crds.md)
