Agent updates
Roll out node-agent versions with compatibility and health checks.
Agent updates replace Infra's node software while preserving the registered node identity and managed resources. They are separate from operating-system patching and control-plane upgrades.
Compatibility
The installation's release manifest defines supported control-plane and agent versions. Fleet → Agents shows the observed version, desired version, compatibility status, and last successful update.
A desired version must be approved for the installation and CPU architecture. Unsupported combinations are rejected before rollout. An outdated but connected agent can continue reporting while new features remain unavailable.
Create a rollout
Open Operations → Maintenance → Create plan, add an agent-update step, choose a version, and target a canary pool. Review the required actions. Some updates restart only the management agent; updates that change hypervisor or network components can require a drain and host maintenance. The release manifest identifies those requirements.
- Verify current control-plane and agent compatibility.
- Select a small, representative target set.
- Review download access, signatures, and local free space.
- Apply the update through a maintenance plan.
- In Fleet → Agents, confirm the canary nodes retain their IDs and report the requested version with fresh metrics. Check the plan's guest-operation, storage, and mesh validation results.
- If all required checks pass for the configured observation period, expand the plan to subsequent waves. If a check fails, keep the rollout paused and follow Failure.
Execution
The agent stages the approved artifact, verifies its signature, applies the update, and reconnects. The control plane compares the observed version with the requested version before marking the step complete.
During a management-agent restart, running hypervisors can continue independently, but affected management operations and observations can be unavailable. An update that restarts other services follows its declared maintenance requirements.
Failure
A download or signature failure leaves the running version unchanged. A service restart failure can leave the node unreachable and cordoned. The rollout pauses under the default failure policy so additional nodes are not updated.
Open the failed rollout operation to identify its last completed stage. If the agent cannot reconnect, use a separate host-management session and run the local agent diagnostics. Correct the reported service or transport error before retrying the rollout.
If the installed version cannot start, use the signed recovery artifact and instructions from that release's manifest. Preserve the agent state directory; it contains the node identity and reconciliation records needed to recover the existing node rather than enroll a duplicate.
Rollback
Select a previous supported version only when the release manifest permits rollback. Persistent state or protocol changes can make a direct downgrade unsupported. In that case, follow the release's recovery procedure or replace the node after evacuating workloads.
Rollback creates another operation and does not reverse application changes performed during the maintenance window. Check logs and resource health after reconnecting.
Disconnected nodes
An offline node retains its previous version until it reconnects and receives the rollout. The plan shows it as pending or skipped according to its policy. Do not count selected targets as updated; use the observed-version result.