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

​
Goal

Update the node runtime without downloading an unsigned command or leaving the node schedulable during a failed activation.

​
Prerequisites

  • A healthy enrolled node
  • Maintenance access
  • A StackShift-assigned signed release for the node OS and architecture

​
Workflow

1
Put the node into maintenance and wait for new placement to stop.
2
Start the assigned immutable release through the node release manager.
3
Verify artifact signatures, inactive-slot installation, Node Guard, WireGuard, mTLS, runtime, and heartbeat readiness.
4
Return the node to service only after the new slot reports healthy; investigate the retained previous slot if activation rolls back.

​
Signed A/B activation

  • The release manager accepts only a signed manifest from the configured Ed25519 release authority.
  • The manifest target, host profile, executable SHA-256, and immutable release identity must match the enrolled node.
  • Files are installed into the inactive slot before the systemd pointer changes.
  • No legacy upgrade-command endpoint, mutable install script, or bearer credential participates in activation.

​
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.

​
Readiness and rollback

  • The candidate slot must start the agent, Node Guard, Caddy, and the qualified runtime successfully.
  • WireGuard must handshake and the exact node certificate must authenticate a monotonically sequenced heartbeat.
  • A failed readiness window restores the previous slot and records the activation error; it does not mark the candidate healthy.
  • Confirm the expected digest, fresh heartbeat, and healthy status before activating scheduling again.

​
Expected result

The node reports the assigned immutable agent digest from the healthy active slot and retains the previous slot for bounded rollback.

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

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