lib: Add experimental unified storage support for install

Add an experimental --experimental-unified-storage flag to bootc install
that uses bootc's container storage (/usr/lib/bootc/storage) to pull
images first, then imports from there. This is the same approach used
for logically bound images (LBIs).

Background:
The unified storage approach allows bootc to share container images with
podman's storage, reducing disk space and enabling offline installs when
images are pre-pulled to the host's container storage.

Changes:
- Add --experimental-unified-storage CLI flag to install subcommands
- Add sysroot_path parameter to prepare_for_pull_unified() and pull_unified()
  to handle the different mount points during install vs upgrade/switch
- Handle localhost images specially by exporting from ostree to container
  storage first (these can't be pulled from a registry)
- Skip pull in prepare_for_pull_unified() if image already exists in
  bootc storage
- Add TMT test for install with unified storage flag
- Add TMT test for switching to unified storage on running system
- Add integration test for system-reinstall-bootc with unified storage

The sysroot_path fix is needed because during install the target disk
is mounted at a specific path (e.g., /var/mnt), not /sysroot. Skopeo
needs the actual filesystem path to find the bootc storage.

Relates: #20

Assisted-by: Claude Code (Sonnet 4.5)
Signed-off-by: Joseph Marrero Corchado <[email protected]>

Author: jmarrero

crates/lib/src/cli.rs

@@ -149,6 +149,14 @@ pub(crate) struct SwitchOpts {
     #[clap(long)]
     pub(crate) retain: bool,
 
+    /// Use unified storage path to pull images (experimental)
+    ///
+    /// When enabled, this uses bootc's container storage (/usr/lib/bootc/storage) to pull
+    /// the image first, then imports it from there. This is the same approach used for
+    /// logically bound images.
+    #[clap(long = "experimental-unified-storage")]
+    pub(crate) unified_storage_exp: bool,
+
     /// Target image to use for the next boot.
     pub(crate) target: String,
 
@@ -445,6 +453,11 @@ pub(crate) enum ImageOpts {
         /// this will make the image accessible via e.g. `podman run localhost/bootc` and for builds.
         target: Option<String>,
     },
+    /// Re-pull the currently booted image into the bootc-owned container storage.
+    ///
+    /// This onboards the system to the unified storage path so that future
+    /// upgrade/switch operations can read from the bootc storage directly.
+    SetUnified,
     /// Copy a container image from the default `containers-storage:` to the bootc-owned container storage.
     PullFromDefaultStorage {
         /// The image to pull
@@ -948,7 +961,15 @@ async fn upgrade(
             }
         }
     } else {
-        let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
+        // Auto-detect whether to use unified storage (no explicit flag for upgrade)
+        let use_unified = crate::deploy::should_use_unified_storage(storage, imgref, None).await;
+
+        let fetched = if use_unified {
+            crate::deploy::pull_unified(repo, imgref, None, opts.quiet, prog.clone(), storage, None)
+                .await?
+        } else {
+            crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?
+        };
         let staged_digest = staged_image.map(|s| s.digest().expect("valid digest in status"));
         let fetched_digest = &fetched.manifest_digest;
         tracing::debug!("staged: {staged_digest:?}");
@@ -1062,7 +1083,21 @@ async fn switch_ostree(
 
     let new_spec = RequiredHostSpec::from_spec(&new_spec)?;
 
-    let fetched = crate::deploy::pull(repo, &target, None, opts.quiet, prog.clone()).await?;
+    // Determine whether to use unified storage path
+    let explicit_flag = if opts.unified_storage_exp {
+        Some(true)
+    } else {
+        None
+    };
+    let use_unified =
+        crate::deploy::should_use_unified_storage(storage, &target, explicit_flag).await;
+
+    let fetched = if use_unified {
+        crate::deploy::pull_unified(repo, &target, None, opts.quiet, prog.clone(), storage, None)
+            .await?
+    } else {
+        crate::deploy::pull(repo, &target, None, opts.quiet, prog.clone()).await?
+    };
 
     if !opts.retain {
         // By default, we prune the previous ostree ref so it will go away after later upgrades
@@ -1460,6 +1495,7 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
             ImageOpts::CopyToStorage { source, target } => {
                 crate::image::push_entrypoint(source.as_deref(), target.as_deref()).await
             }
+            ImageOpts::SetUnified => crate::image::set_unified_entrypoint().await,
             ImageOpts::PullFromDefaultStorage { image } => {
                 let storage = get_storage().await?;
                 storage
@@ -1539,7 +1575,10 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
                 let mut w = SplitStreamWriter::new(&cfs, None, Some(testdata_digest));
                 w.write_inline(testdata);
                 let object = cfs.write_stream(w, Some("testobject"))?.to_hex();
-                assert_eq!(object, "5d94ceb0b2bb3a78237e0a74bc030a262239ab5f47754a5eb2e42941056b64cb21035d64a8f7c2f156e34b820802fa51884de2b1f7dc3a41b9878fc543cd9b07");
+                assert_eq!(
+                    object,
+                    "5d94ceb0b2bb3a78237e0a74bc030a262239ab5f47754a5eb2e42941056b64cb21035d64a8f7c2f156e34b820802fa51884de2b1f7dc3a41b9878fc543cd9b07"
+                );
                 Ok(())
             }
             // We don't depend on fsverity-utils today, so re-expose some helpful CLI tools.

crates/lib/src/deploy.rs

@@ -93,6 +93,17 @@ pub(crate) async fn new_importer(
     Ok(imp)
 }
 
+/// Wrapper for pulling a container image with a custom proxy config (e.g. for unified storage).
+pub(crate) async fn new_importer_with_config(
+    repo: &ostree::Repo,
+    imgref: &ostree_container::OstreeImageReference,
+    config: ostree_ext::containers_image_proxy::ImageProxyConfig,
+) -> Result<ostree_container::store::ImageImporter> {
+    let mut imp = ostree_container::store::ImageImporter::new(repo, imgref, config).await?;
+    imp.require_bootable();
+    Ok(imp)
+}
+
 pub(crate) fn check_bootc_label(config: &ostree_ext::oci_spec::image::ImageConfiguration) {
     if let Some(label) =
         labels_of_config(config).and_then(|labels| labels.get(crate::metadata::BOOTC_COMPAT_LABEL))
@@ -316,6 +327,16 @@ pub(crate) async fn prune_container_store(sysroot: &Storage) -> Result<()> {
     for deployment in deployments {
         let bound = crate::boundimage::query_bound_images_for_deployment(ostree, &deployment)?;
         all_bound_images.extend(bound.into_iter());
+        // Also include the host image itself
+        if let Some(host_image) = crate::status::boot_entry_from_deployment(ostree, &deployment)?
+            .image
+            .map(|i| i.image)
+        {
+            all_bound_images.push(crate::boundimage::BoundImage {
+                image: crate::utils::imageref_to_container_ref(&host_image),
+                auth_file: None,
+            });
+        }
     }
     // Convert to a hashset of just the image names
     let image_names = HashSet::from_iter(all_bound_images.iter().map(|img| img.image.as_str()));
@@ -381,6 +402,189 @@ pub(crate) async fn prepare_for_pull(
     Ok(PreparedPullResult::Ready(Box::new(prepared_image)))
 }
 
+/// Check whether to use the unified storage path for pulling an image.
+///
+/// If `explicit_flag` is Some(true), unified storage is always used.
+/// If `explicit_flag` is Some(false), unified storage is never used.
+/// If `explicit_flag` is None, auto-detect based on whether the image already exists
+/// in bootc's container storage.
+///
+/// Returns true if unified storage should be used.
+pub(crate) async fn should_use_unified_storage(
+    store: &Storage,
+    imgref: &ImageReference,
+    explicit_flag: Option<bool>,
+) -> bool {
+    // Explicit flag takes precedence
+    if let Some(flag) = explicit_flag {
+        return flag;
+    }
+
+    // Auto-detect: check if image exists in bootc storage
+    let imgstore = match store.get_ensure_imgstore() {
+        std::result::Result::Ok(s) => s,
+        std::result::Result::Err(e) => {
+            tracing::warn!("Failed to access bootc storage: {e}; falling back to standard pull");
+            return false;
+        }
+    };
+
+    let image_ref_str = crate::utils::imageref_to_container_ref(imgref);
+    match imgstore.exists(&image_ref_str).await {
+        std::result::Result::Ok(v) => v,
+        std::result::Result::Err(e) => {
+            tracing::warn!(
+                "Failed to check bootc storage for image: {e}; falling back to standard pull"
+            );
+            false
+        }
+    }
+}
+
+/// Unified approach: Use bootc's CStorage to pull the image, then prepare from containers-storage.
+/// This reuses the same infrastructure as LBIs.
+///
+/// The `sysroot_path` parameter specifies the path to the sysroot where bootc storage is located.
+/// During install, this should be the path to the target disk's mount point.
+/// During upgrade/switch on a running system, pass `None` to use the default `/sysroot`.
+pub(crate) async fn prepare_for_pull_unified(
+    repo: &ostree::Repo,
+    imgref: &ImageReference,
+    target_imgref: Option<&OstreeImageReference>,
+    store: &Storage,
+    sysroot_path: Option<&camino::Utf8Path>,
+) -> Result<PreparedPullResult> {
+    // Get or initialize the bootc container storage (same as used for LBIs)
+    let imgstore = store.get_ensure_imgstore()?;
+
+    let image_ref_str = crate::utils::imageref_to_container_ref(imgref);
+
+    // Always pull to ensure we have the latest image, whether from a remote
+    // registry or a locally rebuilt image
+    tracing::info!(
+        "Unified pull: pulling from transport '{}' to bootc storage",
+        &imgref.transport
+    );
+
+    // Pull the image to bootc storage using the same method as LBIs
+    // Show a spinner since podman pull can take a while and doesn't output progress
+    let pull_msg = format!("Pulling {} to bootc storage", &image_ref_str);
+    async_task_with_spinner(&pull_msg, async move {
+        imgstore
+            .pull(&image_ref_str, crate::podstorage::PullMode::Always)
+            .await
+    })
+    .await?;
+
+    // Now create a containers-storage reference to read from bootc storage
+    tracing::info!("Unified pull: now importing from containers-storage transport");
+    let containers_storage_imgref = ImageReference {
+        transport: "containers-storage".to_string(),
+        image: imgref.image.clone(),
+        signature: imgref.signature.clone(),
+    };
+    let ostree_imgref = OstreeImageReference::from(containers_storage_imgref);
+
+    // Configure the importer to use bootc storage as an additional image store
+    use std::process::Command;
+    let mut config = ostree_ext::containers_image_proxy::ImageProxyConfig::default();
+    let mut cmd = Command::new("skopeo");
+    // Use the actual physical path to bootc storage
+    // During install, this is the target disk's mount point; otherwise default to /sysroot
+    let sysroot_base = sysroot_path
+        .map(|p| p.to_string())
+        .unwrap_or_else(|| "/sysroot".to_string());
+    let storage_path = format!(
+        "{}/{}",
+        sysroot_base,
+        crate::podstorage::CStorage::subpath()
+    );
+    crate::podstorage::set_additional_image_store(&mut cmd, &storage_path);
+    config.skopeo_cmd = Some(cmd);
+
+    // Use the preparation flow with the custom config
+    let mut imp = new_importer_with_config(repo, &ostree_imgref, config).await?;
+    if let Some(target) = target_imgref {
+        imp.set_target(target);
+    }
+    let prep = match imp.prepare().await? {
+        PrepareResult::AlreadyPresent(c) => {
+            println!("No changes in {imgref:#} => {}", c.manifest_digest);
+            return Ok(PreparedPullResult::AlreadyPresent(Box::new((*c).into())));
+        }
+        PrepareResult::Ready(p) => p,
+    };
+    check_bootc_label(&prep.config);
+    if let Some(warning) = prep.deprecated_warning() {
+        ostree_ext::cli::print_deprecated_warning(warning).await;
+    }
+    ostree_ext::cli::print_layer_status(&prep);
+    let layers_to_fetch = prep.layers_to_fetch().collect::<Result<Vec<_>>>()?;
+
+    // Log that we're importing a new image from containers-storage
+    const PULLING_NEW_IMAGE_ID: &str = "6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0";
+    tracing::info!(
+        message_id = PULLING_NEW_IMAGE_ID,
+        bootc.image.reference = &imgref.image,
+        bootc.image.transport = "containers-storage",
+        bootc.original_transport = &imgref.transport,
+        bootc.status = "importing_from_storage",
+        "Importing image from bootc storage: {}",
+        ostree_imgref
+    );
+
+    let prepared_image = PreparedImportMeta {
+        imp,
+        n_layers_to_fetch: layers_to_fetch.len(),
+        layers_total: prep.all_layers().count(),
+        bytes_to_fetch: layers_to_fetch.iter().map(|(l, _)| l.layer.size()).sum(),
+        bytes_total: prep.all_layers().map(|l| l.layer.size()).sum(),
+        digest: prep.manifest_digest.clone(),
+        prep,
+    };
+
+    Ok(PreparedPullResult::Ready(Box::new(prepared_image)))
+}
+
+/// Unified pull: Use podman to pull to containers-storage, then read from there
+///
+/// The `sysroot_path` parameter specifies the path to the sysroot where bootc storage is located.
+/// For normal upgrade/switch operations, pass `None` to use the default `/sysroot`.
+pub(crate) async fn pull_unified(
+    repo: &ostree::Repo,
+    imgref: &ImageReference,
+    target_imgref: Option<&OstreeImageReference>,
+    quiet: bool,
+    prog: ProgressWriter,
+    store: &Storage,
+    sysroot_path: Option<&camino::Utf8Path>,
+) -> Result<Box<ImageState>> {
+    match prepare_for_pull_unified(repo, imgref, target_imgref, store, sysroot_path).await? {
+        PreparedPullResult::AlreadyPresent(existing) => {
+            // Log that the image was already present (Debug level since it's not actionable)
+            const IMAGE_ALREADY_PRESENT_ID: &str = "5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9";
+            tracing::debug!(
+                message_id = IMAGE_ALREADY_PRESENT_ID,
+                bootc.image.reference = &imgref.image,
+                bootc.image.transport = &imgref.transport,
+                bootc.status = "already_present",
+                "Image already present: {}",
+                imgref
+            );
+            Ok(existing)
+        }
+        PreparedPullResult::Ready(prepared_image_meta) => {
+            // To avoid duplicate success logs, pass a containers-storage imgref to the importer
+            let cs_imgref = ImageReference {
+                transport: "containers-storage".to_string(),
+                image: imgref.image.clone(),
+                signature: imgref.signature.clone(),
+            };
+            pull_from_prepared(&cs_imgref, quiet, prog, *prepared_image_meta).await
+        }
+    }
+}
+
 #[context("Pulling")]
 pub(crate) async fn pull_from_prepared(
     imgref: &ImageReference,
@@ -430,18 +634,21 @@ pub(crate) async fn pull_from_prepared(
     let imgref_canonicalized = imgref.clone().canonicalize()?;
     tracing::debug!("Canonicalized image reference: {imgref_canonicalized:#}");
 
-    // Log successful import completion
-    const IMPORT_COMPLETE_JOURNAL_ID: &str = "4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8";
-
-    tracing::info!(
-        message_id = IMPORT_COMPLETE_JOURNAL_ID,
-        bootc.image.reference = &imgref.image,
-        bootc.image.transport = &imgref.transport,
-        bootc.manifest_digest = import.manifest_digest.as_ref(),
-        bootc.ostree_commit = &import.merge_commit,
-        "Successfully imported image: {}",
-        imgref
-    );
+    // Log successful import completion (skip if using unified storage to avoid double logging)
+    let is_unified_path = imgref.transport == "containers-storage";
+    if !is_unified_path {
+        const IMPORT_COMPLETE_JOURNAL_ID: &str = "4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8";
+
+        tracing::info!(
+            message_id = IMPORT_COMPLETE_JOURNAL_ID,
+            bootc.image.reference = &imgref.image,
+            bootc.image.transport = &imgref.transport,
+            bootc.manifest_digest = import.manifest_digest.as_ref(),
+            bootc.ostree_commit = &import.merge_commit,
+            "Successfully imported image: {}",
+            imgref
+        );
+    }
 
     if let Some(msg) =
         ostree_container::store::image_filtered_content_warning(&import.filtered_files)