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 <jmarrero@redhat.com>

Author: jmarrero

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.

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

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