Image Types

Note

Before building an image with KIWI NG, it’s important to understand the different image types and their meaning. This document provides an overview of the supported KIWI NG image types, their results, and some words about the environment to run the build.

ISO Hybrid Live Image

An ISO image that can be dumped on a CD/DVD or USB stick and boots from this media without interfering with other system storage components. A useful pocket system for testing, demo, and debugging purposes. For further details, refer to Build an ISO Hybrid Live Image.

Virtual Disk Image

An image representing the system disk, useful for cloud frameworks like Amazon EC2, Google Compute Engine, or Microsoft Azure. For further details, refer to Build a Virtual Disk Image.

OEM Expandable Disk Image

An image representing an expandable system disk. This means after deployment, the system can resize itself to the new disk geometry. The resize operation is configurable as part of the image description, and an installation image for CD/DVD, USB stick, and network deployment can be created in addition. For further details, refer to: Build an Expandable Disk Image.

Docker Container Image

An archive image suitable for the Docker container engine. The image can be loaded via the docker load command and works within the scope of the container engine. For further details, refer to: Build a Container Image.

WSL Container Image

An archive image suitable for the Windows Subsystem for Linux container engine. The image can be loaded from a Windows System that has support for WSL activated. For further details, refer to: Build a WSL Container Image.

KIS Root Filesystem Image

An optional root filesystem image associated with a kernel and initrd. The use case for this component image type is highly customizable. Many different deployment strategies are possible. For further details, refer to: Build KIS Image (Kernel, Initrd, System).

AWS Nitro Enclave

An initrd-based image using the eif binary format. The image is expected to be used in the AWS Nitro Enclave system or for testing in QEMU. For further details, refer to: Build an AWS Nitro Enclave.

Image Results

KIWI NG execution results in an appliance image after a successful run of the kiwi-ng system build or kiwi-ng system create command. The result is the image binary plus some additional metadata files that are needed for image deployment and/or exist for informative reasons. By default, the output files follow this naming convention:

<image-name>.<arch>-<version>.<extension>

where <image-name> is the name stated in the Image Description as an attribute of the <image> element. The <arch> is the CPU architecture used for the build, <version> is the image version defined in the <version> element of the image description, and the <extension> is dependent on the image type and its definition.

Any KIWI NG appliance build results in, at least, the following output files:

  1. The image binary, <image-name>.<arch>-<version>.<image-extension>:

    This is the file containing the actual image binary. Depending on the image type and its definition, it can be a virtual disk image file, an ISO image, a tarball, etc.

  2. The <image-name>.<arch>-<version>.packages file:

    This file includes a sorted list of the packages that are included in the image. In fact, this is a normalized dump of the package manager database. It follows the following CSV format, where each line is represented by:

    <name>|<epoch>|<version>|<release>|<arch>|<disturl>|<license>

    The values represented here are mainly based on RPM packages’ metadata. Other package managers may not provide all of these values. In such cases, the format is the same, and the fields that cannot be provided are set as None. This list can be used to track changes across multiple builds of the same image description over time by diffing the packages installed.

  3. The <image-name>.<arch>-<version>.verified file:

    This file is the output of a verification done by the package manager against the package database. More specifically, it is the output of the rpm verification process or dpkg verification, depending on the packaging technology selected for the image. In both cases, the output follows the RPM verification syntax. This provides an overview of all package statuses right before any boot of the image.

Depending on the image type, the following output files exist:

image=”tbz”

For this image type, the result is mainly a root tree packed in a tarball:

  • root archive: exc_image_base_name.x86_64-1.15.6.tar.xz

image=”btrfs|ext2|ext3|ext4|squashfs|xfs”

The image root tree data is packed into a filesystem image of the given type; hence, the result for an ext4 image would be:

  • filesystem image: exc_image_base_name.x86_64-1.15.6.ext4

image=”iso”

The image result is an ISO file:

  • live image: exc_image_base_name.x86_64-1.15.6.iso

