feat(buildsys): embed guest variant images via build-variant guest-images

Add a declarative `guest-images` field to a host variant's
`[package.metadata.build-variant]` manifest that embeds the disk-image
artifacts of one or more already-built guest variants into the host's
rootfs. This enables shipping variant-A images as content inside
variant-B (e.g. installer media, recovery partitions, AMI-bundled
secondaries) without introducing a new package type or CLI surface.

Manifest schema:

  [package.metadata.build-variant.guest-images]
  inner-variant = "/usr/share/bottlerocket/guests/inner"

  [build-dependencies]
  inner-variant = { path = "../inner-variant" }

`buildsys build-variant` validates each entry: the key must appear in
`[build-dependencies]`, the target must itself be a `build-variant`,
the value must be an absolute install path, and a variant may not
reference itself. Validated entries are threaded through a
`GUEST_IMAGES` build-arg (newline-delimited
`<guest>:<install_path>:build/images/<arch>-<guest>/<version>`) into the
`imgbuild` Dockerfile stage, where `rpm2img` (via the new
`guest-images-helper`) `cp -a`s each guest's image directory into
`${ROOT_MOUNT}<install_path>` after `rpm -iv` and before SELinux
relabel, so embedded files inherit correct labels.

Tests:
- Unit: `test_build_variant_with_guest_images`,
  `test_build_variant_without_guest_images`,
  `test_build_type_default_package_unchanged`, plus
  `validate_guest_image_entries` and `guest_image_variant_deps`
  coverage for invalid names/paths, self-reference, missing build-dep,
  transitive-only build-dep, and the happy path.
- Fixtures: `tests/projects/guest-images-kit` (host wrapper-variant
  embedding an inner-variant) and `guest-images-graph` (direct,
  transitive, and self-referential guest deps).
- Integration (`#[ignore]`, requires Docker):
  `test_twoliter_build_variant_consumes_guest_images` asserts the
  guest variant builds transitively and the host variant produces
  image artifacts.

Author: jmt-lab

tests/integration-tests/src/guest_images_build.rs

