Chapter 1. Migrating applications to Red Hat build of Quarkus 3.2

The Kubernetes Client has been upgraded from 5.12 to 6.7.2. For more information, see the Kubernetes Client - Migration from 5.x to 6.x guide.

Red Hat build of Quarkus 3.2 introduces changes in how the Kubernetes extension generates TLS-based container ports.

Earlier versions automatically added a container port named https to generated deployment resources. This approach posed problems, especially when SSL/TLS was not configured, rendering the port non-functional.

In 3.2 and later, the Kubernetes extension does not add a container port named https by default. The container port is only added if you take the following steps:

With this 3.2 release, some previously deprecated Kubernetes and OpenShift-related properties have been removed. Replace them with their new counterparts.

Additionally, with this release, properties without the quarkus. prefix are ignored. For example, before this release, if you added a kubernetes.name property, it was mapped to quarkus.kubernetes.name. To avoid exceptions like java.lang.ClassCastException when upgrading from 2.16.0.Final to 2.16.1.Final #30850, this kind of mapping is no longer done.

As you continue your work with Kubernetes and OpenShift in the context of Quarkus, use the new properties and include the quarkus. prefix where needed.

With this 3.2 release, Jandex becomes part of the SmallRye project, consolidating all Jandex projects into a single repository: https://github.com/smallrye/jandex/. Consequently, a new release of the Jandex Maven plugin is delivered alongside the Jandex core.

This release also changes the Maven coordinates. Replace the old coordinates with the new ones.

If you use the Maven Enforcer plugin, configure it to ban any dependencies on org.jboss:jandex. An equivalent plugin is available for Gradle users.

Jandex 3 contains many interesting features and improvements. These changes, unfortunately, required a few breaking changes. Here is the recommended migration path:

Alongside this release, Jandex introduces a new documentation site. While it’s a work in progress, it will become more comprehensive over time. You can also refer to the improved Jandex Javadoc for further information.

With this 3.2 release, the previously deprecated io.quarkus.arc.config.ConfigProperties annotation has been removed.

Instead, use the io.smallrye.config.ConfigMapping annotation to inject multiple related configuration properties.

For more information, see the @ConfigMapping section of the "Mapping configuration to objects" guide.

With this 3.2 release, declaring an interceptor binding annotation on a private method is not supported and triggers a build failure; for example:

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. [...]

In earlier releases, declaring an interceptor binding annotation on a private method triggered only a warning in logs but was otherwise ignored.

This support change aims to prevent unintentional usage of interceptor annotations on private methods because they do not have any effect and can cause confusion.

To address this change, remove such annotations from private methods. If removing these annotations is not feasible, you can set the configuration property quarkus.arc.fail-on-intercepted-private-method to false. This setting reverts the system to its previous behavior, where only a warning is logged.

This release removes the previously deprecated @AlternativePriority annotation. Replace it with both the @Alternative and @Priority annotations.

@AlternativePriority(1)

@AlternativePriority(1)

@Alternative
@Priority(1)

@Alternative
@Priority(1)

Use jakarta.annotation.Priority with the @Priority annotation instead of io.quarkus.arc.Priority, which is deprecated and planned for removal in a future release. Both annotations perform identical functions.

This release updates Mockito version 5.x. Notably, Mockito switched the default mockmaker to inline in its 5.0.0 release.

However, to preserve the mocking behavior Quarkus users are familiar with since Quarkus 1.x, and to prevent memory leaks for extensive test suites, Quarkus 3.0 fixes the mockmaker to subclass instead of inline until the latter is fully supported.

If you want to force the inline mockmaker, follow these steps:

Quarkus has undergone a refactoring of its Maven plugins to support Maven 3.9. As a result, the minimum Maven version supported by Quarkus has been raised from 3.6.2 to 3.8.6 or later. Ensure your development environment is updated accordingly to benefit from the latest improvements and features.

With this 3.2 release, the previously-deprecated io.quarkus:quarkus-bootstrap-maven-plugin Maven plugin has been removed.

This plugin is for Quarkus extension development only. Therefore, if you are developing custom Quarkus extensions, you must change the artifact ID from io.quarkus:quarkus-bootstrap-maven-plugin to io.quarkus:quarkus-extension-maven-plugin.

