第4章 Red Hat ビルドの Quarkus 1.7 から Red Hat ビルドの Quarkus 1.11 へのアプリケーションのアップグレード

本セクションでは、Red Hat ビルドの Quarkus 1.7 から Red Hat ビルドの Quarkus 1.11 にアプリケーションをアップグレードする際に対応が必要な互換性を破る変更の概要を説明します。

4.1. Quarkus Quartz エクステンションの設定プロパティーの変更

Red Hat ビルドの Quarkus 1.11 リリースでは、Quarkus Quartz エクステンション で利用可能な設定プロパティーにいくつかの変更が加えられました。

Red Hat ビルドの Quarkus 1.11 で導入された新しい設定プロパティー

  • quarkus.quartz.cluster-checkin-interval
  • quarkus.quartz.instance-name
  • quarkus.quartz.start-mode

Red Hat ビルドの Quarkus 1.11 で削除された設定プロパティー

  • quarkus.quartz.force-start

表4.1 Red Hat ビルドの Quarkus 1.11 で名前が変更された設定プロパティー

Quarkus 1.7 のプロパティー名Quarkus 1.11 のプロパティー名

quarkus.quartz.triggerListener."namedTriggerListener".class

quarkus.quartz.trigger-listeners."listener-name".class

quarkus.quartz.triggerListener."namedTriggerListener"

quarkus.quartz.trigger-listeners."listener-name".properties

quarkus.quartz.jobListener."namedJobListener".class

quarkus.quartz.job-listeners."listener-name".class

quarkus.quartz.jobListener."namedJobListener"

quarkus.quartz.job-listeners."listener-name".properties

quarkus.quartz.plugin."namedPlugin".class

quarkus.quartz.plugins."plugin-name".class

quarkus.quartz.plugin."namedPlugin"

quarkus.quartz.plugins."plugin-name".properties

4.2. Spring Boot 設定プロパティーの命名ストラテジーの変更

Red Hat ビルドの Quarkus 1.11 では、Quarkus アプリケーションの大文字および小文字の組み合わせが含まれる Spring Boot 設定プロパティーに使用される命名ストラテジーは、verbatim に設定されなくなりました。

代わりに、quarkus.arc.config-properties-default-naming-strategy プロパティーを、プロジェクトの application.properties ファイルの以下のいずれかの値に設定できます。

from-config
命名規則はアプリケーション設定で指定されます。
verbatim
設定プロパティーの名前は、プロパティーが適用されるフィールドまたはメソッドの名前と一致します。
kebab
設定プロパティーの名前は小文字を使用し、スペースはハイフンに置き換えます。例: application-name

アプリケーションの quarkus.arc.config-properties-default-naming-strategy プロパティーを設定しない場合は、 kebab がデフォルト値として使用されます。

アプリケーションの verbatim 命名ストラテジーに従ってフォーマットされた Spring Boot 設定プロパティーを使用している場合は、以下のいずれかの変更を行います。

  • プロジェクトの application.properties または application.yml ファイルで、quarkus.arc.config-properties-default-naming-strategy の値を verbatim に設定します。例:

    application.properties

    quarkus.arc.config-properties-default-naming-strategy=verbatim

  • アプリケーションで使用する設定プロパティーの名前を変換し、kebab 命名ストラテジーと一致するようにします。

4.3. quarkus.datasource.url および quarkus.datasource.driver データソース設定プロパティーのサポートの削除

Red Hat ビルドの Quarkus 1.11 では、Red Hat ビルドの Quarkus 1.3 で導入された接続 URL およびデータソースのドライバーを設定するプロパティーをサポートしないことになりました。

サポート対象外の設定プロパティーを Quarkus 1.11 と互換性のあるプロパティーに置き換えて、アプリケーションを Quarkus 1.11 にアップグレードする際にデータソース設定が正しく機能するようにします。

Quarkus 1.11 のアプリケーションでデータソースを設定する方法の詳細は、『Quarkus アプリケーションでのデータソースの設定』 を参照してください。

4.4. Quarkus アプリケーションのデフォルトのメディアタイプの JSON への変更

警告

この変更により、アプリケーションを Red Hat ビルドの Quarkus 1.7 から Red Hat ビルドの Quarkus 1.11 にアップグレードする際に、アプリケーションの REST エンドポイントが破損する可能性があります。アプリケーションの REST エンドポイントが使用する戻り値の型を更新し、アプリケーションのアップグレード後も引き続き REST エンドポイントが正しく動作するようにします。

Red Hat ビルドの Quarkus 1.11 リリースでは、アプリケーションデータをシリアライズするデフォルト形式は JSON に変更されます。

