Get an instance's in-VM agent liveness.
curl --request GET \ --url https://stratum.example.com/v1/projects/example/compute/instances/example/agent-status \ --header 'Authorization: Bearer <token>'Returns the in-VM stratum-instance-agent’s reported
liveness for the instance: a derived health (healthy | unhealthy |
unknown | agent_disabled | enrollment_pending), the last-seen timestamp,
the agent version, and the result of its most recent reconcile. The agent
PUTs a heartbeat over the tokenless IMDS rail on a fast timer; health is
derived from how recently it was last seen. An instance whose agent has
never reported is unknown. An instance that does not want an agent is
agent_disabled, and one enabled but not yet enrolled is
enrollment_pending, matching its agentEnabled and
agentEnrollmentPending.
Gates on the compute:DescribeInstance Cedar action on the instance
(same as reading the instance).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”The instance’s in-VM agent status.
An instance’s in-VM agent liveness. health is
derived from lastSeen: an agent seen within a few heartbeat intervals
is healthy, one that has gone silent is unhealthy, and an instance
whose agent has never reported is unknown (the remaining fields are
then omitted). The instance’s agent settings come first:
agent_disabled when its agentEnabled is false, enrollment_pending
when agentEnrollmentPending is true, whatever the heartbeat says.
object
Derived agent liveness. agent_disabled: the instance’s agentEnabled is false, so no agent is wanted and its silence is not a fault. enrollment_pending: enable-agent ran and its install command has not been run in the guest yet. Exactly the instance fields, so the two never disagree.
When the control plane last received a heartbeat.
The agent’s reported build version.
Result of the agent’s most recent reconcile (“ok” or “error”).
When the agent last completed a reconcile.
Example
{ "instanceId": "i-A8c2D4e6F", "health": "healthy"}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" } ]}