Deploying your Quarkus applications to OpenShift

Guide
  • Red Hat build of Quarkus 2.7
  • Updated 09 March 2023
  • Published 18 May 2022

Topics included in this guide

Deploying your Quarkus applications to OpenShift

Guide
Red Hat build of Quarkus 2.7
  • Updated 09 March 2023
  • Published 18 May 2022

As an application developer, you can deploy your Quarkus applications to OpenShift by 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 OpenJDK 11 or 17 installed and the JAVA_HOME environment variable set to specify the location of the Java SDK.

    In Quarkus 2.7, building native executables by using Java 17 is provided as a Technology Preview feature. To build native executables for production deployments, use Java 11.

  • Have Apache Maven 3.8.4 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.7, 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, and service definitions. 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.7.7.Final-redhat-00005: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

  • Have access to a Red Hat OpenShift Container Platform cluster.

  • The latest version of the OpenShift CLI (oc) is 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

If you built a JVM mode Java 17 application by using the code.quarkus.redhat.com starter code, you must complete some additional configuration. By default, the code.quarkus.redhat.com starter code is set to use the Java 11 Docker package. To deploy your Java 17 application into OpenShift by using a non-S2I Docker build strategy deployment option, make sure that your Maven project Docker build configuration file points to the correct OpenJDK package.

To set the Docker package to OpenJDK 17 for Quarkus applications that are based on the code.quarkus.redhat.com starter code, complete the following procedure:

Procedure

  1. Navigate to the Maven project src/main/docker subdirectory and open the Dockerfile.jvm file.

  2. Set the ARG JAVA_PACKAGE variable to point to the Java 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 pregenerated 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 AMD64 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 pregenerated 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 AMD64 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 pregenerated 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 AMD64 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)

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

Prerequisites
Procedure

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

  2. Package your Java 11 application:

    ./mvnw clean package

  3. Create a 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. To import the supported OpenShift image, enter the following command:

    oc import-image --confirm ubi8/openjdk-11 --from=ubi8/openjdk-11
    If you are deploying on IBM Z infrastructure, enter oc import-image --confirm openj9/openj9-11-rhel8 --from=registry.redhat.io/openj9/openj9-11-rhel8 instead. For information about this image, see the Red Hat Eclipse OpenJ9 11 Java Applications on RHEL8 page.

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

    oc new-app ubi8/openjdk-11 <git_path> --name=<project_name>
    If you are deploying on IBM Z infrastructure, enter oc new-app openj9/openj9-11-rhel8 <git_path> --name=<project_name> instead.

  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:

    <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 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 the following command:

    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 by using 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 this property is used with quarkus.native.container-build=true, Red Hat build of Quarkus only supports Red Hat Enterprise Linux or other Linux distributions. The Red Hat Enterprise Linux and other Linux distributions contain binutils package, which installs the objcopy utility to split the debug information from the native image.

false

10. Additional resources

Revised on 2023-03-09 05:34:38 UTC

Legal Notices for Trademarks