Chapter 1. Release notes for Red Hat build of Quarkus 3.8

Java 21 is now the recommended version, although Java 17 is also supported.

With this 3.8 release, support for Java 11, which was deprecated in version 3.2, has been removed.

The use of Red Hat build of Quarkus with Virtual Threads (VTs) brings the following:

Virtual thread Limitations:

In Red Hat build of Quarkus 3.8, Hibernate Object-Relational Mapping (ORM) is upgraded to version 6.4.

For more information, see the following resources:

In Red Hat build of Quarkus 3.8, Hibernate Reactive can co-exist alongside Agroal, which means you can use Flyway or Liquibase in your applications while using Hibernate Reactive as the Object-Relational Mapping (ORM).

For more information, see the Quarkus Using Hibernate Reactive guide.

In Red Hat build of Quarkus 3.8, the Hibernate Reactive extension is upgraded to version 2.2, which is compatible with Hibernate ORM 6.4.0.

For more information, see the Hibernate Reactive 2.2.0 documentation.

In Red Hat build of Quarkus 3.8, Hibernate Search is upgraded to version 7.0.

Hibernate Search offers indexing and full-text search capabilities to your Red Hat build of Quarkus applications. Version 7.0 introduces enhancements, new features, and some notable changes to the default configuration for geo-point fields.

For more details, see Changes that affect compatibility with earlier versions.

To learn more about Hibernate Search 7.0, see the following resources:

Red Hat build of Quarkus 3.8 introduces a new OpenSearch Dev Service.

When you use Hibernate Search, Dev Services defaults to starting Elasticsearch or OpenSearch based on your Hibernate Search configuration.

To configure Dev Services to use OpenSearch, specify the following setting:

quarkus.elasticsearch.devservices.distribution=opensearch

For more information, see the Configuring the image section of the Quarkus "Dev Services for Elasticsearch" guide.

Red Hat build of Quarkus 3.8 introduces many ways to customize Micrometer by using the new MeterRegistryCustomizer interface implemented as Contexts and Dependency Injection (CDI) beans.

You can customize Micrometer in the following ways:

For more information, see the Customizing Micrometer section of the Quarkus “Micrometer Metrics” guide.

Micrometer defines two annotations, @Counted and @Timed, which you can add to methods.

With Red Hat build of Quarkus 3.8, Micrometer can add the @MeterTag annotation to parameters of methods annotated with @Counted and @Timed.

The @MeterTag annotation uses the ValueResolver or ValueExpressionResolver resolvers from the io.micrometer.common.annotation package to dynamically assign additional tag values to the method counter or timer.

For more information, see the Quarkus Micrometer Metrics guide.

Red Hat build of Quarkus 3.8 introduces support for the gathering of Netty allocator metrics from the Micrometer metrics library.

The quarkus.micrometer.binder.netty.enabled property is introduced, which enables the gathering of Netty metrics if Micrometer support is also enabled.

Netty allocator metrics provide insights on memory allocation and usage within your Netty framework, which can help you to gain an understanding of the performance of your Red Hat build of Quarkus applications that use Netty.

The following metrics are gathered:

For more information about Micrometer, see the Quarkus Micrometer Metrics guide.

In Red Hat build of Quarkus 3.8, the OpenTelemetry (OTel) extension, quarkus-opentelemetry is enhanced to replace the default OTel exporter with a Red Hat build of Quarkus implementation built on top of Vert.x.

This eliminates the dependency on the OkHttp library. The exporter continues to be automatically wired with Contexts and Dependency Injection (CDI), so the quarkus.otel.traces.exporter property defaults to cdi.

For more information, see the Quarkus Using OpenTelemetry guide.

With Red Hat build of Quarkus 3.8, you can split an OpenID Connect (OIDC) session cookie into smaller cookies if its content size exceeds 4KB.

Typically, a session cookie, which is encrypted by default, comprises a concatenation of three tokens, namely, ID, access, and refresh tokens. If its size is greater than 4KB, some browsers might be unable to handle it.

With this update, a session cookie exceeding 4KB in size is automatically split into multiple chunks.

For more information, see the Quarkus OIDC authorization code flow mechanism for protecting web applications guide.

