Deploying your Quarkus applications to OpenShift

Guide
  • Red Hat build of Quarkus 2.2
  • Updated 30 March 2022
  • Published 02 December 2021

Topics included in this guide

Deploying your Quarkus applications to OpenShift

Guide
Red Hat build of Quarkus 2.2
  • Updated 30 March 2022
  • Published 02 December 2021

As an application developer, you can deploy your Quarkus applications to OpenShift using a single Maven command. This functionality is provided by the quarkus-openshift extension, which supports multiple deployment options, including the Docker build strategy and the Source-to-Image (S2I) strategy.

In the Red Hat build of Quarkus documentation, you will learn the recommended workflows to deploy your Quarkus applications to production environments. To learn about alternative deployments, see the Quarkus community documentation.

Prerequisites

  • Have either OpenJDK (JDK) 11 or 17 installed, and ensure that the JAVA_HOME environment variable is set to specify the location of the Java SDK.

  • Have Apache Maven 3.8.1 or higher installed.

  • Have a Quarkus Maven project that includes the quarkus-openshift extension.

  • Have access to a Red Hat OpenShift Container Platform cluster and the latest version of the OpenShift CLI (oc) installed.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

1. OpenShift build strategies and Quarkus

Red Hat OpenShift Container Platform is a Kubernetes-based platform for developing and running containerized applications. For security and convenience, OpenShift supports different build strategies that are not available in the upstream Kubernetes distributions.

Overview of OpenShift build strategies
Docker build
This strategy builds the artifacts (JAR files or a native executable) outside the OpenShift cluster, either locally or in a CI environment, and then provides them to the OpenShift build system together with a Dockerfile. The container is built inside the OpenShift cluster and provided as an image stream.
Since Red Hat build of Quarkus 2.2, the OpenShift Docker build strategy is the preferred build strategy that supports Quarkus applications targeted for JVM as well as Quarkus applications compiled to native executables. However, the S2I remains the default deployment strategy for compatibility with earlier versions. You can configure the deployment strategy using the quarkus.openshift.build-strategy property.
Source to Image (S2I)
The build process is performed inside the OpenShift cluster. Using S2I to deploy Red Hat build of Quarkus as a JVM application is fully supported.
Binary S2I
This strategy uses a JAR file as an input to the S2I build process, which speeds up the build process and deployment of your application.
Table 1. Quarkus support OpenShift build strategies
Build strategy Support for Quarkus tooling Support for JVM Support for Native Support for JVM Serverless Support for native Serverless

Docker build

YES

YES

YES

YES

YES

S2I Binary

YES

YES

NO

NO

NO

Source S2I

NO

YES

NO

NO

NO
Additional resources

2. Adding the Quarkus OpenShift extension

You need to add the quarkus-openshift extension as a dependency to your Quarkus project so that you can build and deploy your applications as a container image to be used inside your OpenShift cluster.

The OpenShift extension also generates OpenShift resources such as image streams, build configuration, deployment configuration, service definitions, and more. If your Quarkus application includes the quarkus-smallrye-health extension OpenShift can access the health endpoint and check the liveness and readiness of your application.

Prerequisites
Procedure

  1. Log in to OpenShift by using oc, and then change to the directory that contains your Quarkus Maven project.

  2. Use one of the following methods to add the quarkus-openshift extension to your project:

    1. Add the quarkus-openshift extension to the pom.xml file:

      pom.xml 
      <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-openshift</artifactId>
</dependency>

    2. Add the quarkus-openshift extension using the command line:

      ./mvnw com.redhat.quarkus.platform:quarkus-maven-plugin:2.2.3.Final-redhat-00013:add-extension -Dextensions="io.quarkus:quarkus-openshift"

3. Switching to the required OpenShift project

You can use the Red Hat OpenShift Container Platform command-line interface (CLI) to create applications and manage your OpenShift projects from a terminal. Use the information provided to create a new OpenShift project or switch to an existing one.

Prerequisites

  • Access to a Red Hat OpenShift Container Platform cluster

  • The latest version of the OpenShift CLI (oc) installed

Procedure

  1. Log in to the OpenShift CLI (oc):

    oc login

  2. Display the current project space:

    oc project -q

  3. Use one of the following steps to navigate to the required OpenShift project:

    1. If the project already exists, switch to the project:

      oc  project  <project_name>

    2. If the project does not exist, create a new project:

      oc new-project <project_name>
Additional resources

4. Setting the Java version for Docker

When you deploy your Red Hat build of Quarkus application into OpenShift in JVM mode by using a non-S2I Docker build strategy deployment option, ensure that the Docker build configuration file of your Maven project points to the OpenJDK version that your application is using.

