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

Kubernetes Client が 5.12 から 6.7.2 にアップグレードされました。詳細は、Kubernetes Client - Migration from 5.x to 6.x ガイドを参照してください。

Red Hat build of Quarkus 3.2 では、Kubernetes エクステンションが TLS ベースのコンテナーポートを生成する方法に変更が導入されています。

以前のバージョンでは、生成されたデプロイメントリソースに https という名前のコンテナーポートが自動的に追加されました。このアプローチでは、特に SSL/TLS が設定されていない場合に問題が発生し、ポートが機能しなくなりました。

3.2 以降では、Kubernetes エクステンションはデフォルトで https という名前のコンテナーポートを追加しません。コンテナーポートは、次の手順を実行した場合にのみ追加されます。

この 3.2 リリースでは、以前に非推奨となった Kubernetes および OpenShift 関連のプロパティーの一部が削除されました。削除されたプロパティーは、新しいプロパティーに置き換えてださい。

さらに、このリリースでは、quarkus. の接頭辞がないプロパティーは無視されます。たとえば、このリリースより前は、kubernetes.name プロパティーを追加した場合、それは quarkus.kubernetes.name にマップされました。2.16.0.Final から 2.16.1.Final #30850 にアップグレードする際の java.lang.ClassCastException のような例外を回避するために、この種のマッピングは行われなくなりました。

Quarkus のコンテキストで Kubernetes と OpenShift の作業を続ける場合は、新しいプロパティーを使用し、必要に応じて quarkus. の接頭辞を付けます。

