-
Notifications
You must be signed in to change notification settings - Fork 2.7k
Migration Guide 3.7
- Java 17 ⚙️ ✅
- REST Client ⚙️ ✅
- JPA / Hibernate ORM
- Hibernate Search
- Scheduler - OpenTelemetry Tracing
- Okhttp/Okio versions not enforced anymore
- Infinispan
- Insecure HTTP port is disabled when mTLS client authentication is required
- Stork
- OpenTelemetry
- Resolving OIDC tenants with annotations for RESTEasy Classic applications
- OpenShift
Note
|
We highly recommend the use of Items marked below with ⚙️ ✅ are automatically handled by |
Starting with Quarkus 3.7, Java 17 is the minimum version you need to use to build and run Quarkus applications.
You can of course also use Java 21.
For more information about this change, see the this blog post.
As part of the renaming of the RESTEasy Reactive extensions that will be spread across several releases, we renamed the quarkus-rest-client*
extensions (client extensions for RESTEasy Classic) to quarkus-resteasy-client*
, which makes it clearer that it is the client counterpart of quarkus-resteasy
.
Relocations have been put into place to not break your applications but we recommend that you adjust your applications already as these particular artifacts (quarkus-rest-client*
) will be switched to RESTEasy Reactive in Quarkus 3.9.
See https://github.com/quarkusio/quarkus/blob/main/adr/0002-reactive-rename.adoc for the full context about this change.
The following table summarizes the changes:
Old name | New name |
---|---|
quarkus-rest-client |
quarkus-resteasy-client |
quarkus-rest-client-jackson |
quarkus-resteasy-client-jackson |
quarkus-rest-client-jaxb |
quarkus-resteasy-client-jaxb |
quarkus-rest-client-jsonb |
quarkus-resteasy-client-jsonb |
quarkus-rest-client-mutiny |
quarkus-resteasy-client-mutiny |
The Quarkus extensions for Hibernate ORM was upgraded to Hibernate ORM 6.4.
Here are the most impactful changes:
-
Compatibility with some older database versions was dropped.
See here for supported versions.
-
The HQL
!=
/<>
operators no longer allow comparing againstnull
-
Numeric literals are now interpreted as defined in Jakarta Persistence 3.2
See the Hibernate ORM migration guides for more details:
Static metamodel annotation processor (hibernate-jpamodelgen
) can no longer be used as a provided
dependency ⚙️ ✅
Some projects used to apply the hibernate-jpamodelgen
annotation processor with a dependency, like so:
<dependencies>
<!-- ... -->
<!-- THIS IS WRONG! See below -->
<dependency>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<scope>provided</scope>
<version>6.2.4</version> <!-- Optional, may be managed by a BOM -->
</dependency>
<!-- ... -->
</dependencies>
This is actually wrong for several reasons, one of them being that dependencies of the annotation processor may not be handled correctly.
With Hibernate ORM 6.4, this annotation processor now has more dependencies, and the snippet above will fail, most likely with an error about an ANTLR class not being available.
Applications using Hibernate ORM 6.4+ (and thus Quarkus 3.7+) should register the hibernate-jpamodelgen
annotation processor using the proper solution depending on their building tool.
<build>
<plugins>
[...]
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
[...]
</plugins>
</build>
Note
|
Make sure you’re using Maven Compiler Plugin 3.12.0 or later:
older versions didn’t handle dependency management for |
Note
|
At the time of this writing, some IDEs such as Eclipse, VSCode and most web-based IDEs do not handle dependency management for <build>
<plugins>
[...]
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>6.4.2.Final</artifactId> <!-- Ideally we'd rely on the BOM, but this is necessary for some IDEs -->
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
[...]
</plugins>
</build> |
dependencies {
annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen"
}
The Quarkus extensions for Hibernate Search was upgraded to Hibernate Search 7.0.
Here are the most impactful changes:
-
The values accepted by configuration properties
quarkus.hibernate-search-orm.coordination.entity-mapping.outbox-event.uuid-type
andquarkus.hibernate-search-orm.coordination.entity-mapping.agent.uuid-type
changed:-
uuid-binary
is deprecated in favor ofbinary
-
uuid-char
is deprecated in favor ofchar
-
-
The default value for
quarkus.hibernate-search-orm.elasticsearch.query.shard-failure.ignore
changed fromtrue
tofalse
, meaning that Hibernate Search will now throw an exception if at least one shard failed during a search operation.To get the previous behavior set this configuration property explicitly to
true
.Note this configuration property must be set for each Elasticsearch backend, if you define multiple backends.
-
The complement operator (
~
) in the regular expression predicate was removed with no alternative to replace it. -
The corresponding Hibernate Search dependencies no longer have an
-orm6
suffix in their artifact ID; for example applications will now depend onhibernate-search-mapper-orm
instead ofhibernate-search-mapper-orm-orm6
.
See the Hibernate Search 7.0 migration guide for more details.
The Quarkus extension for Hibernate Search with outbox-polling relies on system tables in your database, and the schema of these system tables changed.
See this section of the Hibernate Search migration guide for information on how to migrate your database schema if you were using that extension.
The Quarkus extension for Hibernate Search with outbox-polling was renamed:
-
The extension’s artifact ID was renamed from
quarkus-hibernate-search-orm-coordination-outbox-polling
toquarkus-hibernate-search-orm-outbox-polling
-
The base package in the corresponding Hibernate Search dependency changed from
org.hibernate.search.mapper.orm.coordination.outboxpolling
toorg.hibernate.search.mapper.orm.outboxpolling
The integration of OpenTelemetry Tracing and Scheduler has been refactored.
Previously, only @Scheduled
methods had a new io.opentelemetry.api.trace.Span
associated automatically when tracing is enabled, i.e. when the quarkus.scheduler.tracing.enabled
configuration property is set to true
and the OpenTelemetry extension is present.
Since Quarkus 3.7, all scheduled jobs (including the jobs scheduled programmatically) have a Span
associated automatically when tracing is enabled.
Furthermore, the unique job identifier (specified with Scheduled.identity()
or JobDefinition
) is used as a span name.
Previously, the span names followed the <simpleclassname>.<methodName>
format.
Okhttp and Okio versions are not enforced by the Quarkus BOM anymore.
Make sure you define the versions in your build files if you are using any of these dependencies.
The quarkus-test-infinispan-client
artifact has been retired.
We don’t think it was used outside of the Quarkus core repository and it wasn’t used anymore even there since the introduction of Dev Services for Infinispan.
PLain HTTP port is now disabled by default when an mTLS
client authentication is required.
For example, if you have enabled mTLS
with the following configuration:
quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required
Then, attempts to access the Quarkus endpoint over an insecure (not https://
) HTTP URL such as http://localhost:8080/service
will fail because it has been requested by the server that the client sends a certificate to validate its identity. This mechanism is enforced at the transport level.
This stricter policy has been enforced to avoid unexpected insecure HTTP requests reaching Quarkus applications that do not use the Quarkus Security mTLS
authentication mechanism.
If you need to allow insecure HTTP requests when an mTLS
client authentication is required then you can enable such requests with quarkus.http.insecure-requests=enabled
. However, if it is indeed necessary, it is recommended and simpler to use an mTLs
client authentication request
mode instead, for example:
quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=request
The configurations names stork."service-name".load-balancer
or quarkus.stork."service-name".load-balancer
are not used anymore to configure the Stork load-balancer. Please use quarkus.stork."service-name".load-balancer.type
instead.
It is now possible to disable particular automatic tracing instrumentations done within the OpenTelemetry extension. The new configs are:
-
quarkus.otel.instrument.grpc
-
quarkus.otel.instrument.reactive-messaging
-
quarkus.otel.instrument.rest-client-classic
-
quarkus.otel.instrument.resteasy-reactive
-
quarkus.otel.instrument.resteasy-classic
-
quarkus.otel.instrument.vertx-http
-
quarkus.otel.instrument.vertx-event-bus
-
quarkus.otel.instrument.vertx-sql-client
The properties are booleans and are all true
by default.
Using CDI annotations and interceptors to resolve OIDC tenants for RESTEasy Classic applications is no longer possible due to the security checks now enforced before the CDI interceptors are triggered.
Use the @io.quarkus.oidc.Tenant
annotation instead, which works both for RESTEasy Reactive and Classic applications. See Quarkus OIDC tenant resolution using annotations for more information.
As now DeploymentConfig resource are deprecated in OpenShift the default deployment kind for Openshift is now Deployment.
Applications that have been already deployed as DeploymentConfig that are redeployed will get a Deployment without having the old DeploymentConfig removed, leading to both new and old application to be deployed. Please ensure that the old (DeploymentConfig) is manually removed. Alternatively, you can explicitly set quarkus.openshift.deployment-kind
to DeploymentConfig
to retain the old behavior.
Moving from DeploymentConfig
to Deployment
has a potential sideffect related to labels and selectors. While Deployment
config used pod selectors that are muttable, this is not the case for Deployment
. This means that version numbers (added by default to labels and selectors) may mutate selectors preventing direct deployment of the generated resource. In this case the error message is similar to:
Deployment.apps "quarkus-app" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/name":"quarkus-app", "app.kubernetes.io/version":"2.0.1"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable.
Deployemnt
before applying / deploying the new.
To prevent this issue in the first place, it’s a good idea to use quarkus.openshift.add-version-to-label-selectors=false
before moving from DeploymentConfig
to Deployment
.