diff --git a/README.md b/README.md index 92fda7152..c55905fb0 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ Transactional, in-place operating system updates using OCI/Docker container images. -STATUS: Experimental, subject to change! - # Motivation The original Docker container model of using "layers" to model @@ -17,171 +15,6 @@ 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 - -### Installing - - * Fedora: [bootc is packaged](https://bodhi.fedoraproject.org/updates/?packages=bootc) and be available in the main repositories soon. - * CentOS Stream 9: There is a [COPR](https://copr.fedorainfracloud.org/coprs/rhcontainerbot/bootc/) tracking git main with binary packages. - -You can also build this project like any other Rust project, e.g. `cargo build --release` from a git clone. - -### Base images - -Many users will be more interested in base (container) images. - -To build base images "from scratch", see [docs/bootc-images.md](docs/bootc-images.md). - -For pre-built base images: - -* [Fedora CoreOS](https://quay.io/repository/fedora/fedora-coreos) can be used as a base image; you will need to [enable bootc](https://github.com/coreos/rpm-ostree/blob/main/docs/bootc.md) there. -* There is also an in-development [Project Sagano](https://github.com/centos/sagano) for Fedora/CentOS. - -However, bootc itself is not tied to Fedora derivatives; [this issue](https://github.com/coreos/bootupd/issues/468) tracks the main blocker for other distributions. - -### 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 will write the current container to a disk, and set it up for booting. -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 [docs/install.md](docs/install.md). - -#### Switching from an existing ostree-based system - -If you have [an operating system already using ostree](https://ostreedev.github.io/ostree/#operating-systems-and-distributions-using-ostree) then you can use `bootc switch`: - -``` -$ bootc switch --no-signature-verification quay.io/examplecorp/custom:latest -``` - -This will preserve existing state in `/etc` and `/var` - for example, -host SSH keys and home directories. There may be some issues with uid/gid -drift in this scenario however. - -### Upgrading - -Once a chosen container image is used as the boot source, further -invocations of `bootc upgrade` will look for newer versions - again -preserving state. - -## Relationship with other projects - -### Relationship with podman - -It gets a bit confusing to talk about shipping bootable operating systems in container images. -Again, to be clear: we are reusing container images as: - -- A build mechanism (including running *as* a standard OCI container image) -- A transport mechanism - -But, actually when a bootc container is booted, podman (or docker, etc.) is not involved. -The storage used for the operating system content is distinct from `/var/lib/containers`. -`podman image prune --all` will not delete your operating system. - -That said, a toplevel goal of bootc is alignment with the https://github.com/containers ecosystem, -which includes podman. But more specifically at a technical level, today bootc uses -[skopeo](https://github.com/containers/skopeo/) and hence indirectly [containers/image](https://github.com/containers/image) -as a way to fetch container images. - -This means that bootc automatically also honors many of the knobs available in `/etc/containers` - specifically -things like [containers-registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md). - -In other words, if you configure `podman` to pull images from your local mirror registry, then `bootc` will automatically honor that as well. - -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 Kubernetes - -Just as `podman` does not depend on a Kubernetes API server, `bootc` will also not depend on one. - -However, there are also plans for `bootc` to also understand Kubernetes API types. See [configmap/secret support](https://github.com/containers/bootc/issues/22) for example. - -Perhaps in the future we may actually support some kind of `Pod` analogue for representing the host state. Or we may define a [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) which can be used inside and outside of Kubernetes. - -### Relationship with rpm-ostree - -Today rpm-ostree directly links to `ostree-rs-ext`, and hence -gains all the same container functionality. This will likely -continue. For example, 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. However, `bootc upgrade` would -(should) then error out as it will not understand how to upgrade -the system. - -rpm-ostree also has significant other features such as -`rpm-ostree kargs` etc. - -Overall, rpm-ostree is used in several important projects -and will continue to be maintained for many years to come. - -However, for use cases which want a "pure" image based model, -using `bootc` will be more appealing. bootc also does not -e.g. drag in dependencies on `libdnf` and the RPM stack. - -bootc also has the benefit of starting as a pure Rust project; -and while it [doesn't have an IPC mechanism today](https://github.com/containers/bootc/issues/4), the surface -of such an API will be significantly smaller. - -Further, bootc does aim to [include some of the functionality of zincati](https://github.com/containers/bootc/issues/5). - -But all this said: *It will be supported to use both bootc and rpm-ostree together*; they are not exclusive. -For example, `bootc status` at least will still function even if packages are layered. - -### Relationship with Fedora CoreOS (and Silverblue, etc.) - -Per above, it is a toplevel goal to support a seamless, transactional update from existing OSTree based systems, which includes these Fedora derivatives. - -For Fedora CoreOS specifically, see [this tracker issue](https://github.com/coreos/fedora-coreos-tracker/issues/1446). - -See also [OstreeNativeContainerStable](https://fedoraproject.org/wiki/Changes/OstreeNativeContainerStable). - -# More links - -- https://coreos.github.io/rpm-ostree/container/ -- https://github.com/coreos/layering-examples +# More information +See the [project documentation](https://containers.github.io/bootc/). diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 000000000..7b0e21019 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,58 @@ +title: containers/bootc +description: bootc documentation +baseurl: "/bootc" +url: "https://containers.github.io" +# Comment above and use below for local development +# url: "http://localhost:4000" +permalink: /:title/ +markdown: kramdown +kramdown: + typographic_symbols: + ndash: "--" + mdash: "---" + +# Exclude the README and the bundler files that would normally be +# ignored by default. +exclude: + - README.md + - Gemfile + - Gemfile.lock + - prep-docs.sh + - vendor/ + +# These are copies of the apidoc/html and man/html directories. Run +# prep-docs.sh before jekyll to put it in place. +include: [reference, man] + +remote_theme: just-the-docs/just-the-docs@v0.4.1 +plugins: + - jekyll-remote-theme + +color_scheme: coreos + +# Aux links for the upper right navigation +aux_links: + "bootc on GitHub": + - "https://github.com/containers/bootc" + +footer_content: "Copyright © Red Hat, Inc. and others." + +# Footer last edited timestamp +last_edit_timestamp: true +last_edit_time_format: "%b %e %Y at %I:%M %p" + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true +gh_edit_link_text: "Edit this page on GitHub" +gh_edit_repository: "https://github.com/containers/bootc" +gh_edit_branch: "main" +gh_edit_source: docs +gh_edit_view_mode: "tree" + +compress_html: + clippings: all + comments: all + endings: all + startings: [] + blanklines: false + profile: false \ No newline at end of file diff --git a/docs/bootc-images.md b/docs/bootc-images.md index aa9b3beec..05704f44b 100644 --- a/docs/bootc-images.md +++ b/docs/bootc-images.md @@ -1,4 +1,8 @@ -# Understanding "bootc compatible" images +--- +nav_order: 2 +--- + +# "bootc compatible" images At the current time, it does not work to just do: ``` diff --git a/docs/index.md b/docs/index.md index d788ace88..9410b3612 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,191 @@ nav_order: 1 --- -# Rationale +# bootc -The bootc project starts from a basic premise: Docker/OCI style containers -are successful, what if we supported putting a Linux kernel binary inside -one too, and created client tooling (like `docker`/`podman`) that understood -how to use container images for in-place transactional (default stateful) -operating system upgrades. +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 + +### Installing + + * Fedora: [bootc is packaged](https://bodhi.fedoraproject.org/updates/?packages=bootc) and be available in the main repositories soon. + * CentOS Stream 9: There is a [COPR](https://copr.fedorainfracloud.org/coprs/rhcontainerbot/bootc/) tracking git main with binary packages. + +You can also build this project like any other Rust project, e.g. `cargo build --release` from a git clone. + +### Base images + +Many users will be more interested in base (container) images. + +To build base images "from scratch", see [bootc-images.md](bootc-images.md). + +For pre-built base images: + +* [Fedora CoreOS](https://quay.io/repository/fedora/fedora-coreos) can be used as a base image; you will need to [enable bootc](https://github.com/coreos/rpm-ostree/blob/main/docs/bootc.md) there. +* There is also an in-development [Project Sagano](https://github.com/centos/sagano) for Fedora/CentOS. + +However, bootc itself is not tied to Fedora derivatives; [this issue](https://github.com/coreos/bootupd/issues/468) tracks the main blocker for other distributions. + +### 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 will write the current container to a disk, and set it up for booting. +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). + +#### Switching from an existing ostree-based system + +If you have [an operating system already using ostree](https://ostreedev.github.io/ostree/#operating-systems-and-distributions-using-ostree) then you can use `bootc switch`: + +``` +$ bootc switch --no-signature-verification quay.io/examplecorp/custom:latest +``` + +This will preserve existing state in `/etc` and `/var` - for example, +host SSH keys and home directories. There may be some issues with uid/gid +drift in this scenario however. + +### Upgrading + +Once a chosen container image is used as the boot source, further +invocations of `bootc upgrade` will look for newer versions - again +preserving state. + +## Relationship with other projects + +### Relationship with podman + +It gets a bit confusing to talk about shipping bootable operating systems in container images. +Again, to be clear: we are reusing container images as: + +- A build mechanism (including running *as* a standard OCI container image) +- A transport mechanism + +But, actually when a bootc container is booted, podman (or docker, etc.) is not involved. +The storage used for the operating system content is distinct from `/var/lib/containers`. +`podman image prune --all` will not delete your operating system. + +That said, a toplevel goal of bootc is alignment with the https://github.com/containers ecosystem, +which includes podman. But more specifically at a technical level, today bootc uses +[skopeo](https://github.com/containers/skopeo/) and hence indirectly [containers/image](https://github.com/containers/image) +as a way to fetch container images. + +This means that bootc automatically also honors many of the knobs available in `/etc/containers` - specifically +things like [containers-registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md). + +In other words, if you configure `podman` to pull images from your local mirror registry, then `bootc` will automatically honor that as well. + +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 Kubernetes + +Just as `podman` does not depend on a Kubernetes API server, `bootc` will also not depend on one. + +However, there are also plans for `bootc` to also understand Kubernetes API types. See [configmap/secret support](https://github.com/containers/bootc/issues/22) for example. + +Perhaps in the future we may actually support some kind of `Pod` analogue for representing the host state. Or we may define a [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) which can be used inside and outside of Kubernetes. + +### Relationship with rpm-ostree + +Today rpm-ostree directly links to `ostree-rs-ext`, and hence +gains all the same container functionality. This will likely +continue. For example, 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. However, `bootc upgrade` would +(should) then error out as it will not understand how to upgrade +the system. + +rpm-ostree also has significant other features such as +`rpm-ostree kargs` etc. + +Overall, rpm-ostree is used in several important projects +and will continue to be maintained for many years to come. + +However, for use cases which want a "pure" image based model, +using `bootc` will be more appealing. bootc also does not +e.g. drag in dependencies on `libdnf` and the RPM stack. + +bootc also has the benefit of starting as a pure Rust project; +and while it [doesn't have an IPC mechanism today](https://github.com/containers/bootc/issues/4), the surface +of such an API will be significantly smaller. + +Further, bootc does aim to [include some of the functionality of zincati](https://github.com/containers/bootc/issues/5). + +But all this said: *It will be supported to use both bootc and rpm-ostree together*; they are not exclusive. +For example, `bootc status` at least will still function even if packages are layered. + +### Relationship with Fedora CoreOS (and Silverblue, etc.) + +Per above, it is a toplevel goal to support a seamless, transactional update from existing OSTree based systems, which includes these Fedora derivatives. + +For Fedora CoreOS specifically, see [this tracker issue](https://github.com/coreos/fedora-coreos-tracker/issues/1446). + +See also [OstreeNativeContainerStable](https://fedoraproject.org/wiki/Changes/OstreeNativeContainerStable). + +# More links + +- https://coreos.github.io/rpm-ostree/container/ +- https://github.com/coreos/layering-examples -With `bootc`, bootable operating systems can be created and deployed using all the same -familiar tools and techniques one uses for *application* container images. diff --git a/docs/install.md b/docs/install.md index c51b29723..f8887b79e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,4 +1,8 @@ -# Understanding `bootc install` +--- +nav_order: 2 +--- + +# `bootc install` A key goal of the bootc project is to think of bootable operating systems as container images. Docker/OCI container images are just tarballs