From c38a24c7802166ad5ee524c1dffeb5a29e91c72b Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Thu, 31 Jul 2025 10:42:38 +0200 Subject: [PATCH] doc: update usage Make sure to pass `--distro` so the `minimal-raw-xz` image type exists, not all distributions have it and since we're available on multiple it's better to be explicit. Signed-off-by: Simon de Vlieger --- doc/00-installation.md | 8 ++--- doc/01-usage.md | 71 ++++++++++++++++++++++-------------------- 2 files changed, 41 insertions(+), 38 deletions(-) diff --git a/doc/00-installation.md b/doc/00-installation.md index 2589b53..cd55f6c 100644 --- a/doc/00-installation.md +++ b/doc/00-installation.md @@ -9,7 +9,7 @@ Install `image-builder` with the following command: ```console $ sudo dnf install image-builder # ... -$ sudo image-builder build minimal-raw +$ sudo image-builder build --distro fedora-42 minimal-raw-xz # ... ``` @@ -22,7 +22,7 @@ $ sudo dnf copr enable @osbuild/image-builder # ... $ sudo dnf install image-builder # ... -$ sudo image-builder build minimal-raw +$ sudo image-builder build --distro fedora-42 minimal-raw-xz # ... ``` @@ -38,7 +38,7 @@ $ sudo podman run \ -it \ -v ./output:/output \ ghcr.io/osbuild/image-builder-cli:latest \ - build minimal-raw + build --distro fedora-42 minimal-raw-xz # ... ``` @@ -54,5 +54,5 @@ $ git clone github.com/osbuild/image-builder-cli $ cd image-builder-cli $ go build ./cmd/image-builder # ... -$ sudo ./image-builder build minimal-raw +$ sudo ./image-builder build --distro fedora-42 minimal-raw-xz ``` diff --git a/doc/01-usage.md b/doc/01-usage.md index 09b27b9..71202fc 100644 --- a/doc/01-usage.md +++ b/doc/01-usage.md @@ -2,30 +2,33 @@ After [installation](./00-installation.md) you probably want to use `image-builder`. A general workflow would be to find the image type you want to build and then build it. -Let's take a look at the available `x86_64` image types for Fedora 41 and build one of them. +Let's take a look at the available `x86_64` image types for Fedora 42 and build one of them. ```console -$ image-builder list --filter arch:x86_64 --filter distro:fedora-41 -fedora-41 type:ami arch:x86_64 -fedora-41 type:container arch:x86_64 -fedora-41 type:image-installer arch:x86_64 -fedora-41 type:iot-bootable-container arch:x86_64 -fedora-41 type:iot-commit arch:x86_64 -fedora-41 type:iot-container arch:x86_64 -fedora-41 type:iot-installer arch:x86_64 -fedora-41 type:iot-qcow2-image arch:x86_64 -fedora-41 type:iot-raw-image arch:x86_64 -fedora-41 type:iot-simplified-installer arch:x86_64 -fedora-41 type:live-installer arch:x86_64 -fedora-41 type:minimal-raw arch:x86_64 -fedora-41 type:oci arch:x86_64 -fedora-41 type:openstack arch:x86_64 -fedora-41 type:ova arch:x86_64 -fedora-41 type:qcow2 arch:x86_64 -fedora-41 type:vhd arch:x86_64 -fedora-41 type:vmdk arch:x86_64 -fedora-41 type:wsl arch:x86_64 -$ sudo image-builder build --distro fedora-41 qcow2 +$ image-builder list --filter arch:x86_64 --filter distro:fedora-42 +fedora-42 type:container arch:x86_64 +fedora-42 type:iot-bootable-container arch:x86_64 +fedora-42 type:iot-commit arch:x86_64 +fedora-42 type:iot-container arch:x86_64 +fedora-42 type:iot-installer arch:x86_64 +fedora-42 type:iot-qcow2 arch:x86_64 +fedora-42 type:iot-raw-xz arch:x86_64 +fedora-42 type:iot-simplified-installer arch:x86_64 +fedora-42 type:minimal-installer arch:x86_64 +fedora-42 type:minimal-raw-xz arch:x86_64 +fedora-42 type:minimal-raw-zst arch:x86_64 +fedora-42 type:server-ami arch:x86_64 +fedora-42 type:server-oci arch:x86_64 +fedora-42 type:server-openstack arch:x86_64 +fedora-42 type:server-ova arch:x86_64 +fedora-42 type:server-qcow2 arch:x86_64 +fedora-42 type:server-vagrant-libvirt arch:x86_64 +fedora-42 type:server-vagrant-virtualbox arch:x86_64 +fedora-42 type:server-vhd arch:x86_64 +fedora-42 type:server-vmdk arch:x86_64 +fedora-42 type:workstation-live-installer arch:x86_64 +fedora-42 type:wsl arch:x86_64 +$ sudo image-builder build --distro fedora-42 server-qcow2 # ... ``` @@ -66,7 +69,7 @@ $ image-builder list --format=json | jq '.[0]' To filter on a given distribution, one can use `--filter` with the `distro:` prefix: ```console -$ image-builder list --filter distro:fedora-41 +$ image-builder list --filter distro:fedora-42 # ... long list ... ``` @@ -92,7 +95,7 @@ $ image-builder list --filter arch:aarch64 Filters can be combined to narrow the list further. ```console -$ image-builder list --filter type:qcow2 --filter distro:fedora-41 +$ image-builder list --filter type:qcow2 --filter distro:fedora-42 # ... list ... ``` @@ -101,7 +104,7 @@ $ image-builder list --filter type:qcow2 --filter distro:fedora-41 The `build` command builds images of a given [image type](./10-faq.md#image-types), for example: ```console -$ sudo image-builder build minimal-raw +$ sudo image-builder build --distro fedora-42 minimal-raw-xz # ... progress ... ``` @@ -110,7 +113,7 @@ The `build` command requires root privileges in many cases as `image-builder` ne By default the `build` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument: ```console -$ sudo image-builder build --distro fedora-43 minimal-raw +$ sudo image-builder build --distro centos-10 qcow2 # ... progress ... ``` @@ -119,7 +122,7 @@ When passed `--arch` `image-builder` will try to do an experimental cross-archit Cross-architecture builds are much slower than being able to build on native hardware. However, if no native hardware is available they might be an acceptable compromise. ```console -$ sudo image-builder build --arch s390x qcow2 +$ sudo image-builder build --distro fedora-42 --arch s390x server-qcow2 WARNING: using experimental cross-architecture building to build "s390x" # ... progress ... ``` @@ -129,7 +132,7 @@ WARNING: using experimental cross-architecture building to build "s390x" The `describe` command outputs structured information about an image without building it. It lists the packages that would be used to build the images and the partition tables. ```console -$ image-builder describe minimal-raw +$ image-builder describe minimal-raw-xz @WARNING - the output format is not stable yet and may change distro: fedora-43 type: minimal-raw-zst @@ -184,14 +187,14 @@ packages: By default the `describe` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument: ```console -$ image-builder describe --distro fedora-43 minimal-raw +$ image-builder describe --distro fedora-43 minimal-raw-xz # ... output ... ``` When passed `--arch` `image-builder` will show the description for that architecture: ```console -$ image-builder describe --arch aarch64 minimal-raw +$ image-builder describe --arch aarch64 minimal-raw-xz # ... output ... ``` @@ -200,21 +203,21 @@ $ image-builder describe --arch aarch64 minimal-raw The `manifest` command outputs an [osbuild](https://github.com/osbuild/osbuild) manifest for an image. This manifest contains all the steps performed to assemble the eventual image but the image itself is not created. ```console -$ image-builder manifest minimal-raw +$ image-builder manifest minimal-raw-xz # ... json ... ``` By default the `manifest` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument: ```console -$ image-builder manifest --distro fedora-43 minimal-raw +$ image-builder manifest --distro fedora-43 minimal-raw-xz # ... json ... ``` When passed `--arch` `image-builder` will show the manifest for that architecture: ```console -$ image-builder manifest --arch aarch64 minimal-raw +$ image-builder manifest --arch aarch64 minimal-raw-xz # ... output ... ``` @@ -240,6 +243,6 @@ enabled = ["nginx", "haproxy"] [[customizations.user]] name = "user" key = "ssh-ed25519 AAAAC..." -$ sudo image-builder build --blueprint blueprint.toml --distro fedora-41 qcow2 +$ sudo image-builder build --blueprint blueprint.toml --distro fedora-42 server-qcow2 # ... ```