IBM Quarkus 入門：Native ビルドしたアプリを OpenShift にデプロイしてみる

はじめに

本記事では、IBM Enterprise Build of Quarkus を利用して、Quarkus アプリケーションを Native executable としてビルドし、OpenShift Container Platform にデプロイする手順を紹介します。

具体的には、以下の内容を確認します。

• quarkus-openshift 拡張による OpenShift リソースの自動生成
• Podman を利用した Native ビルド
• ConfigMap による設定値の外部化
• Liveness / Readiness Probe の設定
• OpenShift Route 経由でのアプリケーション公開

最終的には、ローカル環境で Native ビルドした Quarkus アプリケーションを OpenShift 上にデプロイし、Route 経由で REST API にアクセスできる状態を目指します。

IBM Quarkus（IBM Enterprise Build of Quarkus）とは？

IBM Enterprise Build of Quarkus は、OSS の Quarkus をベースに、IBM がエンタープライズ向けに提供している Quarkus ディストリビューションです。

コミュニティ版の Quarkus が新機能への追従を重視しているのに対し、IBM Enterprise Build of Quarkus は、エンタープライズ環境での利用を想定し、サポート、セキュリティ修正、検証済み構成の提供など、安定運用を重視しています。

言い換えると、「最新性」よりも「安定性」や「サポート」を重視した Quarkus といえます。

また、Quarkus は Kubernetes / OpenShift 向けのアプリケーション開発との親和性が高く、quarkus-openshift 拡張を利用することで、以下のような OpenShift 関連の設定や操作を効率化できます。

• OpenShift 向けマニフェストの生成
• コンテナイメージのビルド
• OpenShift へのデプロイ
• Service / Route の作成
• Probe や環境変数などの設定反映

なお、2026年5月18日時点で、code.quarkus.ibm.com 上では quarkus-openshift 拡張は dev-support と表示されています。
そのため、本記事では開発・検証用途として利用します。

さらに Native ビルドを利用すると、GraalVM / Mandrel ベースの Native executable を生成できます。Native executable として実行することで、主に以下のメリットが期待できます。

• 起動時間の短縮
• メモリ使用量の削減
• コンテナ環境への最適化
• OpenShift 上でのリソース効率向上

本記事では、Maven と Podman を利用して IBM Enterprise Build of Quarkus アプリケーションを Native ビルドし、OpenShift Container Platform、以降 OCP、へデプロイする方法を解説します。

今回使用するアプリケーション

本記事では、OpenShift 上で動作するシンプルな Quarkus アプリケーションを使用します。

サンプルアプリケーションは、以下の GitHub リポジトリで公開しています。

このアプリケーションでは、主に以下の内容を確認できます。

• REST API の公開
• Health Check の提供
• ConfigMap による設定値の外部化
• OpenShift Route による外部公開
• quarkus-openshift による OpenShift リソースの自動生成
• Native executable としてのビルド
• Podman を利用したコンテナイメージ作成
• OpenShift へのデプロイ

アプリケーションのエンドポイントは以下のとおりです。

エンドポイント	内容
GET /hello	設定値を含むグリーティングメッセージを返却
GET /config	ConfigMap 由来のアプリケーション設定を JSON 形式で返却
GET /q/health	Liveness / Readiness を含む統合ヘルスチェック
GET /q/health/live	Liveness Check
GET /q/health/ready	Readiness Check

OpenShift でアプリケーションを運用するうえでは、Health Check や ConfigMap との連携が重要になります。

そのため本記事では、単にアプリケーションをデプロイするだけでなく、OpenShift 上での運用を意識した構成として、Health Check、ConfigMap、Route などの動作も確認していきます。

なお、自分で一から Quarkus プロジェクトを作成したい場合は、以下の IBM Quarkus のプロジェクトジェネレーターを利用できます。

前提条件

本記事では、以下の環境が利用できることを前提とします。

