Supported builder engines¶
CEKit supports following builder engines:
Docker builder – builds the container image using Docker
OSBS builder – builds the container image using OSBS service
Buildah builder – builds the container image using Buildah
Podman builder – builds the container image using Podman
Docker builder¶
This builder uses Docker daemon as the build engine. Interaction with Docker daemon is done via Python binding.
By default every image is squashed at the end of the build. This means that all layers above the base image
will be squashed into a single layer. You can disable it by using the --no-squash
switch.
- Input format
Dockerfile
- Parameters
--pull
Ask a builder engine to check and fetch latest base image
--tag
<tag-name>Use specified tag to tag the image after the build. (can be specified multiple times). If not specified then the image will be tagged with
<name>:<version>
and<name>:latest
using keys from the image descriptor.--no-squash
Do not squash the image after build is done.
--platform
Set the ARCH of the image to the provided value(s).
- Example
Building Docker image
$ cekit build docker
Remote Docker daemon¶
It is possible to use environment variables to let CEKit know where is the Docker daemon located it should connect to.
Note
Read more about Docker daemon settings related to exposing it to clients.
By default, if you do not specify anything, CEKit will try to use a locally running Docker daemon.
If you need to customize this behavior (for example when you want to use Docker daemon
running in a VM) you can set following environment variables: DOCKER_HOST
, DOCKER_TLS_VERIFY
and
DOCKER_CERT_PATH
. See section about Docker environment variables
below for more information.
Docker environment variables¶
DOCKER_HOST
The
DOCKER_HOST
environment variable is where you specify where the Daemon is running. It supports multiple protocols, but the most widely used ones are:unix://
(where you specify path to a local socket) andtcp://
(where you can define host location and port).Examples of
DOCKER_HOST
:unix:///var/run/docker.sock
,tcp://192.168.22.33:1234
.Depending how your daemon is configured you may need to configure settings related to encryption.
# Connect to a remote Docker daemon $ DOCKER_HOST="tcp://192.168.22.33:1234" cekit build docker
DOCKER_TLS_VERIFY
You can set
DOCKER_TLS_VERIFY
to a non-empty value to indicate that the TLS verification should take place. By default certificate verification is disabled.DOCKER_CERT_PATH
You can point
DOCKER_CERT_PATH
environment variable to a directory containing certificates to use when connecting to the Docker daemon.DOCKER_TMPDIR
You can change the temporary directory used by Docker daemon by specifying the
DOCKER_TMPDIR
environment variable.Note
Please note that this is environment variable should be set on the daemon and not on the client (CEKit command you execute). You need to modify your Docker daemon configuration and restart Docker to apply new value.
By default it points to
/var/lib/docker/tmp
. If you are short on space there, you may want to use a different directory. This temporary directory is used to generate the TAR file with the image that is later processed by the squash tool. If you have large images, make sure you have sufficient free space there.TMPDIR
This environment variable controls which directory should be used when a temporary directory is created by the CEKit tool. In case the default temporary directory location is low on space it may be required to point to a different location.
One example when such change could be required is when the squash post-processing of the image is taking place and the default temporary directory location is low on space. Squashing requires to unpack the original image TAR file and apply transformation on it. This can be very storage-consuming process.
You can read more on how this variable is used in the Python docs.
$ TMPDIR="/mnt/external/tmp" cekit build docker
DOCKER_TIMEOUT
By default it is set to
600
seconds.This environment variable is responsible for setting how long we will wait for the Docker daemon to return data. Sometimes, when the Docker daemon is busy and you have large images, it may be required to set this variable to some even higher number. Setting proper value is especially important when the squashing post-processing takes place because this is a very resource-consuming task and can take several minutes.
$ DOCKER_TIMEOUT="1000" cekit build docker
OSBS builder¶
This build engine is using rhpkg
or fedpkg
tool to build the image using OSBS service. By default
it performs scratch build. If you need a proper build you need to specify --release
parameter.
By default every image is squashed at the end of the build. This means that all layers above the base image will be squashed into a single layer.
Note
URL based artifacts (See here) will not be cached and instead will be added to fetch-artifacts.yaml
to use the OSBS integration. This may be constrained by using OSBS URL Restriction configuration
Note
Extra OSBS Configuration may be passed in via the OSBS descriptor (See here). Automatic Cachito integration may also be included within the OSBS Configuration and if this is detected CEKit will include the commands in the Dockerfile.
- Input format
Dockerfile
- Parameters
--release
Perform an OSBS release build (default is a scratch build)
--user
Alternative user passed to build task
--nowait
Do not wait for the task to finish
--stage
Use stage environment
--commit-message
Custom commit message for dist-git
--tag
<tag-name>Added in version 4.4.0.
An optional annotated tag to be applied to both the source and the dist-git repository after a successful non-scratch build.
If the tag parameter is not specified then it will be constructed from the image name (with
/
changed to-
) and the image version. Finally the release increment will be retrieved from the OSBS Brew build and appended. The default tag name equates to the NVR.The tag name may be constructed using Jinja template e.g.
{{name}}-{{version}}
referencing the keys in the image descriptor.--sync-only
Added in version 3.4.
Generate files and sync with dist-git, but do not execute build
--assume-yes
Added in version 3.4.
Run build in non-interactive mode answering all questions with ‘Yes’, useful for automation purposes
- Example
Performing scratch build
$ cekit build osbs
Performing release build
$ cekit build osbs --release
Buildah builder¶
This build engine is using Buildah.
By default every image is squashed at the end of the build. This means that all layers (including the base image)
will be squashed into a single layer. You can disable it by using the --no-squash
switch.
Note
If you need to use any non default registry, please update /etc/containers/registry.conf
file.
- Input format
Dockerfile
- Parameters
--pull
Ask a builder engine to check and fetch latest base image
--tag
<tag-name>Use specified tag to tag the image after the build. (can be specified multiple times). If not specified then the image will be tagged with
<name>:<version>
and<name>:latest
using keys from the image descriptor.--no-squash
Do not squash the image after build is done.
--platform
Set the ARCH of the image to the provided value(s).
- Example
Build image using Buildah
$ cekit build buildah
Build image using Buildah and tag it as
example/image:1.0
$ cekit build buildah --tag example/image:1.0
Buildah environment variables¶
BUILDAH_LAYERS
The
BUILDAH_LAYERS
environment variable allows you to control whether the builder engine will cache intermediate layers during build.By default it is set to
false
.You can enable it by setting the environment variable to
true
. The initial build process will take longer because result of every command will need to be stored on the disk (commited), but subsequent builds (without any code change) should be faster because the layer cache will be reused.$ BUILDAH_LAYERS="true" cekit build buildah
Warning
Caching layers conflicts with multi-stage builds. A ticket was opened: https://bugzilla.redhat.com/show_bug.cgi?id=1746022. If you use multi-stage builds, make sure the
BUILDAH_LAYERS
environment variable is set tofalse
.
Podman builder¶
This build engine is using Podman. Podman will perform non-privileged builds so no special configuration is required.
By default every image is squashed at the end of the build. This means that all layers (including the base image)
will be squashed into a single layer. You can disable it by using the --no-squash
switch.
- Input format
Dockerfile
- Parameters
--pull
Ask a builder engine to check and fetch latest base image
--tag
<tag-name>Use specified tag to tag the image after the build. (can be specified multiple times). If not specified then the image will be tagged with
<name>:<version>
and<name>:latest
using keys from the image descriptor.--no-squash
Do not squash the image after build is done.
--platform
Set the ARCH of the image to the provided value(s).
- Example
Build image using Podman
$ cekit build podman
Build image using Podman
$ cekit build podman --pull
Podman environment variables¶
BUILDAH_LAYERS
Note
Yes, the environment variable is called
BUILDAH_LAYERS
, there is no typo. Podman uses Buildah code underneath.The
BUILDAH_LAYERS
environment variable allows you to control whether the builder engine will cache intermediate layers during build.By default it is set to
true
.You can disable it by setting the environment variable to
false
. This will make the build faster because there will be no need to commit result of every command. The downside of this setting is that you will not be able to leverage layer cache in subsequent builds.$ BUILDAH_LAYERS="false" cekit build podman
Warning
Caching layers conflicts with multi-stage builds. A ticket was opened: https://bugzilla.redhat.com/show_bug.cgi?id=1746022. If you use multi-stage builds, make sure the
BUILDAH_LAYERS
environment variable is set tofalse
.