Red Hat build of Quarkus 3.20 へのアプリケーションの移行

Red Hat build of Quarkus 3.20 では、次のエクステンションによって Fabric8 Kubernetes Client がバージョン 6.13 から 7.1 にアップグレードされます。

quarkus-openshift および quarkus-kubernetes エクステンションは、Fabric8 を使用しますが、機能は変更されていないため、更新する必要はありません。

このアップグレードの一環として、io.quarkus:quarkus-test-openshift-client モジュールが削除されました。テストでこのモジュールを使用する場合は、同等の機能を提供する io.quarkus:quarkus-test-kubernetes-client に移行してください。詳細は、Quarkus ガイド「Kubernetes Client」の OpenShift Client セクションを参照してください。

アップグレードされた Fabric8 Kubernetes Client では、一部のモデルタイプとクラスが再編成されています。一部は別のモジュールに移動されました。新しい場所を確認するには、Fabric8 公式の Kubernetes Client: Migration from 6.x to 7.x ガイドを参照してください。

影響を受ける依存関係、設定、または API の使用状況をアプリケーションで確認し、必要に応じて更新してください。その後、アプリケーションを十分にテストして、Fabric8 7.1 との完全な互換性を確保します。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

Red Hat build of Quarkus 3.15 で、RESTEasy Reactive から Quarkus REST へ、Reactive Messaging から Quarkus Messaging へブランド変更の一環として、多くのエクステンションと設定プロパティーの名前が変更されました。この変更に対応するために、アーティファクトの再配置と設定のフォールバックが導入されました。

Red Hat build of Quarkus 3.20 では、このアーティファクトの再配置と設定のフォールバックが削除されました。新しいアーティファクト名と設定プロパティーを使用する必要があります。

関連する背景情報は、「Red Hat build of Quarkus 3.15 のリリースノート」ガイドの RESTEasy Reactive エクステンションの名前が Quarkus REST に変更される セクションを参照してください。

Red Hat build of Quarkus 3.20 では、Mandrel バージョン 24.2 以降に合わせてロケール処理が更新されています。

すべてのアプリケーションで一貫したロケールの動作を確保するために、Red Hat build of Quarkus は標準化されたデフォルトのロケールストラテジーを適用します。次の表を使用して、ロケール設定に応じてアプリケーションの動作がどのように変化するかを確認してください。

quarkus.locales の設定に関係なく、en_US ロケールは常にネイティブ実行可能ファイルに埋め込まれます。

予期しない動作の変更を回避するために、設定プロパティーでアプリケーションのロケール設定を確認し、必要に応じて設定を更新してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

Red Hat build of Quarkus 3.20 では、@Fallback.fallbackMethod() および @BeforeRetry.methodName() の設定プロパティーがビルド時に解決され、ランタイムに変更できなくなりました。影響を受ける設定プロパティーは次のとおりです。

この変更により、適切なリフレクション設定とネイティブイメージコンパイルとの互換性が確保されます。

Red Hat build of Quarkus 3.20 では、quarkus-smallrye-fault-tolerance エクステンションに SmallRye Fault Tolerance 6.7.0 が組み込まれています。これにより、互換性を失わせる変更点は導入されませんが、次の更新が導入されます。

詳細は、SmallRye Fault Tolerance 6.7.0 のリリース告知を参照してください。これには、プログラム API の移行ガイドへのリンクと、新しい設定プロパティーの詳細が記載されています。Quarkus ガイド SmallRye のフォールトトレランス には、これらの設定プロパティーの詳細なリファレンスが記載されています。

Red Hat build of Quarkus 3.20 以降、io.quarkus.scheduler.Scheduler 内のメソッドの動作が変更されました。

スケジューラーが起動していない場合、ほぼすべてのメソッドが UnsupportedOperationException を出力するようになりました。

スケジューラーが実行中かどうかを確認するには、新しいメソッド Scheduler#isStarted() を使用できます。

この変更は、quarkus-scheduler および quarkus-quartz エクステンションに基づくスケジューラーインスタンスに影響します。

Red Hat build of Quarkus 3.20 以降、開発モードおよびテストモードを使用する場合、管理インターフェイスがデフォルトで 0.0.0.0 ではなく localhost インターフェイスでリッスンします。この変更により、メインインターフェイスの動作と同じになりました。

Windows Subsystem for Linux (WSL) を搭載した Windows では、管理インターフェイスもメインインターフェイスも、引き続き 0.0.0.0 でリッスンします。

