Skip to content

Commit

Permalink
docs: Various updates and fixes
Browse files Browse the repository at this point in the history
I went through the docs and cleaned some things up, fixed
some missing content, etc.

Also a patch to `xtask` to make it so that `cargo xtask manpages`
works even when $PWD is in `docs`.

Signed-off-by: Colin Walters <[email protected]>
  • Loading branch information
cgwalters committed Mar 28, 2024
1 parent 1707bdd commit 0adfb4a
Show file tree
Hide file tree
Showing 17 changed files with 208 additions and 88 deletions.
53 changes: 1 addition & 52 deletions docs/src/bootc-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,58 +128,7 @@ The bootc project aims to support generic/general-purpose operating
systems and distributions that will ship unconfigured images. An
unconfigured image does not have a default password or SSH key, etc.

There are two fundamental ways to handle this:

### Using cloud-init type flows

Some operating systems may come with `cloud-init` or similar tools
that know how to e.g. inject SSH keys or external configuration.

Other tools in this space are:

- [systemd-firstboot](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
- [gnome-initial-setup](https://gitlab.gnome.org/GNOME/gnome-initial-setup)

The general idea here is that things like users, passwords and ssh keys
are dynamically created on first boot (and in general managed per-system);
the configuration comes from a place *external* to the image.

### Injecting configuration into a custom image

But a new super-power with `bootc` is that you can also easily
create a derived container that injects your desired configuration,
alongside any additional executable code (binaries, packages, scripts, etc).

The expectation is that most operating systems will be designed such
that user state i.e. `/root` and `/home` will be on a separate, persistent data store.
For example, in the default ostree model, `/root` is `/var/roothome`
and `/home` is `/var/home`. Content in `/var` cannot be shipped
in the image - it is per machine state.

#### Injecting SSH keys in a container image

In the following example, we will configure OpenSSH to read the
set of authorized keys for the root user from content
that lives in `/usr` (i.e. is owned by the container image).
We will also create a `/usr/etc-system` directory which is intentionally distinct
from the default ostree `/etc` which may be locally writable.

The `AuthorizedKeysFile` invocation below then configures sshd to look
for keys in this location.

```Dockerfile
FROM <image>
RUN mkdir -p /usr/etc-system/ && \
echo 'AuthorizedKeysFile /usr/etc-system/%u.keys' >> /etc/ssh/sshd_config.d/30-auth-system.conf && \
echo 'ssh-ed25519 AAAAC3Nza... [email protected]' > /usr/etc-system/root.keys && chmod 0600 /usr/etc-system/root.keys && \
ostree container commit
```

A key point here is that now the set of authorized keys is "owned"
by the container image - it will be read-only at runtime because
the files are underneath `/usr`. To rotate or change the set of keys,
one would build a new container image. Client systems using `bootc upgrade`
will transactionally update to this new system state.
For more information, see [Image building and configuration guidance](building/guidance.md).

## More advanced installation with `to-filesystem`

Expand Down
9 changes: 9 additions & 0 deletions docs/src/man-md/bootc-fetch-apply-updates-service.md
Original file line number Diff line number Diff line change
@@ -1 +1,10 @@
# man bootc-fetch-apply-updates.service

This systemd service and associated `.timer` unit simply invoke
`bootc upgrade --apply`. It is a minimal demonstration of
an "upgrade agent".

More information: [bootc-upgrade](../man/bootc-upgrade.md).

The systemd unit is not enabled by default upstream, but it
may be enabled in some operating systems.
2 changes: 1 addition & 1 deletion docs/src/man/bootc-edit.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,4 @@ Only changes to the \`spec\` section are honored.

# VERSION

v0.1.0
v0.1.9
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-print-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`.

# VERSION

v0.1.0
v0.1.9
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-disk.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,4 @@ firmware will be skipped

# VERSION

v0.1.0
v0.1.9
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-existing-root.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,4 +123,4 @@ firmware will be skipped

# VERSION

v0.1.0
v0.1.9
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-filesystem.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,4 @@ mounting. To override this, use \`\--root-mount-spec\`.

# VERSION

v0.1.0
v0.1.9
22 changes: 18 additions & 4 deletions docs/src/man/bootc-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,23 @@ bootc-install - Install the running container to a target

Install the running container to a target.

This has two main sub-commands \`to-disk\` (which expects an empty block
device) and \`to-filesystem\` which supports installation to an already
extant filesystem.
## Understanding installations

OCI containers are effectively layers of tarballs with JSON for
metadata; they cannot be booted directly. The \`bootc install\` flow is
a highly opinionated method to take the contents of the container image
and install it to a target block device (or an existing filesystem) in
such a way that it can be booted.

For example, a Linux partition table and filesystem is used, and the
bootloader and kernel embedded in the container image are also prepared.

A bootc installed container currently uses OSTree as a backend, and this
sets it up such that a subsequent \`bootc upgrade\` can perform in-place
updates.

An installation is not simply a copy of the container filesystem, but
includes other setup and metadata.

# OPTIONS

Expand Down Expand Up @@ -51,4 +65,4 @@ bootc-install-help(8)

# VERSION

v0.1.0
v0.1.9
41 changes: 41 additions & 0 deletions docs/src/man/bootc-rollback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# NAME

bootc-rollback - Change the bootloader entry ordering; the deployment
under \`rollback\` will be queued for the next boot, and the current
will become rollback. If there is a \`staged\` entry (an unapplied,
queued upgrade) then it will be discarded

# SYNOPSIS

**bootc-rollback** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\]

# DESCRIPTION

Change the bootloader entry ordering; the deployment under \`rollback\`
will be queued for the next boot, and the current will become rollback.
If there is a \`staged\` entry (an unapplied, queued upgrade) then it
will be discarded.

Note that absent any additional control logic, if there is an active
agent doing automated upgrades (such as the default
\`bootc-fetch-apply-updates.timer\` and associated \`.service\`) the
change here may be reverted. Its recommended to only use this in concert
with an agent that is in active control.

A systemd journal message will be logged with
\`MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468\` in order to detect a
rollback invocation.

# OPTIONS

**-h**, **\--help**

: Print help (see a summary with -h)

**-V**, **\--version**

: Print version

# VERSION

v0.1.9
2 changes: 1 addition & 1 deletion docs/src/man/bootc-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ The exact API format is not currently declared stable.

# VERSION

v0.1.0
v0.1.9
15 changes: 12 additions & 3 deletions docs/src/man/bootc-switch.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,17 @@ bootc-switch - Target a new container image reference to boot

Target a new container image reference to boot.

This operates in a very similar fashion to \`upgrade\`, but changes the
container image reference instead.
This is almost exactly the same operation as \`upgrade\`, but
additionally changes the container image reference instead.

## Usage

A common pattern is to have a management agent control operating system
updates via container image tags; for example,
\`quay.io/exampleos/someuser:v1.0\` and
\`quay.io/exampleos/someuser:v1.1\` where some machines are tracking
\`:v1.0\`, and as a rollout progresses, machines can be switched to
\`v:1.1\`.

# OPTIONS

Expand Down Expand Up @@ -56,4 +65,4 @@ includes a default policy which requires signatures.

# VERSION

v0.1.0
v0.1.9
5 changes: 3 additions & 2 deletions docs/src/man/bootc-upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ upgrade \--apply\` verb which will automatically take action (rebooting)
if the system has changed.

However, in the future this is likely to change such that reboots
outside of a \`bootc upgrade \--apply\` do \*not\* upgrade.
outside of a \`bootc upgrade \--apply\` do \*not\* automatically apply
the update in addition.

# OPTIONS

Expand Down Expand Up @@ -55,4 +56,4 @@ userspace-only restart.

# VERSION

v0.1.0
v0.1.9
29 changes: 24 additions & 5 deletions docs/src/man/bootc-usr-overlay.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# NAME

bootc-usr-overlay - Add a transient writable overlayfs on \`/usr\` that
bootc-usr-overlay - Adds a transient writable overlayfs on \`/usr\` that
will be discarded on reboot

# SYNOPSIS
Expand All @@ -9,19 +9,38 @@ will be discarded on reboot

# DESCRIPTION

Add a transient writable overlayfs on \`/usr\` that will be discarded on
reboot
Adds a transient writable overlayfs on \`/usr\` that will be discarded
on reboot.

## Use cases

A common pattern is wanting to use tracing/debugging tools, such as
\`strace\` that may not be in the base image. A system package manager
such as \`apt\` or \`dnf\` can apply changes into this transient overlay
that will be discarded on reboot.

## /etc and /var

However, this command has no effect on \`/etc\` and \`/var\` - changes
written there will persist. It is common for package installations to
modify these directories.

## Unmounting

Almost always, a system process will hold a reference to the open mount
point. You can however invoke \`umount -l /usr\` to perform a \"lazy
unmount\".

# OPTIONS

**-h**, **\--help**

: Print help
: Print help (see a summary with -h)

**-V**, **\--version**

: Print version

# VERSION

v0.1.0
v0.1.9
20 changes: 18 additions & 2 deletions docs/src/man/bootc.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ images

# SYNOPSIS

**bootc** \[**-h**\|**\--help**\] \<*subcommands*\>
**bootc** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\]
\<*subcommands*\>

# DESCRIPTION

Expand All @@ -25,6 +26,10 @@ Changes in \`/etc\` and \`/var\` persist.

: Print help (see a summary with -h)

**-V**, **\--version**

: Print version

# SUBCOMMANDS

bootc-upgrade(8)
Expand All @@ -35,6 +40,13 @@ bootc-switch(8)

: Target a new container image reference to boot

bootc-rollback(8)

: Change the bootloader entry ordering; the deployment under
\`rollback\` will be queued for the next boot, and the current will
become rollback. If there is a \`staged\` entry (an unapplied,
queued upgrade) then it will be discarded

bootc-edit(8)

: Apply full changes to the host specification
Expand All @@ -45,7 +57,7 @@ bootc-status(8)

bootc-usr-overlay(8)

: Add a transient writable overlayfs on \`/usr\` that will be
: Adds a transient writable overlayfs on \`/usr\` that will be
discarded on reboot

bootc-install(8)
Expand All @@ -55,3 +67,7 @@ bootc-install(8)
bootc-help(8)

: Print this message or the help of the given subcommand(s)

# VERSION

v0.1.9
23 changes: 18 additions & 5 deletions docs/src/upgrades.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,34 @@ There is also an opinionated `bootc-fetch-apply-updates.timer` and corresponding
service available in upstream for operating systems and distributions
to enable.

Man page: [bootc-upgrade](man/bootc-upgrade.md).

## Changing the container image source

Another useful pattern to implement can be to use a management agent
to invoke `bootc switch` to implement e.g. blue/green deployments,
to invoke `bootc switch` (or declaratively via `bootc edit`)
to implement e.g. blue/green deployments,
where some hosts are rolled onto a new image independently of others.

```shell
bootc switch quay.io/examplecorp/os-prod-blue:lastest
bootc switch quay.io/examplecorp/os-prod-blue:latest
```

`bootc switch` has the same effect as `bootc upgrade`; there is no
semantic difference between the two other than changing the
container image being tracked.

This will preserve existing state in `/etc` and `/var` - for example,
host SSH keys and home directories.

Man page: [bootc-switch](man/bootc-switch.md).

## Rollback

At the current time, bootc does not ship with an opinionated integrated
rollback flow. However, bootc always maintains (by default) a
`rollback` container image that is accessible via `bootc status`.
There is a `bootc rollback` verb, and associated declarative interface
accessible to tools via `bootc edit`. This will swap the bootloader
ordering to the previous boot entry.

Man page: [bootc-rollback](man/bootc-rollback.md).


Loading

0 comments on commit 0adfb4a

Please sign in to comment.