Agents from 0.18.0 update themselves from the signed release feed. Each node has its own update settings: whether it installs updates automatically, its channel and an optional time window. This page covers what you see and change per node. How releases are published and rolled out across all nodes is in Agent updates.
The Agent panel#
On a node's Overview, the Agent panel shows:
| Row | Meaning |
|---|---|
| Version | the running agent, with Update available: X, Updating, Update failed or Up to date |
| Licence | the licence as the node's agent sees it (agents from 0.58.0) |
| State | idle, downloading, waiting for operations (with how many are in progress), updating or failed |
| Updates | Automatic, any time, Automatic, 03:00–05:00 node time, or Off: only reported |
| Channel | stable or beta (a test channel set on the node is shown as such) |
| Latest release | the newest release on the node's channel |
| Last check | when the agent last read the feed, and why it failed if it did |
| Last result | Updated, Rolled back, Failed or Postponed, with the agent's message |
| Failed here | versions that failed on this node and are not tried again |
| Withdrawn | versions the feed withdrew |
| Held off | what keeps the agent from updating itself, such as an operation that has run for 30 minutes |
| Needs panel | shown only when the agent's newest release needs a newer panel than yours |
The Infrastructure › Nodes list has an Agent updates filter (Update available, Needs attention) and marks each node's version.
The panel reads a node's version and update state every 5 minutes, and at every poll while an update is under way.
Change a node's update settings#
- On the node's Overview, in the Agent panel, click Settings.
- In Agent update settings:
- Install updates automatically: when off, the agent still looks for updates and the panel shows them; you install them with Update now.
- Channel: Stable, or Beta: releases before they reach stable.
- When: Any time of day, or Only between these times, in the node's own time zone, with From and To (
HH:MM). A window may run past midnight, such as 23:00 to 02:00.
- Click Save on the node.
The settings are sent to the agent, which keeps them in /var/lib/vmstack/update/settings.json. Every change is audited (node.agent_update_settings).
Keep a node on its current version#
There is no version pin. To keep a node on the version it runs, turn Install updates automatically off. The node then only reports new releases, and nothing is installed until you click Update now. An agent never downgrades itself.
Test channels#
A channel other than stable and beta (for example rollback-test) can only be set on the node, as update_channel in /etc/vmstack/agent.yaml. The panel shows it and keeps it, but does not offer it.
Check and install an update#
- Check for updates asks the agent to read the feed now. With automatic updates on and the window open, an update found is installed.
- Update now (shown when an update is available) installs it at once, whatever the automatic setting and the window say. Confirm in the dialog.
- Retry (in the Failed here row) takes the latest release off the node's failed versions and installs it again.
What happens during an update#
- The agent downloads the release, checks its size and SHA-256 against the signed manifest, and checks that it runs.
- It waits until no operation is in progress on the node: tasks, backups, server creations, image and ISO downloads. Tasks are still accepted while it waits. If operations are still running after 30 minutes, it gives up until the next check (Postponed).
- It swaps the binary and restarts. For a few seconds new tasks are answered with "agent updating"; the panel sends them again afterwards. This is not a failure.
- The new agent checks itself: its configuration, its port, libvirt, and every readiness check line that passed before. Healthy: Updated. Not healthy, or not started within about 3 minutes: the previous binary is put back by
vmstack-agent-rollback.timer(Rolled back), and the version is marked failed on this node.
Running servers are not touched: they are QEMU processes under libvirt, not children of the agent. Open consoles are cut for a few seconds.
The agent checks the feed 2 minutes after it starts (plus a random delay of up to 30 minutes), then every 6 hours plus up to 30 minutes, so nodes do not all update at the same moment.
Agents that cannot update themselves#
An agent older than 0.18, or one whose release needs a newer minimum version, shows Upgrade by hand. The Agent panel then shows the upgrade command, built from the panel's download addresses:
curl -fsSL 'https://panel.example.com/downloads/install.sh' | bash -s -- --upgrade \
--agent-url 'https://panel.example.com/downloads/vmstack-agent' --sha256 <checksum>
Run it as root on the node. It keeps the node's enrolment, certificate and settings, and running servers are not touched. From then on the agent updates itself. If the panel has no download addresses configured, copy a vmstack-agent binary and install.sh to the node and run bash install.sh --upgrade --binary ./vmstack-agent in that directory.
An agent older than the panel's minimum (0.16.0) is marked older than the panel needs: some actions on the node may fail until it is updated.
To check the version on the node itself:
vmstack-agent version
journalctl -u vmstack-agent -u vmstack-agent-rollback --since "1 hour ago"