この 3.2 リリースでは、Jandex は SmallRye プロジェクトの一部となり、すべての Jandex プロジェクトが 1 つのリポジトリー (https://github.com/smallrye/jandex/) に統合されます。その結果、Jandex Maven プラグインの新しいリリースが Jandex コアとともに提供されます。

このリリースでは、Maven コーディネートも変更されます。古いコーディネートを新しいコーディネートに置き換えます。

Maven Enforcer プラグインを使用する場合は、org.jboss:jandex への依存関係を禁止するように設定します。Gradle ユーザーは、同等のプラグインを利用できます。

Jandex 3 には、多くの興味深い機能と改善が含まれています。残念ながら、これらの変更には、いくつかの破壊的変更が必要でした。推奨される移行パスは次のとおりです。

このリリースと並行して、Jandex は 新しいドキュメントサイト を導入します。現在進行中の作業ですが、今後より包括的なものになる予定です。詳細は、改良された Jandex Javadoc を参照してください。

この 3.2 リリースでは、以前に非推奨になった io.quarkus.arc.config.ConfigProperties アノテーションが削除されました。

代わりに、io.smallrye.config.ConfigMapping アノテーションを使用して、複数の関連する設定プロパティーを注入します。

詳細は、MAPPING CONFIGURATION TO OBJECTS ガイドの @ConfigMapping セクションを参照してください。

この 3.2 リリースでは、プライベートメソッドでのインターセプターバインディングアノテーションの宣言はサポートされておらず、ビルドの失敗をトリガーします。以下に例を示します。

jakarta.enterprise.inject.spi.DeploymentException: @Transactional does not affect method com.acme.MyBean.myMethod() because the method is private. [...]

jakarta.enterprise.inject.spi.DeploymentException: @Transactional does not affect method com.acme.MyBean.myMethod() because the method is private. [...]

以前のリリースでは、プライベートメソッドでインターセプターバインディングアノテーションを宣言すると、ログに警告が表示されるだけで、それ以外は無視されていました。

このサポート変更は、プライベートメソッドでのインターセプターアノテーションの意図しない使用を防ぐことを目的としています。インターセプターアノテーションによる効果がなく、混乱を引き起こす可能性があるためです。

この変更に対処するには、プライベートメソッドからそのようなアノテーションを削除します。これらのアノテーションの削除が不可能な場合は、設定プロパティー quarkus.arc.fail-on-intercepted-private-method を false に設定できます。この設定により、システムは以前の動作に戻り、警告のみが記録されます。

このリリースでは、以前に非推奨になった @AlternativePriority アノテーションが削除されました。これを @Alternative および @Priority の両方のアノテーションに置き換えます。

@AlternativePriority(1)

@AlternativePriority(1)

@Alternative
@Priority(1)

@Alternative
@Priority(1)

非推奨となり、今後のリリースで削除される予定の io.quarkus.arc.Priority に代わり、@Priority アノテーションを付けた jakarta.annotation.Priority を使用します。どちらのアノテーションも同じように機能します。

このリリースでは、Mockito バージョン 5.x が更新されます。特に、Mockito は 5.0.0 リリース で、デフォルトの mockmaker を inline に切り替えました。

ただし、Quarkus 1.x 以降、Quarkus ユーザーが慣れ親しんだモック動作を維持し、広範なテストスイートのメモリーリーク を防ぐために、Quarkus 3.0 では、inline がフルサポートされるまで、これに代わって mockmaker を subclass に修正します。

inline mockmaker を強制する場合は、次の手順に従います。

Quarkus は、Maven 3.9 をサポートするために Maven プラグインのリファクタリングを実施しました。その結果、Quarkus がサポートする Maven の最小バージョンは 3.6.2 から 3.8.6 以降に引き上げられました。最新の改善点や機能を活用できるように、開発環境がこれに応じて更新されることを確認してください。

この 3.2 リリースでは、以前に非推奨となった io.quarkus:quarkus-bootstrap-maven-plugin Maven プラグインが削除されました。

このプラグインは、Quarkus エクステンション開発専用です。したがって、カスタム Quarkus エクステンションを開発している場合は、アーティファクト ID を io.quarkus:quarkus-bootstrap-maven-plugin から io.quarkus:quarkus-extension-maven-plugin に変更する必要があります。

Mutiny はリアクティブプログラミングライブラリーで、バージョン 1.x は org.reactivestream インターフェイスに基づいていますが、バージョン 2 は java.util.concurrent.Flow に基づいています。これらの API は同一ですが、パッケージ名が変更されています。

Mutiny は、Mutiny 2 (Flow API) とレガシーリアクティブストリーム API を備えた他のライブラリーの間をブリッジするアダプターを提供します。

この 3.2 リリースでは、以前に非推奨となった Panache メソッドによる Hibernate ORM および Kotlin の Panache メソッドによる Hibernate ORM からの以下のメソッドが削除されました。

代わりに、Panache.getEntityManager(Class<?> clazz) メソッドを使用してください。

この 3.2 リリースでは、Hibernate Object-Relational Mapping (ORM) エクステンションが変更され、デフォルト設定として自動 IN 句パラメーターパディングが組み込まれました。この改善により、IN 句を組み込んだクエリーのキャッシュ効率が向上します。

quarkus.hibernate-orm.query.in-clause-parameter-padding のプロパティー値を false に設定すると、以前の機能に戻してこの機能を非アクティブにできます。

この 3.2 リリースでは、Quarkus は Hibernate Reactive 1 ではなく Hibernate Reactive 2 エクステンションに依存します。この変更は、以前のバージョンと互換性のない動作およびデータベーススキーマの期待項目におけるいくつかの変更を意味します。

変更のほとんどは、Hibernate ORM 5.6 ではなく Hibernate ORM 6.2 に依存する Hibernate Reactive 2 に関連しています。

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

Hibernate Search マッピングに、projectable オプションのデフォルト値と、sortable オプションのデフォルト値または Sortable.NO を使用する GeoPoint フィールドが含まれているとします。その場合、これらのフィールドに doc 値が欠落しているため、Elasticsearch スキーマの検証は起動時に失敗します。

この失敗を防ぐには、次のいずれかの手順を実行します。

詳細は、Hibernate Search 6.2.3.Final: Migration Guide from 6.1 の Data format and schema changes セクションを参照してください。

また、quarkus.hibernate-search-orm.automatic-indexing.enable-dirty-check プロパティーは非推奨となり、今後のバージョンで削除される予定です。これに置き換わる代替のプロパティーはありません。削除後は、トランザクションがオブジェクトのフィールドを変更した後、検索によって常に再インデックス化がトリガーされることが計画されています。つまり、トランザクションによってフィールドが "ダーティー" になった場合です。

詳細は、Hibernate Search 6.2.3.Final: Migration Guide from 6.1 の Configuration changes セクションを参照してください。

この 3.2 リリースでは、Quarkus は ValidatorFactory インスタンスの手動作成をサポートしていません。代わりに、Validation.buildDefaultValidatorFactory() メソッドを使用する必要があります。このメソッドは、コンテキストと依存性注入 (CDI) を通じて注入した Quarkus によって管理される ValidatorFactory インスタンスを返します。この変更の主な理由は、ValidatorFactory がネイティブ実行可能ファイルで動作するように慎重に作成する必要があることです。このリリースより前では、機能させることができる場合は、ValidatorFactory インスタンスを手動で作成し、自分で処理することができました。この変更は、独自の ValidatorFactory を作成するコンポーネントとの互換性を向上させることを目的としています。

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

Java Database Connectivity (JDBC) を使用して Quartz エクステンション のジョブをデータベースに保存している場合は、次のクエリーを実行して、JOB_DETAILS テーブル内のジョブクラス名を更新します。

UPDATE JOB_DETAILS SET JOB_CLASS_NAME = 'io.quarkus.quartz.runtime.QuartzSchedulerImpl$InvokerJob' WHERE JOB_CLASS_NAME = 'io.quarkus.quartz.runtime.QuartzScheduler$InvokerJob';

UPDATE JOB_DETAILS SET JOB_CLASS_NAME = 'io.quarkus.quartz.runtime.QuartzSchedulerImpl$InvokerJob' WHERE JOB_CLASS_NAME = 'io.quarkus.quartz.runtime.QuartzScheduler$InvokerJob';

QuarkusTransaction.run メソッドと QuarkusTransaction.call メソッドは非推奨となり、より明示的な新しいメソッドが採用されました。

これらの非推奨のメソッドに依存するコードを次のように更新します。

QuarkusTransaction.run(() -> { ... });
QuarkusTransaction.call(() -> { ... });

QuarkusTransaction.run(() -> { ... });
QuarkusTransaction.call(() -> { ... });

QuarkusTransaction.requiringNew().run(() -> { ... });
QuarkusTransaction.requiringNew().call(() -> { ... });

QuarkusTransaction.requiringNew().run(() -> { ... });
QuarkusTransaction.requiringNew().call(() -> { ... });

QuarkusTransaction.run(QuarkusTransaction.runOptions()
        .semantic(RunOptions.Semantic.REQUIRED),
        () -> { ... });
QuarkusTransaction.call(QuarkusTransaction.runOptions()
        .semantic(RunOptions.Semantic.REQUIRED),
        () -> { ... });

QuarkusTransaction.run(QuarkusTransaction.runOptions()
        .semantic(RunOptions.Semantic.REQUIRED),
        () -> { ... });
QuarkusTransaction.call(QuarkusTransaction.runOptions()
        .semantic(RunOptions.Semantic.REQUIRED),
        () -> { ... });

QuarkusTransaction.joiningExisting().run(() -> { ... });
QuarkusTransaction.joiningExisting().call(() -> { ... });

QuarkusTransaction.joiningExisting().run(() -> { ... });
QuarkusTransaction.joiningExisting().call(() -> { ... });

QuarkusTransaction.run(QuarkusTransaction.runOptions()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        }),
        () -> { ... });