From release 2.2.5, Red Hat build of Quarkus supports OpenJDK versions 11 and 17 in JVM mode. By default, the OpenJDK package specified in the Docker build configuration for Quarkus is configured for version 11.

In 2.2.5, Java 17 is not supported for building executables in native mode.

If your application is running in JVM mode on OpenJDK 17, use the following procedure to set the correct OpenJDK package. If your application is running on OpenJDK 11, you can skip this step.

Procedure

  1. Navigate to the src/main/docker sub-directory of your Maven project, and open Dockerfile.jvm.

  2. Set the ARG JAVA_PACKAGE variable to point to the OpenJDK 17 package, as outlined in the following configuration extract:

    FROM registry.access.redhat.com/ubi8/ubi-minimal:8.5

ARG JAVA_PACKAGE=java-17-openjdk-headless
...

5. Deploying Quarkus Java applications to OpenShift

By using the Quarkus OpenShift extension, you can deploy your application to OpenShift using the Docker build strategy. The container is built inside the OpenShift cluster and provided as an image stream.

Your Quarkus project includes pre-generated Dockerfiles with instructions. When you want to use a custom Dockerfile, you need to add the file in the src/main/docker directory or anywhere inside the module. Additionally, you need to set the path to your Dockerfile using the quarkus.openshift.jvm-dockerfile property.

Prerequisites

  • Have a Quarkus Maven project that includes the quarkus-openshift extension.

Procedure

  1. Log in to OpenShift by using oc, and then change to the directory that contains your Quarkus Maven project.

  2. Configure the following properties in your application.properties file:

    1. Set the Docker build strategy:

      quarkus.openshift.build-strategy=docker

    2. (Optional) If you are using an untrusted certificate, configure the KubernetesClient:

      quarkus.kubernetes-client.trust-certs=true

    3. (Optional) Expose the service to create an OpenShift route:

      quarkus.openshift.route.expose=true

    4. (Optional) Set the path to your custom Dockerfile:

      quarkus.openshift.jvm-dockerfile=<path_to_your_dockerfile>

      The following example shows the path to the Dockerfile.custom-jvm:

      quarkus.openshift.jvm-dockerfile=src/main/resources/Dockerfile.custom-jvm

  3. Package and deploy your Quarkus application to the current OpenShift project:

    ./mvnw clean package -Dquarkus.kubernetes.deploy=true
Verification

  1. To view a list of pods associated with your current OpenShift project:

    oc get pods

  2. To retrieve the log output for your application’s pod, enter the following command where <pod_name> is the name of the latest pod prefixed with the name of your application:

    oc logs -f <pod_name>

6. Deploying Quarkus applications compiled to native executables

You can deploy your native Quarkus application to OpenShift using the Docker build strategy. You need to create a native executable for your application that targets the Linux X86_64 operating system. If your host operating system is different from this, you will need to create a native Linux executable using a container runtime like Docker or Podman.

Your Quarkus project includes pre-generated Dockerfiles with instructions. When you want to use a custom Dockerfile, you need to add the file in the src/main/docker directory or anywhere inside the module. Additionally, you need to set the path to your Dockerfile using the quarkus.openshift.native-dockerfile property.

Prerequisites

  • A Linux X86_64 operating system or an OCI (Open Container Initiative) compatible container runtime, such as Podman or Docker.

  • Have a Quarkus Maven project that includes the quarkus-openshift extension.

Procedure

  1. Log in to OpenShift by using oc, and then change to the directory that contains your Quarkus Maven project.

  2. Configure the following properties in your application.properties file:

    1. Set the Docker build strategy:

      quarkus.openshift.build-strategy=docker

    2. Set the container runtime:

      quarkus.native.container-build=true

    3. (Optional) If you are using an untrusted certificate, configure the KubernetesClient:

      quarkus.kubernetes-client.trust-certs=true

    4. (Optional) Expose the service to create an OpenShift route:

      quarkus.openshift.route.expose=true

    5. (Optional) Set the path to your custom Dockerfile:

      quarkus.openshift.native-dockerfile=<path_to_your_dockerfile>

      The following example shows the path to the Dockerfile.custom-native:

      quarkus.openshift.jvm-dockerfile=src/main/docker/Dockerfile.custom-native

    6. (Optional) Specify the container engine:

      • To build a native executable with Podman:

        quarkus.native.container-runtime=podman

      • To build a native executable with Docker:

        quarkus.native.container-runtime=docker

  3. Build a native executable, package, and deploy your application to OpenShift:

    ./mvnw clean package -Pnative -Dquarkus.kubernetes.deploy=true