With Red Hat build of Quarkus 3.8, you can create OIDC SecurityIdentity instances for authentication purposes after a HTTP request completes.

With this version, the quarkus-oidc extension includes the io.quarkus.oidc.TenantIdentityProvider interface, which you can inject and call to convert a token to a SecurityIdentity instance after an HTTP request completes.

For more information, see the following Quarkus resources:

Red Hat build of Quarkus 3.8 introduces the OIDC JavaScriptRequestChecker bean that you can use to customize JavaScript request checks.

If you use single-page applications (SPAs) and JavaScript APIs such as Fetch or XMLHttpRequest(XHR) with Red Hat build of Quarkus web applications, you must set a header in the browser script to identify the request as a JavaScript request. However, the script engine can also set an engine-specific request header itself.

With this update, you can now register a custom io.quarkus.oidc.JavaScriptRequestChecker bean, which informs Red Hat build of Quarkus if the current request is a JavaScript request, thereby helping to avoid the creation of redundant headers.

Red Hat build of Quarkus 3.8 introduces support for delayed OIDC JSON Web Key (JWK) resolution, and you can now resolve keys the moment a token is available.

This release adds the quarkus.oidc.jwks.resolve-early configuration property. By default, this property is set to true, which means that JWK keys are resolved the moment you establish an OIDC provider connection.

However, you can set it to false, enabling the delayed resolution of keys simultaneously to token verification. The delayed JWK resolution uses the current token instead of the read-once approach at initialization time. For example, the token might provide information on how to resolve keys correctly.

When mTLS client authentication (quarkus.http.ssl.client-auth) is set to required, Red Hat build of Quarkus automatically disables plain HTTP ports to ensure that only secure HTTPS requests are accepted. To enable plain HTTP, configure quarkus.http.ssl.client-auth to request or set both quarkus.http.ssl.client-auth=required and quarkus.http.insecure-requests=enabled.

Red Hat build of Quarkus has updated to allow runtime configuration of HTTP Permissions and Roles, enabling flexible security settings across profiles. This resolves the issue of native executables locking to build-time security configurations. Security can now be dynamically adjusted per profile, applicable in both JVM and native modes.

If you use Bearer token authentication in Red Hat build of Quarkus, you can map SecurityIdentity roles from the verified JWT access tokens. Red Hat build of Quarkus 3.8 introduces the ability to map the OIDC scope parameter to permissions on the SecurityIdentity object.

For example, you can use @PermissionAllowed("orders_read") to request that JWT tokens have a scope claim with an orders_read value.

For more information, see the Quarkus OIDC Bearer token authentication guide.

With Red Hat build of Quarkus 3.8, you can use Context and Dependency Injection (CDI) to observe authentication and authorization security events.

The CDI observers can be either synchronous or asynchronous and reporting of the following security events is supported:

For more information, see the Observe security events section of the Quarkus “Security tips and tricks” guide.

Red Hat build of Quarkus 3.8 introduces support for an OpenID Connect (OIDC) authorization code flow nonce feature.

When the OIDC authorization server issues an ID token in response to an authorization request, the ID token includes a nonce claim that must match the nonce authentication request query parameter. This feature helps to mitigate replay attacks by ensuring that the ID token is returned in response to the original authorization request and is not a replayed response.

With Red Hat build of Quarkus 3.8, you can customize OIDC client requests made by either quarkus-oidc-client or quarkus-oidc extensions to update or add new request headers by registering one or more OidcRequestFilter implementations.

For example, an OIDC request filter can analyze the request body and add its digest as a new header value.

For more information, see the OIDC request filters section of the Quarkus "OIDC authorization code flow mechanism for protecting web applications" guide.

In Red Hat build of Quarkus 3.8, a new @TenantFeature annotation is introduced to bind OpenID Connect (OIDC) features to OIDC tenants.

The io.quarkus.oidc.Tenant annotation is now used for resolving tenant configuration.

Red Hat build of Quarkus 3.8 introduces support for OIDC token propagation.

With this update, Red Hat build of Quarkus endpoints use REST clients to propagate the incoming OIDC access tokens to other secure endpoints that expect access tokens.