QuarkusTransaction.call(QuarkusTransaction.runOptions()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        }),
        () -> { ... });

QuarkusTransaction.run(QuarkusTransaction.runOptions()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        }),
        () -> { ... });
QuarkusTransaction.call(QuarkusTransaction.runOptions()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        }),
        () -> { ... });

QuarkusTransaction.requiringNew()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        })
        .run(() -> { ... });
QuarkusTransaction.requiringNew()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        })
        .call(() -> { ... });

QuarkusTransaction.requiringNew()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        })
        .run(() -> { ... });
QuarkusTransaction.requiringNew()
        .timeout(10)
        .exceptionHandler((throwable) -> {
            if (throwable instanceof SomeException) {
               return RunOptions.ExceptionResult.COMMIT;
            }
            return RunOptions.ExceptionResult.ROLLBACK;
        })
        .call(() -> { ... });

詳細は、USING TRANSACTIONS IN QUARKUS ガイドの Programmatic approach セクションを参照してください。

この 3.2 リリースでは、quarkus.transaction-manager.object-store-directory 設定プロパティーの名前が quarkus.transaction-manager.object-store.directory に変更されました。古いプロパティー名を新しいプロパティー名に置き換えて、設定を更新します。

このリリースでは、以前に非推奨となった smallrye-reactive-messaging-kafka エクステンションの vertx-kafka-client 依存関係が削除されます。クライアント実装には使用されませんでしたが、vertx-kafka-client は、io.vertx.kafka.client.serialization パッケージから io.vertx.core.buffer.Buffer、io.vertx.core.json.JsonObject、および io.vertx.core.json.JsonArray 型のデフォルトの Kafka Serialization and Deserialization (SerDes) を提供しました。

