Shut a node down (power off), gracefully.
curl --request POST \ --url https://stratum.example.com/v1/compute/nodes/example/actions/shutdown \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reason": "example", "force": false }'Records the shutdown and answers 202; the node’s own control plane then
asks its host-helper to power the host off after a short delay
(notBefore). See NodePowerAction for what happens on the way down and
back. The node stays off until someone powers it on (powerOn).
On a single-node install this takes the console and the API down with it
(controlPlaneOffline): the answer comes first, the power-off after.
Refused with 409 and a code:
NODE_POWER_ACTION_IN_PROGRESS— the node already has a shutdown or reboot in progress.UPGRADE_IN_PROGRESS— an upgrade is running.CLUSTER_SHUTDOWN_IN_PROGRESS— a whole-cluster shutdown is running.NODE_NOT_REPORTING— the node’s heartbeat lapsed: its control plane cannot act on the request (it is probably already off).MIGRATION_IN_PROGRESS— an instance is migrating to or from the node.QUORUM_AT_RISK— the cluster would be left without a majority of its control-plane nodes up.force: trueoverrides this one only.
Gates on compute:ShutdownNode on the node.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Body
Section titled “Request Body”Options for a node shutdown or reboot. An empty body is the safe default: refuse anything that would break the cluster’s quorum.
object
Why. Recorded on the action and in the audit event.
Go ahead when the cluster would be left without a majority of its
control-plane nodes up (refusal QUORUM_AT_RISK): the last node of a
cluster, or a second node while another is already down. Every other
refusal stands. To power off a whole cluster, use
POST /v1/admin/cluster/shutdown instead.
Responses
Section titled “Responses”Recorded; the node powers off at notBefore.
A shutdown or reboot of one node, recorded as desired state. The
node’s own control plane asks its host-helper to run systemctl poweroff or
systemctl reboot once notBefore has passed; the control plane itself
never powers a host off. On the way down the node drain shuts the node’s VMs
down (ACPI, then power-off after its timeout) and sets noout on the node’s
Ceph OSDs; on the way back the VMs it stopped start again and the noout is
cleared once the OSDs are up and in.
While the action is in progress the node is held in the maintenance
admission state, so nothing is placed on it and compute HA does not treat
it as lost; when it is done (or failed) the node goes back to the state
it had before.
object
shutting-down— recorded; the node powers off atnotBefore.rebooting— recorded; the node reboots atnotBefore, and staysrebootinguntil it has booted again.off— a shutdown whose node stopped heartbeating. It staysoffuntil someone powers it on (seepowerOn).done— the node booted again after the action.failed— the host did not power off or reboot;messagesays why.
Bumped by every new action on the node.
When the host acts: a short delay after the request, so the 202 is answered before the node (and, on a single node, the API) goes down.
When a shutdown’s node was seen gone.
What the action is doing or waiting for, or why it failed.
True when this node is the only control-plane node up (a single-node install, or the last node of a cluster): the console and the API go down with it, and nothing answers until it is back.
How the node comes back after a shutdown: its power button, and Wake-on-LAN to its out-of-band NIC’s MAC when the node reported one.
Example
{ "action": "shutdown", "state": "shutting-down"}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" } ]}Conflicting state.
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" } ]}Upstream temporarily unavailable (driver / scheduler / dependency).
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" } ]}