詳細は、Quarkus ガイド Management interface reference を参照してください。

Red Hat build of Quarkus 3.20 では、設定が @ConfigMapping フレームワークに移行されました。この変更により、従来の設定クラスが非推奨になり、インターフェイスとメソッドシグネチャーに基づく統合設定モデルが導入されました。

一般的に使用される特定の設定クラスは、互換性レイヤーが残っています。ただし、このレイヤーは今後のリリースで削除される予定です。

Red Hat build of Quarkus 3.20 以降、Red Hat のビルダーおよびランタイムベースイメージが、Red Hat Universal Base Image 9 (UBI 9) を使用するようにアップグレードされます。

UBI 8 から UBI 9 にアップグレードする場合、システム依存関係、ネイティブイメージビルド、またはパッケージおよび GNU C ライブラリー (glibc) バージョンの更新による変更が、アプリケーションの動作やランタイム環境に影響する可能性があることに注意してください。必要に応じて設定を確認して更新してください。

UBI 9 で問題が発生した場合は、手動で UBI 8 に戻すことができます。

詳細は、以下の資料を参照してください。

Red Hat build of Quarkus の以前のバージョンでは、Dev Services が無効になっているか実稼働モードで実行されている場合、quarkus.datasource.reactive.url および quarkus.datasource.<datasource-name>.reactive.url プロパティーが、ドキュメント化されていないデフォルト値に暗黙的に設定され、データベース固有のポートを使用する localhost をターゲットとしていました。

Red Hat build of Quarkus 3.20 以降、Dev Services が無効になっている場合、またはアプリケーションが本番モードで実行されている場合、これらのプロパティーにデフォルト値が設定されなくなりました。プロパティーが設定されていない場合、対応するデータソースが非アクティブ化されます。非アクティブ化されたデータソースをアプリケーションが使用しようとすると、起動時にデータソースが失敗します。詳細は、リリースノート データソースが非アクティブ化されているか、URL が設定されていない場合、データソースの使用がすぐに失敗する を参照してください。

アプリケーションにアクティブなデータソースが必要で、それを localhost 上のデータベースに接続する場合は、quarkus.datasource.reactive.url または quarkus.datasource.<datasource-name>.reactive.url プロパティーを明示的に設定する必要があります。以下に例を示します。

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

以前のバージョンでは、この設定は暗黙的に指定されていました。このリリース以降、データソースをアクティブ化するには、URL を定義する必要があります。

以前は、Dev Services が無効になっているか本番モードの場合、quarkus.datasource.jdbc.url、quarkus.datasource.<datasource-name>.jdbc.url、quarkus.datasource.reactive.url、または quarkus.datasource.<datasource-name>.reactive.url プロパティーが設定されていない場合でも、Red Hat build of Quarkus がデータソースのヘルスチェックを実行していました。これにより、JDBC データソースでは常に成功し、リアクティブデータソースではほぼ常に失敗していたため、ヘルスチェックの信頼性が低下していました。

Red Hat build of Quarkus 3.20 以降、URL のないデータソースはヘルスチェックに影響しなくなりました。ヘルスチェックを確実に利用可能にするには、quarkus.datasource.jdbc.url、quarkus.datasource.<datasource-name>.jdbc.url、quarkus.datasource.reactive.url、または quarkus.datasource.<datasource-name>.reactive.url プロパティーを明示的に設定します。

Red Hat build of Quarkus 3.20 では、データソースが quarkus.datasource.active=false で非アクティブ化されている場合や URL が欠落している場合でも、アプリケーションが正常に起動します。この動作により、特に Dev Services が無効になっている場合や本番モードになっている場合に、データソースに初めてアクセスしたときにランタイムエラーが発生することがよくあります。

この更新により、データソースが使用されているものの、非アクティブ化されているか URL が欠落していることを Red Hat build of Quarkus が検出した場合、アプリケーションの起動が失敗するようになりました。

Red Hat build of Quarkus は、これらの問題を早期に検出するために、以下のように、より厳格な検証を起動時に実施するようになりました。

これと同じ検証が、Flyway および Liquibase エクステンションの Flyway および LiquibaseFactory CDI Bean にも適用されます。

Red Hat build of Quarkus 3.20 では、quarkus-flyway エクステンションによって Flyway がバージョン 11 にアップグレードされます。これにより、cleanOnValidationError 設定パラメーターが削除されます。さらに、Flyway.validate() を呼び出しても検証エラーがクリーンアップされなくなりました。