Verification

  1. To view a list of pods associated with your current OpenShift project:

    oc get pods

  2. To retrieve the log output for your application’s pod, enter the following command where <pod_name> is the name of the latest pod prefixed with the name of your application:

    oc logs -f <pod_name>

7. Deploying Quarkus applications as an OpenShift Serverless service

You can deploy your Quarkus applications to OpenShift Serverless using the Docker build strategy. By using OpenShift Serverless Knative Serving, you can scale services up and down depending on the load size. Scaling down services that are currently not requested improves memory capabilities.

Your Quarkus project includes pre-generated Dockerfiles with instructions. When you want to use a custom Dockerfile, you need to add the file in the src/main/docker directory or anywhere inside the module. Additionally, you need to set the path to your Dockerfile using the quarkus.openshift.jvm-dockerfile property for JVM mode and quarkus.openshift.native-dockerfile property for native mode.

The following procedure demonstrates how to deploy a Serverless Quarkus Java application or a Serverless application compiled to a native executable using the Quarkus OpenShift extension.

Prerequisites

  • Have a Quarkus Maven project that includes the quarkus-openshift extension.

  • OpenShift Serverless operator is installed.

  • OpenShift Knative Serving is installed and verified. See Installing Knative Serving.

  • For native compilation, a Linux X86_64 operating system or an OCI (Open Container Initiative) compatible container runtime, such as Podman or Docker is required.

Procedure

  1. Log in to OpenShift by using oc, and then change to the directory that contains your Quarkus Maven project.

  2. Configure the following properties in your application.properties file:

    1. Set Knative as a deployment target:

      quarkus.kubernetes.deployment-target=knative

    2. Set the Docker build strategy:

      quarkus.openshift.build-strategy=docker

    3. Direct OpenShift Serverless to pull your container image from the OpenShift internal registry:

      quarkus.container-image.registry=image-registry.openshift-image-registry.svc:5000

      If your OpenShift <project_name> is different from the username of the host system, set the group for the container image otherwise Quarkus cannot pull the image from the image registry.

      quarkus.container-image.group=<project_name>

    4. (Optional) If you are using an untrusted certificate, configure the KubernetesClient:

      quarkus.kubernetes-client.trust-certs=true

    5. (Optional) Expose the service to create an OpenShift route:

      quarkus.openshift.route.expose=true

    6. (Optional) Set the path to your custom Dockerfile:

      quarkus.openshift.jvm-dockerfile=<path_to_your_dockerfile>

      The following example shows the path to the Dockerfile.custom-jvm:

      quarkus.openshift.jvm-dockerfile=src/main/resources/Dockerfile.custom-jvm

  3. (Optional) To deploy a Serverless application compiled to a native executable, you need to configure the following properties:

    1. Set the container runtime:

      quarkus.native.container-build=true

    2. Specify the container engine:

      • To build a native executable with Podman:

        quarkus.native.container-runtime=podman

      • To build a native executable with Docker:

        quarkus.native.container-runtime=docker

    3. (Optional) Set the path to your custom Dockerfile:

      quarkus.openshift.native-dockerfile=<path_to_your_dockerfile>

  4. Package and deploy your Serverless application to OpenShift using one of the following options:

    1. Deploy a Quarkus Java application:

      ./mvnw clean package -Dquarkus.kubernetes.deploy=true

    2. Deploy a Quarkus native application:

      ./mvnw clean package -Pnative -Dquarkus.kubernetes.deploy=true
Verification

  1. To view a list of pods associated with your current OpenShift project:

    oc get pods

  2. To retrieve the log output for your application’s pod, enter the following command where <pod_name> is the name of the latest pod prefixed with the name of your application:

    oc logs -f <pod_name>

8. Using S2I to deploy Quarkus applications to OpenShift

You can deploy your Quarkus applications to OpenShift using the Source-to-Image (S2I) method. With S2I, you must provide the source code to the build container either through a Git repository or by uploading the source at build time.

S2I is not supported for native deployments. For deploying Quarkus applications compiled to native executables, use the Docker build strategy.

The procedure for deploying your Quarkus applications to OpenShift using S2I differs depending on the Java version you are using.

8.1. Using S2I to deploy Quarkus applications to OpenShift (Java 11)

The following section will help you to deploy your Quarkus applications running on Java 11 to OpenShift by using the Source-to-Image (S2I) method. Regardless of processor architecture, Quarkus recommends to use the ubi8/openjdk-11 image for your deployment.