Mutiny is a reactive programming library, the versions 1.x of which were based on the org.reactivestream interfaces, whereas version 2 is based on java.util.concurrent.Flow. These APIs are identical, but the package name has changed.

Mutiny offers adapters to bridge between Mutiny 2 (Flow API) and other libraries with legacy reactive streams API.

With this 3.2 release, the following previously deprecated methods from Hibernate ORM with Panache and Hibernate ORM with Panache in Kotlin have been removed:

Instead, use the Panache.getEntityManager(Class<?> clazz) method.

With this 3.2 release, the Hibernate Object-Relational Mapping (ORM) extension has been changed to incorporate automatic IN clause parameter padding as a default setting. This improvement augments the caching efficiency for queries that incorporate IN clauses.

To revert to the previous functionality and deactivate this feature, you can set the property value of quarkus.hibernate-orm.query.in-clause-parameter-padding to false.

With this 3.2 release, Quarkus depends on the Hibernate Reactive 2 extension instead of Hibernate Reactive 1. This change implies several changes in behavior and database schema expectations that are incompatible with earlier versions.

Most of the changes are related to Hibernate Reactive 2 depending on Hibernate ORM 6.2 instead of Hibernate ORM 5.6.

For more information, see the following resources:

Suppose your Hibernate Search mapping includes GeoPoint fields that use the default value for the projectable option and either the default value or Sortable.NO for the sortable option. In that case, Elasticsearch schema validation fails on startup because of missing doc values on those fields.

To prevent that failure, complete either of the following steps:

For more information, see the Data format and schema changes section of the "Hibernate Search 6.2.1.Final: Migration Guide from 6.1".

Also, the quarkus.hibernate-search-orm.automatic-indexing.enable-dirty-check property is deprecated and is planned for removal in a future version. There is no alternative to replace it. After the removal, it is planned that Search will always trigger reindexing after a transaction modifies an object’s field. That is, if a transaction makes the fields "dirty."

For more information, see the Configuration changes section of the "Hibernate Search 6.2.1.Final: Migration Guide from 6.1".

With this 3.2 release, Quarkus doesn’t support the manual creation of ValidatorFactory instances. Instead, you must use the Validation.buildDefaultValidatorFactory() method, which returns ValidatorFactory instances managed by Quarkus that you inject through Context and Dependency Injection (CDI). The main reason for this change is that a ValidatorFactory must be carefully crafted to work in native executables. Before this release, you could still manually create a ValidatorFactory instance and handle it yourself if you could make it work. This change aims to improve the compatibility with components creating their own ValidatorFactory.

For more information, see the following resources:

If you are storing jobs for the Quartz extension in a database by using Java Database Connectivity (JDBC), run the following query to update the job class name in your JOB_DETAILS table:

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';

The QuarkusTransaction.run and QuarkusTransaction.call methods have been deprecated in favor of new, more explicit methods.

Update code that relies on these deprecated methods as follows:

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(() -> { ... });

For more information, see the Programmatic Approach section of the "Using transactions in Quarkus" guide.

With this 3.2 release, the quarkus.transaction-manager.object-store-directory configuration property is renamed to quarkus.transaction-manager.object-store.directory. Update your configuration by replacing the old property name with the new one.

This release removes the previously deprecated vertx-kafka-client dependency for the smallrye-reactive-messaging-kafka extension. Although it wasn’t used for client implementations, vertx-kafka-client provided default Kafka Serialization and Deserialization (SerDes) for io.vertx.core.buffer.Buffer, io.vertx.core.json.JsonObject, and io.vertx.core.json.JsonArray types from the io.vertx.kafka.client.serialization package.

If you require this dependency, you can get SerDes for the mentioned types from the io.quarkus.kafka.client.serialization package.

With this 3.2 release, changes in GraalVM/Mandrel affect the use of extensions reliant on .so files, such as the Java Abstract Window Toolkit (AWT) extension.

When using these extensions, you must add or copy the corresponding .so files to the native container; for example:

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

With this 3.2 release, if you build native executables on recent machines and run them on older machines, you might encounter the following failure when starting the application:

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.

