Build a Container Image

KIWI NG is capable of building native Container Images from scratch and derived ones. KIWI NG Container images are considered to be native since the KIWI NG tarball image is ready to be loaded into a Container Runtime like Podman, Docker or Containerd, including common container configurations.

The Container configuration metadata is provided 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 field of the container, this is 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: Define 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 via which all commands inside the container will be executed. Equivalent of the ENTRYPOINT directive in a Dockerfile.

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

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 to your list:

    $ zypper addrepo<DIST> container-tools

    where the placeholder <DIST> is the preferred distribution.

  3. Install umoci and skopeo tools

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

    $ sudo kiwi-ng system build \
        --description kiwi/build-tests/x86/leap/test-image-docker \
        --set-repo obs://openSUSE:Leap:15.3/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

    and then run the image:

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