Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,139 changes: 2,139 additions & 0 deletions crates/lib/src/applylive.rs

Large diffs are not rendered by default.

110 changes: 107 additions & 3 deletions crates/lib/src/boundimage.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
//! is considered ready.

use anyhow::{Context, Result};
use camino::Utf8Path;
use camino::{Utf8Path, Utf8PathBuf};
use cap_std_ext::cap_std::fs::Dir;
use cap_std_ext::dirext::CapStdExtDirExt;
use fn_error_context::context;
Expand All @@ -25,12 +25,23 @@ pub(crate) const BOUND_IMAGE_DIR: &str = "usr/lib/bootc/bound-images.d";
///
/// In the future this may be extended to include e.g. certificates or
/// other pull options.
#[derive(Debug, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct BoundImage {
pub(crate) image: String,
pub(crate) auth_file: Option<String>,
}

/// A bound image definition together with the quadlet file that defines it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct BoundImageSpec {
pub(crate) image: BoundImage,
/// Path of the quadlet file relative to the root, e.g.
/// `usr/share/containers/systemd/foo.container`.
pub(crate) path: Utf8PathBuf,
/// The raw contents of the quadlet file.
pub(crate) contents: String,
}

#[derive(Debug, PartialEq, Eq)]
pub(crate) struct ResolvedBoundImage {
pub(crate) image: String,
Expand Down Expand Up @@ -70,6 +81,39 @@ pub(crate) fn query_bound_images_for_deployment(

#[context("Querying bound images")]
pub(crate) fn query_bound_images(root: &Dir) -> Result<Vec<BoundImage>> {
let specs = query_bound_image_specs(root)?;
Ok(specs.into_iter().map(|s| s.image).collect())
}

/// Lexically resolve the target of a symlink in `dir` (relative to the root)
/// to a root-relative path, without following any further symlinks. Like
/// `RESOLVE_IN_ROOT` (which is how the file is actually read), `..` at the
/// root stays at the root.
fn resolve_link_target(dir: &Utf8Path, target: &Utf8Path) -> Result<Utf8PathBuf> {
let mut ret = Utf8PathBuf::new();
let base = if target.is_absolute() {
Utf8Path::new("")
} else {
dir
};
for component in base.components().chain(target.components()) {
use camino::Utf8Component::*;
match component {
RootDir | CurDir => {}
ParentDir => {
ret.pop();
}
Normal(n) => ret.push(n),
Prefix(_) => anyhow::bail!("Unexpected path prefix: {target}"),
}
}
Ok(ret)
}

/// Like [`query_bound_images`], but also returns the path and contents
/// of the quadlet file defining each image.
#[context("Querying bound image specs")]
pub(crate) fn query_bound_image_specs(root: &Dir) -> Result<Vec<BoundImageSpec>> {
let spec_dir = BOUND_IMAGE_DIR;
let Some(bound_images_dir) = root.open_dir_optional(spec_dir)? else {
tracing::debug!("Missing {spec_dir}");
Expand Down Expand Up @@ -112,7 +156,19 @@ pub(crate) fn query_bound_images(root: &Dir) -> Result<Vec<BoundImage>> {
_ => anyhow::bail!("Invalid file extension: {file_name}"),
}?;

bound_images.push(bound_image);
// Record where the quadlet actually lives, so callers can relate it
// to podman's quadlet search directories.
let target = bound_images_dir
.read_link_contents(file_name)
.with_context(|| format!("Reading link {path}"))?;
let target = Utf8PathBuf::try_from(target).context("Non-UTF8 symlink target")?;
let target = resolve_link_target(Utf8Path::new(spec_dir), &target)?;

bound_images.push(BoundImageSpec {
image: bound_image,
path: target,
contents: file_contents,
});
}

Ok(bound_images)
Expand Down Expand Up @@ -294,6 +350,32 @@ mod tests {
assert_eq!(images[0].image, "quay.io/bar/bar:latest");
assert_eq!(images[1].image, "quay.io/foo/foo:latest");

// The specs should record the resolved quadlet path and contents
let mut specs = query_bound_image_specs(td).unwrap();
specs.sort_by(|a, b| a.path.cmp(&b.path));
assert_eq!(specs.len(), 2);
assert_eq!(specs[0].path, format!("{CONTAINER_IMAGE_DIR}/bar.image"));
assert_eq!(specs[0].image.image, "quay.io/bar/bar:latest");
assert!(specs[0].contents.contains("quay.io/bar/bar:latest"));
assert_eq!(specs[1].path, format!("{CONTAINER_IMAGE_DIR}/foo.image"));

// Relative symlinks are resolved relative to the bound images directory
td.symlink(
"../../../share/containers/systemd/bar.image",
format!("{BOUND_IMAGE_DIR}/relative.image"),
)
.unwrap();
let specs = query_bound_image_specs(td).unwrap();
assert_eq!(specs.len(), 3);
assert!(
specs
.iter()
.all(|s| s.path == format!("{CONTAINER_IMAGE_DIR}/bar.image")
|| s.path == format!("{CONTAINER_IMAGE_DIR}/foo.image"))
);
td.remove_file(format!("{BOUND_IMAGE_DIR}/relative.image"))
.unwrap();

// Invalid symlink should return an error
td.symlink("./blah", format!("{BOUND_IMAGE_DIR}/blah.image"))
.unwrap();
Expand All @@ -308,6 +390,28 @@ mod tests {
Ok(())
}

#[test]
fn test_resolve_link_target() {
let d = Utf8Path::new("usr/lib/bootc/bound-images.d");
assert_eq!(
resolve_link_target(d, "/usr/share/containers/systemd/foo.image".into()).unwrap(),
"usr/share/containers/systemd/foo.image"
);
assert_eq!(
resolve_link_target(d, "../../../share/containers/systemd/foo.image".into()).unwrap(),
"usr/share/containers/systemd/foo.image"
);
assert_eq!(
resolve_link_target(d, "./foo.image".into()).unwrap(),
"usr/lib/bootc/bound-images.d/foo.image"
);
// Excess `..` is clamped at the root, matching RESOLVE_IN_ROOT
assert_eq!(
resolve_link_target(d, "../../../../../../foo.image".into()).unwrap(),
"foo.image"
);
}

#[test]
fn test_parse_spec_value() -> Result<()> {
//should parse string with no % characters
Expand Down
76 changes: 75 additions & 1 deletion crates/lib/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,42 @@ pub(crate) enum SoftRebootMode {
Auto,
}

/// Options for `bootc apply-live bound-images`
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct ApplyLiveBoundImagesOpts {
/// Write the definitions and ensure the images are present, but don't
/// reload systemd or restart any units.
#[clap(long)]
pub(crate) no_restart: bool,

/// Print what would be done without changing the running system.
#[clap(long)]
pub(crate) dry_run: bool,
}

/// Subcommands for applying staged content to the running system.
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum ApplyLiveOpts {
/// Apply the staged deployment's logically bound image definitions to the running system.
///
/// The staged deployment must differ from the booted deployment only in
/// logically bound image definitions: the `/usr/lib/bootc/bound-images.d`
/// symlinks and the `.container` or `.image` files they reference. If
/// anything else changed, this command fails and a reboot is required.
///
/// Changed quadlet files are written to `/run/containers/systemd/`, which
/// podman gives precedence over `/etc` and `/usr`, and the corresponding
/// units are restarted (added units are started, removed units stopped).
/// The images themselves are already present in the bootc-owned storage
/// shared by all deployments.
///
/// Because `/run` is transient this state is discarded on reboot, at which
/// point the staged deployment's own content applies. Live state lives in
/// `/run/containers/systemd/` markers and `/run/bootc/apply-live/`.
#[clap(alias = "lbi")]
BoundImages(ApplyLiveBoundImagesOpts),
}

/// Perform an status operation
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct StatusOpts {
Expand Down Expand Up @@ -1179,6 +1215,11 @@ pub(crate) enum Opt {
/// Allows temporary package installation that will be discarded on reboot.
#[clap(alias = "usroverlay")]
UsrOverlay(UsrOverlayOpts),
/// Apply content from the staged deployment to the running system without a reboot.
///
/// Stability: This interface is experimental and may change in the future.
#[clap(subcommand, hide = true)]
ApplyLive(ApplyLiveOpts),
/// Install the running container to a target.
///
/// Takes a container image and installs it to disk in a bootable format.
Expand Down Expand Up @@ -1319,7 +1360,12 @@ fn has_soft_reboot_capability(deployment: Option<&crate::spec::BootEntry>) -> bo
deployment.map(|d| d.soft_reboot_capable).unwrap_or(false)
}

/// Prepare a soft reboot for the given deployment
/// Prepare a soft reboot for the given deployment.
///
/// Does not clear live-applied `/run` state: soft-reboot without `--apply`
/// leaves containers running, and clearing protection early would allow GC
/// to prune in-use images. Clear at reboot handoff via
/// [`clear_live_state_before_reboot`] instead.
#[context("Preparing soft reboot")]
fn prepare_soft_reboot(sysroot: &SysrootLock, deployment: &ostree::Deployment) -> Result<()> {
let cancellable = ostree::gio::Cancellable::NONE;
Expand All @@ -1329,6 +1375,16 @@ fn prepare_soft_reboot(sysroot: &SysrootLock, deployment: &ostree::Deployment) -
Ok(())
}

/// Clear live-applied bound-image state immediately before reboot when a
/// soft reboot was prepared. Soft reboot preserves `/run`, so overrides and
/// image protection must not leak into the target deployment.
fn clear_live_state_before_reboot(soft_reboot: Option<SoftRebootMode>) -> Result<()> {
if soft_reboot.is_some() {
crate::applylive::clear_state_from_host()?;
}
Ok(())
}

/// Handle soft reboot based on the configured mode
#[context("Handling soft reboot")]
fn handle_soft_reboot<F>(
Expand Down Expand Up @@ -1462,6 +1518,7 @@ async fn apply_from_downloaded_ostree(

handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
if opts.apply {
clear_live_state_before_reboot(opts.soft_reboot)?;
crate::reboot::reboot()?;
}
return Ok(());
Expand Down Expand Up @@ -1647,6 +1704,7 @@ async fn upgrade(

handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
if opts.apply {
clear_live_state_before_reboot(opts.soft_reboot)?;
crate::reboot::reboot()?;
}
} else if booted_unchanged {
Expand Down Expand Up @@ -1684,6 +1742,7 @@ async fn upgrade(
}

if opts.apply {
clear_live_state_before_reboot(opts.soft_reboot)?;
crate::reboot::reboot()?;
}
} else {
Expand Down Expand Up @@ -1862,6 +1921,7 @@ async fn switch_ostree(
// `--apply` cannot be passed along with `--download-only` (handled by clap)
// but for sanity nonetheless
if opts.apply {
clear_live_state_before_reboot(opts.soft_reboot)?;
crate::reboot::reboot()?;
}

Expand Down Expand Up @@ -2270,11 +2330,25 @@ async fn run_from_opt(opt: Opt) -> Result<CliExitStatus> {
Opt::Rollback(opts) => {
rollback(&opts).await?;
if opts.apply {
clear_live_state_before_reboot(opts.soft_reboot)?;
crate::reboot::reboot()?;
}
Ok(())
}
Opt::Edit(opts) => edit(opts).await,
Opt::ApplyLive(opts) => {
let storage = &get_storage().await?;
match storage.kind()? {
BootedStorageKind::Ostree(booted_ostree) => match opts {
ApplyLiveOpts::BoundImages(opts) => {
crate::applylive::apply_bound_images(storage, &booted_ostree, &opts).await
}
},
BootedStorageKind::Composefs(_) => {
anyhow::bail!("apply-live is not yet supported on composefs systems")
}
}
}
Opt::UsrOverlay(opts) => {
use crate::store::Environment;
let env = Environment::detect()?;
Expand Down
10 changes: 10 additions & 0 deletions crates/lib/src/deploy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -457,6 +457,16 @@ pub(crate) async fn prune_container_store(sysroot: &Storage) -> Result<()> {
});
}
}
// Images applied live via `bootc apply-live bound-images` must survive
// even if the deployment they came from is discarded before reboot.
all_bound_images.extend(
crate::applylive::protected_images_from_host()?
.into_iter()
.map(|image| crate::boundimage::BoundImage {
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()));
let pruned = sysroot
Expand Down
2 changes: 2 additions & 0 deletions crates/lib/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
//! - [`image`] - Image operations and queries
//! - [`delta`] - oci-delta artifacts (`--from-delta`)
//! - [`boundimage`] - Logically Bound Images (LBIs)
//! - [`applylive`] - Applying staged content to the running system (`bootc apply-live`)
//! - [`podstorage`] - bootc-owned container storage (`/usr/lib/bootc/storage`)
//! - [`podman`] - Podman command helpers
//!
Expand Down Expand Up @@ -65,6 +66,7 @@
//! - [`etc-merge`](../etc_merge/index.html) - `/etc` three-way merge

mod aboot;
mod applylive;
mod boot_artifact;
mod bootc_composefs;
pub(crate) mod bootc_kargs;
Expand Down
52 changes: 52 additions & 0 deletions docs/src/bootc-logically-bound-images.7.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,58 @@ Images are fetched using the global bootc pull secret by default (`/etc/ostree/a
The bootc image store is owned by bootc; images will be garbage collected when they are no longer referenced
by a file in `/usr/lib/bootc/bound-images.d`.

## Applying changes without a reboot (experimental)

The container images for logically bound images live in a single bootc-owned
storage shared by all deployments, so after a `bootc upgrade` or `bootc switch`
the new images are already on disk. What is tied to a deployment is only the
*definition*: the symlink in `/usr/lib/bootc/bound-images.d` and the quadlet
file it references, which the running system reads from its own `/usr`.

If the staged deployment differs from the booted one *only* in bound image
definitions, they can be applied to the running system without a reboot:

```
bootc apply-live bound-images
```

This writes the changed quadlet files to `/run/containers/systemd/`, which
podman gives precedence over `/etc` and `/usr`, reloads systemd and restarts
the affected `.container` units (removed units are stopped). Pass `--dry-run`
to see what would change, or `--no-restart` to write the definitions without
touching any units; a later plain invocation stops and restarts the units
still pending, as does re-running after a failed stop or restart.

If the staged deployment contains any other change, the command fails and
lists the out-of-scope paths; a reboot is required to apply it. Note that a
locally modified quadlet in `/etc/containers/systemd` that also changed in
the image is reported this way, since the local copy wins in `/etc`. For the
same reason, a changed bound quadlet in `/usr/share/containers/systemd` that
a quadlet of the same name in `/etc/containers/systemd` overrides is refused,
as is a change that would replace or remove a quadlet in
`/run/containers/systemd/` that bootc did not write.

Because `/run` is transient, the override disappears on the next boot, at
which point the staged deployment's own content applies. (A soft reboot
preserves `/run`; the override is cleared at the reboot handoff with
`--apply`, not when soft-reboot is merely prepared.) Each quadlet written to
`/run/containers/systemd/` carries a leading marker comment (checksum and
whether its unit still needs a restart). Small flat lists under
`/run/bootc/apply-live/` protect the staged images from garbage collection
until reboot, even if the staged deployment is discarded (for example by
`bootc rollback`), and record the units still to be stopped (removed or
renamed units) or restarted (units reverting to the booted definition), as
well as the units that were stopped, which a later invocation starts again
if the staged deployment then defines them once more.

Limitations: only the `.container` or `.image` file referenced from
`bound-images.d` is applied. Quadlet drop-ins (`*.container.d/`) and other
referenced quadlet files (`.volume`, `.network`, `.pod`) are not copied, and
changes to them are treated as out of scope. A `.container` unit that
references a changed `.image` is not restarted unless its own file changed.
Removed units are stopped but not masked, so a dependency could start them
again until reboot. Only supported on ostree-backed systems.

## Installation

Logically bound images must be present in the default container store (`/var/lib/containers`) when invoking
Expand Down
Loading
Loading