monitor: One-to-one relationship between guests and images (#75)

so far, we’ve managed the lifecycle of an image like servo-ubuntu2204
like this:

- rebuild the image by building a new _profile guest_ (libvirt guest
named “**servo-ubuntu2204**”)
  - destroy the guest with that name, if it exists
  - recreate the guest from profiles/servo-ubuntu2204/guest.xml
  - set the disk to /path/to/base/servo-ubuntu2204/base.img@[timestamp]
- start the guest, so that it can install tooling, bake in cached
builds, etc
  - destroy the libvirt guest
  - recreate the guest from profiles/servo-ubuntu2204/guest.xml
  - set the disk to /path/to/base/servo-ubuntu2204/base.img (symlink)
- if successful, symlink /path/to/base/servo-ubuntu2204/base.img to
base.img@[timestamp]
- if unsuccessful, symlink /path/to/base/servo-ubuntu2204/base.img to
base.img@[oldTimestamp]
- create runners by cloning that guest into each _runner guest_
(“**ci-runner-servo-ubuntu2204.[number]**”)
- clone the disks, but not the guests, with the monitor (so it can be
parallelised)
  - clone the guest, but not the disks, with virt-clone

that works well enough for our current setup with libvirt and ZFS, but
some hypervisors, like UTM (#64), will require us to treat each virtual
machine as a self-contained object, with its own configuration and image
files. in UTM, it’s hard to destroy a guest without also destroying its
disks.

this patch moves the monitor closer to that world, by avoiding the
destroy-recreate-configure pattern in image rebuilds. the lifecycle for
servo-ubuntu2204 images now looks like this:

- rebuild the image by building a new _rebuild guest_
(“**ci-rebuild-servo-ubuntu2204@[timestamp]**”)
  - create the guest from profiles/servo-ubuntu2204/guest.xml
  - set the disk to /path/to/base/servo-ubuntu2204/base.img@[timestamp]
- start the guest, so that it can install tooling, bake in cached
builds, etc
- if successful, convert that guest to a new _template guest_
(“**ci-template-servo-ubuntu2204@[timestamp]**”)
- conversion just means renaming the guest from “ci-rebuild-…” to
“ci-template-…”
- if unsuccessful, just destroy that guest
- create runners by cloning that guest into each _runner guest_
(“**ci-runner-servo-ubuntu2204.[number]**”)
- clone the disks, but not the guests, with the monitor (so it can be
parallelised)
  - clone the guest, but not the disks, with virt-clone

bonus: with this patch, failed rebuilds will no longer leave the
template in an inconsistent state, with the old image data (good) but
the new guest configuration (bad because it may be broken).

<img width="771" height="519" alt="image"
src="https://github.com/user-attachments/assets/21898110-d243-401a-9e0d-8852d2b74a9a"
/>

Author: delan

monitor.toml.example

@@ -52,6 +52,12 @@ base_image_max_age = 86400
 # Uncomment to skip cached Servo repo updates.
 # dont_update_cached_servo_repo = true
 
+# Create libvirt guests for profile templates as “ci-template-<profile_name>.0”. Namespace must not be used by anything else!
+# libvirt_template_guest_prefix = "ci-template"
+
+# Create libvirt guests for image rebuilds as “ci-rebuild-<profile_name>.0”. Namespace must not be used by anything else!
+# libvirt_rebuild_guest_prefix = "ci-rebuild"
+
 # Create libvirt guests for runners as “ci-runner-<profile_name>.0”. Namespace must not be used by anything else!
 # libvirt_runner_guest_prefix = "ci-runner"
 

monitor/settings/src/lib.rs

@@ -80,6 +80,8 @@ pub struct Toml {
     pub main_repo_path: String,
     base_image_max_age: u64,
     dont_update_cached_servo_repo: Option<bool>,
+    libvirt_template_guest_prefix: Option<String>,
+    libvirt_rebuild_guest_prefix: Option<String>,
     libvirt_runner_guest_prefix: Option<String>,
     pub available_1g_hugepages: usize,
     pub available_normal_memory: MemorySize,
@@ -242,6 +244,18 @@ impl Toml {
         self.queue_member.unwrap_or(false)
     }
 
+    pub fn libvirt_template_guest_prefix(&self) -> &str {
+        self.libvirt_template_guest_prefix
+            .as_deref()
+            .unwrap_or("ci-template")
+    }
+
+    pub fn libvirt_rebuild_guest_prefix(&self) -> &str {
+        self.libvirt_rebuild_guest_prefix
+            .as_deref()
+            .unwrap_or("ci-rebuild")
+    }
+
     pub fn libvirt_runner_guest_prefix(&self) -> &str {
         self.libvirt_runner_guest_prefix
             .as_deref()

monitor/settings/src/profile.rs

@@ -1,3 +1,4 @@
+use jane_eyre::eyre::{self, OptionExt};
 use serde::{Deserialize, Serialize};
 
 use crate::{TOML, units::MemorySize};
@@ -20,8 +21,24 @@ pub enum ImageType {
 }
 
 impl Profile {
-    pub fn profile_guest_name(&self) -> String {
-        format!("{}", self.profile_name)
+    pub fn snapshot_path_slug(&self, snapshot_name: &str) -> String {
+        format!("{}@{snapshot_name}", self.profile_name)
+    }
+
+    pub fn template_guest_name(&self, snapshot_name: &str) -> String {
+        format!(
+            "{}-{}@{snapshot_name}",
+            TOML.libvirt_template_guest_prefix(),
+            self.profile_name
+        )
+    }
+
+    pub fn rebuild_guest_name(&self, snapshot_name: &str) -> String {
+        format!(
+            "{}-{}@{snapshot_name}",
+            TOML.libvirt_rebuild_guest_prefix(),
+            self.profile_name
+        )
     }
 
     pub fn runner_guest_name(&self, id: usize) -> String {
@@ -33,3 +50,23 @@ impl Profile {
         )
     }
 }
+
+pub fn parse_template_guest_name(template_guest_name: &str) -> eyre::Result<(&str, &str)> {
+    let prefix = format!("{}-", TOML.libvirt_template_guest_prefix());
+    let (profile_key, snapshot_name) = template_guest_name
+        .strip_prefix(&prefix)
+        .ok_or_eyre("Failed to strip template guest prefix")?
+        .split_once("@")
+        .ok_or_eyre("Failed to split snapshot path slug into profile key and snapshot name")?;
+    Ok((profile_key, snapshot_name))
+}
+
+pub fn parse_rebuild_guest_name(rebuild_guest_name: &str) -> eyre::Result<(&str, &str)> {
+    let prefix = format!("{}-", TOML.libvirt_rebuild_guest_prefix());
+    let (profile_key, snapshot_name) = rebuild_guest_name
+        .strip_prefix(&prefix)
+        .ok_or_eyre("Failed to strip rebuild guest prefix")?
+        .split_once("@")
+        .ok_or_eyre("Failed to split snapshot path slug into profile key and snapshot name")?;
+    Ok((profile_key, snapshot_name))
+}