KIWI basics for openSUSE Tumbleweed Minimal OS images

KIWI is a tool that builds complete Linux images from a declarative description. It is used by openSUSE and SUSE to create ready-to-run disks for many platforms such as KVM, Xen, VMware, Hyper-V, cloud providers, and hardware devices. With KIWI, you keep your image recipe in version control and rebuild it any time. The recipe is mostly one description file, written in YAML, TOML, or XML and following a schema, plus small scripts. This makes the result maintainable and easy to review.

For the exact template used here, see Minimal.kiwi on build.opensuse.org.

What is a KIWI image description?

A KIWI image description is a folder with one main description file (the “.kiwi” file) and optional helper scripts such as config.sh. Together this provides the layout of the later binary image in a human readable form. Information about filesystem, packages, bootloader, disk layout, and more is part of this description. The scripts runs at build time to finish the setup.

The top of the file: <image> and <description>

At the top of the .kiwi file you see the schema version and some metadata. This tells KIWI which features are used and shows a human-readable name. For example, the Tumbleweed Minimal template sets the schema, project name, and contact details.

Profiles: one description can build many images

The <profiles> section allows to produce different images for different targets from one description. A profile can be limited to certain CPU architectures and can switch packages, disk format, or bootloader. Common profiles in the Minimal template include kvm-and-xen-sdboot (a UEFI VM image that uses systemd-boot), Cloud (for cloud platforms with cloud-init), and s390x-Cloud (IBM Z cloud).

Preferences: image type, filesystem, bootloader, and size

Each profile has a <preferences> block. Inside it, the <type> element is the heart of the image. It defines the image kind (for example, an OEM-style VM disk), the filesystem (such as Btrfs or XFS), the output disk format (qcow2, vmdk, vhdx), and the firmware/bootloader (GRUB2, systemd-boot, platform-specific loaders). It also holds the disk layout (partitions or volumes) and the base size. For instance, kvm-and-xen-sdboot uses qcow2 with Btrfs and sd-boot; Cloud profiles often use XFS and GRUB2 with a smaller base size; s390x-Cloud uses XFS for root and a small ext4 /boot partition with a GRUB2 s390x emulator.

Where software comes from: <repository>

The <repository> entries tell KIWI where to fetch packages. In the template, they point to rpm-md repositories from the relevant OBS project. You can add or remove repositories to control where packages are pulled from during the build. (You usually have to setup the repository when building from an image that was created to build in OBS. In most cases the predefined repository section uses obsrepositories:// which you need to change when building locally.)

What gets installed: <packages>

Packages are listed in groups by their role. The bootstrap group is the minimal set needed to assemble the root filesystem. The image group adds extra packages for the final image. Profiles can add or remove packages to fit the target. For example, Cloud profiles add cloud-init and xfsprogs; sd-boot images add systemd-boot utilities; VM images often add qemu-guest-agent. The template also selects different kernels depending on the architecture and purpose.

If you want to see the exact finishing script, open config.sh on build.opensuse.org.

What config.sh does (finishing steps)

config.sh is a shell script that runs inside the chroot during the build. It allows to customize the image beyond the capabilities of the declarative description. In the Minimal template, it enables sshd, turns on cloud-init services when present, and enables NetworkManager and firewalld where suitable. On s390x, it adjusts first-boot behavior for text consoles.

How to build (quick start)
With kiwi-ng installed, you can build a chosen profile like this:

kiwi-ng –profile kvm-and-xen-sdboot system build \
–description /path/to/kiwi-templates-Minimal \
–target-dir ./build \
–set-repo <REPO_URL>

References

Minimal.kiwi (Tumbleweed template): build.opensuse.org link
config.sh (Tumbleweed template): build.opensuse.org link
KIWI documentation (concepts & workflow): osinside.github.io