@@ -0,0 +1,110 @@
+use crate::twoliter_build::copy_project_to_temp_dir;
+use std::path::Path;
+use tempfile::TempDir;
+
+use super::{run_command, test_projects_dir, TWOLITER_PATH};
+
+/// Copy the `guest-images-kit` fixture to a temp directory and run `twoliter update`/`fetch`
+/// so it is ready to build.
+fn prepare_guest_images_kit() -> TempDir {
+    let project = test_projects_dir().join("guest-images-kit");
+    let tmp_dir = copy_project_to_temp_dir(&project);
+    let project_path = tmp_dir.path().join("Twoliter.toml");
+    let project_path_str = project_path.to_str().unwrap();
+
+    let output = run_command(
+        TWOLITER_PATH,
+        ["update", "--project-path", project_path_str],
+        [],
+    );
+    assert!(
+        output.status.success(),
+        "twoliter update failed for guest-images-kit"
+    );
+
+    let output = run_command(
+        TWOLITER_PATH,
+        ["fetch", "--project-path", project_path_str],
+        [],
+    );
+    assert!(
+        output.status.success(),
+        "twoliter fetch failed for guest-images-kit"
+    );
+
+    tmp_dir
+}
+
+/// Returns the single per-version artifact directory under
+/// `build/images/<arch>-<variant>/`, or `None` if no version directory yet exists.
+fn variant_version_dir(
+    project_root: &Path,
+    arch: &str,
+    variant: &str,
+) -> Option<std::path::PathBuf> {
+    let images_root = project_root.join(format!("build/images/{arch}-{variant}"));
+    if !images_root.is_dir() {
+        return None;
+    }
+    for entry in std::fs::read_dir(&images_root).ok()? {
+        let entry = entry.ok()?;
+        if entry.file_type().ok()?.is_dir() {
+            return Some(entry.path());
+        }
+    }
+    None
+}
+
+/// Build the host `wrapper-variant`. Cargo's build-dependency graph drives a build of the guest
+/// `inner-variant` first, and during the host's image build the guest's image directory is
+/// copied directly into the host rootfs. We assert here that:
+///
+///   1. The host variant build succeeds end-to-end.
+///   2. The guest variant's image directory exists (proving the build-dependency triggered it).
+///   3. The host variant's image directory exists and contains artifacts.
+#[test]
+#[ignore]
+fn test_twoliter_build_variant_consumes_guest_images() {
+    let tmp_dir = prepare_guest_images_kit();
+    let project_path = tmp_dir.path().join("Twoliter.toml");
+    let project_path_str = project_path.to_str().unwrap();
+
+    let arch = "x86_64";
+
+    let output = run_command(
+        TWOLITER_PATH,
+        [
+            "build",
+            "variant",
+            "wrapper-variant",
+            "--project-path",
+            project_path_str,
+            "--arch",
+            arch,
+        ],
+        [],
+    );
+    assert!(
+        output.status.success(),
+        "twoliter build variant wrapper-variant failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    // The guest variant must have been built as a transitive build-dependency.
+    let inner_dir = variant_version_dir(tmp_dir.path(), arch, "inner-variant")
+        .expect("expected inner-variant images dir to exist after host build");
+    assert!(
+        std::fs::read_dir(&inner_dir).unwrap().next().is_some(),
+        "no image artifacts produced for guest inner-variant under {}",
+        inner_dir.display()
+    );
+
+    // The host variant should also have produced its own image dir with artifacts.
+    let wrapper_dir = variant_version_dir(tmp_dir.path(), arch, "wrapper-variant")
+        .expect("expected wrapper-variant images dir to exist after host build");
+    assert!(
+        std::fs::read_dir(&wrapper_dir).unwrap().next().is_some(),
+        "no image artifacts produced for host wrapper-variant under {}",
+        wrapper_dir.display()
+    );
+}

tests/integration-tests/src/guest_images_helper.rs

@@ -0,0 +1,199 @@
+use crate::run_command;
+use std::path::{Path, PathBuf};
+use tempfile::TempDir;
+
+/// Path to the `guest-images-helper` shell file embedded by twoliter and sourced by `rpm2img`.
+fn helper_path() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("twoliter/embedded/guest-images-helper")
+}
+
+/// Build a synthetic guest image directory mimicking the layout produced by a real variant
+/// build. Includes:
+///   - the bootable image artifacts that should be copied
+///   - the build-metadata files that must NOT be copied (the bug we're guarding against)
+///   - a stable-name symlink (`os_image.img.lz4` -> `bottlerocket-…img.lz4`)
+fn populate_synthetic_guest_dir(dir: &Path) {
+    // Bootable artifacts (these are the ones that SHOULD be copied).
+    for f in [
+        "bottlerocket-inner-x86_64-1.0.0-0.img.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-data.img.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-boot.ext4.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-root.ext4.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-root.verity.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0.qcow2",
+        "bottlerocket-inner-x86_64-1.0.0-0.vmdk",
+    ] {
+        std::fs::write(dir.join(f), b"image-bytes").unwrap();
+    }
+
+    // Stable-name symlink. After copy it should still point at the right target name.
+    std::os::unix::fs::symlink(
+        "bottlerocket-inner-x86_64-1.0.0-0.img.lz4",
+        dir.join("os_image.img.lz4"),
+    )
+    .unwrap();
+
+    // Build metadata + SBOMs (these MUST NOT be copied).
+    for f in [
+        "application-inventory.json",
+        "artifact-metadata.json",
+        "pcr-predictions.json",
+        "bottlerocket-inner-x86_64-1.0.0-0-sbom-os.spdx.json",
+        "bottlerocket-inner-x86_64-1.0.0-0-sbom-os.cdx.json",
+    ] {
+        std::fs::write(dir.join(f), b"metadata-bytes").unwrap();
+    }
+    // A stray non-image binary (e.g. left-over from a tool) — must not be copied either.
+    std::fs::write(dir.join("README.txt"), b"text").unwrap();
+}
+
+/// Source the helper, run `copy_guest_image_artifacts`, and return the destination directory
+/// for inspection.
+fn run_copy(src: &Path, dst: &Path) -> std::process::Output {
+    let helper = helper_path();
+    let script = format!(
+        r#"
+        set -euo pipefail
+        source "{helper}"
+        copy_guest_image_artifacts "{src}" "{dst}"
+        "#,
+        helper = helper.display(),
+        src = src.display(),
+        dst = dst.display(),
+    );
+    run_command("bash", ["-c", script.as_str()], [])
+}
+
+fn entries_in(dir: &Path) -> Vec<String> {
+    let mut names: Vec<String> = std::fs::read_dir(dir)
+        .unwrap()
+        .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
+        .collect();
+    names.sort();
+    names
+}
+
+/// All bootable image artifacts (and the stable-name symlink) end up at the destination, and
+/// none of the JSON / SBOM / README files do. This is the regression test for the original
+/// `cp -a` finding that copied the entire guest image directory verbatim.
+#[test]
+fn test_copy_guest_image_artifacts_filters_metadata_and_sboms() {
+    let temp = TempDir::new().unwrap();
+    let src = temp.path().join("src");
+    let dst = temp.path().join("dst");
+    std::fs::create_dir_all(&src).unwrap();
+    std::fs::create_dir_all(&dst).unwrap();
+    populate_synthetic_guest_dir(&src);
+
+    let output = run_copy(&src, &dst);
+    assert!(
+        output.status.success(),
+        "copy_guest_image_artifacts failed: stderr={}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    let copied = entries_in(&dst);
+
+    // Required: every bootable artifact + the symlink. Order independent.
+    for required in [
+        "bottlerocket-inner-x86_64-1.0.0-0.img.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-data.img.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-boot.ext4.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-root.ext4.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0-root.verity.lz4",
+        "bottlerocket-inner-x86_64-1.0.0-0.qcow2",
+        "bottlerocket-inner-x86_64-1.0.0-0.vmdk",
+        "os_image.img.lz4",
+    ] {
+        assert!(
+            copied.iter().any(|n| n == required),
+            "expected {required:?} in dst, got {copied:?}"
+        );
+    }
+
+    // Forbidden: no JSON, no SBOM, no README. These would leak guest build metadata into
+    // the host rootfs and are exactly what the `cp -a` regression copied.
+    for forbidden in copied.iter() {
+        assert!(
+            !forbidden.ends_with(".json"),
+            "metadata file {forbidden:?} must not be copied (came from src JSON)"
+        );
+        assert!(
+            !forbidden.contains("-sbom-"),
+            "SBOM file {forbidden:?} must not be copied"
+        );
+        assert!(
+            forbidden != "README.txt",
+            "non-image file {forbidden:?} must not be copied"
+        );
+    }
+
+    // The symlink must remain a symlink (so its target name is preserved verbatim) and
+    // must point at one of the real artifacts in the same directory.
+    let symlink_meta = std::fs::symlink_metadata(dst.join("os_image.img.lz4")).unwrap();
+    assert!(
+        symlink_meta.file_type().is_symlink(),
+        "os_image.img.lz4 should remain a symlink at the destination"
+    );
+    let target = std::fs::read_link(dst.join("os_image.img.lz4")).unwrap();
+    assert_eq!(
+        target.to_string_lossy(),
+        "bottlerocket-inner-x86_64-1.0.0-0.img.lz4",
+        "symlink target should be preserved verbatim"
+    );
+}
+
+/// If a guest directory holds no recognizable image artifacts, the helper returns non-zero so
+/// the caller can fail the build instead of silently producing an empty install path.
+#[test]
+fn test_copy_guest_image_artifacts_fails_on_empty_input() {
+    let temp = TempDir::new().unwrap();
+    let src = temp.path().join("src");
+    let dst = temp.path().join("dst");
+    std::fs::create_dir_all(&src).unwrap();
+    std::fs::create_dir_all(&dst).unwrap();
+    // Only metadata files: nothing the helper considers an artifact.
+    std::fs::write(src.join("application-inventory.json"), b"{}").unwrap();
+    std::fs::write(src.join("README.txt"), b"text").unwrap();
+
+    let output = run_copy(&src, &dst);
+    assert!(
+        !output.status.success(),
+        "copy_guest_image_artifacts should fail when no artifacts match"
+    );
+    assert!(
+        entries_in(&dst).is_empty(),
+        "no files should have been copied; got {:?}",
+        entries_in(&dst)
+    );
+}
+
+/// Filenames containing spaces must round-trip correctly through the find/while pipeline.
+/// This guards against accidentally re-introducing word-splitting bugs in the copy logic.
+#[test]
+fn test_copy_guest_image_artifacts_handles_spaces_in_names() {
+    let temp = TempDir::new().unwrap();
+    let src = temp.path().join("src");
+    let dst = temp.path().join("dst");
+    std::fs::create_dir_all(&src).unwrap();
+    std::fs::create_dir_all(&dst).unwrap();
+    let weird = "name with spaces.img.lz4";
+    std::fs::write(src.join(weird), b"image").unwrap();
+
+    let output = run_copy(&src, &dst);
+    assert!(
+        output.status.success(),
+        "copy_guest_image_artifacts failed on space-in-name: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(
+        dst.join(weird).is_file(),
+        "expected {weird:?} to be copied; dst contents: {:?}",
+        entries_in(&dst)
+    );
+}

tests/integration-tests/src/lib.rs

@@ -8,6 +8,8 @@ use tempfile::TempDir;
 
 mod advisory_checker;
 mod appinventory;
+mod guest_images_build;
+mod guest_images_helper;
 mod imghelper;
 mod twoliter_build;
 mod twoliter_update;

tests/projects/guest-images-graph/Cargo.lock

@@ -0,0 +1,16 @@
+[workspace]
+resolver = "2"
+members = [
+    "variants/host",
+    "variants/direct",
+    "variants/transitive",
+    "kits/middle-kit",
+    "packages/some-pkg",
+]
+
+[profile.dev]
+debug = false
+opt-level = 'z'
+
+[profile.dev.build-override]
+opt-level = 'z'

tests/projects/guest-images-graph/Cargo.toml

@@ -0,0 +1,15 @@
+# guest-images-graph
+
+Minimal Cargo workspace used only by buildsys unit tests to exercise the
+`guest-images` dependency-graph rules. The shape is:
+
+```
+host (variant)
+├─ [build-deps] direct (variant)         <- valid guest
+└─ [build-deps] middle-kit (kit)
+   ├─ [deps]    transitive (variant)     <- reachable but NOT a direct build-dep
+   └─ [deps]    some-pkg (package)
+```
+
+No crate here is intended to be passed to `twoliter build`; the fixtures only
+need to be valid enough for `cargo metadata --offline` to succeed.