Per-deployment migration reference

This page is the reference companion to Configure per-deployment migration and Manage and observe per-deployment migration. It documents the configuration settings, cluster failover states, mission and flight states, migration errors and skips, the GraphQL surface, and the permissions for per-deployment migration on Astro Private Cloud (APC) 2.1 and later.

Configuration settings

There is no per-deployment migration feature flag, no separate mutation to enable, and no per-cluster opt-in beyond failoverEnabled. The settings that govern it are the data plane failover settings plus the new region model.

Setting	Default	Set to	Effect
`global.dataPlaneFailover.enabled`	`false`	`true` on every participating control plane and data plane	Master switch for data plane failover and per-deployment migration. Requires split mode — not supported in unified mode. On a data plane, enables the data plane execution components (Pilot and Flightdeck) and the data plane internal API’s `StartFlight` remote procedure call. On a control plane, enables Navigator and the APC API dispatcher.
`global.dataPlaneFailover.externalSecretManagerName`	Unset	The name of your `ClusterSecretStore`	Tells the data plane internal API which External Secrets Operator (ESO) `ClusterSecretStore` to use when pushing and pulling Deployment secrets. Required on data planes.
`external-secrets.enabled`	`false`	`true` on every data plane	Installs the ESO custom resource definitions that data plane failover depends on.
`Region.name`	—	Unique, human-meaningful	Region identity. Compared by ID, not by name — the name is for you. Must be unique.
`Region.cloudProvider`	—	`aws`, `gcp`, `azure`, or `local`	Every region has exactly one cloud provider. A cluster can only be assigned to a region whose provider matches the cluster’s own, so region equality implies provider equality.
`Cluster.regionId`	Backfilled to `unset`	The region the cluster physically lives in	The value the migration gate compares. Not enforced non-null, but migration is impossible while it points at `unset`.
`Cluster.cloudProvider`	Inherited from the assigned region at registration; from data plane metadata when no region	Editable on the cluster	Editable on the cluster edit form, and no longer overwritten by the data plane metadata reconcile. When you assign or change a region on an existing cluster, it is checked case-insensitively against `region.cloudProvider`, and skipped if the cluster’s provider is empty.

Cluster failover states

The cluster detail page shows a Failover field, which replaces the older binary “Failover Enabled.” Reading it is how you tell whether a cluster can participate in migration:

Status	Meaning	Can it be a migration destination?
Not Capable	The data plane doesn’t have `dataPlaneFailover.enabled` set.	No
Pending Upgrade	Failover-capable, but Deployments still need the one-time failover upgrade, and no upgrade missions are running.	No
Upgrading (N/M)	At least one upgrade mission is in flight. N of M Deployments upgraded.	No
Enabled	All eligible Deployments are upgraded and the cluster passes the eligibility check.	Yes
Issues Detected	The cluster has upgraded Deployments that are individually ineligible, for example a Deployment type change or ESO config drift. Hover for the affected list.	No

The underlying API fields are Cluster.failoverEnabled (the control-plane-effective state) and Cluster.failoverUpgradeStatus (not_started, in_progress, complete, or null).

Cluster.failoverEnabled starts from what the data plane reports, but the control plane force-downgrades it to false whenever an eligibility check fails. It reflects reality, not intent. If you enabled the Helm value and the field is still false, something in the eligibility check is failing, and the Failover status tells you which.

Failover-readiness shield states

The Deployments list shows a failover-readiness shield next to each Deployment name, on failover-capable clusters only. It uses one outline icon, distinguished by color, plus an exclamation badge for Attention. The API field behind it is Deployment.failoverReadiness.

State	Color	`failoverReadiness` value	Meaning
Not applicable	No shield	`not_capable`	Failover-incapable cluster.
Pending upgrade	Grey	`pending_upgrade`	Failover-capable but not yet upgraded for failover.
In progress	Amber	`in_progress`	An upgrade mission is in flight.
Ready	Green	`ready`	Upgraded and currently failover-eligible.
Attention	Red	`attention`	The upgrade failed, or the Deployment is upgraded but now ineligible.

The shield tracks the one-time failover-upgrade lifecycle, not migrations. A Deployment that is mid-migration keeps a green Ready shield the entire time. Use the Mission Status column, or Deployment.activeMission, to see an in-flight migration.

Mission states

Selecting N Deployments creates N independent missions, one per Deployment. Each moves through the following states:

State	Meaning
`CREATED`	Deployment claimed and the mission row exists. Flights may not exist yet.
`PLANNING`	Navigator has claimed the mission for planning.
`PLANNED`	The required control plane flights are created and initialized.
`IN_PROGRESS`	At least one flight has been dispatched to a data plane.
`CLEANUP_PENDING`	The Hyperjump flight succeeded, but source-side cleanup is still pending or failed. A per-deployment migration never reaches this state — see the following note.
`COMPLETED`	Fully complete: cutover done and cleanup done.
`FAILED`	The mission failed. See Recover a failed migration.

CLEANUP_PENDING doesn’t occur in per-deployment migration. Migrations always run in controlled mode, so the Scavenger flight (source cleanup) must succeed before the Hyperjump flight is dispatched. Once the Hyperjump succeeds, the source is already cleaned and the mission goes straight to COMPLETED. If the Scavenger fails, the Hyperjump never runs and the mission is FAILED. This state arises only in a forced cluster failover, where the Hyperjump can cut over while source-side cleanup is still deferred or has failed — and even there it isn’t an error.

Flight states

Each flight within a mission has its own state:

State	Meaning
`READY_TO_DISPATCH`	Queued, waiting for the dispatcher.
`HOLDING`	Held — a dependency isn’t satisfied yet, for example the Hyperjump flight waiting on the Scavenger flight.
`DISPATCHING`	The dispatcher holds a claim and is attempting `StartFlight`.
`DISPATCHED`	The data plane internal API acknowledged, and the data plane has durably recorded the flight.
`AWAITING_DP_HEALTH`	The data plane is unhealthy or unreachable. Dispatch is paused and resumes automatically when it recovers.
`FAILED_DISPATCH`	Dispatch failed after the configured retries.
`SUCCEEDED`	The flight completed successfully.
`FAILED`	The flight failed.
`CANCELED`	The flight was canceled.

AWAITING_DP_HEALTH is a wait, not a failure: the circuit breaker parked the flight because the data plane was unreachable. Fix the data plane and it resumes on its own.

Migration errors and skips

migrateDeployments has two failure modes. Whole-mutation errors are about the destination and reject the entire call, so nothing moves. Per-deployment skips pass over one Deployment and let the rest proceed.

Whole-mutation errors

These are evaluated in order, and the first match wins. Because cordon and in-flight-failover are checked before authorization, an unauthorized caller may see a health or cordon error first.

Error	Cause	Fix
`DESTINATION_NOT_FOUND`	The destination cluster ID doesn’t exist, or the cluster is deleted.	Check the ID.
`DESTINATION_NOT_FAILOVER_ENABLED`	The destination’s `failoverEnabled` is `false`.	Check the Failover field on the cluster detail page and resolve what is holding it back, usually Deployments pending the failover upgrade.
`DESTINATION_CLUSTER_UNHEALTHY`	The destination’s data plane health isn’t healthy.	Restore data plane health, then retry.
`DESTINATION_CLUSTER_CORDONED`	The destination cluster is in maintenance mode.	Uncordon it, or pick another destination.
`DESTINATION_FAILOVER_IN_PROGRESS`	A cluster failover is already targeting the destination.	Wait for it to finish and clean up.
`DESTINATION_NOT_AUTHORIZED`	You aren’t a System Admin and lack `cluster.config.update` on the destination.	See Permissions.

Per-deployment skips

When a Deployment is skipped, the rest of the batch still migrates. Skips are safe to retry: re-issuing migrateDeployments with just the skipped IDs is a normal workflow, because a skipped Deployment was never claimed and nothing is left in a partial state.