This error message means that the native compilation used more advanced instruction sets that are unsupported by the CPU running the application. To work around that issue, add the following line to the application.properties file:

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

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

Then, rebuild your native executable. This setting forces the native compilation to use an older instruction set, increasing the chance of compatibility but decreasing optimization.

To explicitly define the target architecture, run native-image -march=list to get a list of supported configurations. Then, specify a target architecture; for example:

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

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

If you are experiencing this problem with older AMD64 hosts, try -march=x86-64-v2 before using -march=compatibility.

The GraalVM documentation for Native Image Build Options states that "[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."

With this 3.2 release, the previously deprecated @io.quarkus.test.junit.NativeImageTest and @io.quarkus.test.junit.DisabledOnNativeImageTest annotations have been rimage::images/ref_changes-that-affect-backward-compatibility-88d2f.png[]. Replace them with their new counterparts.

The replacement annotations are functionally equivalent to the removed ones.

With this 3.2 release, support for the OpenTracing driver has been deprecated. Removal of the OpenTracing driver is planned for a future Quarkus release.

With this 3.2 release, the SmallRye GraphQL extension has replaced its OpenTracing integration with OpenTelemetry. As a result, when using OpenTracing, the extension no longer generates spans for GraphQL operations.

Also, with this release, the quarkus.smallrye-graphql.tracing.enabled configuration property is obsolete and has been removed. Instead, the SmallRye GraphQL extension automatically produces spans when the OpenTelemetry extension is present.

Update your Quarkus applications to use OpenTelemetry so that they remain compatible with future Quarkus releases.

With this 3.2 release, the Micrometer extension exports metrics in the application/openmetrics-text format by default, in line with the Prometheus standard. This change helps make your data easier to read and interpret.

