From 5e2ce88694cdff3b47c7e6a3cb16d87574c7f62b Mon Sep 17 00:00:00 2001 From: Joseph Marrero Corchado Date: Sat, 31 Oct 2026 14:46:31 -0400 Subject: [PATCH 1/2] docs: Describe / as a composefs mount in bootc-sysroot(7) The text predates composefs and still says / is a bind mount of the deployment directory. With composefs enabled, which the docs recommend and the composefs backend always uses, / is a composefs mount instead, and its mount source is no longer the root block device. That matters for tools that look at / to find the disk. Assisted-by: AI Signed-off-by: Joseph Marrero Corchado --- docs/src/bootc-sysroot.7.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/src/bootc-sysroot.7.md b/docs/src/bootc-sysroot.7.md index 64473b7c1..1deabe1a3 100644 --- a/docs/src/bootc-sysroot.7.md +++ b/docs/src/bootc-sysroot.7.md @@ -19,11 +19,13 @@ In the future, this functionality will be exposed and used by `bootc`. ## /sysroot mount When booted, the physical root will be available at `/sysroot` as a -read-only mount point and the logical root `/` will be a bind mount -pointing to a deployment directory under `/sysroot/ostree`. This is a -key aspect of how `bootc upgrade` operates: it fetches the updated -container image and writes the base image files (using OSTree storage -to `/sysroot/ostree/repo`). +read-only mount point. With composefs enabled (as recommended in +[filesystem](bootc-filesystem.7.md), and always with the composefs +backend), the logical root `/` is a read-only composefs mount of the +deployed image; otherwise it is a bind mount of a deployment directory +under `/sysroot/ostree`. This is a key aspect of how `bootc upgrade` +operates: it fetches the updated container image and writes the base +image files (using OSTree storage to `/sysroot/ostree/repo`). Beyond that and debugging/introspection, there are few use cases for tooling to operate on the physical root. From d9f38deaf031cc5a96a2a27cdc1aba57fa71faeb Mon Sep 17 00:00:00 2001 From: Joseph Marrero Corchado Date: Sat, 31 Oct 2026 14:46:31 -0400 Subject: [PATCH 2/2] docs: Explain how base images grow the root filesystem Base image authors need to know that disk images booted on larger disks, as in the cloud, need their root grown, and that bootc leaves this to the image. Provisioning tools are often assumed to take care of it, but the image based systems that do it (the Fedora and CentOS Stream bootc base images, Fedora CoreOS, Flatcar) each use a separate service, and cloud-init's growpart and resizefs can't find the device when / is a composefs mount. Point to those services and their docs from bootc-sysroot(7), note that minimal image variants may need one layered in, and link there from the image requirements and provisioning sections. Also fix the systemd-growfs typo. Assisted-by: AI Signed-off-by: Joseph Marrero Corchado --- docs/src/bootc-compatible-images.7.md | 6 ++++ docs/src/bootc-installation.7.md | 4 +++ docs/src/bootc-sysroot.7.md | 43 +++++++++++++++++++++++++-- 3 files changed, 50 insertions(+), 3 deletions(-) diff --git a/docs/src/bootc-compatible-images.7.md b/docs/src/bootc-compatible-images.7.md index cd197d713..2362ebdb7 100644 --- a/docs/src/bootc-compatible-images.7.md +++ b/docs/src/bootc-compatible-images.7.md @@ -64,6 +64,12 @@ e.g. `dracut` to ensure the initramfs is set up, etc. The `bootc container lint` command will check this. +Disk images made from your image will often be booted on a larger +disk, for example in the cloud, and something in the image needs to +grow the root filesystem to fill it; bootc does not. See +[expanding the root filesystem](bootc-sysroot.7.md#expanding-the-root-filesystem) +for how existing base images do this. + ## SELinux The default mechanism for labeling today is that bootc will load the file contexts from the image (e.g. `/etc/selinux/policy`) and apply labels dynamically. This is the only mechanism that will work today with a generic bootc-unaware build tooling. diff --git a/docs/src/bootc-installation.7.md b/docs/src/bootc-installation.7.md index 22f086add..457285f06 100644 --- a/docs/src/bootc-installation.7.md +++ b/docs/src/bootc-installation.7.md @@ -663,6 +663,10 @@ works on Linux will work with bootc. Common approaches include: The choice of provisioning tool depends on your base image and deployment environment—bootc itself is agnostic. +Growing the root filesystem to fill a larger disk is commonly done by +a separate service in the image rather than by the provisioning tool; +see [expanding the root filesystem](bootc-sysroot.7.md#expanding-the-root-filesystem). + ### SSH key injection For simple SSH access without a full provisioning system, bootc provides the diff --git a/docs/src/bootc-sysroot.7.md b/docs/src/bootc-sysroot.7.md index 1deabe1a3..52b1d0892 100644 --- a/docs/src/bootc-sysroot.7.md +++ b/docs/src/bootc-sysroot.7.md @@ -25,7 +25,8 @@ backend), the logical root `/` is a read-only composefs mount of the deployed image; otherwise it is a bind mount of a deployment directory under `/sysroot/ostree`. This is a key aspect of how `bootc upgrade` operates: it fetches the updated container image and writes the base -image files (using OSTree storage to `/sysroot/ostree/repo`). +image files (in `/sysroot/ostree/repo` with the OSTree backend, or in +`/sysroot/composefs` with the composefs backend). Beyond that and debugging/introspection, there are few use cases for tooling to operate on the physical root. @@ -47,10 +48,44 @@ This [unified storage issue](https://github.com/bootc-dev/bootc/issues/20) track One notable use case that *does* need to operate on `/sysroot` is expanding the root filesystem. +Disk images are often booted on a disk larger than the image, for +example in the cloud, so the root partition and filesystem need to be +grown at boot. bootc does not do this itself; the base image (or an +image derived from it) needs to include something that does. + +Provisioning tools such as cloud-init or Ignition are commonly expected +to handle this, but the image based systems below each do it with a +dedicated systemd service: + +- The [Fedora and CentOS Stream bootc base images](https://gitlab.com/fedora/bootc/base-images/-/tree/9b469901d99583d59b270e802795be8676dc8d19/standard) + ship `bootc-generic-growpart.service`, which runs early in boot on + virtual machines, grows the root partition with `growpart`, and then + grows the filesystem as described [below](#growing-the-filesystem). + Despite its name, it is not part of bootc. Only the `standard` variant + includes it; the `minimal` and `minimal-plus` variants do not. +- Fedora CoreOS grows the root on first boot with + `ignition-ostree-growfs.service`, which runs in the initramfs after + Ignition has set up the disks; see its + [storage documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/storage/#_disk_layout). +- Flatcar Container Linux checks on every boot and grows the root when + the disk has grown, with `extend-filesystems.service`; see + [adding disk space](https://www.flatcar.org/docs/latest/setup/storage/adding-disk-space/). + +Your distribution may also have image variants that don't include +a solution, such as the minimal variants above. If you build on one of +those and need the root grown, add a service like these in your +derived image. + Some higher level tools such as e.g. `cloud-init` may (reasonably) expect the `/` mount point to be the physical root. Tools like this will need to be adjusted to instead detect this and operate -on `/sysroot`. +on `/sysroot`. For example, cloud-init's +[growpart](https://docs.cloud-init.io/en/latest/reference/modules.html#growpart) +and [resizefs](https://docs.cloud-init.io/en/latest/reference/modules.html#resizefs) +modules find the device from the source of the `/` mount, which is +`composefs` when composefs is enabled, so they currently grow neither +the partition nor the filesystem on such a system (see +[cloud-init#6293](https://github.com/canonical/cloud-init/issues/6293)). ### Growing the block device @@ -70,11 +105,13 @@ root filesystem type and running the underlying tool such as At the current time, most Linux filesystems require the target to be mounted writable in order to grow. Hence, -an invocation of `system-growfs /sysroot` or `xfs_growfs /sysroot` +an invocation of `systemd-growfs /sysroot` or `xfs_growfs /sysroot` will need to be further wrapped in a temporary mount namespace. Using a `MountFlags=slave` drop-in stanza for `systemd-growfs@sysroot.service` is recommended, along with an `ExecStartPre=mount -o remount,rw /sysroot`. +`bootc-generic-growpart.service` above uses the same approach, with +`MountFlags=slave` on its own unit. ### Detecting bootc/ostree systems