Container Images
Container Image extensions
Jib
The extension quarkus-container-image-jib
is powered by
Jib for performing container
image builds. The major benefit of using Jib with Quarkus is that all the
dependencies (everything found under target/lib
) are cached in a different
layer than the actual application making rebuilds really fast and small
(when it comes to pushing). Another important benefit of using this
extension is that it provides the ability to create a container image
without having to have any dedicated client side tooling (like Docker) or
running daemon processes (like the Docker daemon) when all that is needed
is the ability to push to a container image registry.
To use this feature, add the following extension to your project:
quarkus extension add container-image-jib
./mvnw quarkus:add-extension -Dextensions='container-image-jib'
./gradlew addExtension --extensions='container-image-jib'
In situations where all that is needed to build a container image and no
push to a registry is necessary (essentially by having set
quarkus.container-image.build=true and left quarkus.container-image.push
unset - it defaults to false ), then this extension creates a container
image and registers it with the Docker daemon. This means that although
Docker isn’t used to build the image, it is nevertheless necessary. Also
note that using this mode, the built container image will show up when
executing docker images .
|
Including extra files
There are cases when additional files (other than ones produced by the
Quarkus build) need to be added to a container image. To support these
cases, Quarkus copies any file under src/main/jib
into the built container
image (which is essentially the same idea that the Jib Maven and Gradle
plugins support). For example, the presence of src/main/jib/foo/bar
would
result in /foo/bar
being added into the container filesystem.
JVM Debugging
There are cases where the built container image may need to have Java debugging conditionally enabled at runtime.
When the base image has not been changed (and therefore
ubi8/openjdk-11-runtime
, ubi8/openjdk-17-runtime
, or
ubi8/openjdk-21-runtime
is used), then the quarkus.jib.jvm-arguments
configuration property can be used in order to make the JVM listen on the
debug port at startup.
The exact configuration is:
quarkus.jib.jvm-arguments=-agentlib:jdwp=transport=dt_socket\\,server=y\\,suspend=n\\,address=*:5005
Other base images might provide launch scripts that enable debugging when an environment variable is set, in which case you would set than environment variable when launching the container.
Custom Entrypoint
The quarkus.jib.jvm-entrypoint
configuration property can be used to
completely override the container entry point and can thus be used to either
hard code the JVM debug configuration or point to a script that handles the
details.
For example, if the base images ubi8/openjdk-11-runtime
,
ubi8/openjdk-17-runtime
or ubi8/openjdk-21-runtime
are used to build the
container, the entry point can be hard-coded on the application properties
file.
quarkus.jib.jvm-entrypoint=java,-Dcustom.param=custom_value,-jar,quarkus-run.jar
Or a custom start-up script can be created and referenced on the properties file. This approach works better if there’s a need to set application params using environment variables:
quarkus.jib.jvm-entrypoint=/bin/sh,run-java.sh
java \
-Djavax.net.ssl.trustStore=/deployments/truststore \
-Djavax.net.ssl.trustStorePassword="$TRUST_STORE_PASSWORD" \
-jar quarkus-run.jar
/home/jboss is the WORKDIR for all quarkus binaries in the base images
ubi8/openjdk-11-runtime , ubi8/openjdk-17-runtime and
ubi8/openjdk-21-runtime
(Dockerfile for ubi8/openjdk-17-runtime)
|
Multi-module projects and layering
When building a multi-module project containing a Quarkus application as one module and various supporting project dependencies as other modules, Quarkus supports placing these supporting modules in a separate container image layer from the rest of the application dependencies, with the expectation that these supporting modules will change more frequently than the regular application dependencies - thus making a rebuild faster if the application dependencies have not changed.
To enable this feature, the property quarkus.bootstrap.workspace-discovery
needs to be set to true
either as a system property when invoking the
build tool, either as a build tool property. Setting this property in
application.properties
will not work because this property needs to be
known very early on in the build process.
AppCDS
Quarkus supports generating and including an Application Class Data Sharing archive when generating a container image using Jib. See the AppCDS documentation for more details.
Docker
The extension quarkus-container-image-docker
is using the Docker binary
and the generated Dockerfiles under src/main/docker
in order to perform
Docker builds.
To use this feature, add the following extension to your project.
quarkus extension add container-image-docker
./mvnw quarkus:add-extension -Dextensions='container-image-docker'
./gradlew addExtension --extensions='container-image-docker'
The quarkus-container-image-docker
extension is capable of
creating
multi-platform (or multi-arch) images using
docker
buildx build
. See the quarkus.docker.buildx.*
configuration items in the
Docker Options section below.
docker buildx build ONLY supports
loading
the result of a build to docker images when building for a single
platform. Therefore, if you specify more than one argument in the
quarkus.docker.buildx.platform property, the resulting images will not be
loaded into docker images . If quarkus.docker.buildx.platform is omitted
or if only a single platform is specified, it will then be loaded into
docker images .
|
OpenShift
The extension quarkus-container-image-openshift
is using OpenShift binary
builds in order to perform container builds inside the OpenShift cluster.
The idea behind the binary build is that you just upload the artifact and
its dependencies to the cluster and during the build they will be merged to
a builder image (defaults to fabric8/s2i-java
).
The benefit of this approach, is that it can be combined with OpenShift’s
DeploymentConfig
that makes it easy to roll out changes to the cluster.
To use this feature, add the following extension to your project.
quarkus extension add container-image-openshift
./mvnw quarkus:add-extension -Dextensions='container-image-openshift'
./gradlew addExtension --extensions='container-image-openshift'
OpenShift builds require creating a BuildConfig
and two ImageStream
resources, one for the builder image and one for the output image. The
creation of such objects is being taken care of by the Quarkus Kubernetes
extension.
Buildpack
The extension quarkus-container-image-buildpack
is using buildpacks in
order to perform container image builds. Under the hood buildpacks will use
a Docker daemon for the actual build. While buildpacks support alternatives
to Docker, this extension will only work with Docker.
Additionally, the user will have to configure which build image to use (no default image is provided). For example:
quarkus.buildpack.jvm-builder-image=<jvm builder image>
or for native:
quarkus.buildpack.native-builder-image=<native builder image>
To use this feature, add the following extension to your project.
quarkus extension add container-image-buildpack
./mvnw quarkus:add-extension -Dextensions='container-image-buildpack'
./gradlew addExtension --extensions='container-image-buildpack'
When using the buildpack container image extension it is strongly advised to
avoid adding quarkus.container-image.build=true in your properties
configuration as it might trigger nesting builds within builds. It’s
preferable to pass it as an option to the build command instead.
|
Building
To build a container image for your project,
quarkus.container-image.build=true
needs to be set using any of the ways
that Quarkus supports.
quarkus build -Dquarkus.container-image.build=true
./mvnw install -Dquarkus.container-image.build=true
./gradlew build -Dquarkus.container-image.build=true
If you ever want to build a native container image and already have an
existing native image you can set -Dquarkus.native.reuse-existing=true and
the native image build will not be re-run.
|
Using @QuarkusIntegrationTest
To run tests on the resulting image, quarkus.container-image.build=true
needs to be set using any of the ways that Quarkus supports.
./mvnw verify -Dquarkus.container-image.build=true
./gradlew quarkusIntTest -Dquarkus.container-image.build=true
Pushing
To push a container image for your project,
quarkus.container-image.push=true
needs to be set using any of the ways
that Quarkus supports.
quarkus build -Dquarkus.container-image.push=true
./mvnw install -Dquarkus.container-image.push=true
./gradlew build -Dquarkus.container-image.push=true
If no registry is set (using quarkus.container-image.registry ) then
docker.io will be used as the default.
|
Selecting among multiple extensions
It does not make sense to use multiple extension as part of the same
build. When multiple container image extensions are present, an error will
be raised to inform the user. The user can either remove the unneeded
extensions or select one using application.properties
.
For example, if both container-image-docker
and
container-image-openshift
are present and the user needs to use
container-image-docker
:
quarkus.container-image.builder=docker
Integrating with systemd-notify
If you are building a container image in order to deploy your Quarkus application as a Linux service with Podman and Systemd, you might want to consider including the Quarkus Systemd Notify Extension as part of your application, with:
quarkus extension add io.quarkiverse.systemd.notify:quarkus-systemd-notify
./mvnw quarkus:add-extension -Dextensions='io.quarkiverse.systemd.notify:quarkus-systemd-notify'
./gradlew addExtension --extensions='io.quarkiverse.systemd.notify:quarkus-systemd-notify'
Customizing
The following properties can be used to customize the container image build process.
Container Image Options
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
The group the container image will be part of Environment variable: Show more |
string |
|
The name of the container image. If not set defaults to the application name Environment variable: Show more |
string |
|
The tag of the container image. If not set defaults to the application version Environment variable: Show more |
string |
|
Additional tags of the container image. Environment variable: Show more |
list of string |
|
The container registry to use Environment variable: Show more |
string |
|
Represents the entire image string. If set, then Environment variable: Show more |
string |
|
The username to use to authenticate with the registry where the built image will be pushed Environment variable: Show more |
string |
|
The password to use to authenticate with the registry where the built image will be pushed Environment variable: Show more |
string |
|
Whether or not insecure registries are allowed Environment variable: Show more |
boolean |
|
Whether or not a image build will be performed. Environment variable: Show more |
boolean |
|
Whether or not an image push will be performed. Environment variable: Show more |
boolean |
|
The name of the container image extension to use (e.g. docker, jib, s2i). The option will be used in case multiple extensions are present. Environment variable: Show more |
string |
|
Custom labels to add to the generated image. Environment variable: Show more |
|
Using CI Environments
Various CI environments provide a ready to use container-image registry which can be combined with the container-image Quarkus extensions in order to effortlessly create and push a Quarkus application to said registry.
For example, GitLab provides such a registry and in the
provided CI environment, makes available the CI_REGISTRY_IMAGE
environment
variable (see GitLab’s
documentation) for more
information), which can be used in Quarkus like so:
quarkus.container-image.image=${CI_REGISTRY_IMAGE}
See this for more information on how to combine properties with environment variables. |
Jib Options
In addition to the generic container image options, the
container-image-jib
also provides the following options:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
The base image to be used when a container image is being produced for the jar build. When the application is built against Java 21 or higher, Environment variable: Show more |
string |
|
The base image to be used when a container image is being produced for the native binary build. The default is "quay.io/quarkus/quarkus-micro-image". You can also use "registry.access.redhat.com/ubi8/ubi-minimal" which is a bigger base image, but provide more built-in utilities such as the microdnf package manager. Environment variable: Show more |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: Show more |
list of string |
|
If this is set, then it will be used as the entry point of the container image. There are a few things to be aware of when creating an entry point
Environment variable: Show more |
list of string |
|
If this is set, then it will be used as the entry point of the container image. There are a few things to be aware of when creating an entry point
Environment variable: Show more |
list of string |
|
The username to use to authenticate with the registry used to pull the base JVM image Environment variable: Show more |
string |
|
The password to use to authenticate with the registry used to pull the base JVM image Environment variable: Show more |
string |
|
list of int |
|
|
The user to use in generated image Environment variable: Show more |
string |
|
The working directory to use in the generated image. The default value is chosen to work in accordance with the default base image. Environment variable: Show more |
string |
|
Controls the optimization which skips downloading base image layers that exist in a target registry. If the user does not set this property, then read as false. If Environment variable: Show more |
boolean |
|
List of target platforms. Each platform is defined using the pattern:
for example:
If not specified, OS default is linux and architecture default is Environment variable: Show more |
list of string |
|
The path of a file in which the digest of the generated image will be written. If the path is relative, the base path is the output directory of the build tool. Environment variable: Show more |
string |
|
The path of a file in which the id of the generated image will be written. If the path is relative, the base path is the output directory of the build tool. Environment variable: Show more |
string |
|
Whether or not to operate offline. Environment variable: Show more |
boolean |
|
Name of binary used to execute the docker commands. This is only used by Jib when the container image is being built locally. Environment variable: Show more |
string |
|
Whether to set the creation time to the actual build time. Otherwise, the creation time will be set to the Unix epoch (00:00:00, January 1st, 1970 in UTC). See Jib FAQ for more information Environment variable: Show more |
boolean |
|
Whether to set the modification time (last modified time) of the files put by Jib in the image to the actual build time. Otherwise, the modification time will be set to the Unix epoch (00:00:00, January 1st, 1970 in UTC). If the modification time is constant (flag is set to false so Unix epoch is used) across two consecutive builds, the docker layer sha256 digest will be different only if the actual files added by Jib to the docker layer were changed. More exactly, having 2 consecutive builds will generate different docker layers only if the actual content of the files within the docker layer was changed. If the current timestamp is used the sha256 digest of the docker layer will always be different even if the content of the files didn’t change. Environment variable: Show more |
boolean |
|
Environment variables to add to the container image Environment variable: Show more |
|
|
Sets environment variables used by the Docker executable. This is only used by Jib when the container image is being built locally. Environment variable: Show more |
|
Docker Options
In addition to the generic container image options, the
container-image-docker
also provides the following options:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
Path to the JVM Dockerfile. If set to an absolute path then the absolute path will be used, otherwise the path will be considered relative to the project root. If not set src/main/docker/Dockerfile.jvm will be used. Environment variable: Show more |
string |
|
Path to the native Dockerfile. If set to an absolute path then the absolute path will be used, otherwise the path will be considered relative to the project root. If not set src/main/docker/Dockerfile.native will be used. Environment variable: Show more |
string |
|
Images to consider as cache sources. Values are passed to Environment variable: Show more |
list of string |
|
The networking mode for the RUN instructions during build Environment variable: Show more |
string |
|
Name of binary used to execute the docker commands. This setting can override the global container runtime detection. Environment variable: Show more |
string |
|
Additional arbitrary arguments passed to the executable when building the container image. Environment variable: Show more |
list of string |
|
Build args passed to docker via Environment variable: Show more |
|
|
Type |
Default |
|
Which platform(s) to target during the build. See https://docs.docker.com/engine/reference/commandline/buildx_build/#platform Environment variable: Show more |
list of string |
|
Sets the export action for the build result. See https://docs.docker.com/engine/reference/commandline/buildx_build/#output. Note that any filesystem paths need to be absolute paths, not relative from where the command is executed from. Environment variable: Show more |
string |
|
Set type of progress output ( Environment variable: Show more |
string |
OpenShift Options
In addition to the generic container image options, the
container-image-openshift
also provides the following options:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
The build config strategy to use. Environment variable: Show more |
|
|
The base image to be used when a container image is being produced for the jar build. The value of this property is used to create an ImageStream for the builder image used in the Openshift build. When it references images already available in the internal Openshift registry, the corresponding streams are used instead. When the application is built against Java 21 or higher, Environment variable: Show more |
string |
|
The base image to be used when a container image is being produced for the native binary build. The value of this property is used to create an ImageStream for the builder image used in the Openshift build. When it references images already available in the internal Openshift registry, the corresponding streams are used instead. Environment variable: Show more |
string |
|
The default Dockerfile to use for jvm builds Environment variable: Show more |
string |
|
The default Dockerfile to use for native builds Environment variable: Show more |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: Show more |
list of string |
|
The directory where the jar is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non default image is used. Environment variable: Show more |
string |
|
The resulting filename of the jar in the S2I image. This option may be used if the selected S2I image uses a fixed name for the jar. Environment variable: Show more |
string |
|
The directory where the native binary is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non-default image is used. Environment variable: Show more |
string |
|
The resulting filename of the native binary in the S2I image. This option may be used if the selected S2I image uses a fixed name for the native binary. Environment variable: Show more |
string |
|
The build timeout. Environment variable: Show more |
|
|
The log level of OpenShift build log. Environment variable: Show more |
|
|
The image push secret to use for pushing to external registries. (see: https://cloud.redhat.com/blog/pushing-application-images-to-an-external-registry) Environment variable: Show more |
string |
|
The build config strategy to use. Environment variable: Show more |
|
|
The base image to be used when a container image is being produced for the jar build. When the application is built against Java 17 or higher, Environment variable: Show more |
string |
|
The base image to be used when a container image is being produced for the native binary build Environment variable: Show more |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: Show more |
list of string |
|
The directory where the jar is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non default image is used. Environment variable: Show more |
string |
|
The resulting filename of the jar in the S2I image. This option may be used if the selected S2I image uses a fixed name for the jar. Environment variable: Show more |
string |
|
The directory where the native binary is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non-default image is used. Environment variable: Show more |
string |
|
The resulting filename of the native binary in the S2I image. This option may be used if the selected S2I image uses a fixed name for the native binary. Environment variable: Show more |
string |
|
The build timeout. Environment variable: Show more |
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|