この依存関係が必要な場合は、io.quarkus.kafka.client.serialization パッケージから前述の型の SerDes を取得できます。

この 3.2 リリースでは、GraalVM/Mandrel の変更は、Java Abstract Window Toolkit (AWT) エクステンションなどの .so ファイルに依存するエクステンションの使用に影響します。

これらのエクステンションを使用する場合は、対応する .so ファイルをネイティブコンテナーに追加またはコピーする必要があります。以下に例を示します。

COPY --chown=1001:root target/*.so /work/
COPY --chown=1001:root target/*-runner /work/application

COPY --chown=1001:root target/*.so /work/
COPY --chown=1001:root target/*-runner /work/application

この 3.2 リリースでは、最近のマシンでネイティブ実行可能ファイルをビルドし、古いマシンで実行すると、アプリケーションの起動時に次のエラーが発生する可能性があります。

The current machine does not support all of the following CPU features that are required by the image: [CX8, CMOV, FXSR, MMX, SSE, SSE2, SSE3, SSSE3, SSE4_1, SSE4_2, POPCNT, LZCNT, AVX, AVX2, BMI1, BMI2, FMA].
Please rebuild the executable with an appropriate setting of the -march option.

The current machine does not support all of the following CPU features that are required by the image: [CX8, CMOV, FXSR, MMX, SSE, SSE2, SSE3, SSSE3, SSE4_1, SSE4_2, POPCNT, LZCNT, AVX, AVX2, BMI1, BMI2, FMA].
Please rebuild the executable with an appropriate setting of the -march option.

このエラーメッセージは、ネイティブコンパイルで、アプリケーションを実行している CPU でサポートされていない高度な命令セットが使用されたことを意味します。この問題を回避するには、application.properties ファイルに次の行を追加します。

quarkus.native.additional-build-args=-march=compatibility

quarkus.native.additional-build-args=-march=compatibility

次に、ネイティブ実行可能ファイルを再ビルドします。この設定により、ネイティブコンパイルで古い命令セットの使用が強制され、互換性の可能性は高まりますが、最適化は低下します。

ターゲットアーキテクチャーを明示的に定義するには、native-image -march=list を実行して、サポートされる構成のリストを取得します。次に、ターゲットアーキテクチャーを指定します。以下に例を示します。

quarkus.native.additional-build-args=-march=x86-64-v4

quarkus.native.additional-build-args=-march=x86-64-v4

古い AMD64 ホストでこの問題が発生している場合は、-march=compatibility を使用する前に -march=x86-64-v2 を試してください。

ネイティブイメージビルドオプション に関する GraalVM ドキュメントには、次のように記載されています: "[the -march parameter generates] instructions for a specific machine type. [This parameter] defaults to x86-64-v3 on AMD64 and armv8-a on AArch64.Use -march=compatibility for best compatibility, or -march=native for best performance if a native executable is deployed on the same machine or on a machine with the same CPU features.To list all available machine types, use -march=list."

この 3.2 リリースでは、以前は非推奨だった @io.quarkus.test.junit.NativeImageTest および @io.quarkus.test.junit.DisabledOnNativeImageTest アノテーションが、rimage::images/ref_changes-that-affect-backward-compatibility-88d2f.png[] になりました。削除されたプロパティーは、新しいプロパティーに置き換えてださい。

置き換えられたアノテーションは、削除されたアノテーションと機能的に同等です。

この 3.2 リリースでは、OpenTracing ドライバーのサポートが非推奨となりました。OpenTracing ドライバーの削除は、今後の Quarkus リリースで計画されています。

この 3.2 リリースでは、SmallRye GraphQL エクステンションが OpenTracing インテグレーションを OpenTelemetry に置き換えました。その結果、OpenTracing を使用する場合、エクステンションは GraphQL 操作のスパンを生成しなくなります。

また、このリリースでは、quarkus.smallrye-graphql.tracing.enabled 設定プロパティーは廃止され、削除されました。代わりに、OpenTelemetry エクステンションが存在する場合、SmallRye GraphQL エクステンションは自動的にスパンを生成します。

OpenTelemetry を使用するように Quarkus アプリケーションを更新して、今後の Quarkus リリースとの互換性を維持します。

この 3.2 リリースでは、Micrometer エクステンションは、Prometheus 標準に準拠して、デフォルトで application/openmetrics-text フォームでメトリクスをエクスポートします。この変更により、データの読み取りと解釈が容易になります。

以前のフォームでメトリクスを取得する場合は、Accept リクエストヘッダーを text/plain に変更できます。curl コマンドを使用すると、以下のようになります。

curl -H "Accept: text/plain" localhost:8080/q/metrics/

curl -H "Accept: text/plain" localhost:8080/q/metrics/

この 3.2 リリースでは、OpenTelemetry (OTel) エクステンションが大幅に改善されました。このリリースより前は、OpenTelemetry SDK (OTel SDK) がビルド時に作成され、設定オプションが限られていました。最も注目すべき点は、実行時に無効にできないことでした。現在は、柔軟性が強化されています。quarkus.otel.sdk.disabled=true を設定することで、実行時に無効にできます。

ビルド時にいくつかの準備手順を行った後、実行時に OTel 自動設定機能を使用して OTel SDK が設定されます。この機能は、Java OpenTelemetry SDK で定義されているプロパティーの一部をサポートしています。詳細は、OpenTelemetry SDK Autoconfigure リファレンスを参照してください。

OpenTelemetry エクステンションは、以前のバージョンと互換性があります。ほとんどのプロパティーは非推奨になりましたが、今後のリリースで削除されるまで、新しいプロパティーと並行して機能します。非推奨のプロパティーを新しいプロパティーに置き換えることができます。

この 3.2 リリースでは、古い quarkus.opentelemetry.tracer.sampler 関連のプロパティー値の一部が削除されました。

サンプラーが親ベースの場合、現在削除されている quarkus.opentelemetry.tracer.sampler.parent-based プロパティーを設定する必要はありません。

次の quarkus.opentelemetry.tracer.sampler 値を新しい値に置き換えます。

多くの新しいプロパティーが利用できるようになりました。詳細は、Quarkus の USING OPENTELEMETRY ガイドを参照してください。

Quarkus では、IdGenerator、Resource 属性、Sampler、および SpanProcessor などの多くのクラスのコンテキストと依存性注入 (CDI) 設定が許可されていました。これは標準の OTel では利用できない機能ですが、便宜上引き続きここで提供されています。ただし、LateBoundBatchSpanProcessor による SpanProcessor の CDI 作成は非推奨になりました。オーバーライドまたはカスタマイズする必要がある場合は、フィードバックをお寄せください。このプロセッサーは以前のバージョンのサポートに引き続き使用されますが、すぐに OTel SDK にバンドルされている標準エクスポートが使用される予定です。これは、デフォルトのエクスポーターが次の設定を使用することを意味します。

quarkus.otel.traces.exporter=cdi

quarkus.otel.traces.exporter=cdi

プレビューとして、ストック OTLP エクスポーターを次のように設定することで利用できるようになりました。

quarkus.otel.traces.exporter=otlp

quarkus.otel.traces.exporter=otlp

Sampler および SpanExporter の標準 Service Provider Interface (SPI) フックを使用して、OTel SDK の追加設定が利用できるようになりました。残りの SPI にもアクセスできますが、テストによる互換性の検証が引き続き必要です。詳細は、更新された USING OPENTELEMETRY ガイドを参照してください。

quarkus.datasource.jdbc.url=jdbc:otel:postgresql://localhost:5432/mydatabase
# use the 'OpenTelemetryDriver' instead of the one for your database
quarkus.datasource.jdbc.driver=io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver

quarkus.datasource.jdbc.url=jdbc:otel:postgresql://localhost:5432/mydatabase
# use the 'OpenTelemetryDriver' instead of the one for your database
quarkus.datasource.jdbc.driver=io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver

この 3.2 リリースでは、より単純な設定を使用できます。

quarkus.datasource.jdbc.telemetry=true

quarkus.datasource.jdbc.telemetry=true

この設定では、データベース URL を変更したり、別のドライバーを宣言したりする必要はありません。

Cross-Origin Resource Sharing (CORS) フィルターのデフォルトの動作が大幅に変更されました。以前のリリースでは、CORS フィルターが有効になっている場合、デフォルトですべてのオリジンがサポートされていました。この 3.2 リリースでは、すべてのオリジンのサポートがデフォルトで有効化されなくなりました。すべてのオリジンを許可する場合は、そのように明示的に設定する必要があります。

徹底的な評価の後、すべてのオリジンでサポートが必要であると判断した場合は、次の方法でシステムを設定します。

quarkus.http.cors=true
quarkus.http.cors.origins=/.*/

