c38a24c780
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 <supakeen@redhat.com>
248 lines
6.9 KiB
Markdown
248 lines
6.9 KiB
Markdown
# Usage
|
|
|
|
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 42 and build one of them.
|
|
|
|
```console
|
|
$ 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
|
|
# ...
|
|
```
|
|
|
|
## `image-builder list`
|
|
|
|
The `list` command for `image-builder` lists the available built-in image types that can be built for the [built-in distributions](./10-faq.md#built-in-distributions).
|
|
|
|
```console
|
|
$ image-builder list
|
|
# ... long list ...
|
|
```
|
|
|
|
### Format
|
|
|
|
The output format used by `list` can be swapped with the `--format` flag. Available types are `text` (for display in a terminal) and `json` which can be useful to consume programmatically:
|
|
|
|
```console
|
|
$ image-builder list --format=json | jq '.[0]'
|
|
{
|
|
"distro": {
|
|
"name": "centos-9"
|
|
},
|
|
"arch": {
|
|
"name": "aarch64"
|
|
},
|
|
"image_type": {
|
|
"name": "ami"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Filtering
|
|
|
|
`list` output can be filtered with the `--filter` argument.
|
|
|
|
### Distribution
|
|
|
|
To filter on a given distribution, one can use `--filter` with the `distro:` prefix:
|
|
|
|
```console
|
|
$ image-builder list --filter distro:fedora-42
|
|
# ... long list ...
|
|
```
|
|
|
|
### Type
|
|
|
|
To filter on a given [image type](./10-faq.md#image-types) the `type:` prefix:
|
|
|
|
```console
|
|
$ image-builder list --filter type:qcow2
|
|
# ... long list ...
|
|
```
|
|
### Architecture
|
|
|
|
To filter on a given architecture use the `arch:` prefix:
|
|
|
|
```console
|
|
$ image-builder list --filter arch:aarch64
|
|
# ... long list ...
|
|
```
|
|
|
|
### Combinations
|
|
|
|
Filters can be combined to narrow the list further.
|
|
|
|
```console
|
|
$ image-builder list --filter type:qcow2 --filter distro:fedora-42
|
|
# ... list ...
|
|
```
|
|
|
|
## `image-builder build`
|
|
|
|
The `build` command builds images of a given [image type](./10-faq.md#image-types), for example:
|
|
|
|
```console
|
|
$ sudo image-builder build --distro fedora-42 minimal-raw-xz
|
|
# ... progress ...
|
|
```
|
|
|
|
The `build` command requires root privileges in many cases as `image-builder` needs access to loopback devices and `mount`.
|
|
|
|
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 centos-10 qcow2
|
|
# ... progress ...
|
|
```
|
|
|
|
When passed `--arch` `image-builder` will try to do an experimental cross-architecture build. Note that not all image types are available for all architectures.
|
|
|
|
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 --distro fedora-42 --arch s390x server-qcow2
|
|
WARNING: using experimental cross-architecture building to build "s390x"
|
|
# ... progress ...
|
|
```
|
|
|
|
## `image-builder describe`
|
|
|
|
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-xz
|
|
@WARNING - the output format is not stable yet and may change
|
|
distro: fedora-43
|
|
type: minimal-raw-zst
|
|
arch: x86_64
|
|
os_version: "43"
|
|
bootmode: uefi
|
|
partition_type: gpt
|
|
default_filename: disk.raw.zst
|
|
build_pipelines:
|
|
- build
|
|
payload_pipelines:
|
|
- os
|
|
- image
|
|
- zstd
|
|
packages:
|
|
build:
|
|
include:
|
|
- coreutils
|
|
- dosfstools
|
|
- e2fsprogs
|
|
- glibc
|
|
- policycoreutils
|
|
- python3
|
|
- rpm
|
|
- selinux-policy-targeted
|
|
- systemd
|
|
- xz
|
|
- zstd
|
|
exclude: []
|
|
os:
|
|
include:
|
|
- '@core'
|
|
- NetworkManager-wifi
|
|
- brcmfmac-firmware
|
|
- dosfstools
|
|
- dracut-config-generic
|
|
- e2fsprogs
|
|
- efibootmgr
|
|
- grub2-efi-x64
|
|
- initial-setup
|
|
- iwlwifi-mvm-firmware
|
|
- kernel
|
|
- libxkbcommon
|
|
- realtek-firmware
|
|
- selinux-policy-targeted
|
|
- shim-x64
|
|
exclude:
|
|
- dracut-config-rescue
|
|
- firewalld
|
|
```
|
|
|
|
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-xz
|
|
# ... output ...
|
|
```
|
|
|
|
When passed `--arch` `image-builder` will show the description for that architecture:
|
|
|
|
```console
|
|
$ image-builder describe --arch aarch64 minimal-raw-xz
|
|
# ... output ...
|
|
```
|
|
|
|
## `image-builder manifest`
|
|
|
|
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-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-xz
|
|
# ... json ...
|
|
```
|
|
|
|
When passed `--arch` `image-builder` will show the manifest for that architecture:
|
|
|
|
```console
|
|
$ image-builder manifest --arch aarch64 minimal-raw-xz
|
|
# ... output ...
|
|
```
|
|
|
|
## Blueprints
|
|
|
|
Images can be customized with [blueprints](https://osbuild.org/docs/user-guide/blueprint-reference). For example we could build the `qcow2` we built above with some customizations applied.
|
|
|
|
We'll be adding the `nginx`, and `haproxy` packages and enabling their services so they start on boot. We'll also add a user by the name `user` with an ssh key and set the hostname of the machine:
|
|
|
|
```console
|
|
$ cat blueprint.toml
|
|
packages = [
|
|
{ name = "nginx" },
|
|
{ name = "haproxy" },
|
|
]
|
|
|
|
[customizations]
|
|
hostname = "mynewmachine.home.arpa"
|
|
|
|
[customizations.services]
|
|
enabled = ["nginx", "haproxy"]
|
|
|
|
[[customizations.user]]
|
|
name = "user"
|
|
key = "ssh-ed25519 AAAAC..."
|
|
$ sudo image-builder build --blueprint blueprint.toml --distro fedora-42 server-qcow2
|
|
# ...
|
|
```
|