From 34051e7b9c8e618b60fdddef23f149f9211f25a8 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 27 Oct 2023 14:30:30 -0400 Subject: [PATCH] README: Add more information on base images Came up in chat Signed-off-by: Colin Walters --- README.md | 4 +++ docs/bootc-images.md | 58 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/bootc-images.md diff --git a/README.md b/README.md index f8fbf0dd5..f976993d5 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,10 @@ 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 [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://gitlab.com/CentOS/cloud/sagano) for Fedora/CentOS. diff --git a/docs/bootc-images.md b/docs/bootc-images.md new file mode 100644 index 000000000..ca2f6b3c9 --- /dev/null +++ b/docs/bootc-images.md @@ -0,0 +1,58 @@ +# Understanding "bootc compatible" images + +At the current time, it does not work to just do: +``` +FROM fedora +RUN dnf -y install kernel +``` +or +``` +FROM debian +RUN apt install kernel +``` + +And get an image compatible with bootc. Supporting this +is an eventual goal, however there are a few reasons why +this doesn't yet work. The biggest reason is SELinux +labeling support; the underlying ostree stack currently +handles this and requires that the "base image" +have a pre-computed set of labels that can be used +for any derived layers. + +# Building bootc compatible base images + +As a corollary to this, the build process +for generating base images currently requires running +through ostree tooling to generate an "ostree commit" +which has some special formatting in the base image. + +However, the ostree usage is an implementation detail +and the requirement on this will be lifted in the future. + +For example, the [rpm-ostree compose image](https://coreos.github.io/rpm-ostree/container/#creating-base-images) +tooling currently streamlines this, operating just +on a declarative input and writing to a registry. + +This is how the [Project Sagano](https://gitlab.com/CentOS/cloud/sagano) +base images are built. + +# Deriving from existing base images + +However, it's important to emphasize that from one +of these specially-formatted base images, every +tool and technique for container building applies! +In other words it will Just Work to do +``` +FROM +RUN dnf -y install foo && dnf clean all +``` + +## Using the `ostree container commit` command + +As an opt-in optimization today, you can also add `ostree container commit` +as part of your `RUN` invocations. This will perform early detection +of some incompatibilities. + +However, its usage is not and will never be strictly required. + +