Skip to content

Commit

Permalink
Merge pull request #840 from cgwalters/doc-containers-arch
Browse files Browse the repository at this point in the history
docs: Various elaborations
  • Loading branch information
jmarrero authored Oct 20, 2024
2 parents e12cd9d + 62772a6 commit 33fcf92
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 10 deletions.
9 changes: 8 additions & 1 deletion docs/src/filesystem-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,17 @@

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

```mermaid
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
Expand Down Expand Up @@ -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).
11 changes: 7 additions & 4 deletions docs/src/filesystem.md
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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

Expand Down
17 changes: 12 additions & 5 deletions docs/src/relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 33fcf92

Please sign in to comment.