Reason	Cause	Fix
`DEPLOYMENT_NOT_FOUND`	The Deployment ID doesn’t exist or the Deployment is deleted.	Check the ID.
`MISSING_CLUSTER_ID`	The Deployment’s source cluster is missing or deleted.	Data integrity issue — contact Astronomer support.
`SOURCE_CLUSTER_NOT_AUTHORIZED`	You lack `cluster.config.update` on this Deployment’s source cluster.	Migration is a cluster-admin operation on both clusters. See Permissions.
`CLUSTER_REGION_NOT_SET`	The source or destination cluster is still on the `unset` sentinel region.	Assign a real region. See Configure per-deployment migration. This is the most common skip after upgrading to 2.1.
`CROSS_REGION_MIGRATION_NOT_ALLOWED`	The source and destination are in different regions.	You can’t override this. Pick an in-region destination, or use cluster failover.
`SAME_CLUSTER`	The destination is the Deployment’s current cluster.	Nothing to do — it’s already there.
`CURRENT_MISSION_CONFLICT`	The Deployment already has an active mission.	Wait for it to reach a terminal state, then retry. The conflicting mission ID isn’t returned in the skip payload — query `Deployment.activeMission` to find it.
`CLUSTER_FAILOVER_IN_PROGRESS`	A cluster failover is active on the Deployment’s source cluster.	Wait for the failover to finish. Cluster failover and Deployment-scoped missions are mutually exclusive per Deployment.
`DEPLOYMENT_CORDONED`	The Deployment is cordoned.	Uncordon it first.
`CLUSTER_CORDONED`	The Deployment’s source cluster is in maintenance mode.	Uncordon the cluster first.
`NOT_FAILOVER_READY`	The Deployment predates the failover prerequisites and hasn’t been retrofitted.	Run the failover upgrade on it, then retry.
`UNSUPPORTED_DEPLOY_TYPE`	The Deployment’s latest deploy revision isn’t `image`, for example git-sync or Dag-only.	This can’t be migrated. Convert to image-based deploys.
`INTERNAL_ERROR` / `DB_ERROR`	Transient failure during the claim transaction.	Retry. If it persists, check the control plane logs.

Cluster failover skipping a migrating Deployment

The exclusion runs both ways. If a cluster failover starts while one of your migration missions is in flight, the failover silently skips that Deployment rather than aborting, and records it in FailoverRequest.skippedDeployments. Each entry carries the Deployment ID, release name, mission ID, and reason. The skipped list is surfaced on the cluster detail page at reconcile finalization. Those Deployments weren’t failed over — once the migration mission completes, retry them explicitly.

GraphQL surface

# Trigger
migrateDeployments(deploymentIds: [Id!]!, destinationClusterId: Id!): MigrateDeploymentsPayload!

type MigrateDeploymentsPayload {
  missions: [MigrationResult]!    # successfully claimed
  skipped:  [SkippedDeployment]!  # failed a per-deployment check
}
type MigrationResult   { deploymentId: Id, missionId: Id }
type SkippedDeployment { deploymentId: Id, reason: MigrationSkipReason }

# Observe
missionProgress(missionIds: [Id!]!): [MissionProgress]

type MissionProgress {
  id: Id
  kind: MissionKind                 # MOVE for migration and cluster failover; UPGRADE for retrofit
  state: MissionState
  originClusterId: Id
  destinationClusterId: Id          # null for upgrade missions
  failoverRequestId: Id             # null for migration and upgrade missions
  flights: [MissionFlightProgress!]
}
type MissionFlightProgress { id: Id, role: FlightRole, state: CpFlightState }

# Candidate destinations
failoverTargetClusters(sourceClusterId: Uuid!): [Cluster]

# Regions
regions: [Region]!
createRegion(name: String!, cloudProvider: String!): CreateRegionPayload!
updateRegion(regionId: Id!, name: String, cloudProvider: String): UpdateRegionPayload!
deleteRegion(regionId: Id!): DeleteRegionPayload!

Relevant fields

Field	Type	Meaning
`Deployment.isBeingFailedOver`	`Boolean!`	True while any mission is active. Clients should disable destructive actions.
`Deployment.activeMission`	`MissionProgress`	The current mission with its flights, or `null`.
`Deployment.failoverReadiness`	`String`	Shield state: `not_capable`, `pending_upgrade`, `in_progress`, `ready`, or `attention`.
`Deployment.isCordoned`	`Boolean!`	Cordoned Deployments are skipped by migration.
`Deployment.secretsSynced`	`Boolean`	Whether the ESO push-secret sync succeeded. A failure surfaces as an Attention shield.
`Cluster.failoverEnabled`	`Boolean`	Control-plane-effective: can this cluster be a migration destination?
`Cluster.failoverUpgradeStatus`	`String`	`not_started`, `in_progress`, or `complete`; `null` when the cluster isn’t failover-capable.
`Cluster.isCordoned`	`Boolean`	Cordoned clusters are rejected as destinations and block their Deployments as sources.
`FailoverRequest.skippedDeployments`	`JSON`	Deployments a cluster failover skipped because they were already in a mission.

The data plane health signal the migration gate reads is an internal control plane column and isn’t exposed on the Cluster GraphQL type. To confirm it from the API, use failoverTargetClusters, which already filters on it.

Enumerations