• OpenShift Container Platform にアクセスできること
• OpenShift クラスターにログイン可能であること
• oc CLI がインストール済みであること
• JDK 21 が利用できること
• Podman が利用できること

本記事では Maven Wrapper（./mvnw）を使用します。
そのため、ローカル環境に Maven を事前インストールしておく必要はありません。
なお、mvn コマンドを使用する場合は、別途 Maven のインストールが必要です。

また、Native ビルドでは通常の JVM ビルドよりも多くの時間とリソースを消費します。
環境にもよりますが、ビルドには数分から 10 分程度かかる場合があります。

筆者のローカル環境はmacOSです。

サンプルプロジェクトの構成

今回利用するプロジェクトの構成は以下の通りです。

code-quarkus-ocp/
├── src/
│   ├── main/
│   │   ├── java/org/acme/
│   │   │   ├── GreetingResource.java
│   │   │   ├── ConfigResource.java
│   │   │   ├── MyLivenessCheck.java
│   │   │   └── MyReadinessCheck.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── openshift/
│   └── configmap.yaml
├── pom.xml
└── README.md

主なファイルは以下です。

ファイル	内容
GreetingResource.java	/hello エンドポイントを提供
ConfigResource.java	/config エンドポイントを提供
MyLivenessCheck.java	Liveness Probe を提供
MyReadinessCheck.java	Readiness Probe を提供
application.properties	Quarkus / OpenShift 向けの設定
openshift/configmap.yaml	OpenShift に作成する ConfigMap
pom.xml	Maven 依存関係とビルド設定

アプリケーション設定

このアプリケーションでは、以下の設定値を利用します。

設定キー	内容
app.name	アプリケーション名
app.version	バージョン情報
app.message	カスタムメッセージ

これらの値は、application.properties にデフォルト値を定義し、OpenShift 上では ConfigMap から環境変数として注入する構成にしています。
OpenShift 上で ConfigMap を利用することで、アプリケーションイメージを作り直さずに設定値を外部化できます。

今回の構成では、以下のような流れで設定値を扱います。

1. ローカル実行時は application.properties の値を利用する
2. OpenShift デプロイ時は ConfigMap の値を環境変数として Pod に注入する
3. アプリケーションは注入された値を設定値として読み込む

quarkus-openshift 拡張のポイント

今回のポイントは、quarkus-openshift 拡張を利用することです。

通常、OpenShift にアプリケーションをデプロイする場合は、以下のようなリソースを個別に作成する必要があります。

• Deployment
• Service
• Route
• ImageStream
• BuildConfig
• Probe 設定
• 環境変数設定

しかし、quarkus-openshift 拡張を利用すると、application.properties の設定をもとに、これらの OpenShift リソースを自動生成できます。

今回のサンプルでは、以下のような設定を利用します。

# アプリケーション名
quarkus.application.name=quarkus-app

# Route の公開設定
quarkus.openshift.route.expose=true
quarkus.openshift.route.tls.termination=edge
quarkus.openshift.route.tls.insecure-edge-termination-policy=Redirect

# リソース制限
quarkus.openshift.resources.requests.memory=256Mi
quarkus.openshift.resources.requests.cpu=250m
quarkus.openshift.resources.limits.memory=512Mi
quarkus.openshift.resources.limits.cpu=500m

# ヘルスチェック設定
quarkus.openshift.liveness-probe.http-action-path=/q/health/live
quarkus.openshift.liveness-probe.initial-delay=10s
quarkus.openshift.liveness-probe.period=10s
quarkus.openshift.readiness-probe.http-action-path=/q/health/ready
quarkus.openshift.readiness-probe.initial-delay=5s
quarkus.openshift.readiness-probe.period=5s

# ConfigMap を環境変数として Pod に注入
quarkus.openshift.env.configmaps=quarkus-app-config

# OpenShift 上でコンテナイメージをビルドするためのビルド戦略
quarkus.openshift.build-strategy=docker