この変更を緩和するために、Red Hat build of Quarkus 3.20 では、quarkus.flyway.validate-at-start.clean-on-validation-error 設定プロパティーが導入されました。これは cleanOnValidationError と同様の動作を提供するものですが、アプリケーションの起動時にのみ適用されます。

回避策: Flyway.validate() への明示的な呼び出しで cleanOnValidationError の以前の動作が必要な場合は、アプリケーションで検証エラーをキャッチし、Flyway.clean() を使用してデータベースのクリーンアップを明示的にトリガーすることを検討してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

詳細は、Quarkus ガイド Using Flyway を参照してください。

Red Hat build of Quarkus 3.20 では、Dev Services が使用する IBM Db2 ドライバーとコンテナーイメージがバージョン 12 にアップグレードされました。

IBM Db2 ドライバーとコンテナーイメージは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新により、バージョン 12 にアップグレードされます。

Db2 Connect 12.1 にアップグレードする場合は、IBM の Features with behavior changes when upgrading to the Db2 Connect 12.1 driver に記載されている新しいライセンス要件、設定手順、および SSL/TLS 設定を確認してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

Red Hat build of Quarkus 3.20 では、Hibernate ORM の Bean Validation 統合のデフォルト動作が変更されました。以前は、データ定義言語 (DDL) の生成時に検証制約が考慮されていませんでした。このリリースでは、Hibernate ORM がデフォルトで適用可能な検証制約を DDL に含めるようになりました。これにより、データベーススキーマとアプリケーションレベルの制約の整合性が向上します。

quarkus.hibernate-orm.validation.enabled プロパティーも非推奨になりました。

これらの変更の詳細とアプリケーションの移行に関するガイダンスは、Migration Guide 3.19 または次のリソースを参照してください。

Red Hat build of Quarkus 3.20 では、quarkus.log.*.json 設定プロパティーが非推奨になりました。ロギングで JSON 形式を有効にするには、代わりに quarkus.log.*.json.enabled プロパティーを使用します。

この変更は、YAML 設定との互換性を向上させるために導入されました。以前の構造では、ルートキーに値を割り当てるために ~ などの特殊な構文を使用する必要がありました。そのため、設定で混乱やエラーが発生しやすくなっていました。

詳細は、Migration Guide 3.19 を参照してください。

Red Hat build of Quarkus 3.20 では、quarkus-opentelemetry エクステンションによって互換性を失わせる変更が導入されました。これは、開発中のデータベース値 (Redis に関連する値など) が別のパッケージに移動されたためです。

OpenTelemetry では、データベースのセマンティック規則がまだ安定していないため、変更のリストが保持されていません。

手動計装を使用する場合、この変更によって手動による介入が必要になる可能性があります。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

Red Hat build of Quarkus 3.20 では、以前非推奨になった quarkus-smallrye-opentracing エクステンションと、関連する設定プロパティー quarkus.datasource.jdbc.tracing が削除されました。

現在は、quarkus-opentelemetry エクステンションが推奨されるトレーシングソリューションです。OpenTelemetry で JDBC トレーシングを有効にするには、次の設定プロパティーを使用します。

quarkus.datasource.jdbc.telemetry=true

quarkus.datasource.jdbc.telemetry=true

移行するには、OpenTracing エクステンションを OpenTelemetry に置き換え、それに応じて設定を更新します。

Red Hat build of Quarkus 3.20 以降、quarkus-oidc-client エクステンションを使用する場合に、OpenID Connect (OIDC) クライアントが特定の URL を参照するように設定していないと、Dev Services for Keycloak が自動的に開発モードで起動します。

この動作を無効にするには、次のプロパティーを application.properties ファイルに追加します。

quarkus.keycloak.devservices.enabled=false

quarkus.keycloak.devservices.enabled=false

Red Hat build of Quarkus 3.20 では、セキュリティーの強化、業界標準への準拠、長期的な保守性の向上のために、WebAuthn4J を使用して quarkus-security-webauthn エクステンションが再実装されました。

そのため、この更新は以前のバージョンのエクステンションと互換性がありません。

新しい実装にスムーズに移行するために、次の情報を使用してください。

この機能のステータスは、さらなる安定化を図るために preview から experimental にダウングレードされました。

詳細は、Quarkus ガイド Using Security with WebAuthn を参照してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

以前は、Red Hat build of Quarkus 3.15 に、不具合がある未発表のバージョンの @WithTestResource が同梱されていました。