Prerequisites
Procedure

  1. Log in to OpenShift by using oc, then change to the directory that contains your Quarkus Maven project.

  2. Package your Java 11 application:

    ./mvnw clean package

  3. Create a hidden directory called .s2i at the same level as the pom.xml file.

  4. Create a file called environment in the .s2i directory and add the following content:

    MAVEN_S2I_ARTIFACT_DIRS=target/quarkus-app
S2I_SOURCE_DEPLOYMENTS_FILTER=app lib quarkus quarkus-run.jar
JAVA_OPTIONS=-Dquarkus.http.host=0.0.0.0
AB_JOLOKIA_OFF=true
JAVA_APP_JAR=/deployments/quarkus-run.jar

  5. Commit and push your changes to the remote Git repository.

  6. Import the supported OpenShift image:

    oc import-image --confirm ubi8/openjdk-11 --from=ubi8/openjdk-11

  7. To build the project, create the application, and deploy the OpenShift service, enter:

    oc new-app ubi8/openjdk-11 <git_path> --name=<project_name>

  8. To deploy an updated version of the project, push any updates to the Git repository then enter the following command:

    oc start-build <project_name>
Verification

  1. To view a list of pods associated with your current OpenShift project:

    oc get pods

  2. To retrieve the log output for your application’s pod, enter the following command where <pod_name> is the name of the latest pod prefixed with the name of your application:

    oc logs -f <pod_name>
Additional resources

8.2. Using S2I to deploy Quarkus applications to OpenShift (Java 17)

Information is provided to help you to deploy your Quarkus applications running on Java 17 to OpenShift by using the Source-to-Image (S2I) method.

Prerequisites
Procedure

  1. Open the pom.xml file, and change the Java configuration to version 17, as follows:name:

    <maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>

  2. Log in to OpenShift by using oc, and then change to the directory that contains your Quarkus Maven project.

  3. Package your Java 17 application:

    ./mvnw clean package

  4. Create a hidden directory called .s2i at the same level as the pom.xml file.

  5. Create a file called environment in the .s2i directory and add the following content:

    MAVEN_S2I_ARTIFACT_DIRS=target/quarkus-app
S2I_SOURCE_DEPLOYMENTS_FILTER=app lib quarkus quarkus-run.jar
JAVA_OPTIONS=-Dquarkus.http.host=0.0.0.0
AB_JOLOKIA_OFF=true
JAVA_APP_JAR=/deployments/quarkus-run.jar

  6. Commit and push your changes to the remote Git repository.

  7. To import the supported OpenShift image, enter one of the following commands:

    oc import-image --confirm ubi8/openjdk-17 --from=registry.access.redhat.com/ubi8/openjdk-17

  8. To build the project on OpenShift, enter the following command:

    oc new-app ubi8/openjdk-17 <git_path> --name=<project_name>

    Where: * <git_path> is the path to the Git repository that hosts your Quarkus project * <project_name> is the OpenShift project that you created.

  9. To begin the deployment to OpenShift, enter the following command:

    oc start-build <project_name>
Verification

  1. To view a list of pods associated with your current OpenShift project:

    oc get pods

  2. To retrieve the log output for your application’s pod, enter the following command where <pod_name> is the name of the latest pod prefixed with the name of your application:

    oc logs -f <pod_name>
Additional resources

9. Quarkus configuration properties for customizing deployments on OpenShift

You can customize your deployments on OpenShift by defining optional configuration properties. You can configure your Quarkus project in your applications.properties file or via the command line.

Table 2. Quarkus configuration properties and their default values:
Property Description Default

quarkus.container-image.group

The container image group. Must be set if the OpenShift <project_name> is different from the username of the host system

${user.name}

quarkus.container-image.registry

The container registry to use

quarkus.kubernetes-client.trust-certs

Kubernetes client certificate authentication

quarkus.kubernetes.deployment-target

Deployment target platform. For example, openshift or knative

quarkus.native.container-build

Builds a native Linux executable using a container runtime. Docker is used by default

false

quarkus.native.container-runtime

The container runtime used to build the image, for example: Docker

quarkus.openshift.build-strategy

The deployment strategy

s2i

quarkus.openshift.route.expose

Exposes a route for the Quarkus application

false

quarkus.native.debug.enabled

Enables debug and generates debug symbols in a separate .debug file. When used with quarkus.native.container-build=true, Red Hat build of Quarkus only supports Red Hat Enterprise Linux or other Linux distributions as they contain the binutils package that installs the objcopy utility to split the debug info from the native image.

false

10. Additional resources

Revised on 2022-03-30 08:24:12 UTC

Legal Notices for Trademarks