Virtainer Guest Agent (VGA)

Every classic VM can run the Virtainer Guest Agent (VGA), a small program that lets the host ask the guest questions and give it instructions over a private channel (vsock) that needs no network. The console calls it VGA where space is short. It is on by default; the Virtainer Guest Agent (VGA) switch is under First boot on the create form and in VM templates.

VGA speaks the QEMU Guest Agent protocol, so tools written for that protocol work with it, and it is open source under the Apache-2.0 licence: virtainer/virtainer-guest-agent.

What it does

Feature	What the agent provides
Addresses	Reports the guest’s own IP addresses, so the Instances list can show where the machine is
Consistent snapshots	Freezes the guest’s filesystems for the instant a running snapshot is committed, then thaws them. See Snapshots
CPU and memory hot-plug	Brings vCPUs and memory added while the machine runs online inside the guest, on every distribution. See Create a VM for the Max vCPUs and Max memory headroom
Shell	The day-to-day terminal in the console: several sessions, a window size that follows your browser, and a choice of the default cloud-init user or root. See Lifecycle and console

How it gets into the guest

The agent is a single static program that ships with the host. It is placed on the machine’s cloud-init seed disk and installed or upgraded from there at every boot. Nothing is downloaded and no package is installed, so it works on any distribution cloud-init supports and on machines with no network interface or no internet access. Each boot also brings the guest’s agent up to the version the host carries.

If the host image does not contain the agent, a machine with the switch on fails to start with a message saying so, rather than booting without it.

The seed disk is therefore attached at every boot, not only the first. That does not re-run your first-boot setup: cloud-init applies the accounts, keys and network from the seed once, on the first boot, and records that it did. On later boots the seed only carries the agent. Changes you made inside the VM since are never overwritten from it.

The seed disk stays attached until the guest’s agent reports the version the seed carries, for at most ten minutes after boot, and is then removed from the running machine. Attaching a data volume to a running machine can therefore return 409 with a request to try again shortly during the first seconds after a boot.

Versions and updates

Every boot already brings the agent up to the version the host carries (see above). For machines that stay up for months, the console also shows each agent’s version and can push the host’s version into a running machine without a reboot.

• VGA column. The Instances list has a VGA column, shown by default, with the version each running classic VM reports. A machine whose VGA is older than the one this host ships shows its version in the warning colour. A dash means the host has not read a version, for example because the machine is stopped or the VGA is not answering.
• One machine. Next to an outdated version in a running VM’s row is an update button. It asks for confirmation first: the VGA restarts, the machine keeps running, and any open Shell sessions on it end. When the window is too narrow for the VGA column, the button sits beside the machine’s name instead. The machine’s More menu offers the same Update VGA.
• Selected machines. Select machines in the list (or all of them) and choose Update VGA in the selection bar; the count on it is how many of the selected machines are running with an outdated VGA. They are updated as one operation.
• Every machine. Update VGAs at the top of the Instances page updates every running classic VM whose VGA is outdated, and shows how many that is. It is disabled when none is outdated, and hidden when the host image ships no agent. Both the selected and the every-machine update ask for confirmation, run as an operation, and only one such operation runs at a time. It cannot be cancelled; if it is interrupted, run it again, and machines that already have the new version are skipped.
• Results. Open the operation under Operations to see one line per machine: updated, skipped with the reason, or failed. An update counts as done only once the agent reports the host’s version again within 30 seconds.

A machine is skipped, not failed, when an update would not be safe or is not needed:

Reason	What to do
The machine is not running	Nothing. It gets the host’s version at its next boot
The agent is not answering	Check the machine, then run the update again
It is not running VGA	Restart the machine; it installs the agent from the seed
Already at the host’s version	Nothing
The guest has turned off command execution or file access (block-rpcs)	Nothing. The agent upgrades itself at the next boot
A snapshot is in progress	Run the update again afterwards
A Shell session is open	Close it and run the update again. The single-machine update, after you confirm, ends the session instead; the bulk update never does

The Shell

• Version. The Shell needs agent version 0.2.0 or later. An older agent keeps the other features, and the Shell tab says the agent is too old.
• Users. A session starts as the machine’s default cloud-init user. More offers Shell (root). No other user is accepted.
• Not a login. It starts the user’s login shell directly, like docker exec: there is no password prompt and no login record, so who does not list it.
• Guest control. The owner of the guest can turn the Shell off by blocking the __io.virtainer_shell command in the agent’s configuration, and blocking command execution (guest-exec) turns it off too. The Shell tab then states that the guest has disabled it and offers the Rescue console instead.
• Limits. Sessions count toward the host’s global limit on concurrent console and exec sessions. Closing the browser tab hangs the session up, like closing an SSH connection; jobs started with nohup keep running.
• Audit. Every session is recorded under Change audit on Logs and diagnostics.

When the agent is off or not answering

With the switch off, nothing about the agent goes into the seed. The machine runs as usual, and what remains is limited to what has to ask the guest:

• the guest reports no addresses of its own, so the host shows only what it can learn from the network, such as a DHCP lease;
• snapshots of a running machine cannot be filesystem-consistent, so only crash-consistent ones are possible;
• hot-added vCPUs and memory are not brought online by Virtainer, and on many distributions they stay offline until you online them yourself;
• there is no Shell, only the Rescue console.

The switch is a create-time choice. If the agent is on but does not answer, the instance shows that and offers the Rescue console beside the other actions, since that works without the agent.

No agent, no problem for the machine itself

The agent is a convenience for the host. Turning it off is the right call for a guest that must not run a root-privileged agent; nothing about booting, networking, or disks depends on it.