Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Update the node agent without leaving it in a confused scheduling state.

​
Prerequisites

  • A connected node
  • Maintenance access

​
Workflow

1
Put the node into maintenance.
2
Apply the upgrade command or reinstall flow.
3
Verify heartbeat freshness and version state before returning the node to service.

​
How the upgrade path is framed

  • StackShift exposes copyable upgrade commands from the node page.
  • Maintenance mode is the expected safety gate before upgrading.
  • The UI distinguishes “upgrade available” from a real failed upgrade operation.

​
Why maintenance first

Upgrading restarts the agent, which briefly disrupts heartbeats and the node-side workflows it runs. Draining the node into maintenance first keeps the scheduler from placing new work mid-upgrade, so the restart does not collide with a fresh deployment.

​
After the upgrade

  • Confirm a fresh heartbeat and the expected agent version on the node page.
  • An “upgrade available” badge is informational — it is not the same as a failed upgrade operation.
  • Return the node to service (activate) only once it reports healthy.

​
Expected result

The node reports the expected agent version and can safely leave maintenance.

Maintenance mode

Use maintenance as a safety control before upgrades or disruptive host changes.

Node overview

What a node is, what the agent does, and what node health means in StackShift.

Node health, diagnostics, and deletion

Read node diagnostics correctly and understand when deletion is safe or blocked.