アプリケーションの REST エンドポイントのコンテンツタイプ形式として JSON をデフォルトで使用することを無効にし、JSON を使用するインターフェースのみに対してアノテーションを使用して JSON の仕様を明示的に有効化することができます。

  1. アプリケーションの application.properties ファイルで、quarkus.resteasy-json.default-json プロパティーの値を false に設定します。

    application.properties

    quarkus.resteasy-json.default-json=false

  2. JSON をコンテンツタイプ形式として使用するアプリケーションの REST エンドポイントに @Produces(MediaType.APPLICATION_JSON) および @Consumes(MediaType.APPLICATION_JSON) アノテーションを追加します。

4.5. Jackson の FAIL_ON_UNKNOWN_PROPERTIES 機能はデフォルトで無効化

Red Hat ビルドの Quarkus 1.11 では、Jackson はデフォルトで DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES を無効にし、認識されないプロパティーを無視するように設定されています。これは、アプリケーションによって認識されないプロパティーが含まれる JSON データオブジェクトをデシリアライズしようとする際に失敗しないようにするためです。

アプリケーションの application.properties ファイルで quarkus.jackson.fail-on-unknown-properties の値を true に設定して、FAIL_ON_UNKNOWN_PROPERTIES 機能を有効にします。この機能は、アプリケーションのクラスごとに個別に有効にする必要があります。

application.properties

<fully-qualified-class-name>.quarkus.jackson.fail-on-unknown-properties=true

REST アプリケーションでの Jackson の使用およびカスタマイズに関する詳細は、Quarkus REST JSON extension guide を参照してください。

4.6. DEBUG および TRACE レベルでの最小ロギングレベルの設定への変更

Quarkus 1.11 では、DEBUG および TRACE レベルでメッセージをログに記録するようにロガーを設定する際に、最小ロギングレベルを設定する必要があります。アプリケーションを起動する前に、最小ロギングレベルを設定する必要があります。ロガー設定に最小ロギングレベルを設定しない場合、DEBUG および TRACE ログレベルのメッセージはログ出力に表示されません。たとえば、TRACE レベルでログを記録するようにロガーを設定する場合は、最小ログレベルを TRACE にする必要があります。そうしないと、TRACE レベルのメッセージはログ出力に表示されません。

アプリケーションの application.properties ファイルで、特定カテゴリーの最小ログレベルを設定できます。application.properties。たとえば、ロガー設定の io.quarkus.smallrye.jwt および io.undertow.request.security カテゴリーの TRACE レベルでロギングを有効にするには、以下のプロパティーを設定します。

application.properties

quarkus.log.file.enable=true
# Send output to a trace.log file under the /tmp directory
quarkus.log.file.path=/tmp/trace.log
quarkus.log.file.level=TRACE
quarkus.log.file.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Set 2 categories (io.quarkus.smallrye.jwt, io.undertow.request.security) to TRACE level
quarkus.log.min-level=TRACE
quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE

4.7. Red Hat ビルドの Quarkus BOM の内部構造への変更

Red Hat ビルドの Quarkus 1.11 では、com.redhat.quarkus:quarkus-universe-bom にすべてのエクステンションおよび依存関係の goupIdartifactID、および version を直接含まなくなりました。代わりに、com.redhat.quarkus:quarkus-universe-bom は、Red Hat がサポートするすべての Red Hat ビルドの Quarkus エクステンションおよびすべてのコミュニティー Quarkus エクステンションを含む io.quarkus:quarkus-universe-bom の依存関係宣言が含まれる com.redhat.quarkus quarkus-product-bom をインポートします。

この変更は、Maven プロジェクトで Red Hat ビルドの Quarkus BOM を使用する方法には影響しません。ただし、カスタムスクリプトを使用して BOM を解析する場合は、アプリケーションを Red Hat ビルドの Quarkus 1.11 にアップグレードした後も引き続き解析が正しく機能するように、カスタムスクリプトを更新する必要があります。

4.8. REST エンドポイントパス解決における変更

警告

この変更により、アプリケーションを Red Hat ビルドの Quarkus 1.7 から Red Hat ビルドの Quarkus 1.11 にアップグレードする際に、アプリケーションの REST エンドポイントが破損する可能性があります。アプリケーションの移行後にエンドポイントパスを更新するようにしてください。

Red Hat ビルドの Quarkus 1.11 では、アプリケーションとアプリケーション以外の REST エンドポイントのパスは、一般的な絶対ルートパスと相対的に解決されます。REST エンドポイントのデフォルトの一般的なルートパスは、以下のように設定されます。

  • /: アプリケーションのメイン REST コントローラークラスによって直接公開される REST エンドポイント。アプリケーションエンドポイントのデフォルトパスを変更するには、プロジェクトの application.properties ファイルの quarkus.http.root-path プロパティーの値を変更します。
  • q: アプリケーションと統合されるツールが提供するサービスの REST エンドポイント (アプリケーションのヘルスモニタリングやメトリクスコレクションなどを目的とする)。アプリケーションエンドポイントのデフォルトパスを変更するには、プロジェクトの application.properties ファイルの quarkus.http.non-application-root-path プロパティーの値を変更します。

