From 62772a6abf859985a701b7bd0a5d57bac1709350 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Sat, 19 Oct 2024 14:50:59 +0000 Subject: [PATCH] docs: Various elaborations - Clarify c/storage instance and LBIs in multiple places - Flesh out/clarify some differences between bootc and rpm-ostree Signed-off-by: Colin Walters --- docs/src/filesystem-storage.md | 9 ++++++++- docs/src/filesystem.md | 11 +++++++---- docs/src/relationships.md | 17 ++++++++++++----- 3 files changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/src/filesystem-storage.md b/docs/src/filesystem-storage.md index 4b89f35ef..6bd77369d 100644 --- a/docs/src/filesystem-storage.md +++ b/docs/src/filesystem-storage.md @@ -2,7 +2,9 @@ The bootc project uses [ostree](https://github.com/ostreedev/ostree/) and specifically the [ostree-rs-ext](https://github.com/ostreedev/ostree-rs-ext/) Rust library -which handles storage of container images on top of an ostree-based system. +which handles storage of container images on top of an ostree-based system for +the booted host, and additionally there is a +[containers/storage](https://github.com/containers/storage) instance for [logically bound images](logically-bound-images.md). ## Architecture @@ -10,6 +12,7 @@ which handles storage of container images on top of an ostree-based system. flowchart TD bootc --- ostree-rs-ext --- ostree-rs --- ostree ostree-rs-ext --- containers-image-proxy-rs --- skopeo --- containers/image + bootc --- podman --- image-storage["containers/{image,storage}"] ``` There were two high level goals that drove the design of the current system @@ -88,3 +91,7 @@ from an OCI image or some other mechanism; it just targets a prepared flattened filesystem tree. This is what is referenced by the `ostree=` kernel commandline. + +## Logically bound images + +In addition to the base image, bootc supports [logically bound images](logically-bound-images.md). diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md index 578bf1a65..b7f14d2e9 100644 --- a/docs/src/filesystem.md +++ b/docs/src/filesystem.md @@ -1,9 +1,11 @@ # Filesystem -As noted in other chapters, the bootc project inherits -a lot of code from the [ostree project](https://github.com/ostreedev/ostree/). +As noted in other chapters, the bootc project currently +depends on [ostree project](https://github.com/ostreedev/ostree/) +for storing the base container image. Additionally there is a [containers/storage](https://github.com/containers/storage) instance for [logically bound images](logically-bound-images.md). -However, bootc is intending to be a "fresh, new container-native interface". +However, bootc is intending to be a "fresh, new container-native interface", +and ostree is an implementation detail. First, it is strongly recommended that bootc consumers use the ostree [composefs backend](https://ostreedev.github.io/ostree/composefs/); to do this, @@ -14,7 +16,8 @@ ensure that you have a `/usr/lib/ostree/prepare-root.conf` that contains at leas enabled = true ``` -This will ensure that the entire `/` is a read-only filesystem. +This will ensure that the entire `/` is a read-only filesystem which +is very important for achieving correct semantics. ## Understanding container build/runtime vs deployment diff --git a/docs/src/relationships.md b/docs/src/relationships.md index 49dffe53b..089b83e78 100644 --- a/docs/src/relationships.md +++ b/docs/src/relationships.md @@ -46,11 +46,18 @@ as a backing model. Hence, when using a container source, `rpm-ostree upgrade` and `bootc upgrade` are effectively equivalent; you can use either command. -However with rpm-ostree (or, perhaps re-framed as -"dnf image"), it will continue to work to e.g. `dnf install` -(i.e. `rpm-ostree install`) on the *client side* system. -In addition there are other client-side mutation commands such as -`rpm-ostree initramfs --enable`. +### Differences from rpm-ostree + +- The ostree project never tried to have an opinionated "install" mechanism, + but bootc does with `bootc install to-filesystem` +- Bootc has additional features such as `/usr/lib/bootc/kargs.d` and + [logically bound images](logically-bound-images.md). + +### Client side changes + +Currently all functionality for client-side changes +such as `rpm-ostree install` or `rpm-ostree initramfs --enable` +continue to work, because of the shared base. However, as soon as you mutate the system in this way, `bootc upgrade` will error out as it will not understand how to upgrade