# Native ビルドをコンテナ内で実行
quarkus.native.container-build=true

# Native ビルド時に使用するコンテナランタイム
quarkus.native.container-runtime=podman

# Native ビルド時に使用する Native Builder Image
# サポート対象の Red Hat Build of Quarkus Native builder image を指定
quarkus.native.builder-image=registry.access.redhat.com/quarkus/mandrel-for-jdk-21-rhel8:23.1-42.1777859703

# linux/amd64 向けにビルドする場合
quarkus.native.container-runtime-options=--platform=linux/amd64

# 実行先 CPU との互換性を優先して Native executable を生成
quarkus.native.additional-build-args=-march=compatibility

この設定により、Quarkus は OpenShift 向けのマニフェストを生成し、-Dquarkus.openshift.deploy=true を指定した場合には OpenShift へのデプロイまで実行します。
生成されるマニフェストには、Deployment、Service、Route、Probe 設定、ConfigMap 参照などが含まれます。

ローカルでの動作確認

まずはローカル環境でアプリケーションを起動し、基本的な動作を確認します。

./mvnw quarkus:dev

起動後、別ターミナルから/helloエンドポイントにアクセスします。

curl http://localhost:8080/hello

以下のように、設定値を含むメッセージが返却されれば成功です。

Quarkus OpenShift Demo (v1.0.0) - Hello from local application.properties

/configエンドポイントはローカル環境でも確認できますが、この時点ではapplication.propertiesの値が返却されます。
ConfigMap から注入された設定値の確認は、OpenShift へデプロイした後に実施します。

ここでは、続いて Health Check の動作を確認します。

curl http://localhost:8080/q/health

以下のようにUP が返却されれば、アプリケーションは正常に動作しています。

{
    "status": "UP",
    "checks": [
        {
            "name": "alive",
            "status": "UP"
        },
        {
            "name": "ready",
            "status": "UP"
        }
    ]
}

JVM モードでビルドする

Native ビルドに進む前に、通常の JVM モードでもビルドできることを確認しておきます。

./mvnw clean package

ビルドが成功すると、target/quarkus-app/ディレクトリにアプリケーションが生成されます。
ローカルで実行する場合は、以下のコマンドを使用します。

java -jar target/quarkus-app/quarkus-run.jar

JVM モードは、開発中の動作確認や一般的な Java アプリケーションとしての実行に便利です。

一方で、本記事の目的は、Native ビルドしたアプリケーションを OpenShift にデプロイすることです。
そのため、ここでは JVM モードでも正常にビルド・実行できることを確認したうえで、OpenShift へのデプロイ準備に進みます。

OpenShift へのデプロイ準備

まず、OpenShift クラスターにログインします。

oc login <your-openshift-cluster-url>

今回の検証用に、新しい OpenShift プロジェクトを作成します。

oc new-project quarkus-demo

すでにプロジェクトが存在している場合は、以下のように切り替えます。

oc project quarkus-demo

今回のアプリケーションでは、設定値を ConfigMap から読み込めるようにしています。
ConfigMap のマニフェストは以下に配置されています。

openshift/configmap.yaml

今回のアプリケーションでは、OpenShift 上で ConfigMap の値を環境変数として Pod に注入し、アプリケーション設定として利用します。
ConfigMap のマニフェストは以下に配置しています。
openshift/configmap.yaml

ConfigMap を作成します。

oc apply -f openshift/configmap.yaml

作成された ConfigMap を確認します。

oc get configmap quarkus-app-config -o yaml

ここで重要なのは、application.properties に以下の設定が含まれている点です。

quarkus.openshift.env.configmaps=quarkus-app-config

この設定により、Quarkus が生成する OpenShift の Deployment マニフェストに、ConfigMap 参照が自動的に含まれます。

つまり、手動で以下のようなコマンドを実行する必要はありません。

oc set env deployment/quarkus-app --from=configmap/quarkus-app-config