To you get metrics in the earlier format, you can change the Accept request header to text/plain. For example, with the `curl command:

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

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

With this 3.2 release, the OpenTelemetry (OTel) extension has significant improvements. Before this release, the OpenTelemetry SDK (OTel SDK) was created at build time and had limited configuration options; most notably, it could not be disabled at run time. Now, it offers enhanced flexibility. It can be disabled at run time by setting quarkus.otel.sdk.disabled=true.

After some preparatory steps at build time, the OTel SDK is configured at run time using the OTel auto-configuration feature. This feature supports some of the properties defined in the Java OpenTelemetry SDK. For more information, see the OpenTelemetry SDK Autoconfigure reference.

The OpenTelemetry extension is compatible with earlier versions. Most properties have been deprecated but still function alongside the new ones until they are removed in a future release. You can replace the deprecated properties with new ones.

With this 3.2 release, some of the old quarkus.opentelemetry.tracer.sampler-related property values have been removed.

If the sampler is parent based, there is no need to set the now-dropped quarkus.opentelemetry.tracer.sampler.parent-based property.

Replace the following quarkus.opentelemetry.tracer.sampler values with new ones:

Many new properties are now available. For more information, see the Quarkus Using OpenTelemetry guide.

Quarkus allowed the Context and Dependency Injection (CDI) configuration of many classes: IdGenerator, Resource attributes, Sampler, and SpanProcessor. This is a feature not available in standard OTel, but it’s still provided here for convenience. However, the CDI creation of the SpanProcessor through the LateBoundBatchSpanProcessor is now deprecated. If there’s a need to override or customize it, feedback is appreciated. The processor will continue to be used for supporting earlier versions, but soon the standard exports bundled with the OTel SDK will be used. This means the default exporter uses the following configuration:

quarkus.otel.traces.exporter=cdi

quarkus.otel.traces.exporter=cdi

As a preview, the stock OTLP exporter is now available by setting:

quarkus.otel.traces.exporter=otlp

quarkus.otel.traces.exporter=otlp

Additional configurations of the OTel SDK are now available, using the standard Service Provider Interface (SPI) hooks for Sampler and SpanExporter. The remaining SPIs are also accessible, although compatibility validation through testing is still required. For more information, see the updated OpenTelemetry Guide.

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

With this 3.2 release, you can use a much simpler configuration:

quarkus.datasource.jdbc.telemetry=true

quarkus.datasource.jdbc.telemetry=true

With this configuration, you do not need to change the database URL or declare a different driver.

The default behavior of the cross-origin resource sharing (CORS) filter has significantly changed. In earlier releases, when the CORS filter was enabled, it supported all origins by default. With this 3.2 release, support for all origins is no longer enabled by default. Now, if you want to permit all origins, you must explicitly configure it to do so.

After a thorough evaluation, if you determine that all origins require support, configure the system in the following manner:

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

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

Same-origin requests receive support without needing the quarkus.http.cors.origins configuration. Therefore, adjusting the quarkus.http.cors.origins becomes essential only when you allow trusted third-party origin requests. In such situations, enabling all origins might pose unnecessary risks.

With this 3.2 release, OpenAPI has changed its cross-origin resource sharing (CORS) settings and no longer enables wildcard (*) origin support by default. This change helps to prevent potential leakage of OpenAPI documents, enhancing the overall security of your applications.

Although you can enable wildcard origin support in dev mode, it is crucial to consider the potential security implications. Avoid enabling all origins in a production environment because it exposes your applications to security threats. Ensure your CORS settings align with your production environment’s recommended security best practices.

With this 3.2 release, the OpenID Connect (OIDC) session cookie, created after the completion of an OIDC Authorization Code Flow, is encrypted by default. In most scenarios, you are unlikely to notice this change.

However, if the mTLS or private_key_jwt authentication methods - where the OIDC client private key signs a JSON Web Token (JWT) - are used between Quarkus and the OIDC Provider, an in-memory encryption key gets generated. This key generation can result in some pods failing to decrypt the session cookie, especially in applications dealing with many requests. This situation can arise when a pod attempting to decrypt the cookie isn’t the one that encrypted it.

If such issues occur, register an encryption secret of 32 characters; for example:

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

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

An encrypted session cookie can exceed 4096-bytes, which can cause some browsers to ignore it. If this occurs, try one or more of the following steps:

If application users access the Quarkus application from within a trusted network, disable the session cookie encryption by applying the following configuration:

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

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

With this 3.2 release, for the Quarkus OpenID Connect (OIDC) extension, the session cookie SameSite attribute is set to Lax by default.

In some earlier releases of Quarkus, the OIDC session cookie SameSite attribute was set to Strict by default. This setting introduced unpredictability in how different browsers handled the session cookie.

With this 3.2 release, the OpenID Connect (OIDC) ID token aud (audience) claim is verified by default. This claim must equal the value of the configured quarkus.oidc.client-id property, as required by the OIDC specification.

To override the expected ID token audience value, set the quarkus.oidc.token.audience configuration property. If you deal with a noncompliant OIDC provider that does not set an ID token aud claim, you can set quarkus.oidc.token.audience to any.

Before this release, Quarkus used password as the default password for the JSON Web Token (JWT) key and keystore. With this 3.2 release, this default value has been removed.

If you are still using the default password, set a new value to replace password for the following properties in the application.properties file:

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

With this 3.2 release, the following changes impact multipart support in RESTEasy Reactive:

The JAXB extension detects classes that use JAXB annotations and registers them into the default JAXBContext instance. Before this release, any issues or conflicts between the classes and JAXB triggered a JAXB exception at runtime, providing a detailed description to help troubleshoot the problem. However, you could preemptively tackle these conflicts during the build stage.

This release adds a feature that can validate the JAXBContext instance at build time so that you can detect and fix JAXB errors early in the development cycle.

For example, as shown in the following code block, binding both classes to the default JAXBContext instance would inevitably lead to a JAXB exception. This is because the classes share the identical name, Model, despite existing in different packages. This concurrent naming creates a conflict, leading to the exception.

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

To activate this feature, add the following property:

quarkus.jaxb.validate-jaxb-context=true

quarkus.jaxb.validate-jaxb-context=true

Additionally, this release adds the quarkus.jaxb.exclude-classes property. With this property, you can specify classes to exclude from binding to the JAXBContext. You can provide a comma-separated list of fully qualified class names or a list of packages.

For example, to resolve the conflict in the preceding example, you can exclude one or both of the classes:

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

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

Or you can exclude all the classes under a package:

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

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