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

​
Goal

Keep nodes out of the scheduler when you are about to perform risky host-level work.

​
Prerequisites

  • A connected node

​
Workflow

1
Enter maintenance before upgrades or host maintenance.
2
Keep the node in maintenance until health and heartbeat are clean again.
3
Exit maintenance only when you want the node schedulable again.

​
What maintenance does

Draining a node puts it into maintenance, which takes it out of the scheduler so no new workloads are placed on it. It is the safety control to reach for before an agent upgrade or any disruptive host-level work.

​
Drain and activate

  • Drain: move the node into maintenance — it stops receiving new placements.
  • Activate: bring the node back to a schedulable state once it is healthy again.
  • Maintenance stops new placement; it does not automatically evacuate workloads already running on the node, so move stateful workloads deliberately if the host work is destructive.

​
When to use it

  • Before upgrading the node agent.
  • Before host-level maintenance (kernel updates, disk work, reboots).
  • When a node is misbehaving and you want to stop it taking new work while you investigate.

​
Expected result

Node lifecycle work happens with fewer accidental scheduling side effects.

Upgrade the agent

Use the signed A/B release manager to move an existing node to a qualified immutable agent release and roll back automatically if readiness fails.

Node health, diagnostics, and deletion

Interpret overlay, mTLS, heartbeat, runtime, operation, inventory, and explicit deletion-blocker state before taking action.

Node overview

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