MissionKind    MOVE | UPGRADE
MissionState   CREATED | PLANNING | PLANNED | IN_PROGRESS | CLEANUP_PENDING | COMPLETED | FAILED
FlightRole     HYPERJUMP | SCAVENGER | RETROFIT
CpFlightState  READY_TO_DISPATCH | AWAITING_DP_HEALTH | FAILED_DISPATCH | HOLDING |
               DISPATCHING | DISPATCHED | SUCCEEDED | FAILED | CANCELED
FailoverMode   CONTROLLED | FORCED        (migration is always CONTROLLED)

MigrationSkipReason
  DEPLOYMENT_NOT_FOUND | MISSING_CLUSTER_ID | SOURCE_CLUSTER_NOT_AUTHORIZED |
  CLUSTER_REGION_NOT_SET | CROSS_REGION_MIGRATION_NOT_ALLOWED | SAME_CLUSTER |
  CLUSTER_FAILOVER_IN_PROGRESS | CLUSTER_CORDONED | DEPLOYMENT_CORDONED |
  CURRENT_MISSION_CONFLICT | NOT_FAILOVER_READY | UNSUPPORTED_DEPLOY_TYPE |
  INTERNAL_ERROR | DB_ERROR

Permissions

Operation	Required permission
`regions` (list)	`cluster.config.get` or `system.clusters.get`
`createRegion` / `updateRegion` / `deleteRegion`	`cluster.config.update` or `system.clusters.update`
`updateCluster` (assign region)	A cluster-admin role on that cluster, or System Admin
`failoverTargetClusters`	`cluster.config.get` or `system.clusters.get`
`migrateDeployments`	System Admin, or `cluster.config.update` on both the source and the destination cluster
`missionProgress`	`system.clusters.get`, or a cluster-admin role on the cluster

Migration is a cluster-admin operation. To migrate Deployments you must be a System Admin, or hold cluster.config.update on both the source and the destination cluster. Deployment-level permissions alone aren’t enough. If you lack a cluster-admin role on the destination, the whole call is rejected with DESTINATION_NOT_AUTHORIZED. If you have it on the destination but not on a given Deployment’s source cluster, that Deployment is skipped with SOURCE_CLUSTER_NOT_AUTHORIZED while the rest proceed.

Troubleshooting index

Symptom	Look at
Every Deployment was skipped with `CLUSTER_REGION_NOT_SET`	Configure per-deployment migration — assign a real region.
The destination cluster isn’t in the picker	`Cluster.failoverEnabled` and the Failover field on cluster detail. You can’t query data plane health directly — use `failoverTargetClusters`, which filters on it.
The picker offered a cluster that then failed	`failoverTargetClusters` doesn’t filter by region or cordon. Confirm both manually.
You can’t deploy code to a Deployment	It probably has an active mission — check `Deployment.activeMission`.
The shield is green but the Deployment is migrating	Expected. The shield tracks the upgrade lifecycle; use the Mission Status column.
A mission is stuck in `CLEANUP_PENDING`	Not stuck — cutover succeeded, only cleanup remains. This applies to cluster failover only; a per-deployment migration never enters this state.
A flight is `AWAITING_DP_HEALTH`	A wait, not a failure. Restore data plane health and it resumes automatically.
A mission `FAILED` and the Deployment is gone	See Recover a failed migration. Retry forward — never hand-restore the source.
A cluster failover didn’t move one of your Deployments	Check `FailoverRequest.skippedDeployments` on the cluster detail page.

Overview

Architecture

Upgrade to Astro Private Cloud 2.0

Install Astro Private Cloud

Develop Dags

Airflow administration

Airflow 3

Deploy Dags

Manage Deployments

Platform administration

Manage Platform resources

Security and compliance

APC API

Platform Observability

Release notes

Reference

Per-deployment migration reference

Configuration settings

Cluster failover states

Failover-readiness shield states

Mission states

Flight states

Migration errors and skips

Whole-mutation errors

Per-deployment skips

Cluster failover skipping a migrating Deployment

GraphQL surface

Relevant fields

Enumerations

Permissions

Troubleshooting index

​Configuration settings

​Cluster failover states

​Failover-readiness shield states

​Mission states

​Flight states

​Migration errors and skips

​Whole-mutation errors

​Per-deployment skips

​Cluster failover skipping a migrating Deployment

​GraphQL surface

​Relevant fields

​Enumerations

​Permissions

​Troubleshooting index

​Related documentation

Configuration settings

Cluster failover states

Failover-readiness shield states

Mission states

Flight states

Migration errors and skips

Whole-mutation errors

Per-deployment skips

Cluster failover skipping a migrating Deployment

GraphQL surface

Relevant fields

Enumerations

Permissions

Troubleshooting index

Related documentation