Red Hat build of Quarkus 3.8 now supports mapping the Common Name (CN) attribute from a client’s X.509 certificate to roles when using the Mutual TLS (mTLS) authentication mechanism. This functionality is activated under specific conditions:

This functionality is activated under specific conditions:

The role mapping file is expected to have the CN=role1,role,…​,roleN format and encoded by using UTF-8.

Red Hat build of Quarkus 3.8 introduces the verification of OIDC bearer access tokens by using the X.509 certificate chain that is inlined in the token.

This means that you validate the certificate chain before you extract a public key from the leaf certificate. The leaf certificate refers to an X.509 certificate that is positioned at the end of a certificate chain. To verify the token’s signature, you use this public key.

quarkus update now supports OpenRewrite recipes for external Red Hat build of Quarkus extensions, expanding its capabilities beyond built-in extensions only. New recipes have been introduced, enhancing migration support for external extensions.

Be aware that Red Hat provides development support for using Quarkus development tools, including the Quarkus CLI to prototype, develop, test, and deploy Red Hat build of Quarkus applications. Red Hat does not support using Quarkus development tools in production environments.

Applications using quarkus-info can now enrich the /info endpoint with additional data through CDI integration. This feature enhances the ability to customize and extend application diagnostics and metadata visibility.

With Red Hat build of Quarkus 3.8, the REST Client’s Server-Sent Events (SSE) capabilities are enhanced, enabling complete event returns and filtering. These updates and new descriptions in REST Client provide developers with increased control and flexibility in managing real-time data streams.

With Red Hat build of Quarkus 3.8, you can customize the ObjectMapper when using the rest-client-reactive-jackson extension. You can add the custom ObjectMapper, that only the client uses, by using the annotation @ClientObjectMapper.

For more information, see the Customizing the ObjectMapper in REST Client Reactive Jackson section of the Quarkus “Using the REST client” guide.

The @TestHTTPResource annotation now supports path parameters. Validation as a URI string is no longer applied due to non-compliance with the URI format.

Red Hat provides development support for using Quarkus development tools, including the Quarkus CLI and the Maven and Gradle plugins, to prototype, develop, test, and deploy Red Hat build of Quarkus applications.

Red Hat does not support using Quarkus development tools in production environments. For more information, see the Red Hat Knowledgebase article Development Support Scope of Coverage.

You can no longer use the previous configuration names stork."service-name".load-balancer and quarkus.stork."service-name".load-balancer for configuring the Stork load balancer. Instead, use quarkus.stork."service-name".load-balancer.type for configuration settings.

OkHttp and Okio have been removed from the Quarkus Platform BOM, and their versions are no longer enforced, addressing issues related to outdated dependencies. This change affects test framework dependencies and streamlines runtime dependencies. Developers using these dependencies must now specify their versions in build files. Additionally, the quarkus-test-infinispan-client artifact has been removed due to the availability of robust Dev Services support for Infinispan.

Beginning with this version of Red Hat build of Quarkus, support for Java 11, deprecated in the previous version, has been removed. Java 21 is now the recommended version, although Java 17 is also supported.

In Red Hat build of Quarkus, using RESTEasy Reactive with Java Architecture for XML Binding (JAXB) does not support using collections, arrays, and maps as parameters or return types in REST methods. To overcome this limitation of JAXB, encapsulate these types within a class annotated with @XmlRootElement.

During the static initialization phase, Red Hat build of Quarkus collects the configuration to inject in CDI beans. The collected values are then compared with their runtime initialization counterparts, and if a mismatch is detected, the application startup fails. With Red Hat build of Quarkus 3.8, you can now annotate configuration objects with the @io.quarkus.runtime.annotations.StaticInitSafe annotation to inform users that the injected configuration:

User tags in templates are now executed in isolation by default, restricting access to the calling template’s context. This update can alter data handling within tag templates, potentially impacting their current functionality. To bypass this isolation and maintain access to the parent context, include _isolated=false or _unisolated in the tag call, for example, # itemDetail item showImage=true _isolated=false. This approach allows tags to access data from the parent context as before. This change minimizes unintended data exposure from the parent context to the tag, enhancing template data integrity. However, it might necessitate updates to existing templates reliant on shared context access, representing a notable change that could affect users unfamiliar with this isolation mechanism.

