Where this instance can live-migrate to, and why not elsewhere.
curl --request GET \ --url https://stratum.example.com/v1/projects/example/compute/instances/example/migration-destinations \ --header 'Authorization: Bearer <token>'Every workload-capable node with a verdict, and a reason against each one that cannot take this instance.
It exists so a client renders the control plane’s answer instead of re-deriving it. Live-migration eligibility is seven rules deep — admission state, role, architecture, capacity, migration transport, CPU model, and the instance’s own preconditions — and a client that reimplements them drifts every time the platform learns a new one. That has happened three times: the transport check was added, its capability key was later renamed (and the stale read failed OPEN, offering nodes whose listener was dead), and the CPU-model gate arrived that clients still do not know about.
Ineligible nodes are included deliberately. A list of only the usable nodes cannot explain an empty result, and “nowhere to go” is exactly when an operator needs the reason.
Advisory, not a guarantee. This is a snapshot: a node eligible when it was computed can fill up, be cordoned, or lose its listener before anyone acts on it. The migrate action re-checks and is the only thing that decides. Authorized as compute:DescribeInstance, not compute:MigrateInstance — it reads placement facts and performs nothing, so a read-only operator diagnosing a stuck drain does not need permission to move a guest.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”The verdict for every candidate node.
Which nodes an instance can live-migrate to right now, with a reason against every node that cannot take it.
object
The node the instance is on now.
Reasons this instance cannot live-migrate ANYWHERE — it is stopped, its root volume is node-local, the driver cannot live-migrate. When this is non-empty every destination is ineligible.
Reported separately from the per-node reasons because “nowhere to go” and “this instance cannot go anywhere” are different problems with different fixes, and a client that conflates them shows a list of red nodes when the real answer is that the instance is stopped.
One reason a migration cannot happen.
object
Stable machine-readable reason. detail carries the specific values; this is what a client branches on.
Human-readable explanation naming the specific values — the two CPU models, the node’s admission state — rather than restating the rule.
Every workload-capable node, eligible ones first, then by node id.
One candidate node and the verdict on it.
object
True only when this node has no blockers AND the instance has no instance-level blockers.
Every reason this node cannot take the instance, not just the first. An operator who repairs the migration transport only to discover a CPU mismatch has been told half the truth. Empty exactly when eligible.
One reason a migration cannot happen.
object
Stable machine-readable reason. detail carries the specific values; this is what a client branches on.
Human-readable explanation naming the specific values — the two CPU models, the node’s admission state — rather than restating the rule.
The node’s self-reported live-migration listener state. unknown means the node has never reported it, which is a different claim from down — absent keys mean “not reported”, never “false”.
What the node reports as capability.cpu.model, so a client can show why a node mismatched without a second lookup. Empty when unreported.
Example
{ "instanceBlockers": [ { "code": "INSTANCE_NOT_RUNNING" } ], "destinations": [ { "blockers": [ { "code": "INSTANCE_NOT_RUNNING" } ], "migrationTransport": "listening" } ]}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}