Skip to content

Commit

Permalink
docs: Even more about how bootc is not a container at runtime
Browse files Browse the repository at this point in the history
This is definitely the #1 confusion many people have to start;
it's very understandable!  Because in theory we *could* have
a runtime and a larger role, but it was an explicit choice
not to do that.

Signed-off-by: Colin Walters <walters@verbum.org>
  • Loading branch information
cgwalters committed Jun 16, 2024
1 parent 2138aa0 commit e4eedcc
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 5 deletions.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ 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
*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.
More about this in the docs; see below.

## Status

Expand Down
13 changes: 9 additions & 4 deletions docs/src/building/bootc-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,16 @@ Fundamentally, `bootc` reuses the [OCI image format](https://github.com/opencont
as a way to transport serialized filesystem trees with included metadata such as a `version`
label, etc.

However, `bootc` generally ignores the [Container configuration](https://github.com/opencontainers/image-spec/blob/main/config.md)
section at runtime today.
A bootc container operates in two basic modes. First, when invoked by a container run time such as `podman` or `docker` (typically as part of a build process), the bootc container behaves exactly the same as any other container. For exmaple, although there is a kernel embedded in the container image, it is not executed - the host kernel is used. There's no additional mount namespaces, etc. Ultimately, the container runtime is in full control here.

Container runtimes like `podman` and `docker` of course *will* interpret this metadata
when running a bootc container image as a container.
The second, and most important mode of operation is when a bootc container is installed to a physical or virtual machine. Here, bootc is in control; the container runtime used to build is no longer relevant. However, it's *very* important to understand that bootc's role is quite limited:

- On boot, there is code in the initramfs to do a "chroot" equivalent into the target filesystem root
- On upgrade, bootc will fetch new content, but this will not affect the running root

Crucially, besides setting up some mounts, bootc itself does not act as any kind of "container runtime". It does not set up pid or other namespace, does not change cgroups, etc. That remains the role of other code (typically systemd). `bootc` is not a persistent daemon by default; it does not impose any runtime overhead.

Another example of this: While one can add [Container configuration](https://github.com/opencontainers/image-spec/blob/main/config.md) metadata, `bootc` generally ignores that at runtime today.

## Labels

Expand Down

0 comments on commit e4eedcc

Please sign in to comment.