ResultNode class is updated to be an abstract class, not an interface, and should not be user-implemented despite being in the public API. The Qute API now limits CompletionStage implementations to java.util.concurrent.CompletableFuture and io.quarkus.qute.CompletedStage by default, a restriction alterable with -Dquarkus.qute.unrestricted-completion-stage-support=true.

With Red Hat build of Quarkus 3.8, the following quarkus-rest-client extensions are renamed:

The @TestHTTPResource annotation now supports path parameters. Validation as a URI string is no longer applied due to non-compliance with the URI format.

The GraalVM SDK version has been updated to 23.1.2 in Red Hat build of Quarkus 3.8. Developers using extensions requiring GraalVM substitutions should switch from org.graalvm.sdk:graal-sdk to org.graalvm.sdk:nativeimage to access necessary classes. For those that use org.graalvm.js:js, replace this dependency with org.graalvm.polyglot:js-community for the community version. For the enterprise version, replace this dependency with org.graalvm.polyglot:js. The adjustment for the graal-sdk is automated with quarkus update. However, changes to the js dependency must be made manually. Even though it is highly unlikely, this change could affect users who depend on:

In this release, QuarkusComponentTest has undergone several adjustments. It remains experimental and is not supported by Red Hat build of Quarkus. This experimental status indicates that the API might change at any time, reflecting feedback received.

The QuarkusComponentTestExtension is now immutable, requiring programmatic registration through the simplified constructor QuarkusComponentTestExtension(Class…) or the QuarkusComponentTestExtension.builder() method. The test instance lifecycle, either Lifecycle#PER_METHOD (default) or Lifecycle#PER_CLASS, dictates when the CDI container starts and stops; PER_METHOD starts the container before each test and stops it afterward, whereas PER_CLASS starts it before all tests and stops it after all tests. This represents a change from previous versions, where the container always started before and stopped after all tests.

In Red Hat build of Quarkus 3.8, Hibernate Object-Relational Mapping (ORM) was upgraded to version 6.4 and introduced the following breaking changes:

For more information, see the Hibernate ORM 6.4 migration guide.

In Red Hat build of Quarkus 3.8, Hibernate Search was upgraded to version 7.0 and introduced the following breaking changes:

For more information, see the following resources:

Dev Services for SQL Server updated its default image from mcr.microsoft.com/mssql/server:2019-latest to mcr.microsoft.com/mssql/server:2022-latest.

Users preferring the previous version can specify an alternative by using the config property detailed in the References section in the Red Hat build of Quarkus "Configure data sources" guide.

In Red Hat build of Quarkus 3.8, the Flyway extension is upgraded to Flyway 9.20.0, which delivers an additional dependency, flyway-database-oracle, for Oracle users.

Oracle users must update the pom.xml file to include the flyway-database-oracle dependency. To do so, do the following:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-oracle</artifactId>
</dependency>

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-oracle</artifactId>
</dependency>

For more information, see the Quarkus Using Flyway guide.