quarkus-openshift 拡張が、ConfigMap を環境変数として Pod に注入する設定を自動生成してくれます。

ここまでで、OpenShift プロジェクトと ConfigMap の準備が完了しました。
次に、Podman を利用して Native ビルドを実行するための準備を行います。

Podman Machine の起動（Native ビルドの準備）

本記事では、Native ビルドをコンテナ内で実行するため、コンテナランタイムとして Podman を使用します。

macOS 環境で Podman を利用する場合、Linux コンテナを実行するために Podman Machine を起動しておく必要があります。

Native ビルドでは、通常の JVM ビルドよりも多くの CPU・メモリを使用します。
今回のような小規模な Quarkus アプリケーションでも、Podman Machine に割り当てられたメモリが 2GB 程度だと、Native Image 生成中にメモリ不足で失敗する場合があります。
macOS 環境で Podman を利用する場合は、目安として 4 CPU / 8GB メモリ程度を Podman Machine に割り当てておくことをおすすめします。
すでに Podman Machine を作成済みの場合は、この初期化手順は不要です。

今回は、以下のコマンドで Podman Machine を初期化します。

podman machine init --memory 8192 --cpus 4

初期化が完了したら、Podman Machine を起動します。

podman machine start

Podman が利用できる状態になっているか確認します。

podman ps

コンテナ一覧が表示されれば、Podman を利用できる状態です。

Native ビルドして OpenShift にデプロイする

ここからが本題です。
Native ビルドと OpenShift へのデプロイを実行します。

今回のサンプルでは、Native ビルドに必要な設定を application.properties に定義しています。
そのため、Native ビルドと OpenShift へのデプロイは以下のコマンドで実行できます。

./mvnw clean package -Dnative -Dquarkus.openshift.deploy=true

このコマンドでは、Quarkus アプリケーションを Native executable としてビルドし、その後 quarkus-openshift 拡張により OpenShift へのデプロイを実行します。
Native ビルドでは、application.properties に定義した以下の設定が利用されます。

quarkus.native.container-build=true
quarkus.native.builder-image=registry.access.redhat.com/quarkus/mandrel-for-jdk-21-rhel8:23.1-42.1777859703
quarkus.native.container-runtime=podman
quarkus.native.container-runtime-options=--platform=linux/amd64
quarkus.native.additional-build-args=-march=compatibility

各設定の意味は以下のとおりです。

quarkus.native.container-build=true：
Native ビルドをローカル環境で直接実行するのではなく、コンテナ内で実行するための設定です。
ローカル環境に GraalVM / Mandrel を直接インストールしなくても、Builder Image を利用して Native executable を生成できます。

quarkus.native.builder-image=...：
Native executable の生成に使用する Builder Image を指定します。
本記事ではサポート対象のJDK 21 向け Mandrel ベース Builder Image を指定しています。

quarkus.native.container-runtime=podman：
コンテナ内で Native ビルドを実行する際に利用するコンテナランタイムを指定します。
本記事では Docker ではなく Podman を使用するため、podman を指定しています。

quarkus.native.container-runtime-options=--platform=linux/amd64：
コンテナランタイムに渡す追加オプションです。
ここでは、ビルド時に利用するコンテナのプラットフォームとして linux/amd64 を指定しています。特に Apple Silicon など arm64 環境から amd64 向けにビルドする場合に有効です。

quarkus.native.additional-build-args=-march=compatibility：
Native Image 生成時に native-image コマンドへ渡す追加オプションです。
-march=compatibility を指定することで、生成される Native executable が要求する CPU 命令セットを互換性重視にできます。
これにより、ビルド環境と実行環境の CPU 機能が異なる場合でも、実行時に CPU 命令セット不足で失敗するリスクを下げられます。

以上をapplication.properties に設定することで、Maven コマンド自体はシンプルに保ちながら、Native ビルドに必要な設定をプロジェクト側で管理できます。