相対ルートパスは、quarkus.http.root-path プロパティーによって定義されるルートパスの下にネストされる点に留意してください。たとえば、quarkus.http.root-path プロパティーに定義されたルートパスが / に設定され、quarkus.http.non-applicationroot-path プロパティーに定義されたアプリケーション以外のエンドポイントのルートパスが q に設定されている場合、アプリケーション以外のエンドポイントの絶対エンドポイントパスは /q/<non-application-endpoint-name> になります。

ただし、アプリケーション以外の個々のエンドポイントのパスを、/q/<non-application-endpoint-name> に配置するように明示的に設定することもできます。

エンドポイントパスは quarkus.http.root-path および quarkus.http.non-application-root-path によって設定されるルートパスに相対的と解釈されるため、アプリケーションのエンドポイントに設定するカスタムパスおよびサブパスから先頭のスラッシュ (/) を除外する必要があります。

たとえば、アプリケーションの REST コントローラーで Prometheus のメトリクスエンドポイントを公開する場合、エンドポイントが /q/metrics で公開されるように、@Path アノテーションのエンドポイントパスを metrics に設定する必要があります。同じパス値を /metrics に設定すると、メトリクスエンドポイントは /metrics で公開されます。

アプリケーション以外のエンドポイントを別の namespace の下に設定する例

たとえば、プロジェクトの application.properties ファイルに以下のプロパティーを設定し、/api ルートパスで hello エンドポイントアプリケーションを、そして /api/q パスで metrics エンドポイントを公開することができます。

application.properties

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=q

この設定では、/api/hello/api/q/metrics の両方ともパブリックです。つまり、/api/hello にアクセスするパーミッションを持つユーザーは、/api/q/metrics エンドポイントにもリクエストを送信して、有効な Response を受け取ることができます。

health エンドポイントをパブリック以外にする場合は、application.properties のアプリケーション以外のエンドポイントのルートパスを /q namespace に設定できます。

application.properties

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=/q

この設定では、/api/hello エンドポイントはパブリックですが、/q/metrics は異なるアクセスパーミッションを設定できる別の namespace に公開されています。

Red Hat ビルドの Quarkus 1.11 では、元のアプリケーション以外のエンドポイントパスに送信されたリクエストは、/q namespace の新しいパスに自動的にリダイレクトされます。

プロジェクトの application.properties ファイルで以下の属性を設定して、アプリケーション以外のエンドポイントパスの自動リダイレクトを無効にすることができます。

quarkus.http.redirect-to-non-application-root-path=false

quarkus.http.non-application-root-path の値を、絶対アプリケーションエンドポイントルートの値に解決する変数に設定し、すべてのエンドポイントの絶対エンドポイントのルートパスを使用するようにアプリケーションを切り替えることができます。

quarkus.http.non-application-root-path=${quarkus.http.root-path}

4.9. REST アプリケーションを Red Hat OpenShift Container Platform にデプロイする ConfigMap オブジェクトの処理時に、追加の設定プロパティーが必要

警告

この変更により、アプリケーションを Red Hat ビルドの Quarkus 1.7 から Red Hat ビルドの Quarkus 1.11 にアップグレードする際に、アプリケーションの OpenShift へのデプロイに使用する設定に不具合が生じる可能性があります。ConfigMap で提供される設定パラメーターがアプリケーションによって確実に認識されるように、アプリケーションの applications.properties ファイルを更新する必要があります。

Red Hat ビルドの Quarkus 1.11 では、Resteasy をベースとする Quarkus アプリケーションを Red Hat OpenShift Container Platform に設定し、quarkus.openshift で指定された ConfigMap にアプリケーションの設定パラメーターを提供する場合は、アプリケーションが ConfigMap を認識および処理するように、application.properties ファイルの quarkus.openshift.app-secret および quarkus-openshift.app-configmap プロパティーも指定する必要があります。

  • アプリケーションの application.properties ファイルに以下のプロパティーを追加して、アプリケーションが ConfigMap を認識できるようにします。

    application.properties

    quarkus.openshift.app-secret=<secret-name>
    quarkus-openshift.app-configmap=<configmap-name>

    <secret-name> を使用するシークレットの名前に置き換え、<configmap-name> を使用する ConfigMap の名前に置き換える必要があります。