Debian Codegraph @

doc/source/building_images/build_container_image.rst

raw
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