Merge pull request #5332 from jeckersb/chunked-docs

docs: expand on chunked images

Author: cgwalters

docs/build-chunked-oci.md

@@ -11,18 +11,31 @@ However, it does not support common container-native workflows such
 as copying content from a distinct container image.
 
 The `rpm-ostree compose build-chunked-oci` command
-accepts an arbitrary input container image, and synthesizes a
-bootc (ostree container) ready image from it.
+accepts exactly one of:
 
-At the current time, it is recommended that the input
-container image be derived from a reference maintained base image,
-such as the fedora-bootc ones. Especially if you are
-targeting bootc systems with this, please follow
+- an arbitrary input container image
+- a source root filesystem tree
+
+and synthesizes a bootc (ostree container) ready image from it.  This
+produces a chunked output image via the [same process](https://coreos.github.io/rpm-ostree/container/#creating-chunked-images)
+as `rpm-ostree compose container-encapsulate`.
+
+At the current time, when using an input container image, it is
+recommended that the input container image be derived from a reference
+maintained base image, such as the fedora-bootc ones. Especially if
+you are targeting bootc systems with this, please follow
 <https://gitlab.com/fedora/bootc/tracker/-/issues/32>.
 
 ## Running
 
-This command expects a container image already fetched into a `containers-storage:`
+Note that the `--from` and `--rootfs` options are mutually-exclusive;
+exactly one is required.  Currently both `--bootc` and
+`--format-version=1` are required options.  Additional format versions
+may be added in the future.
+
+### Using `--from`
+
+This expects a container image already fetched into a `containers-storage:`
 instance, and can output to `containers-storage:` or `oci`. 
 
 ```
@@ -32,3 +45,16 @@ rpm-ostree compose build-chunked-oci --bootc --format-version=1 \
            --from=quay.io/exampleos/exampleos:build --output containers-storage:quay.io/exampleos/exampleos:latest
 podman push quay.io/exampleos/exampleos:latest
 ```
+
+### Using `--rootfs`
+
+This expects a source root filesystem tree, such as one created with
+`rpm-ostree compose rootfs`.
+
+```
+# assumes package system configuration in /repos
+rpm-ostree compose rootfs --source-root=/repos /path/to/input_manifest.yml /path/to/target_rootfs
+rpm-ostree compose build-chunked-oci --bootc --format-version=1 --rootfs=/path/to/target_rootfs \
+           --output containers-storage:quay.io/exampleos/exampleos:latest
+podman push quay.io/exampleos/exampleos:latest
+```

docs/container.md

@@ -146,15 +146,17 @@ In the future, this command may perform more operations.
 There is now an `rpm-ostree compose image` command which generates a new base image using a treefile:
 
 ```
-$ rpm-ostree compose image --initialize-mode=if-not-exists --format=ociarchive workstation-ostree-config/fedora-silverblue.yaml fedora-silverblue.ociarchive
+$ rpm-ostree compose image --initialize-mode=if-not-exists --format=ociarchive \
+             workstation-ostree-config/fedora-silverblue.yaml fedora-silverblue.ociarchive
 ```
 
 The `--initialize-mode=if-not-exists` command here is what you almost always want: to create
 the image if it doesn't exist, but to otherwise check for changes.  It isn't the default
 for historical reasons.
 
 ```
-$ rpm-ostree compose image  --initialize-mode=if-not-exists --format=registry workstation-ostree-config/fedora-silverblue.yaml quay.io/example/exampleos:latest
+$ rpm-ostree compose image  --initialize-mode=if-not-exists --format=registry \
+             workstation-ostree-config/fedora-silverblue.yaml quay.io/example/exampleos:latest
 ```
 
 ## Adding container image configuration
@@ -201,25 +203,39 @@ In ostree upstream, there is a simplistic CLI (and API) that "encapsulates"
 a commit into a container image with a *single layer*:
 
 ```
-$ ostree container encapsulate --repo=/path/to/repo fedora/35/x86_64/silverblue docker://quay.io/myuser/fedora-silverblue:35
+$ ostree container encapsulate --repo=/path/to/repo fedora/35/x86_64/silverblue \
+         docker://quay.io/myuser/fedora-silverblue:35
 ```
 
 The `encapsulate` command accepts all the same "transport prefixes" as the `skopeo`
 CLI.  For more information, see `man skopeo`.
 
-However, this "single layer" is not an efficient way to deliver content.  It means
-that any time anything in the ostree commit changes, clients need to download
-a full new tarball.
+## Creating chunked images
 
-The ostree shared library has low level APIs that support creating reproducible
-"chunked" images.  A key adavantage of this is that if e.g. just the kernel
-changes, one only downloads the layer containing the kernel/initramfs
-(plus a metadata layer) instead of everything.
+The "single layer" image produced by `ostree container encapsulate`
+above is not an efficient way to deliver content.  It means that any
+time anything in the ostree commit changes, clients need to download a
+full new tarball.
+
+The ostree shared library has low level APIs that support creating
+reproducible "chunked" images.  A key adavantage of this is that if
+e.g. just the kernel changes, one only downloads the layer containing
+the kernel/initramfs (plus a metadata layer) instead of everything.
+The algorithm uses generalized heuristics to pack the image content
+together (primarily consulting RPM metadata) into a number of layers
+in order to minimize the amount of data/layers modified when producing
+updated images in the future.  The `--max-layers` option may be
+supplied to specify the number of layers; if not specified this
+defaults to a maximum of 64 layers.
 
 Use a command like this to generate chunked images:
 
 ```
-$ rpm-ostree compose container-encapsulate --repo=/path/to/repo fedora/35/x86_64/silverblue docker://quay.io/myuser/fedora-silverblue:35
+$ rpm-ostree compose container-encapsulate --repo=/path/to/repo fedora/35/x86_64/silverblue \
+             docker://quay.io/myuser/fedora-silverblue:35
 ```
 
 This "chunked" format is used by default by `rpm-ostree compose image`.
+
+You can also create chunked images from pre-existing (typically
+single-layer) images using [`rpm-ostree compose build-chunked-oci`](https://coreos.github.io/rpm-ostree/build-chunked-oci/).