What are .v/ directories used for?

What are .v/ directories used for?

They replace symlinks/hardlinks used to point you at "the latest" version of something like a container image or a discoverable disk image.

In a traditional setup, you have a file such as foo_container_v1.img, containing v1 of foo_container. You then have a symlink or hardlink pointing foo_container_current.img to foo_container_v1.img, and configure everything to point to foo_container_current.img. To update to foo_container_v2.img, you download foo_container_latest.img, rename it to foo_container_v2.img, then change the link to point to it.

.v directories solve this differently; you put files in foo_container.img.v, and when you give them the right names, systemd-vpick and other systemd tools like systemd-nspawn will pick up the latest version.

That's the basic mechanism, but systemd adds a couple of extras that aren't easily possible with the link-based version; firstly, systemd is architecture-aware, so you can use the same .vdirectory with the same contents across multiple systems (e.g. just copying it down as part of your fleet management). More usefully, systemd knows how to keep a retry counter in the filename, so you can download a new image, but if it fails to run, systemd will track this and do the "normal" automatic fallback to the old version. And you can look at ls in that directory to see the retry count.

So, using this with foo_container version 2, you'd download foo_container_latest.x86-64.img into the .v directory, then rename it to foo_container_2_x86-64+5-0.img. This is now a newer version than the existing v1, so the next time a systemd tool on x86-64 looks for foo_container.img in foo_container.img.v, it'll find this v2 image. Before it attempts to start it, it'll rename it to foo_container_2_x86-64+4-1.img, showing you that it's used up one retry. If it succeeds, it'll rename the file again to foo_container_2_x86-64.img, which will cause this to be used unconditionally if v2 is the latest. If it fails, it's kept under the new name; if it keeps failing, it'll eventually be renamed to foo_container_2_x86-64+0-5.img, which causes it to be ignored in favour of foo_container_1.img. And this is all ignored by an aarch64 host, which will stick to v1 until you bring in a new aarch64 container.