quarkus.http.cors=true
quarkus.http.cors.origins=/.*/

同一オリジンリクエストは、quarkus.http.cors.origins 設定を必要とせずにサポートを受けられます。したがって、quarkus.http.cors.origins の調整は、信頼できるサードパーティーのオリジンリクエストを許可する場合にのみ必須となります。このような状況では、すべてのオリジンを有効にすると、不必要なリスクが生じる可能性があります。

この 3.2 リリースでは、OpenAPI は Cross-Origin Resource Sharing (CORS) 設定を変更し、デフォルトでワイルドカード (*) オリジンサポートを有効化しなくなりました。この変更は、OpenAPI ドキュメントの漏洩の可能性を防ぎ、アプリケーションの全体的なセキュリティーを強化するのに役立ちます。

開発モードでワイルドカードオリジンのサポートを有効にする ことはできますが、潜在的なセキュリティーへの影響を考慮することが重要です。実稼働環境では、アプリケーションがセキュリティーの脅威にさらされることになるため、すべてのオリジンを有効にしないでください。CORS 設定が、実稼働環境で推奨されるセキュリティーのベストプラクティスと一致していることを確認してください。

この 3.2 リリースでは、OpenID Connect (OIDC) 認証コードフローの完了後に作成される OIDC セッション Cookie が、デフォルトで暗号化されます。ほとんどのシナリオでは、この変化に気づくことはほとんどありません。

