From 06cd4197a366f24e5946483942ee108f0b868f63 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 29 Feb 2024 21:12:09 -0500 Subject: [PATCH] wip --- docs/faq.md | 17 ----- docs/index.md | 93 ----------------------- docs/src/SUMMARY.md | 2 + docs/src/bootc-images.md | 11 ++- docs/src/filesystem.md | 64 ++++++++++++++++ docs/{usage.md => src/offline-updates.md} | 13 +++- docs/src/relationship-oci-artifacts.md | 5 ++ docs/src/relationships.md | 8 +- 8 files changed, 89 insertions(+), 124 deletions(-) delete mode 100644 docs/faq.md delete mode 100644 docs/index.md rename docs/{usage.md => src/offline-updates.md} (65%) create mode 100644 docs/src/relationship-oci-artifacts.md diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 0c619f6a6..000000000 --- a/docs/faq.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -nav_order: 4 ---- - -# Frequently Asked Questions - -## How do users include their own packages/binaries in a custom "bootc compatible" container? - -The "bootc compatible" containers are OCI container images, so you can customize them in the same way you build containers today. This means using a Containerfile to customize your image and build tools like `buildah`, `podman build`, or `docker build` to generate your customized "bootc compatible" container image. - -For examples of how use build a "bootc compatible" base image, see the [centos-boot repo](https://github.com/CentOS/centos-boot) as a starting point. For examples of how to use a Containerfile to build a customized "bootc compatible" image, see the [centos-boot-layered repo](https://github.com/CentOS/centos-boot-layered). - -## How does the use of OCI artifacts intersect with this effort? - -The "bootc compatible" images are OCI container images; they do not rely on the [OCI artifact specification](https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md) or [OCI referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#enabling-the-referrers-api). - -It is foreseeable that users will need to produce "traditional" disk images (i.e. raw disk images, qcow2 disk images, Amazon AMIs, etc.) from the "bootc compatible" container images using additional tools. Therefore, it is reasonable that some users may want to encapsulate those disk images as an OCI artifact for storage and distribution. However, it is not a goal to use `bootc` to produce these "traditional" disk images nor to facilitate the encapsulation of those disk images as OCI artifacts. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 42ce43c64..000000000 --- a/docs/index.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -nav_order: 1 ---- - -# bootc - -Transactional, in-place operating system updates using OCI/Docker container images. - -STATUS: Stable enough for dev/test by interested parties, but all interfaces are subject to change. - -# Motivation - -The original Docker container model of using "layers" to model -applications has been extremely successful. This project -aims to apply the same technique for bootable host systems - using -standard OCI/Docker containers as a transport and delivery format -for base operating system updates. - -The container image includes a Linux kernel (in e.g. `/usr/lib/modules`), -which is used to boot. At runtime on a target system, the base userspace is -*not* itself running in a container by default. For example, assuming -systemd is in use, systemd acts as pid1 as usual - there's no "outer" process. - -## ostree - -This project currently leverages significant work done in -[the ostree project](https://github.com/ostreedev/ostree-rs-ext/). - -In the future, there may be non-ostree backends. - -## Modeling operating system hosts as containers - -The bootc project suggests that Linux operating systems and distributions -to provide a new kind of "bootable" base image, distinct from "application" -base images. See below for available images. - -Effectively, these images contain a Linux kernel - and while this kernel -is not used when the image is used via e.g. `podman|docker run`, it *is* -used when booted via `bootc`. - -In the current defaults, `/etc` and `/var` both act a bit like -mounted, persistent volumes. -More on this in [the ostree docs](https://ostreedev.github.io/ostree/adapting-existing/#system-layout). - -## Status - -The core `bootc update` functionality is really just the same -technology which has shipped for some time in rpm-ostree so there -should be absolutely no worries about using it for OS updates. -A number of people do this today. - -That said bootc is in active development and some parts -are subject to change, such as the command line interface and -the CRD-like API exposed via `bootc edit`.` - -The `bootc install` functionality is also more experimental. - -## Using bootc - -To build base images "from scratch", see [bootc-images.md](bootc-images.md). - -### Deriving from and switching to base images - -A toplevel goal is that *every tool and technique* a Linux system -administrator knows around how to build, inspect, mirror and manage -application containers also applies to bootable host systems. - -There are a number of examples in e.g. [coreos/layering-examples](https://github.com/coreos/layering-examples). - -First, build a derived container using any container build tooling. - -#### Using `bootc install` - -The `bootc install` command has two high level sub-commands; `to-disk` and `to-filesystem`. - -The `bootc install to-disk` handles basically everything in taking the current container -and writing it to a disk, and set it up for booting and future in-place upgrades. - -In brief, the idea is that every container image shipping `bootc` also comes with a simple -installer that can set a system up to boot from it. Crucially, if you create a -*derivative* container image from a stock OS container image, it also automatically -supports `bootc install`. - -For more information, please see [install.md](install.md) as well as the [../manpages-md/bootc-install.md] manpage. - - - -# More links - -- [rpm-ostree container](https://coreos.github.io/rpm-ostree/container/) -- [centos-boot](https://github.com/centos/centos-boot) -- [coreos/layering-examples](https://github.com/coreos/layering-examples) - diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 429ad0597..cf2b5e989 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -9,6 +9,7 @@ # Using bootc - [Upgrade and rollback](upgrades.md) +- [Offline/disconnected updates](offline-updates.md) - [`man bootc`](man/bootc.md) - [`man bootc status`](man/bootc-status.md) - [`man bootc upgrade`](man/bootc-upgrade.md) @@ -32,4 +33,5 @@ # More information - [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/bootc-images.md b/docs/src/bootc-images.md index 0bfbaef6e..3c7363545 100644 --- a/docs/src/bootc-images.md +++ b/docs/src/bootc-images.md @@ -11,7 +11,7 @@ or ```Dockerfile FROM debian -RUN apt install kernel +RUN apt install linux ``` And get an image compatible with bootc. Supporting any base image @@ -72,9 +72,8 @@ You can then use `podman build`, `buildah`, `docker build`, or any other contain build tool to produce your customized image. The only requirement is that the container build tool supports producing OCI container images. -## Using the `ostree container commit` command +## The `ostree container commit` command + +You may find some references to this; it is no longer very useful +and is not recommended. -As an opt-in optimization today, you can also add `ostree container commit` -as part of your `RUN` invocations. This will perform early detection -of some incompatibilities but is not a strict requirement today and will not be -in the future. diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md index 6d41ab86f..ed9b4f7ed 100644 --- a/docs/src/filesystem.md +++ b/docs/src/filesystem.md @@ -1 +1,65 @@ # Filesystem + +As noted in other chapters, the bootc project inherits +a lot of code from the [ostree project](https://github.com/ostreedev/ostree/). + +However, bootc is intending to be a "fresh, new container-native interface". + +First, it is strongly recommended that bootc consumers use the ostree +[composefs backend](https://ostreedev.github.io/ostree/composefs/); to do this, +ensure that you have a `/usr/lib/ostree/prepare-root.conf` that contains at least + +```ini +[composefs] +enabled = true +``` + +This will ensure that the entire `/` is a read-only filesystem. + +## `/usr` + +The overall recommendation is to keep all operating system content in `/usr`. See [UsrMove](https://fedoraproject.org/wiki/Features/UsrMove) for example. + +## `/etc` + +The `/etc` directory contains persistent state by default; however, +it is suppported to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html). + +When in persistent mode, it inherits the OSTree semantics of [performing a 3-way merge](https://ostreedev.github.io/ostree/atomic-upgrades/#assembling-a-new-deployment-directory) +across upgrades. + +## `/var` + +Content in `/var` persists by default; it is however supported to make it or subdirectories +mount points (whether network or `tmpfs`) + +As of OSTree v2024.3, by default [content in /var acts like a Docker VOLUME /var](https://github.com/ostreedev/ostree/pull/3166/commits/f81b9fa1666c62a024d5ca0bbe876321f72529c7). + +This means that the content from the container image is copied at *initial installation time*, and not updated thereafter. + +## Other directories + +It is not supported to ship content in `/run` or `/proc` or other [API Filesystems](https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems/) in container images. + +Besides those, for other toplevel directories such as `/usr` `/opt`, they will be lifecycled with the container image. + +### `/opt` + +In the default suggested model of using composefs (per above) the `/opt` directory will be read-only, alongside +other toplevels such as `/usr`. + +Some software expects to be able to write to its own directory in `/opt/exampleapp`. For these +cases, there are several options (containerizing the app, running it in a system unit that sets up custom mounts, etc.) + +#### Enabling transient root + +However, some use cases may find it easier to enable a fully transient writable rootfs by default. +To do this, set the + +``` +[root] +transient = true +``` + +option in `prepare-root.conf`. In particular this will allow software to write (transiently) to `/opt`, +with symlinks to `/var` for content that should persist. \ No newline at end of file diff --git a/docs/usage.md b/docs/src/offline-updates.md similarity index 65% rename from docs/usage.md rename to docs/src/offline-updates.md index 0ec7e736b..2bfe2037f 100644 --- a/docs/usage.md +++ b/docs/src/offline-updates.md @@ -1,8 +1,13 @@ ---- -nav_order: 3 ---- +# Mirrored/disconnected upgrades -# Managing bootc systems +It is common (a best practice even) to maintain systems which default +to being disconnected from the public Internet. + +## Pulling updates from a local mirror + +The bootc project reuses the same container libraries that are in use by `podman`; +this means that configuring [containers-registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md) +allows `bootc upgrade` to fetch from local mirror registries. ## Performing offline updates via USB diff --git a/docs/src/relationship-oci-artifacts.md b/docs/src/relationship-oci-artifacts.md new file mode 100644 index 000000000..5c1ec7f5b --- /dev/null +++ b/docs/src/relationship-oci-artifacts.md @@ -0,0 +1,5 @@ +# How does the use of OCI artifacts intersect with this effort? + +The "bootc compatible" images are OCI container images; they do not rely on the [OCI artifact specification](https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md) or [OCI referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#enabling-the-referrers-api). + +It is foreseeable that users will need to produce "traditional" disk images (i.e. raw disk images, qcow2 disk images, Amazon AMIs, etc.) from the "bootc compatible" container images using additional tools. Therefore, it is reasonable that some users may want to encapsulate those disk images as an OCI artifact for storage and distribution. However, it is not a goal to use `bootc` to produce these "traditional" disk images nor to facilitate the encapsulation of those disk images as OCI artifacts. diff --git a/docs/src/relationships.md b/docs/src/relationships.md index fe598cb7b..75e724c24 100644 --- a/docs/src/relationships.md +++ b/docs/src/relationships.md @@ -1,7 +1,3 @@ ---- -nav_order: 5 ---- - # Relationship with other projects ## Relationship with podman @@ -28,6 +24,10 @@ In other words, if you configure `podman` to pull images from your local mirror The simple way to say it is: A goal of `bootc` is to be the bootable-container analogue for `podman`, which runs application containers. Everywhere one might run `podman`, one could also consider using `bootc`. +## Relationship with Image Builder (osbuild) + +There is a new [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) project that is dedicated to the intersection of these two! + ## Relationship with Kubernetes Just as `podman` does not depend on a Kubernetes API server, `bootc` will also not depend on one.