Skip to Content
✨ Check out our new MCP server! (tech preview)
Reference guidesKIWI NG
KIWI NG Logo

Get started

KIWI NG  is a powerful, command-line-driven tool that allows you to create customized Linux operating system images for a variety of platforms and use cases. Whether you’re building for bare metal, virtual machines, containers, or cloud environments, KIWI provides the flexibility and control you need to craft the perfect OS image.

Before exploring the container’s possibilities, let’s start by deploying the default configuration:

docker run \
    --interactive \
    --tty \
    --rm \
    --name <container-name> \
    dp.apps.rancher.io/containers/kiwi:10

Check our authentication guide if you need to configure Application Collection OCI credentials in your Docker client.

Container overview

Since there is no official upstream container for KIWI NG, our container is built from scratch using the SUSE Linux BCI Micro base image and following our best practices.

Container configuration

The KIWI NG container in Application Collection includes the KIWI Boxed Build Plugin  to provide self contained build support. Building the images in a self contained environment is recommended.

By default, the container runs with an unprivileged, non-root user ID (1000) that belongs to the root (0) system group and has no home directory.

Each of the KIWI boxes (Virtual machine images) referenced from the image descriptions are cached in the /.kiwi_boxes directory, which is writable by default. Mounting this directory as a persisted volume is encouraged. The volume should be mounted in /.kiwi_boxes unless a different path is specified via configuration, since the effective container user does not have a home directory.

Any shared host’s volumes where the container is intended to write must have the proper permissions to allow it. This is typically achieved by granting write permissions to the group in the host machine: chmod g+w <path-to-volume-in-the-host>.

Container usage

The examples below show how to build an example OS image in a self contained environment by using the KIWI NG container available in Application Collection.

Show available KIWI boxes

To list all the available KIWI boxes for self contained builds, run the command below:

docker run --rm dp.apps.rancher.io/containers/kiwi:10 system boxbuild --list-boxes

Build an OS image

Before building the OS image, clone the KIWI NG Git repository in your working directory to obtain example OS image descriptions:

git clone https://github.com/OSInside/kiwi

Prepare the directories where the built OS image will be stored and the KIWI boxes cache folder:

mkdir ./target_image
mkdir ./kiwi_boxes
# Grant write permissions within the KIWI container
chmod g+w ./target_image
chmod g+w ./kiwi_boxes

Build the OS image. The image description used as example is x86/leap/test-image-disk-simple, a simple virtual machine image in the VMDK format that can be booted in virtualization platforms. The resulting OS image files are placed at ./target_image:

docker run \
    --interactive \
    --tty \
    --rm \
    --privileged \
    --volume ./kiwi/build-tests/x86/leap/test-image-disk-simple:/image_description \
    --volume ./target_image:/target_image \
    --volume ./kiwi_boxes:/.kiwi_boxes \
    dp.apps.rancher.io/containers/kiwi:10 \
    --debug \
    system boxbuild --box leap -- \
        --description /image_description \
        --set-repo https://download.opensuse.org/distribution/leap/15.6/repo/oss \
        --target-dir /target_image

Refer to the official documentation  to obtain more information about each of the options available when running the KIWI NG tool.

Run an OS image

The OS image built in the section above can be simply booted with QEMU within the KIWI NG container:

docker run \
    --interactive \
    --tty \
    --rm \
    --volume ./target_image:/target_image \
    --entrypoint qemu-system-x86_64 \
    dp.apps.rancher.io/containers/kiwi:10 \
    -boot c \
    -drive file=/target_image/kiwi-test-image-disk-simple.x86_64-1.15.3-0.vmdk,format=vmdk,if=virtio \
    -m 4096 \
    -serial stdio

You can login to the system once the operating system boots. In these examples  the system user is root and the password is linux:

...
Welcome to openSUSE Leap 15.6!
...
Have a lot of fun...
localhost:~ # hostnamectl
...
    Virtualization: qemu
  Operating System: openSUSE Leap 15.6
       CPE OS Name: cpe:/o:opensuse:leap:15.6
...
      Architecture: x86-64
   Hardware Vendor: QEMU
...
localhost:~ # poweroff
Last updated on