Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

このコンテンツは選択した言語では利用できません。

Chapter 1. Deploying your Quarkus applications to OpenShift

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.

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

1.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>
      Copy to Clipboard Toggle word wrap

    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"
      Copy to Clipboard Toggle word wrap

1.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
    Copy to Clipboard Toggle word wrap

  2. Display the current project space: 

    oc project -q
    Copy to Clipboard Toggle word wrap

  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>
      Copy to Clipboard Toggle word wrap

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

      oc new-project <project_name>
      Copy to Clipboard Toggle word wrap

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

Important

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
...
    Copy to Clipboard Toggle word wrap

1.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
      Copy to Clipboard Toggle word wrap

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

      quarkus.kubernetes-client.trust-certs=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.route.expose=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.jvm-dockerfile=<path_to_your_dockerfile>
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.jvm-dockerfile=src/main/resources/Dockerfile.custom-jvm
      Copy to Clipboard Toggle word wrap

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

    ./mvnw clean package -Dquarkus.kubernetes.deploy=true
    Copy to Clipboard Toggle word wrap

Verification

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

    oc get pods
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

1.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
      Copy to Clipboard Toggle word wrap

    2. Set the container runtime: 

      quarkus.native.container-build=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.kubernetes-client.trust-certs=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.route.expose=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.native-dockerfile=<path_to_your_dockerfile>
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.jvm-dockerfile=src/main/docker/Dockerfile.custom-native
      Copy to Clipboard Toggle word wrap

    6. (Optional) Specify the container engine:

      • To build a native executable with Podman: 

        quarkus.native.container-runtime=podman
        Copy to Clipboard Toggle word wrap

      • To build a native executable with Docker: 

        quarkus.native.container-runtime=docker
        Copy to Clipboard Toggle word wrap

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

    ./mvnw clean package -Pnative -Dquarkus.kubernetes.deploy=true
    Copy to Clipboard Toggle word wrap

Verification

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

    oc get pods
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

1.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
      Copy to Clipboard Toggle word wrap

    2. Set the Docker build strategy: 

      quarkus.openshift.build-strategy=docker
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap
      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>
      Copy to Clipboard Toggle word wrap

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

      quarkus.kubernetes-client.trust-certs=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.route.expose=true
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.jvm-dockerfile=<path_to_your_dockerfile>
      Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.jvm-dockerfile=src/main/resources/Dockerfile.custom-jvm
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    2. Specify the container engine:

      • To build a native executable with Podman: 

        quarkus.native.container-runtime=podman
        Copy to Clipboard Toggle word wrap

      • To build a native executable with Docker: 

        quarkus.native.container-runtime=docker
        Copy to Clipboard Toggle word wrap

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

      quarkus.openshift.native-dockerfile=<path_to_your_dockerfile>
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    2. Deploy a Quarkus native application: 

      ./mvnw clean package -Pnative -Dquarkus.kubernetes.deploy=true
      Copy to Clipboard Toggle word wrap

Verification

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

    oc get pods
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

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

Important

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.

1.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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

Verification

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

    oc get pods
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

1.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>
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

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

    oc new-app ubi8/openjdk-17 <git_path> --name=<project_name>
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

Verification

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

    oc get pods
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

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

Expand
Table 1.2. 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 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

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat