| 1 |
.. _building_container_build: |
| 2 |
|
| 3 |
Build a Container Image |
| 4 |
======================= |
| 5 |
|
| 6 |
.. sidebar:: Abstract |
| 7 |
|
| 8 |
This page explains how to build a Container Image. It covers the following topics: |
| 9 |
|
| 10 |
* a basic configuration explanation |
| 11 |
* how to build a Container Image |
| 12 |
* how to run it with a Container Runtime |
| 13 |
|
| 14 |
{kiwi} can build native container images from scratch or using existing images. |
| 15 |
{kiwi} container images are considered native because a {kiwi} tarball |
| 16 |
image can be loaded directly into container runtimes like Podman, Docker, or |
| 17 |
Containerd, including common container configurations. |
| 18 |
|
| 19 |
The container configuration metadata is supplied to {kiwi} as part of the |
| 20 |
:ref:`XML description file <description_components>` using the |
| 21 |
`<containerconfig>` tag. The following configuration metadata can be |
| 22 |
specified. |
| 23 |
|
| 24 |
`containerconfig` attributes: |
| 25 |
|
| 26 |
* ``name``: Specifies the repository name of the container image. |
| 27 |
* ``tag``: Sets the tag of the container image. |
| 28 |
* ``maintainer``: Specifies the author of the container. Equivalent to the |
| 29 |
`MAINTAINER` directive in a :file:`Dockerfile`. |
| 30 |
* ``user``: Sets the user name or user id (UID) to be used when |
| 31 |
running `entrypoint` and `subcommand`. Equivalent to the `USER` |
| 32 |
directive of a :file:`Dockerfile`. |
| 33 |
* ``workingdir``: Sets the working directory to be used when running |
| 34 |
`cmd` and `entrypoint`. Equivalent to the `WORKDIR` directive in a |
| 35 |
:file:`Dockerfile`. |
| 36 |
|
| 37 |
`containerconfig` child tags: |
| 38 |
|
| 39 |
* ``subcommand``: Provides the default execution parameters of the |
| 40 |
container. Equivalent to the `CMD` directive in a :file:`Dockerfile`. |
| 41 |
* ``labels``: Adds custom metadata to an image using key-value pairs. |
| 42 |
Equivalent to one or more `LABEL` directives in a :file:`Dockerfile`. |
| 43 |
* ``expose``: Defines which ports can be exposed to the outside when |
| 44 |
running this container image. Equivalent to one or more `EXPOSE` |
| 45 |
directives in a :file:`Dockerfile`. |
| 46 |
* ``environment``: Sets environment variables using key-value pairs. |
| 47 |
Equivalent to one or multiple `ENV` directives in a :file:`Dockerfile`. |
| 48 |
* ``entrypoint``: Sets the binary to use for executing all commands inside the |
| 49 |
container. Equivalent to the `ENTRYPOINT` directive of a :file:`Dockerfile`. |
| 50 |
* ``volumes``: Creates mountpoints with the given name and marks them to hold |
| 51 |
external volumes from the host or from other containers. Equivalent to |
| 52 |
one or more `VOLUME` directives in a :file:`Dockerfile`. |
| 53 |
* ``stopsignal``: The `stopsignal` element sets the system call signal that |
| 54 |
will be sent to the container to exit. This signal can be a signal name |
| 55 |
in the format `SIG[NAME]`, for instance, `SIGKILL`, or an unsigned number that |
| 56 |
matches a position in the kernel's syscall table, for instance, 9. |
| 57 |
The default is `SIGTERM` if not defined. |
| 58 |
|
| 59 |
Other :file:`Dockerfile` directives such as `RUN`, `COPY`, or `ADD`, |
| 60 |
can be mapped to {kiwi} using the |
| 61 |
:ref:`config.sh <description_components>` script file to run Bash commands, |
| 62 |
or the :ref:`overlay tree <description_components>` to include |
| 63 |
additional files. |
| 64 |
|
| 65 |
The following example illustrates how to build a container image based on |
| 66 |
openSUSE Leap: |
| 67 |
|
| 68 |
1. Make sure you have checked out the example image descriptions |
| 69 |
(see :ref:`example-descriptions`). |
| 70 |
|
| 71 |
#. Include the `Virtualization/containers` repository in your list (replace the placeholder `<DIST>` with the name of the desired distribution): |
| 72 |
|
| 73 |
.. code:: bash |
| 74 |
|
| 75 |
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/containers/<DIST> container-tools |
| 76 |
|
| 77 |
#. Install `umoci` and `skopeo` tools. |
| 78 |
|
| 79 |
.. code:: bash |
| 80 |
|
| 81 |
$ zypper in umoci skopeo |
| 82 |
|
| 83 |
#. Build an image with {kiwi}: |
| 84 |
|
| 85 |
.. code:: bash |
| 86 |
|
| 87 |
$ sudo kiwi-ng system build \ |
| 88 |
--description kiwi/build-tests/{exc_description_docker} \ |
| 89 |
--set-repo {exc_repo_leap} \ |
| 90 |
--target-dir /tmp/myimage |
| 91 |
|
| 92 |
#. Test the container image. |
| 93 |
|
| 94 |
First, load the new image into your container runtime: |
| 95 |
|
| 96 |
.. code:: bash |
| 97 |
|
| 98 |
$ podman load -i {exc_image_base_name_docker}.x86_64-{exc_image_version}.docker.tar.xz |
| 99 |
|
| 100 |
Then, run the image: |
| 101 |
|
| 102 |
.. code:: bash |
| 103 |
|
| 104 |
$ podman run --rm -it buildsystem /bin/bash |