image=”oem”

An image representing an expandable disk image. KIWI NG can also produce an installation ISO for this disk image by setting installiso="true" in the <preferences><type>) section or a tarball, including the artifacts for a network deployment, by setting installpxe="true". For further details, see Build an Expandable Disk Image. The results for oem can be:

  • disk image: exc_image_base_name.x86_64-1.15.6.raw

  • installation image (optional): exc_image_base_name.x86_64-1.15.6.install.iso

  • installation pxe archive (optional): exc_image_base_name.x86_64-1.15.6.install.tar

The disk image can also be provided in one of the various virtual disk formats, which can be specified in the format attribute of the <preferences><type> section. For further details, see Build a Virtual Disk Image. The result for e.g., format="qcow2" would be:

  • disk image: exc_image_base_name.x86_64-1.15.6.qcow2

instead of the raw default disk format.

image=”docker”

An archive image suitable for the Docker container engine. The result is a loadable (docker load -i) tarball:

  • container: exc_image_base_name.x86_64-1.15.6.docker.tar.xz

image=”oci”

An archive image that builds a container matching the OCI (Open Container Interface) standard. The result is a tarball matching OCI standards:

  • container: exc_image_base_name.x86_64-1.15.6.oci.tar.xz

image=”appx”

An archive image suitable for the Windows Subsystem for Linux container engine. The result is an appx binary file:

  • container: exc_image_base_name.x86_64-1.15.6.appx

image=”wsl”

An archive image suitable for the Windows Subsystem for Linux container engine >= v2.4.4. The result is a gzip-compressed tar archive with the wsl extension:

  • container: exc_image_base_name.x86_64-1.15.6.wsl

image=”kis”

An optional root filesystem image associated with a kernel and initrd. All three binaries are packed in a tarball. See Build KIS Image (Kernel, Initrd, System) for further details about the kis archive:

  • kis archive: exc_image_base_name.x86_64-1.15.6.tar.xz

Image Bundle Format

The result files as mentioned above are used in the KIWI NG result bundler. The kiwi-ng result bundle command can be used to copy or package the mandatory image files to create a customer release. In this process, it’s possible to apply a specific name pattern suitable for the requirements of the release. A typical result bundle call can look like the following:

$ kiwi-ng result bundle --target-dir /path/to/image/build_result \
      --bundle-dir=/path/to/image/release_result \
      --id=release_identifier

In this call, and depending on the image type, the required files as they exist in /path/to/image/build_result are copied to /path/to/image/release_result/. The only modification to the file names is the --id information, which is appended with a - at the end of the version substring. If we take exc_image_base_name.x86_64-1.15.6.iso as an example. This file would be bundled as exc_image_base_name.x86_64-1.15.6-release_identifier.iso.

Depending on the use case and the customer requirements, this naming schema and the default way the kiwi bundler processes the result files is not appropriate. To allow for a more flexible naming schema when bundling results, KIWI NG allows you to specify a bundle_format per type, like in the following example:

<type image="..." bundle_format="name_pattern">
    <!-- type definition -->
</type>

The specified name_pattern is used as the base name for the image files the bundler uses. As part of the name_pattern, the following placeholders, which are replaced by their real value, can be used:

%N

Turns into the contents of the name attribute of the <image> section.

%P

Turns into the profile name used at build time of the image. If multiple profiles were used to build the image, the result name consists of the individual profile names concatenated by a _ in the order of their specification in the image description and/or the command line.

%A

Turns into the architecture name at build time of the image. Arch names are taken from Python’s platform.machine information.

%I

Turns into the identifier name given via the --id option at the call time of the bundler.

%T

Turns into the contents of the image attribute of the <type> section.

%M

Turns into the major number of the <version> section.

%m

Turns into the minor number of the <version> section.

%p

Turns into the patch number of the <version> section.

%v

Turns into the version text of the <version> section.