Native ビルドは JVM モードと比較してかなり時間がかかります。
しかし、起動時間やメモリ使用量の面で大きなメリットがあります。

生成された OpenShift マニフェストを確認する

ビルドとデプロイが完了すると、Quarkus によって OpenShift 向けのマニフェストが生成されます。

生成先は以下です。

target/kubernetes/openshift.yml

内容を確認すると、このファイルには、OpenShift にデプロイされる各種リソース定義が含まれています。

たとえば以下のようなリソースが生成されます。

• Deployment
• Service
• Route
• ImageStream
• BuildConfig
• Probe 設定
• ConfigMap 参照設定

特に、以下の点を確認すると理解しやすいです。

• Deployment に ConfigMap 由来の環境変数設定が含まれているか
• livenessProbe が /q/health/live を参照しているか
• readinessProbe が /q/health/ready を参照しているか
• Route が作成されているか
• リソース requests / limits が反映されているか

デプロイされたリソースを確認する

OpenShift 上にリソースが作成されているか確認します。

oc get pods

Pod が Running になっていれば、アプリケーションは起動しています。

Deployment、Service、Route を確認します。

# Deployment の確認
oc get deployment quarkus-app

# Service の確認
oc get svc quarkus-app

# Route の確認
oc get route quarkus-app

ログも確認してみます。

oc logs -f deployment/quarkus-app

アプリケーション起動ログや、各エンドポイントへのアクセスログが確認できます。

Route 経由でアプリケーションにアクセスする

OpenShift Route の URL を取得します。

# Route のホスト名をシェル変数に代入
ROUTE_URL=$(oc get route quarkus-app -o jsonpath='{.spec.host}')

# シェル変数を確認
echo $ROUTE_URL

/hello エンドポイントにアクセスします。

curl https://$ROUTE_URL/hello

以下のように、ConfigMap で定義した値を含むメッセージが返ってくれば成功です。
Quarkus OCP Demo (v1.0.0) - Hello from Quarkus on OpenShift!

続いて、設定情報を確認します。

curl https://$ROUTE_URL/config

以下のように、ConfigMap で定義した値を含むメッセージが返ってくれば成功です。

{
"app.message":"Hello from Quarkus on OpenShift!",
"app.name":"Quarkus OCP Demo",
"app.version":"1.0.0"
}

Health Check も確認します。

curl https://$ROUTE_URL/q/health

正常であれば、以下のようにHealth Check のレスポンスとして UP が返却されます。

{
    "status": "UP",
    "checks": [
        {
            "name": "alive",
            "status": "UP"
        },
        {
            "name": "ready",
            "status": "UP"
        }
    ]
}

ConfigMap の値が反映されていることを確認する

今回のアプリケーションでは、ConfigMap の値が環境変数として Pod に注入されます。

現在の ConfigMap を確認します。

oc get configmap quarkus-app-config -o yaml

以下のように、アプリケーションで利用する設定値が定義されていることを確認できます。

apiVersion: v1
data:
  app.message: Hello from Quarkus on OpenShift!
  app.name: Quarkus OCP Demo
  app.version: 1.0.0

Health Check の確認

OpenShift では、Liveness Probe と Readiness Probe を利用して Pod の状態を監視できます。

今回のアプリケーションでは、以下のエンドポイントを Probe として利用しています。

Probe	エンドポイント	役割
Liveness Probe	/q/health/live	アプリケーションが生きているか確認
Readiness Probe	/q/health/ready	リクエストを受け付ける準備ができているか確認

Liveness Probe が失敗すると、OpenShift は Pod を再起動します。

Readiness Probe が失敗すると、OpenShift はその Pod を Service の負荷分散対象から外します。

生成された Deployment の Probe 設定を確認するには、以下を実行します。

oc get deployment quarkus-app -o yaml

または、Pod 内から直接 Health Check を確認することもできます。

oc exec <pod-name> -- curl http://localhost:8080/q/health

Native ビルドアプリケーションの特徴

