From 5ebd1722c5391e1310b39a4d2c609dd784da9ef6 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 10 Jul 2024 15:52:57 -0400 Subject: [PATCH] docs: Add new package-managers section with guidance - Talk about readonly `/usr` - Note how easy it is to do with podman - Give examples with both `apt` and `dnf` as the exist today - Include brief blurbs on transient and persistent changes Signed-off-by: Colin Walters --- docs/src/SUMMARY.md | 1 + docs/src/package-managers.md | 109 +++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 docs/src/package-managers.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 2a92e1c53..e6a6a8dc7 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -46,6 +46,7 @@ # More information +- [Package manager integration](package-managers.md) - [Relationship with other projects](relationships.md) - [Relationship with OCI artifacs](relationship-oci-artifacts.md) - [Relationship with systemd "particles"](relationship-particles.md) diff --git a/docs/src/package-managers.md b/docs/src/package-managers.md new file mode 100644 index 000000000..05557600a --- /dev/null +++ b/docs/src/package-managers.md @@ -0,0 +1,109 @@ +# Package manager integration + +A toplevel goal of bootc is to encourage a default model +where Linux systems are built and delivered as (container) images. +In this model, the default usage of package managers such as `apt` and `dnf` +will be at container build time. + +However, one may end up shipping the package manager tooling onto +the end system. In some cases this may be desirable even, to allow +workflows with transient overlays using e.g. `bootc usroverlay`. + +## Detecting image-based systems + +bootc is not the only image based system; there are many. A common +emphasis is on having the operating system content in `/usr`, +and for that filesystem to be mounted read-only at runtime. + +A first recommendation here is that package managers should +detect if `/usr` is read-only, and provide a useful error +message referring users to documentation guidance. + +An example of a non-bootc case is "Live CD" environments, +where the *physical media* is readonly. Some Live operating system environments end +up mounting a transient writable overlay (whether via e.g. devicemapper or overlayfs) +that make the system appear writable, but it's arguably clearer not to do so by +default. Detecting `/usr` as read-only here and providing the same information +would make sense. + +### Running a read-only system via podman/docker + +The historical default for docker (inherited into podman) is that +the `/` is a writable (but transient) overlayfs. However, e.g. `podman` +supports a `--read-only` flag, and [Kubernetes pods](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/) offer a +`securityContext.readOnlyRootFilesystem` flag. + +Running containers in production in this way is a good idea, +for exactly the same reasons that bootc defaults to mounting +the system read-only. + +Ensure that your package manager offers a useful error message +in this mode. Today for example: + +``` +$ podman run --read-only --rm -ti debian apt update +Reading package lists... Done +E: List directory /var/lib/apt/lists/partial is missing. - Acquire (30: Read-only file system) +$ podman run --read-only --rm -ti quay.io/fedora/fedora:40 dnf -y install strace +Config error: [Errno 30] Read-only file system: '/var/log/dnf.log': '/var/log/dnf.log' +``` + +However note that both of these fail on `/var` being read-only; in a default bootc +model, it won't be. A more accurate check is thus closer to: + +``` +$ podman run --read-only --rm -ti --tmpfs /var quay.io/fedora/fedora:40 dnf -y install strace +... +Error: Transaction test error: + installing package strace-6.9-1.fc40.x86_64 needs 2MB more space on the / filesystem +``` + +``` +$ podman run --read-only --rm --tmpfs /var -ti debian /bin/sh -c 'apt update && apt -y install strace' +... +dpkg: error processing archive /var/cache/apt/archives/libunwind8_1.6.2-3_amd64.deb (--unpack): + unable to clean up mess surrounding './usr/lib/x86_64-linux-gnu/libunwind-coredump.so.0.0.0' before installing another version: Read-only file system +``` + +These errors message are misleading and confusing for the user. A more useful error may look like e.g.: + +``` +$ podman run --read-only --rm --tmpfs /var -ti debian /bin/sh -c 'apt update && apt -y install strace' +error: read-only /usr detected, refusing to operate. See `man apt-image-based` for more information. +``` + +### Detecting bootc specifically + +You may also reasonably want to detect that the operating system is specifically +using `bootc`. This can be done via e.g.: + +`bootc status --format=json | jq -r .spec.image` + +If the output of that field is non-`null`, then the system is a bootc system +tracking the specified image. + +## Transient overlays + +Today there is a simple `bootc usroverlay` command that adds a transient writable overlayfs for `/usr`. +This makes many package manager operations work; conceptually it is similar +to the writable overlay that many "Live CDs" use. However, one cannot change the kernel +this way for example. + +An optional integration that package managers can do is to detect this transient overlay +situation and inform the user that the changes will be ephemeral. + +## Persistent changes + +A bootc system by default *does* have a writable, persistent data store that holds +multiple container image versions (more in [filesystem](filesystem.md)). + +Systems such as [rpm-ostree](https://github.com/coreos/rpm-ostree/) implement +a "hybrid" mechanism where packages can be persistently layered and re-applied; +the system effectively does a "local build", unioning the intermediate filesystems. + +One aspect of how rpm-ostree implements this is by caching individual unpacked RPMs as ostree commits +in the ostree repo. + +This section will be expanded later; you may also be able to find more information in [booting local builds](booting-local-builds.md). + +