OS updates

Virtainer Free ships as one immutable host image. Updating is not a package upgrade: you point the host at a different image and reboot into it.

That is what makes the update reversible. The previous image stays on disk, so going back is a reboot rather than a restore.

One image is the whole host system: its OS, its kernel, the firmware a machine boots from, and the runtime that runs your machines. Those pieces take the versions they had when the image was built, so an image can carry newer ones than the last, and no part of the host system crosses on its own.

Switching image

1. Open OS Updates. The page shows the image the host booted from, labelled Booted image. The reference names the version, so this is where you confirm what you are actually running before you change it.

2. Pick the target version. The page lists the builds published to the repository this host reads from, with the date each was published and its size where the registry reports them. Pick a newer one to move forward, or an older one deliberately.

   Every entry is a fixed build, and a build is not the same thing as a release: the list shows whatever that repository currently publishes. A normal installation sees one repository and has no channel control. A host deliberately opted into the release-candidate channel gets a channel selector as well, and switching channel changes which builds appear in the list.

3. Choose how to apply it.

   • Switch & reboot stages the new image and reboots into it. The dialog asks you to type a confirmation phrase before it will run, so a stray click cannot reboot the host.
   • Stage only prepares it and leaves the host running as it is. Reboot later, on your own schedule, to activate it.

4. Follow the operation. The host reports the change as three steps: Pull & stage image, Reboot host, and Verify booted image. The last one confirms the host really came back on the image you asked for.

Staging is the safe default for a busy host

Staging does all the downloading and preparation while the host keeps serving, and it does not apply anything. The current image stays in charge until the host boots the staged one, and the page keeps listing it as Staged for next boot until you reboot, so the pending change outlives a reload of the console. The only disruption is the reboot you choose to run.

When an update does nothing

Virtainer Free 1.0.1-rc.4 and later are not affected. Earlier images are.

On a host running an image built before 1.0.1-rc.4, an update can pull the new image, create the deployment, reboot, and come back on the image it already had, reporting no error. The machine looks unchanged rather than broken, which is why this is worth a section of its own.

The cause is a collision over one path. The host’s boot directory is mounted by the image system, and systemd’s own partition discovery can decide that nothing has claimed that path and mount a second filesystem over it. Which of the two is torn down first at shutdown is a race, so the failure is intermittent. When the discovery mount wins, the write that records the new deployment’s boot entries has nowhere to write, the staged deployment is discarded, and the host boots the image it already had.

The console’s explanation is a guess, and in this case it is wrong. It reports that the host came back on a different image than the target, and suggests the most likely cause is that the new deployment failed to boot and the system rolled back. Nothing ever booted, so that is not what happened. Treat the wording as “the update did not land” and confirm which of the two it was before acting:

• The host log carries Remounting /boot read-write: Invalid argument from the image layer.
• The boot entries under /boot/loader/entries/ keep their old timestamps.
• The boot list shows one reboot rather than a boot attempt and a rollback.

Recovery is manual, at the host’s own console. Mask the automount that systemd created, by stopping it from starting at all with systemctl mask boot.automount, and then run the switch again. Masking is the workaround, not the fix. The fix is a kernel boot parameter carried inside the image, which means a host only receives it on the first update that actually lands. That is the awkward part: on a host already in this state, the operation the fix depends on is the operation that is failing, so mask the mount first and then update. A host that updates cleanly to 1.0.1-rc.4 or later never needs the mask step again.

A host that is rebooting cannot be reached, and the page notices: it keeps checking and recovers on its own once Virtainer Free answers again. If the host has not answered for eight minutes the page says so and stops claiming to know, so reload it once the host is reachable to see the verified result. A host that comes back on an image other than the one you chose is reported as that, not as a success. Read when an update does nothing before you accept the reason the console offers for that outcome, because on an image older than 1.0.1-rc.4 the console is guessing.

The console reloads when the served build changed

The web console is served by the host itself, so after a switch and reboot the tab you are looking at is the previous release’s copy of the console. Choosing Done reloads it, but only once the build the host is serving has actually moved: a stage-only switch never rebooted anything, and an update that failed before the reboot left the same binary in place, so neither one pulls the page out from under you. Other tabs you left open are not reloaded for you: the console compares the build it is running with the build the host is serving and raises a New version available notice with a Reload button when the two differ.

The version list

Every entry in the list names one fixed image, because picking an entry means deciding exactly what the host will run.

The registry also publishes a latest tag. It is a name for the most recently published image, not an image of its own, and it exists so that install and switch commands typed by hand do not need a new version number every time. It is deliberately never offered in the console, and two properties of it are worth knowing before you use it in a script:

• It tracks the last publish, not the newest version. Re-publishing an older build moves it backwards, and anything installing by latest then receives that older build.
• Each repository has its own latest. The stable repository’s and the release-candidate repository’s are independent names pointing at independent images.

Rolling back

There are two different operations here, and only one of them is a reboot.

Boot the image that is already installed. The previous deployment is still on disk, so selecting it at boot time is a single reboot that depends on no backup. This belongs to the host image mechanism rather than to Virtainer Free, and the console offers no button for it.

Switch to an older version. This is an ordinary update in the other direction: pick the older build in the list and switch to it, staging first if you want the choice to sit there until you decide. Because it is the same operation, it carries the same failure mode, including the one described below. A host running an image older than 1.0.1-rc.4 can discard a switch back to an older version exactly as readily as it discards a switch forward.

Machines across an update

A host reboot stops every machine. When the host comes back, machines that were running are started again, and their addresses are preserved. See After a host reboot for the details and the failure cases.

Nothing about your machines lives in the host image. Configuration and data persist across the switch; only the host system is replaced.

Externally managed hosts

If the host was not installed from a Virtainer image, the page says so and the switch is unavailable. Update it the way you update the rest of that system.

Registries

The image reference behind the version you pick must be reachable over a valid TLS connection. There is no option to disable certificate checking. A registry using plain HTTP or a self-signed certificate has to be trusted by the host image itself.