ただし、mTLS または private_key_jwt 認証方法 (OIDC クライアントの秘密鍵が JSON Web Token (JWT) に署名する) が Quarkus と OIDC プロバイダーの間で使用される場合、メモリー内暗号化キーが生成されます。このキーの生成により、特に多くのリクエストを処理するアプリケーションでは、一部の Pod がセッション Cookie の復号化に失敗する可能性があります。この状況は、Cookie を復号化しようとしている Pod が、それを暗号化した Pod ではない場合に発生する可能性があります。

このような問題が発生した場合は、32 文字の暗号化シークレットを登録してください。以下に例を示します。

quarkus.oidc.token-state-manager.encryption-secret=eUk1p7UB3nFiXZGUXi0uph1Y9p34YhBU

quarkus.oidc.token-state-manager.encryption-secret=eUk1p7UB3nFiXZGUXi0uph1Y9p34YhBU

暗号化されたセッション Cookie は、4096 バイトを超える可能性があるため、一部のブラウザーがそれを無視する可能性があります。この問題が発生した場合は、次の手順を 1 つ以上試してください。

アプリケーションユーザーが信頼できるネットワーク内から Quarkus アプリケーションにアクセスする場合は、次の設定を適用してセッション Cookie 暗号化を無効にします。

quarkus.oidc.token-state-manager.encryption-required=false

quarkus.oidc.token-state-manager.encryption-required=false

