public
/
bootc-base-images
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #172 from cgwalters/doc-partitioning 

usage: Describe filesystem semantics
This commit is contained in:
Colin Walters 2024-01-21 11:28:19 -05:00 committed by GitHub
parent 460ba40b76 c93512c6b1
commit 8245847221
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 42 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/usage.md
View File

@ -35,3 +35,45 @@ Then add it into your container:
RUN mkdir -p /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
COPY 50-weekly.conf /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
```
## Filesystem interaction and layout
At "build" time, this image runs the same as any other OCI image where
the default filesystem setup is an `overlayfs` for `/` that captures all
changes written - to anywhere.
However, the default runtime (when booted on a virtual or physical host system,
with systemd as pid 1) there are some rules around persistence and writability.
The reason for this is that the primary goal is that base operating system
changes (updating kernels, binaries, configuration) are managed in your container
image and updated via `bootc upgrade`.
In general, aim for most content in your container image to be underneath
the `/usr` filesystem. This is mounted read-only by default, and this
matches many other "immutable infrastructure" operating systems.
The `/etc` filesystem defaults to persistent and writable - and is the expected
place to put machine-local state (static IP addressing, hostnames, etc).
All other machine-local persistent data should live underneath `/var` by default;
for example, the default is for systemd to persist the journal to `/var/log/journal`.
### Understanding `root.transient``
At a technical level today, the base image uses the
[bootc](https://github.com/containers/bootc) project, which uses
[ostree](https://github.com/ostreedev/ostree) as a backend. However, unlike many
other ostree projects, this base image enables the `root.transient` feature from
[ostree-prepare-root](https://github.com/ostreedev/ostree/blob/main/man/ostree-prepare-root.xml#L121).
This has two primary effects:
- Content placed underneath `/var` at container build time is moved t
`/usr/share/factory/var`, and on firstboot, updated files are handled via a
systemd `tmpfiles.d` rule that copies new files (see
`/usr/lib/tmpfiles.d/ostree-tmpfiles.conf`)
- The default `/` filesystem is writable, but not persistent. All content added
in the container image in other toplevel directories (e.g. `/opt`) will be
refreshed from the new container image on updates, and any modifications will
be lost.