Skip to content

Migration Guide 3.7

Jump to bottom
Yoann Rodière edited this page Oct 11, 2024 · 37 revisions
Note

We highly recommend the use of quarkus update to update to a new version of Quarkus.

Items marked below with ⚙️ ✅ are automatically handled by quarkus update.

Java 17 ⚙️ ✅

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.

REST Client ⚙️ ✅

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.

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

JPA / Hibernate ORM

Upgrade to Hibernate ORM 6.4

The Quarkus extensions for Hibernate ORM was upgraded to Hibernate ORM 6.4.

Here are the most impactful changes:

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 annotationProcessorPaths entries, forcing you to set the version of hibernate-jpamodelgen manually, even if you use the Quarkus BOM.
Note

At the time of this writing, some IDEs such as Eclipse, VSCode and most web-based IDEs do not handle dependency management for annotationProcessorPaths entries. So you will have to set the version of hibernate-jpamodelgen manually, even if you use the Quarkus BOM:

<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"
}

Hibernate Search

Upgrade to Hibernate Search 7.0

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 and quarkus.hibernate-search-orm.coordination.entity-mapping.agent.uuid-type changed:

    • uuid-binary is deprecated in favor of binary

    • uuid-char is deprecated in favor of char

  • The default value for quarkus.hibernate-search-orm.elasticsearch.query.shard-failure.ignore changed from true to false, 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 on hibernate-search-mapper-orm instead of hibernate-search-mapper-orm-orm6.

See the Hibernate Search 7.0 migration guide for more details.

Database schema changed for outbox-polling system tables

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.

quarkus-hibernate-search-orm-coordination-outbox-polling was renamed ⚙️ ✅

  • The extension’s artifact ID was renamed from quarkus-hibernate-search-orm-coordination-outbox-polling to quarkus-hibernate-search-orm-outbox-polling

  • The base package in the corresponding Hibernate Search dependency changed from org.hibernate.search.mapper.orm.coordination.outboxpolling to org.hibernate.search.mapper.orm.outboxpolling

Scheduler - OpenTelemetry Tracing

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/Okio versions not enforced anymore

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.

Infinispan

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.

Insecure HTTP port is disabled when mTLS client authentication is required

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

Stork

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.

OpenTelemetry

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.

Resolving OIDC tenants with annotations for RESTEasy Classic applications

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.

OpenShift

Deprecation of DeploymentConfig

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.

Troubleshooting

Field is immutable

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.
To work around this issue the only solution is to delete the old 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.

Current Version

Migration Guide 3.16

Next Version

Migration Guide 3.17

Clone this wiki locally