From 0b675a765e3408071fe740c52e579c08855a1c59 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 7 Nov 2023 13:32:53 -0500 Subject: [PATCH 1/4] docs: Split out relationship.md Start breaking up the big index doc. Signed-off-by: Colin Walters --- docs/index.md | 71 ------------------------------------------ docs/relationship.md | 74 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 71 deletions(-) create mode 100644 docs/relationship.md diff --git a/docs/index.md b/docs/index.md index 8720260f2..8445b7037 100644 --- a/docs/index.md +++ b/docs/index.md @@ -114,77 +114,6 @@ 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/ diff --git a/docs/relationship.md b/docs/relationship.md new file mode 100644 index 000000000..58c7dc90e --- /dev/null +++ b/docs/relationship.md @@ -0,0 +1,74 @@ +--- +nav_order: 5 +--- + +# 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). From 9c7f1e62af11f47c03a037261d26274d42fbbf0f Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 7 Nov 2023 13:39:51 -0500 Subject: [PATCH 2/4] index: A few minor fixes Signed-off-by: Colin Walters --- docs/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8445b7037..9543b55e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,7 +59,7 @@ The `bootc install` functionality is also more experimental. ### Installing - * Fedora: [bootc is packaged](https://bodhi.fedoraproject.org/updates/?packages=bootc) and be available in the main repositories soon. + * Fedora: [bootc is packaged](https://bodhi.fedoraproject.org/updates/?packages=bootc). * 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. @@ -116,6 +116,7 @@ preserving state. # More links -- https://coreos.github.io/rpm-ostree/container/ -- https://github.com/coreos/layering-examples +- [rpm-ostree container](https://coreos.github.io/rpm-ostree/container/) +- [centos-boot](https://github.com/centos/centos-boot) +- [coreos/layering-examples](https://github.com/coreos/layering-examples) From 41574e46144b3c1daec10db44c5dec019a04856f Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 7 Nov 2023 13:49:14 -0500 Subject: [PATCH 3/4] docs: Reorder base image bits This is a bit clearer. Signed-off-by: Colin Walters --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9543b55e0..89d8904e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,8 +68,6 @@ You can also build this project like any other Rust project, e.g. `cargo build - 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. @@ -77,6 +75,8 @@ For pre-built base images: 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. +To build base images "from scratch", see [bootc-images.md](bootc-images.md). + ### Deriving from and switching to base images A toplevel goal is that *every tool and technique* a Linux system From 8a4fe1975a206107ed7f4b9cb31b45321f886633 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 7 Nov 2023 13:49:33 -0500 Subject: [PATCH 4/4] docs: Clarify upgrades a bit Signed-off-by: Colin Walters --- docs/index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 89d8904e5..1f8068b7e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -111,8 +111,15 @@ 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. +invocations of `bootc upgrade` from the installed operating system +will fetch updates from the container image registry. + +This is backed today by ostree, implementing an A/B style upgrade system. +Changes to the base image are staged, and the running system is not +changed by default. + +Use `bootc upgrade --apply` to apply updates; today this will always +reboot. # More links