Red Hat build of Quarkus 3.20 では、この不具合が修正されました。これにより、互換性を失わせる変更が生じました。このリリースでは、以前の restrictToAnnotatedClass フィールドが scope に置き換えられました。

以前のリリースでは、quarkus-junit5-mockito 依存関係が、subclass モッキングストラテジーを使用してモックオブジェクトを作成するように設定されていました。

Red Hat build of Quarkus 3.20 以降、この依存関係はデフォルトで inline モッキングストラテジーを使用するように設定されます。

Red Hat build of Quarkus 3.20.0 では、依存関係バージョンの意図的な不一致により、quarkus-junit5-mockito 依存関係が一時的に機能しなくなっていました。使用中の Mockito のバージョンには JUnit 5.11 以降が必要でしたが、プラットフォームには JUnit 5.10 が含まれていました。

この問題を解決するために、Red Hat build of Quarkus 3.20.1 では JUnit をバージョン 5.12.1 にアップグレードします。この更新により、JUnit と Mockito のバージョンが調整され、quarkus-junit5-mockito 依存関係の互換性が回復されます。

この更新の影響は最小限になると予想されます。コミュニティーと Camel Quarkus でのテストでは、リグレッションは発生しませんでした。詳細は、関連する問題 https://github.com/quarkusio/quarkus/issues/46858 を参照してください。

すべての JUnit アーティファクトにわたって一貫したアライメントを確保するには、次のように 3.20.0 で使用される JUnit BOM バージョンをインポートします。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

HTTP 圧縮が有効な場合、quarkus.http.compress-media-types 設定プロパティーで、圧縮するメディアタイプのリストが定義されます。Red Hat build of Quarkus 3.20 では、このプロパティーのデフォルト値が変更されました。新しく圧縮されるメディアタイプに、application/json と application/xhtml+xml が追加されました。

Red Hat build of Quarkus 3.20 では、REST Client の設定がより厳格になり、設定を取得するために必要な検索と組み合わせの数が削減されました。

Red Hat build of Quarkus 3.20 以降、quarkus-qute エクステンションは、対応するテンプレートのバリアントが設定されている場合、JSON テンプレート内の二重引用符 (")、バックスラッシュ (\)、および制御文字 (U+0000 から U+001F) を自動的にエスケープします。このエクステンションは、src/main/resources/templates ディレクトリーにあるテンプレートにバリアントを自動的に割り当てます。

デフォルトでは、java.net.URLConnection#getFileNameMap() によってテンプレートファイルのコンテンツタイプが決定されます。quarkus.qute.content-types 設定を使用しすると、追加の接尾辞とコンテンツタイプのマッピングを定義できます。

エスケープされていない値をレンダリングするには、java.lang.Object の拡張メソッドとして実装されている raw プロパティーまたは safe プロパティーを使用するか、文字列値を io.quarkus.qute.RawString クラスでラップします。

詳細は、Quarkus ガイド「Qute reference」の Character escapes セクションを参照してください。

Red Hat build of Quarkus 3.20 では、quarkus-rest-jackson エクステンションにより、修飾子のない ObjectMapperCustomizer Bean のみが Jackson JSON プロセッサーのデフォルトの ObjectMapper インスタンスに適用されます。

以前のバージョンでは、カスタム修飾子を持つものも含め、すべての Customizer Bean がデフォルトの ObjectMapper インスタンスに適用されていました。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

詳細は、以下の資料を参照してください。

以前のリリースでは、quarkus-rest エクステンションでは、?foo= などの空の値を持つクエリーパラメーターが、次のようにデシリアライズされていました。

Red Hat build of Quarkus 3.20 では、この動作が次のように変更されました。

これに応じてコードを更新してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。

Red Hat build of Quarkus 3.20 では、Jakarta WebSocket 仕様を実装する quarkus-websockets および quarkus-websockets-client エクステンションが非推奨になりました。

Red Hat build of Quarkus は、今後のリリースでこれらのエクステンションのサポートを停止する予定です。

今後のバージョンとの互換性を確保するには、Quarkus WebSockets Next エクステンション (quarkus-websockets-next) に移行してください。このエクステンションは、より効率的な最新の WebSocket API を提供します。

詳細は、次の Quarkus リソースを参照してください。

この変更には手動による介入が必要です。これは、Red Hat build of Quarkus 3.20 へのアプリケーションの移行 ガイドで説明されている自動更新プロセスには含まれていません。