Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Deploying your Quarkus applications to OpenShift

Red Hat build of Quarkus 1.11

Abstract

This guide describes how to deploy Quarkus applications to OpenShift.

Preface

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 that 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

Providing feedback on Red Hat documentation

We appreciate your feedback on our technical content and encourage you to tell us what you think. If you’d like to add comments, provide insights, correct a typo, or even ask a question, you can do so directly in the documentation.

Note

You must have a Red Hat account and be logged in to the customer portal.

To submit documentation feedback from the customer portal, do the following:

  1. Select the Multi-page HTML format.
  2. Click the Feedback button at the top-right of the document.
  3. Highlight the section of text where you want to provide feedback.
  4. Click the Add Feedback dialog next to your highlighted text.
  5. Enter your feedback in the text box on the right of the page and then click Submit.

We automatically create a tracking issue each time you submit feedback. Open the link that is displayed after you click Submit and start watching the issue or add more comments.

Thank you for the valuable feedback.

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.

Chapter 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.
Note

Since Red Hat build of Quarkus 1.11, 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 backwards compatibility reasons. 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 Quarkus as a JVM application is fully supported.
Binary S2I
This strategy uses a JAR file as an input to the S2I build process. This speeds up the build process and deployment of your application.
Table 1.1. Quarkus support OpenShift build strategies
Build strategySupport for Quarkus toolingSupport for JVMSupport for NativeSupport for JVM ServerlessSupport 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

Chapter 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. Change to the directory that contains your Quarkus 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 quarkus:add-extension -Dextensions="openshift"

Chapter 3. 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.

  • Login to OpenShift using oc and select your project.

Procedure

  1. Change to the directory that contains your Quarkus 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.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. 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>

Chapter 4. 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.

  • Login to OpenShift using oc and select your project.

Procedure

  1. Change to the directory that contains your Quarkus 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.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. 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>

Chapter 5. 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.

  • Login to OpenShift using oc and select your project.

  • 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. Change to the directory that contains your Quarkus 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
      Note

      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.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. 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>

Chapter 6. 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.

Important

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

Prerequisites

  • Have a Quarkus Maven project that includes the quarkus-openshift extension.
  • Host your Quarkus Maven project in a Git repository.

  • Login to OpenShift using oc and select your project.

Procedure

  1. Change to the directory that contains your Quarkus Maven project.
  2. Create a hidden directory called .s2i at the same level as the pom.xml file.

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

    ARTIFACT_COPY_ARGS=-p -r lib/ *-runner.jar
  4. Commit and push your changes to the remote Git repository.

  5. To import the supported OpenShift image, enter the following command: 

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

    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.

    For information about this image, see the Red Hat OpenJ9 11 Java Applications on RHEL8 page.

  6. To build the project in OpenShift, enter the following command where <git_path> is the path to the Git repository that hosts your Quarkus project and <project_name> is the OpenShift project that you created. 

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

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

    This command builds the project, creates the application, and deploys the OpenShift service.

  7. 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. 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

Chapter 7. Verifying the OpenShift project namespace

Prerequisites

  • Have access to a Red Hat OpenShift Container Platform cluster and 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. (Optional) Create a new OpenShift project: 

    oc new-project <project_name>

Additional resources

Chapter 8. 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 8.1. Table Quarkus configuration properties and their default values:
PropertyDescriptionDefault

quarkus.container-image.group

The container image group. Must be set if the OpenShift <project_name> is different from a 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 build the image. For example, Docker

 

quarkus.openshift.build-strategy

The deployment strategy

s2i

quarkus.openshift.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

Chapter 9. Additional resources

Revised on 2021-06-15 14:51:41 UTC

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.