Native ビルドした Quarkus アプリケーションは、JVM モードと比較して以下の特徴があります。

メリット

• 起動が非常に速い → スケールアウト時の起動待ち時間を短縮できる
• メモリ使用量が少ない → コンテナ環境でのリソース効率を高めやすい

注意点

• ビルド時間が長い
• ビルド時に必要な CPU・メモリなどのリソースが多い
• 一部のライブラリでは、リフレクション設定などの追加設定が必要になる場合がある　

OpenShift 上で大量の Pod を起動するようなワークロードや、スケールアウト / スケールインが頻繁に発生するワークロードでは、Native ビルドのメリットを活かしやすいです。

一方で、開発中は JVM モードで素早く動作確認し、本番向けや検証向けに Native ビルドを利用する、という使い分けが現実的です。

JVM モードと Native モードの切り替え

今回のプロジェクトでは、JVM モードと Native モードを以下のように切り替えられます。

# JVM モード
./mvnw clean package -Dquarkus.openshift.deploy=true

# Native モード
./mvnw clean package -Dnative -Dquarkus.openshift.deploy=true

deployment.yaml を書いた方がよいケース

今回の記事では、quarkus-openshift 拡張を利用して OpenShift マニフェストを自動生成しました。

一方で、以下のように Kubernetes / OpenShift の設定をより細かく制御したい場合は、deployment.yaml を自前で管理したり、Helm / Kustomize / GitOps で管理したりするケースもあります。

• 複雑な Volume Mount が必要な場合
• 複数コンテナ構成にしたい場合
• initContainer を利用したい場合
• sidecar コンテナを追加したい場合
• 特殊な SecurityContext が必要な場合
• 細かい RBAC 制御が必要な場合
• NetworkPolicy を管理したい場合
• PodDisruptionBudget を定義したい場合
• 複雑な Affinity / Toleration が必要な場合
• 独自 Operator と連携したい場合

シンプルなアプリケーションでは quarkus-openshift による自動生成で十分なケースも多いですが、運用要件が複雑になる場合は、マニフェスト管理の方針を別途検討するとよいです。

再デプロイする

コードを変更した後に再デプロイする場合も、同じコマンドを実行します。

./mvnw clean package -Dnative -Dquarkus.openshift.deploy=true

Quarkus が新しいイメージをビルドし、OpenShift の Deployment を更新します。

OpenShift 側ではローリングアップデートにより、アプリケーションが更新されます。

ロールアウト状況は以下で確認できます。

oc rollout status deployment/quarkus-app

後片付け

検証が終わったら、作成した OpenShift プロジェクトを削除します。

oc delete project quarkus-demo

プロジェクトを削除すると、その中に作成された Deployment、Service、Route、ConfigMap などのリソースも削除されます。

まとめ

本記事では、IBM Enterprise Build of Quarkus を利用して、Quarkus アプリケーションを Native ビルドし、OpenShift Container Platform にデプロイする流れを確認しました。

今回のポイントは以下です。

• quarkus-openshift 拡張により、OpenShift 向けマニフェスト生成からデプロイまでを簡略化できる
• application.properties で、Route、Probe、リソース制限、ConfigMap 参照などを管理できる
• ConfigMap を利用することで、アプリケーション設定を外部化できる
• Podman を利用して、コンテナ内で Native ビルドを実行できる
• Native ビルドにより、起動時間とメモリ使用量の面でメリットが得られる

Quarkus は Kubernetes / OpenShift ネイティブな Java アプリケーション開発と非常に相性がよく、特に OpenShift 環境では quarkus-openshift 拡張を利用することで、ビルドからデプロイまでを大きく簡略化できます。

Native ビルドはビルド時間こそ長くなりますが、起動速度やメモリ効率の面で大きなメリットがあります。

OpenShift 上で Java アプリケーションを効率よく運用したい場合、IBM Enterprise Build of Quarkus は有力な選択肢の一つになります。