この 3.2 リリースでは、Quarkus OpenID Connect (OIDC) エクステンションの場合、セッション Cookie の SameSite 属性がデフォルトで Lax に設定されます。

Quarkus の以前のリリースの一部では、OIDC セッション Cookie の SameSite 属性がデフォルトで Strict に設定されていました。この設定により、さまざまなブラウザーがセッション Cookie をどのように処理するかが予測不能になりました。

この 3.2 リリースでは、OpenID Connect (OIDC) ID トークン aud (audience) クレームがデフォルトで検証されます。このクレームは、OIDC 仕様の要求に従って、設定された quarkus.oidc.client-id プロパティーの値と等しくなければなりません。

予期される ID トークンオーディエンス値をオーバーライドするには、quarkus.oidc.token.audience 設定プロパティーを設定します。ID トークン aud クレームを設定しない非準拠の OIDC プロバイダーを扱う場合は、quarkus.oidc.token.audience を any に設定できます。

このリリースより前は、Quarkus は JSON Web Token (JWT) キーとキーストアのデフォルトのパスワードとして password を使用していました。この 3.2 リリースでは、このデフォルト値は削除されました。

デフォルトのパスワードをまだ使用している場合は、application.properties ファイル内の次のプロパティーの password を置き換える新しい値を設定します。

quarkus.oidc-client.credentials.jwt.key-store-password=password
quarkus.oidc-client.credentials.jwt.key-password=password

quarkus.oidc-client.credentials.jwt.key-store-password=password
quarkus.oidc-client.credentials.jwt.key-password=password

この 3.2 リリースでは、次の変更が RESTEasy Reactive のマルチパートサポートに影響します。

JAXB エクステンションは、JAXB アノテーションを使用するクラスを検出し、それらをデフォルトの JAXBContext インスタンスに登録します。このリリースより前は、クラスと JAXB の間の問題または競合により、実行時に JAXB 例外がトリガーされ、この問題のトラブルシューティングに役立つ詳細な説明が提供されていました。ただし、ビルド段階でこれらの競合に事前に対処することができます。

このリリースでは、ビルド時に JAXBContext インスタンスを検証できる機能が追加され、開発サイクルの早い段階で JAXB エラーを検出して修正できるようになりました。

たとえば、次のコードブロックに示すように、両方のクラスをデフォルトの JAXBContext インスタンスにバインドすると、必然的に JAXB 例外が発生します。これは、クラスが異なるパッケージに存在しているにもかかわらず、Model という同じ名前を共有しているためです。この同じ名前により競合が発生し、例外が発生します。

package org.acme.one;

import jakarta.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Model {
    private String name1;

    public String getName1() {
        return name1;
    }

    public void setName1(String name1) {
        this.name1 = name1;
    }
}

package org.acme.two;

import jakarta.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Model {
    private String name2;

    public String getName2() {
        return name2;
    }

    public void setName2(String name2) {
        this.name2 = name2;
    }
}

package org.acme.one;

import jakarta.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Model {
    private String name1;

    public String getName1() {
        return name1;
    }

    public void setName1(String name1) {
        this.name1 = name1;
    }
}

package org.acme.two;

import jakarta.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Model {
    private String name2;

    public String getName2() {
        return name2;
    }

    public void setName2(String name2) {
        this.name2 = name2;
    }
}

この機能を有効にするには、次のプロパティーを追加します。

quarkus.jaxb.validate-jaxb-context=true

quarkus.jaxb.validate-jaxb-context=true

さらに、このリリースでは、quarkus.jaxb.exclude-classes プロパティーが追加されています。このプロパティーを使用すると、JAXBContext へのバインドから除外するクラスを指定できます。完全修飾クラス名のコンマ区切りリストまたはパッケージのリストを指定できます。

たとえば、前の例の競合を解決するには、クラスの 1 つまたは両方を除外します。

quarkus.jaxb.exclude-classes=org.acme.one.Model,org.acme.two.Model

quarkus.jaxb.exclude-classes=org.acme.one.Model,org.acme.two.Model

または、パッケージ内のすべてのクラスを除外することもできます。

quarkus.jaxb.exclude-classes=org.acme.*

quarkus.jaxb.exclude-classes=org.acme.*