The Kafka extension’s Strimzi OAuth support in quarkus-bom now uses io.strimzi:strimzi-kafka-oauth version 0.14.0, introducing a known issue that leads to native build failures. The error, Substitution target for `io.smallrye.reactive.kafka.graal.Target_com_jayway_jsonpath_internal_DefaultsImpl is not loaded can be bypassed by adding io.strimzi:kafka-oauth-common to your project’s classpath.

When using Opentelemetry (oTel) instrumentation with Red Hat build of Quarkus 3.8, you can now annotate a method in any Context Dependency Injection (CDI)-aware bean by using the io.opentelemetry.instrumentation.annotations.AddingSpanAttributes annotation, which does not create a new span but adds annotated method parameters to attributes in the current span.

For more information, see the CDI section of the Quarkus "Using OpenTelemetry" guide.

With Red Hat build of Quarkus 3.8, the quarkus-smallrye-metrics extension is no longer supported. Now, it is available as a community extension only. Its use in production environments is discouraged.

From Red Hat build of Quarkus 3.8, quarkus-smallrye-metrics is replaced by the fully supported quarkus-micrometer extension.

With Red Hat build of Quarkus 3.8, SmallRye OpenTracing is no longer supported. To continue using distributed tracing, migrate your applications to SmallRye OpenTelemetry, which is now fully supported with this release and no longer a Technology Preview feature. If you still need to use quarkus-smallrye-opentracing, adjust your application to use the extensions from Quarkiverse by updating the groupId and specifying the version manually.

In Red Hat build of Quarkus 3.8, integration of OpenTelemetry Tracing and the quarkus-scheduler extension has been refactored.

Before this update, only @Scheduled methods had a new io.opentelemetry.api.trace.Span class, which is associated automatically when you enable tracing. That is, when the quarkus.scheduler.tracing.enabled configuration property is set to true, and the quarkus-opentelemetry extension is available.

With this 3.8 release, all scheduled jobs, including those that are scheduled programmatically, have a Span associated automatically when tracing is enabled. The unique job identifier for each scheduled method is either generated, is specified by setting the io.quarkus.scheduler.Scheduled#identity attribute or with the JobDefinition method. Before this update, span names followed the <simpleclassname>.<methodName> format.

For more information, see the following Quarkus resources:

When mTLS client authentication (quarkus.http.ssl.client-auth) is set to required, Red Hat build of Quarkus automatically disables plain HTTP ports to ensure that only secure HTTPS requests are accepted. To enable plain HTTP, configure quarkus.http.ssl.client-auth to request or set both quarkus.http.ssl.client-auth=required and quarkus.http.insecure-requests=enabled.

The JWT extension no longer transitively depends on the Reactive Routes extension. If your application uses both JWT and Reactive Routes features but does not declare an explicit dependency on Reactive Routes, you must add this dependency.

The quarkus-keycloak-authorization extension no longer includes the org.keycloak:keycloak-adapter-core dependency due to its update to Keycloak 22.0.0 and its irrelevance to the extension’s functionality. In future Keycloak versions, it is planned to remove the Keycloak Java adapters code. If your application requires this dependency, manually add it to your project’s pom.xml.

You can no longer use Context and Dependency Injection (CDI) annotations and interceptors to resolve tenant OIDC configuration for RESTEasy Classic applications.

Due to security checks that are enforced before CDI interceptors and checks requiring authentication are triggered, using CDI interceptors to resolve multiple OIDC provider configuration identifiers no longer works.

Use @Tenant annotation or custom io.quarkus.oidc.TenantResolver instead.

For more information, see the Resolve with annotations section of the Quarkus "Using OIDC multitenancy guide".

In Red Hat build of Quarkus 3.8, you must now use the quarkus.oidc.TenantFeature annotation instead of quarkus.oidc.Tenant to bind OpenID Connect (OIDC) features to OIDC tenants.

The quarkus.oidc.Tenant annotation is now used for resolving tenant configuration.

Red Hat build of Quarkus 3.8 allows runtime configuration of HTTP permissions and roles, enabling flexible security settings across profiles. This resolves the issue of native executables locking to build-time security configurations. Security can now be dynamically adjusted per profile, applicable in both JVM and native modes.

The application of annotation-based GraphQL directives has been corrected to ensure they are only applied to the schema element types for which they are declared.

For example, if a directive was declared to apply to the GraphQL element type FIELD but was erroneously applied to a different element type, it was still visible in the schema on the element where it should not be applicable, leading to an invalid schema. This was now corrected, and directives have their usage checked against their applicability declaration.

If you had directives applied incorrectly in this way, they will no longer appear in the schema, and Red Hat build of Quarkus 3.8 will log a warning during the build.

Red Hat build of Quarkus 3.8 has enhanced its REST Client’s Server-Sent Events (SSE) capabilities, enabling complete event returns and filtering. These updates and new descriptions in REST Client provide developers with increased control and flexibility in managing real-time data streams.

Until version 3.8, the Red Hat build of Quarkus SmallRye JWT automatically incorporated quarkus-reactive-routes, a feature discontinued from version 3.8 onwards. To ensure continued functionality, manually add quarkus-reactive-routes as a dependency in your build configuration.