Build a Container Image

KIWI NG can build native container images from scratch or using existing images. KIWI NG container images are considered to be native, because a KIWI NG tarball image can be loaded directly into container runtimes like Podman, Docker or Containerd, including common container configurations.

The container configuration metadata is supplied to KIWI NG as part of the XML description file using the <containerconfig> tag. The following configuration metadata can be specified.

containerconfig attributes:

  • name: Specifies the repository name of the container image.

  • tag: Sets the tag of the container image.

  • maintainer: Specifies the author of the container. Equivalent to the MAINTAINER directive in a Dockerfile.

  • user: Sets the user name or user id (UID) to be used when running entrypoint and subcommand. Equivalent of the USER directive of a Dockerfile.

  • workingdir: Sets the working directory to be used when running cmd and entrypoint. Equivalent of the WORKDIR directive in a Dockerfile.

containerconfig child tags:

  • subcommand: Provides the default execution parameters of the container. Equivalent of the CMD directive in a Dockerfile.

  • labels: Adds custom metadata to an image using key-value pairs. Equivalent to one or more LABEL directives in a Dockerfile.

  • expose: Defines which ports can be exposed to the outside when running this container image. Equivalent to one or more EXPOSE directives in a Dockerfile.

  • environment: Sets environment variables using key-value pairs. Equivalent to one or multiple ENV directives in a Dockerfile.

  • entrypoint: Sets the binary to use for executing all commands inside the container. Equivalent of the ENTRYPOINT directive in a Dockerfile.

  • volumes: Creates mountpoints with the given name and marks them to hold external volumes from the host or from other containers. Equivalent to one or more VOLUME directives in a Dockerfile.

  • stopsignal: The stopsignal element sets the system call signal that will be sent to the container to exit. This signal can be a signal name in the format SIG[NAME], for instance SIGKILL, or an unsigned number that matches a position in the kernel’s syscall table, for instance 9. The default is SIGTERM if not defined

Other Dockerfile directives such as RUN, COPY or ADD, can be mapped to KIWI NG using the script file to run Bash commands, or the overlay tree to include additional files.

The following example illustrates how to build a container image based on openSUSE Leap:

  1. Make sure you have checked out the example image descriptions (see Example Appliance Descriptions).

  2. Include the Virtualization/containers repository into your list (replace the placeholder <DIST> with the name of the desired distribution):

    $ zypper addrepo<DIST> container-tools
  3. Install umoci and skopeo tools

    $ zypper in umoci skopeo
  4. Build an image with KIWI NG:

    $ sudo kiwi-ng system build \
        --description kiwi/build-tests/x86/leap/test-image-docker \
        --set-repo obs://openSUSE:Leap:15.5/standard \
        --target-dir /tmp/myimage
  5. Test the container image.

    First load the new image into your container runtime:

    $ podman load -i kiwi-test-image-docker.x86_64-1.15.3.docker.tar.xz

    Then run the image:

    $ podman run --rm -it buildsystem /bin/bash