Quarkus Images

This repository contains the container images used by Quarkus.

NOTE: Require CEKit 3.10.x

Quarkus images

The images are available on Quay.io

• ubi-quarkus-native-image - provides the native-image executable. Used by the Maven and Gradle plugin from Quarkus to build linux64 executables
• ubi-quarkus-mandrel - provides the native-image executable from the Mandrel distribution of GraalVM. Used by the Maven and Gradle plugin from Quarkus to build linux64 executables
• centos-quarkus-maven - Image delivering GraalVM, Maven, Gradle, Podman and Buildah; this image can be used to build a native executable from source.
• ubi-quarkus-native-s2i - S2I builder image for OpenShift building a native image from source code (using Gradle or Maven)
• ubi-quarkus-native-binary-s2i - S2I builder image for OpenShift taking a pre-built native executable as input

To pull these images use:

• docker pull quay.io/quarkus/ubi-quarkus-native-image:VERSION
• docker pull quay.io/quarkus/ubi-quarkus-mandrel:VERSION
• docker pull quay.io/quarkus/centos-quarkus-maven:VERSION
• docker pull quay.io/quarkus/ubi-quarkus-native-s2i:VERSION
• docker pull quay.io/quarkus/ubi-quarkus-native-binary-s2i:1.0

with VERSION being the version. The version matches the GraalVM version used in the image, for example: 21.1.0-java11, 21.1.0-java16...

quay.io/quarkus/ubi-quarkus-native-s2i:21.1.0-java11 <-- GraalVM 21.1.0 with java 11 support
quay.io/quarkus/ubi-quarkus-native-s2i:21.1.0-java16 <-- GraalVM 21.1.0 with java 16 support
quay.io/quarkus/ubi-quarkus-native-binary-s2i:1.0 <-- Native binary s2i

NOTE: You may wonder why we don't use latest. It's because latest has introduced more problems than benefits especially when reproducing issues. For this reason, we recommend using a stable version.

Build Prerequisites

CEKit

To build you need CEKit. We recommend using virtualenv to run cekit. On MacOS X and Linux, you can run the build as follows:

virtualenv --python=python3 .cekit
source .cekit/bin/activate
pip install -r requirements.txt

# Run the scripts from the .github directory
# i.e. .github/build-native-images.sh

For other Systems, please refer to the CEKit docs.

s2i

s2i are needed for tests, download your OS version from https://github.com/openshift/source-to-image/releases/latest and put it in s2i folder.

Something like the following:

mkdir s2i
cd s2i
tar -zxvf source-to-image-*.tar.gz

Build

The build is controlled by 5 image files:

• quarkus-native-image.yaml produces ubi-quarkus-native-image images
• quarkus-mandrel.yaml produces ubi-quarkus-mandrel images
• quarkus-micro-image.yaml produces the quarkus-micro-image image, a runtime image to execute your native executable
• quarkus-native-binary-s2i.yaml produces the ubi-quarkus-native-binary-s2i image
• quarkus-native-s2i.yaml produces the ubi-quarkus-native-s2i images
• quarkus-tooling.yaml produces the centos-quarkus-maven images (deprecated)

To build the images, you must pass the "GraalVM" version as parameter (except for quarkus-mandrel.yaml, quarkus-native-binary-s2i.yaml and quarkus-micro-image.yaml):

cekit --descriptor ${IMAGE} build \
        --overrides "{'version': '${version}', 'modules': {'install': [{'name':'graalvm', 'version': '${version}'}]}}" \
        docker --tag="${IMAGE_NAME}:${version}"

For quarkus-mandrel.yaml you must pass the "Mandrel" version instead:

cekit --descriptor ${IMAGE} build \
        --overrides "{'version': '${version}', 'modules': {'install': [{'name':'mandrel', 'version': '${version}'}]}}" \
        docker --tag="${IMAGE_NAME}:${version}"

The .github directory contains the script to build the different images.

Note about CEKit

Run the scripts from the .github directory

Images

native-image

This image provides GRAALVM and the native-image executable. It is used by the Quarkus Maven plugin and Quarkus Gradle plugin to generate linux 64 executable.

S2I - Source to Image

S2I (Source to Image) are builder images used by OpenShift to build image streams. Two S2I are available:

• GraalVM Native S2I - build your source code using Maven or Gradle and create a new container image from the produced native executable.
• Binary S2I - build a new container image from a provided native executable. This executable is generally built on your machine, and uploaded.

Both resulting containers are based on UBI images.

Centos + GraalVM + Maven/Gradle Image

For more information about this image, please refer to its module README: centos-quarkus-maven

Maintenance

IMPORTANT: The images are produced both the last 2 versions of GraalVM. For most images, this version defines the image tag (i.e. version)

Updating GraalVM version

1. Create new directories under modules/graalvm named after the new version. You need to create 2 directories to distinguish the java versions, e.g. java11 and java16.
2. In each directory, write the configure and module.yaml files. The configure file should not differ from the existing versions, so just copy it. In the module.yaml, change the versions, labels, sha256 hash...
3. In the .github directory, edit the native-images.yaml, mandrel-images.yaml, s2i-native-images.yaml and tooling-images.yaml to add/replace versions in the versions list. If needed, also update tha tags list.

IMPORTANT: Always keep the last GraalVM LTS.

Updating the Maven/Gradle versions

1. Create a new directory under modules/maven-binary / modules/gradle-binary named after the new version
2. In the new directory, create (or copy from an existing version) the configure and module.yaml file
3. Edit the module.yaml file to target the new version
4. Edit the quarkus-native-s2i.yaml and quarkus-tooling.yaml files to update the Maven/Gradle version

Building, testing and pushing the images

Before proceeding make sure you have CEKit installed, see build.

Build:

The build scripts are located in the .github directory:

• build-distroless-images.sh - build the distroless images suitable for packaging native applications (experimental)
• build-mandrel-images.sh - build the mandrel images
• build-micro-images.sh - build the micro images suitable for packaging native applications on an UBI based image
• build-native-images.sh - build the images providing the native-image executable
• build-s2i-binary-images.sh - build the s2i builder images taking a pre-built native executable
• build-s2i-native-images.sh - build the s2i builder images taking Java sources as input and building the native executable and the container
• build-tooling-images.sh - build the tooling image (deprecated)

Except build-s2i-binary-images.sh, the other scripts expect the GraalVM/Mandrel version as unique parameter:

> .github/build-native-images.sh 20.2.0-java11

Continuous Integration and Automation

This repository uses GitHub Actions to build the images. On each PR, the images are built. Check the Actions tab in the GitHub project.

To push the images to Quay, you need to trigger a deployment. Once the images have been built from master successfully, issue the following cURL command:

curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
    -H "Accept: application/vnd.github.ant-man-preview+json"  \
    -H "Content-Type: application/json" \
    https://api.github.com/repos/quarkusio/quarkus-images/deployments \
    --data '{"ref": "main", "environment": "quay"}'

Note that you need a GITHUB_TOKEN (API token) to trigger the deployment.