From 0eb26914496eb6ff626ee7dd41463ae09b9b0065 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 27 Feb 2024 08:50:15 -0500 Subject: [PATCH] docs/install: Revamp - Split into "local virt" and "production" - Link to podman-desktop-extension-bootc - Link to podman-bootc-cli - Clean up, fix and inline kickstart example for readability - Include bootc-image-builder in both local and production paths --- docs/install.md | 140 ++++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 76 deletions(-) diff --git a/docs/install.md b/docs/install.md index 0b7aa9e3..16fa823f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,70 +4,90 @@ nav_order: 2 # Trying out development builds -## No default user accounts +Before you build a [derived container image](https://gitlab.com/bootc-org/examples), +you may want to just get a feel for the system, try out `bootc`, etc. The bootable +container images produced by this project are intended to be deployable in every +physical and virtual environment that is supported by CentOS Stream 9 today. -The default images produced do *not* include any default passwords or SSH keys. -There is a `root` user present, but its password is locked. +First, an important note to understand: the generic base container images +do *not* include any default passwords or SSH keys. -## Using the "generic cloud" image +## Local virtualization (Linux & MacOS) -Many people who just want to "try things out" will find it easiest to start -with [the cloud image](https://github.com/CentOS/centos-bootc-layered/tree/main/cloud). -(It's a separate container image because cloud-init does not work on every deployment - target, and it also serves as an effective demonstration of layering) +### podman desktop plugin (currently MacOS only) -The [bootc playground](https://github.com/vrothberg/bootc-playground) repository -helps automate this. +There is a +[podman desktop extension](https://github.com/containers/podman-desktop-extension-bootc) +dedicated to this. -## Use bootc-image-builder +### podman-bootc-cli -The [bootc-image-builder tool](https://github.com/osbuild/bootc-image-builder) -supports generating disk images, including injecting user accounts. +A new [podman-bootc-cli tool](https://gitlab.com/bootc-org/podman-bootc-cli) +project offers a dedicated and streamlined CLI interface for running images, and +in the future, it will become the backend for the podman desktop plugin. -## Generating a raw disk image that can be launched via virt tooling +### bootc-image-builder -The above bootc-image-builder tool can generate disk images; however, a key part -of the idea of `bootc` is that operating system images that use it are their -own self-sufficient "baseline" installer. So you can use this example: +The +[bootc-image-builder tool](https://github.com/osbuild/bootc-image-builder) +supports generating local-virtualization ready types such as `qcow2` and `.raw` +from the bootable container image. - +### The dedicated cloud-init image -to generate a raw disk image from the default container base image, or your own -without any external tooling. +Many people who just want to "try things out" will find it easiest to start +with +[the cloud image](https://gitlab.com/bootc-org/centos-bootc-layered/-/tree/main/cloud). +It's a separate container image because cloud-init does not work on every deployment +target, and it also serves as an effective demonstration of layering. -If you choose not to include SSH keys or other credentials directly in your image, -a useful pattern can often be to use [systemd credentials](https://systemd.io/CREDENTIALS/) -to inject a SSH key for root. The above page has this example for qemu: +## Production-oriented physical installation -```bash --smbios type=11,value=io.systemd.credential.binary:tmpfiles.extra=$(echo "f~ /root/.ssh/authorized_keys 600 root root - $(ssh-add -L | base64 -w 0)" | base64 -w 0) +This project uses the same +[Anaconda](https://anaconda-installer.readthedocs.io/en/latest/intro.html) +installer as the package-based CentOS. Here's an example kickstart: + +```text +# Basic setup +text +network --bootproto=dhcp --device=link --activate +# Basic partitioning +clearpart --all --initlabel --disklabel=gpt +reqpart --add-boot +part / --grow --fstype xfs + +# Here's where we reference the container image to install - notice the kickstart +# has no `%packages` section! What's being installed here is a container image. +ostreecontainer --url quay.io/centos-bootc/centos-bootc:stream9 --no-signature-verification + +firewall --disabled +services --enabled=sshd + +# Only inject a SSH key for root +rootpw --iscrypted locked +sshkey --username root "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOQkQHeKan3X+g1jILw4a3KtcfEIED0kByKGWookU7ev walters+2015-general@verbum.org" +reboot ``` -## Installation using Anaconda +## Production-oriented cloud virtualization -Tools like -[Anaconda](https://anaconda-installer.readthedocs.io/en/latest/intro.html) -support injecting configuration at image installation time, such as SSH keys and -passwords. This means that in contrast to what was said just before, it's -possible to directly install (and update from) an "unconfigured base image" -provided by this project. +### Generating AMIs, ISO and qcow2 (and more) -Because a current development target for this project is [Fedora ELN](https://docs.fedoraproject.org/en-US/eln/), -which includes the latest support for `bootupd`, it's recommended to use -that ISO at this time. The support for `ostreecontainer` does not -yet exist in CentOS Stream 9. +The [bootc-image-builder tool](https://github.com/osbuild/bootc-image-builder) +which supports `.qcow2` usable in OpenStack/libvirt etc. also supports generating +Amazon Machine Images, and other production-oriented IaaS formats as well as a +self-installing ISO. For more, please see the docs for that project. -See [example.ks](example.ks) for an example Kickstart file. The -[virt-install --initrd-inject](https://github.com/virt-manager/virt-manager/blob/main/man/virt-install.rst#--initrd-inject) -helps inject kickstart for installation to virtual machines. +After a disk image is generated, further updates will come from the container image. -## Using `bootc install to-filesystem --replace=alongside` with a cloud image +### Replacing existing cloud images A toplevel goal of this project is that the "source of truth" for Linux operating system management is a container image registry - as opposed to e.g. a -set of qcow2 OpenStack images or AMIs, etc. You should not need to maintain -infrastructure to e.g. manage garbage collection or versioning of cloud (IaaS) -VM images. +set of qcow2 OpenStack images or AMIs, etc. Generating cloud disk images +gives fast boots into the target container image state, but also requires +maintaining infrastructure to e.g. manage garbage collection or versioning of +these images. The latest releases of `bootc` have support for `bootc install to-filesystem --replace=alongside`. More about this core mechanic @@ -80,38 +100,6 @@ configuration. ```shell dnf -y install podman skopeo -podman run --rm --privileged --pid=host -v /:/target --security-opt label=type:unconfined_t bootc install to-filesystem --karg=console=ttyS0,115200n8 --replace=alongside /target +podman run --rm --privileged --pid=host -v /:/target -v /var/lib/containers:/var/lib/containers --security-opt label=type:unconfined_t bootc install to-filesystem --karg=console=ttyS0,115200n8 --replace=alongside /target reboot ``` - - - -## Using `bootc install to-disk --via-loopback` to generate a raw disk image - -```shell -truncate -s 10G myimage.raw -podman run --rm --privileged --pid=host --security-opt label=type:unconfined_t -v .:/output bootc install to-disk --via-loopback /output/myimage.raw -``` - -This disk image can then be launched in a virtualization tool. - -## Rebasing from Fedora CoreOS - -[Fedora CoreOS](https://docs.fedoraproject.org/en-US/fedora-coreos/) supports -many different platforms, and can be used as a starting point to "rebase" to a -custom derived image from CentOS boot. These commands should all be invoked -as root. - -```shell -systemctl mask --now zincati && rm -vf /run/ostree/staged-deployment-locked -echo "# dummy change" >> "/etc/sudoers.d/coreos-sudo-group" -cp -a ~core/.ssh/authorized_keys.d/ignition ~core/.ssh/authorized_keys -rpm-ostree rebase ostree-unverified-registry:quay.io/centos-bootc/fedora-bootc:eln -systemctl reboot -```