Migrating applications to Red Hat build of Quarkus 3.20

In Red Hat build of Quarkus 3.20, the following extensions upgrade the Fabric8 Kubernetes Client from version 6.13 to 7.2.

Although the quarkus-openshift and quarkus-kubernetes extensions use Fabric8, their functionality remains unchanged, so you do not need to make any updates for them.

The io.quarkus:quarkus-test-openshift-client module has been removed as part of this upgrade. If your tests use this module, migrate to io.quarkus:quarkus-test-kubernetes-client, which offers equivalent functionality. For more information, see the OpenShift client section of the Quarkus "Kubernetes Client" guide.

The upgraded Fabric8 Kubernetes Client reorganized some model types and classes, moving some to different modules. To find their new locations, refer to the official Fabric8 Kubernetes Client: Migration from 6.x to 7.x guide.

Review your application for any affected dependencies, configurations, or API usages, and update them as needed. Then, thoroughly test your application to ensure full compatibility with Fabric8 7.2.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

In Red Hat build of Quarkus 3.15, many extensions and configuration properties were renamed as part of the rebranding of RESTEasy Reactive to Quarkus REST and Reactive Messaging to Quarkus Messaging. To support this transition, artifact relocations and configuration fallbacks were introduced.

In Red Hat build of Quarkus 3.20, these artifact relocations and configuration fallbacks have been removed. You must now use the new artifact names and configuration properties.

For more additional background information, see the RESTEasy Reactive extensions renamed to Quarkus REST section of the "Release Notes for Red Hat build of Quarkus 3.15" guide.

Red Hat build of Quarkus 3.20 updates locale handling to align with Mandrel version 24.2 and later.

To ensure consistent locale behavior across all applications, Red Hat build of Quarkus applies a standardized default locale strategy. Use the following table to determine how your application’s behavior changes based on your locale configuration.

The en_US locale is always embedded in the native executable, regardless of the quarkus.locales configuration.

Review your application’s locale settings in the configuration properties and, if necessary, update the settings to avoid unexpected changes in behavior.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

In Red Hat build of Quarkus 3.20, the configuration properties for @Fallback.fallbackMethod() and @BeforeRetry.methodName() are now resolved at build time and cannot be changed at runtime. The affected configuration properties are:

This change ensures proper reflection configuration and compatibility with native image compilation.

In Red Hat build of Quarkus 3.20, the quarkus-smallrye-fault-tolerance extension includes SmallRye Fault Tolerance 6.7.0, which introduces no breaking changes but includes the following updates:

For more information, see the SmallRye Fault Tolerance 6.7.0 release announcement, which includes links to the migration guides for the programmatic API and details about the new configuration properties. The Quarkus SmallRye Fault Tolerance guide provides a complete reference for these configuration properties.

Starting in Red Hat build of Quarkus 3.20, the behavior of methods in io.quarkus.scheduler.Scheduler has changed.

When the scheduler is not started, almost all methods now throw an UnsupportedOperationException.

To verify whether the scheduler is running, you can use a new method, Scheduler#isStarted().

This change affects scheduler instances coming from both the quarkus-scheduler and quarkus-quartz extensions.

Starting in Red Hat build of Quarkus 3.20, when you use development and test modes, the management interface listens on the localhost interface by default instead of on 0.0.0.0. This change aligns with the behavior of the main interface.

On Windows with Windows Subsystem for Linux (WSL), both the management and main interfaces continue to listen on 0.0.0.0.

For more information, see the Quarkus Management interface reference guide.

In Red Hat build of Quarkus 3.20, configuration has migrated to the @ConfigMapping framework. This change deprecates the legacy configuration classes in favor of a unified configuration model based on interfaces and method signatures.

A compatibility layer remains in place for certain commonly used configuration classes, but it is planned for removal in a future release.

Starting in Red Hat build of Quarkus 3.20, Red Hat builder and runtime base images are upgraded to use Red Hat Universal Base Image 9 (UBI 9).

When upgrading from UBI 8 to UBI 9, be aware that changes in system dependencies, native image builds, or package and GNU C Library (glibc) version updates might affect your application’s behavior or runtime environment. Review and update your configurations as needed.

If you encounter issues with UBI 9, you can manually switch back to using UBI 8:

For more information, see the following resources:

In earlier versions of Red Hat build of Quarkus, when Dev Services were disabled or running in production mode, the quarkus.datasource.reactive.url and quarkus.datasource.<datasource-name>.reactive.url properties were implicitly set to an undocumented default, targeting localhost with a database-specific port.

Starting in Red Hat build of Quarkus 3.20, these properties no longer have a default value when Dev Services are disabled or the application is running in production mode. If the property is not set, the corresponding datasource is deactivated. If the application attempts to use a deactivated datasource, it will fail at startup. For details, see the Datasource usage fails fast if datasource is deactivated or has no URL set release note.

If your application requires an active datasource and you want it to connect to a database on localhost, you must now set the quarkus.datasource.reactive.url or quarkus.datasource.<datasource-name>.reactive.url property explicitly. For example:

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

In earlier versions, this configuration was set implicitly. Starting with this release, you must define the URL to activate the datasource.

Previously, when Dev Services were disabled or in production mode, Red Hat build of Quarkus contributed a health check for datasources even if quarkus.datasource.jdbc.url, quarkus.datasource.<datasource-name>.jdbc.url, quarkus.datasource.reactive.url, or quarkus.datasource.<datasource-name>.reactive.url properties were not set. This caused unreliable health checks that always succeeded for JDBC datasources and almost always failed for reactive datasources.

Starting with Red Hat build of Quarkus 3.20, datasources without a URL no longer contribute a health check. To ensure a health check is available, explicitly set the quarkus.datasource.jdbc.url, quarkus.datasource.<datasource-name>.jdbc.url, quarkus.datasource.reactive.url, or quarkus.datasource.<datasource-name>.reactive.url property.

In Red Hat build of Quarkus 3.20, applications start successfully even if a datasource is deactivated with quarkus.datasource.active=false or lacks a URL. This behavior often leads to runtime failures when the datasource is first accessed, especially when Dev Services are disabled or in production mode.

With this update, applications fail to start if Red Hat build of Quarkus detects that a datasource is used but is either deactivated or missing a URL.

Red Hat build of Quarkus now enforces stricter validation during startup to catch these issues early:

The same validation applies to the Flyway and Liquibase extensions for their Flyway and LiquibaseFactory CDI beans.

In Red Hat build of Quarkus 3.20, the quarkus-flyway extension upgrades Flyway to version 11, which removes the cleanOnValidationError configuration parameter. Additionally, calling Flyway.validate() no longer cleans on validation error.

To mitigate this change, Red Hat build of Quarkus 3.20 introduces the quarkus.flyway.validate-at-start.clean-on-validation-error configuration property, which provides behavior similar to cleanOnValidationError, but applies only when the application starts.

Workaround: If you require the previous behavior of cleanOnValidationError in explicit calls to Flyway.validate(), consider catching validation errors in your application and triggering a database cleanup explicitly using Flyway.clean().

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

For more information, see the Quarkus Using Flyway guide.

In Red Hat build of Quarkus 3.20, the IBM Db2 driver and container image that Dev Services uses have been upgraded to version 12.

The automated update described in the Migrating applications to Red Hat build of Quarkus 3.20 guide upgrades the IBM Db2 driver and container image to version 12.

Review the new license requirements, configuration steps, and SSL/TLS settings detailed on IBM’s Features with behavior changes when upgrading to the Db2 Connect 12.1 driver for upgrading to Db2 Connect 12.1.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

In Red Hat build of Quarkus 3.20, the default behavior of Hibernate ORM’s Bean Validation integration has changed. Previously, validation constraints were not considered during Data Definition Language (DDL) generation. With this release, Hibernate ORM includes applicable validation constraints in DDL by default, ensuring that database schemas align more closely with application-level constraints.

The quarkus.hibernate-orm.validation.enabled property has also been deprecated.

For more information about these changes and guidance on migrating your application, see the Migration Guide 3.19, or the following resources:

In Red Hat build of Quarkus 3.20, the quarkus.log.*.json configuration property has been deprecated. To enable JSON formatting for logging, use the quarkus.log.*.json.enabled property instead.

This change was introduced to improve compatibility with YAML configuration, where the previous structure required using special syntax such as ~ to assign a value to the root key, leading to confusing or error-prone setups.

For more information, see the Migration Guide 3.19.

In Red Hat build of Quarkus 3.20, the quarkus-opentelemetry extension introduces breaking changes because some database incubating values, such as those related to Redis, were moved to a different package.

OpenTelemetry does not maintain a list of changes for database semantic conventions because they are not yet stable.

This change might require manual intervention, if you use manual instrumentation. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

In Red Hat build of Quarkus 3.20, the previously deprecated quarkus-smallrye-opentracing extension and related configuration property quarkus.datasource.jdbc.tracing have been removed.

The quarkus-opentelemetry extension is now the preferred tracing solution. To enable JDBC tracing with OpenTelemetry, use the following configuration property:

quarkus.datasource.jdbc.telemetry=true

quarkus.datasource.jdbc.telemetry=true

To migrate, replace the OpenTracing extension with OpenTelemetry and update your configuration accordingly.

Starting in Red Hat build of Quarkus 3.20, if you use the quarkus-oidc-client extension but do not configure the OpenID Connect (OIDC) client to point to a specific URL, Dev Services for Keycloak automatically starts in dev mode.

To disable this behavior, add the following property to your application.properties file:

quarkus.keycloak.devservices.enabled=false

quarkus.keycloak.devservices.enabled=false

In Red Hat build of Quarkus 3.20, the quarkus-security-webauthn extension has been reimplemented by using WebAuthn4J to enhance security, align with industry standards, and improve long-term maintainability.

As a result, this update is not compatible with previous versions of the extension.

To transition smoothly to the new implementation, use the following information.

The status of this feature is downgraded from preview to experimental to allow for further stabilization.

For more information, see the Quarkus Using Security with WebAuthn guide.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

Earlier, Red Hat build of Quarkus 3.15 shipped with a version of @WithTestResource that was flawed and was thus not announced.

In Red Hat build of Quarkus 3.20, the flaws have been fixed, resulting in a breaking change. In this release, the earlier restrictToAnnotatedClass field has been replaced by scope.

In earlier releases, the quarkus-junit5-mockito dependency was configured to create mock objects by using the subclass mocking strategy.

Starting in Red Hat build of Quarkus 3.20, the dependency is now configured to use an inline mocking strategy by default.

In Red Hat build of Quarkus 3.20.0, the quarkus-junit5-mockito dependency was temporarily non-functional due to an intentional mismatch in its dependency versions. The version of Mockito in use required JUnit 5.11 or later, but the platform included JUnit 5.10.

To resolve the issue, Red Hat build of Quarkus 3.20.1 upgrades JUnit to version 5.12.1. This update aligns the versions of JUnit and Mockito and restores compatibility for the quarkus-junit5-mockito dependency.

The impact of this update is expected to be minimal. Testing in the community and Camel Quarkus has not revealed any regressions. For more information, see the related issue: https://github.com/quarkusio/quarkus/issues/46858.

To ensure consistent alignment across all JUnit artifacts, import the JUnit BOM version used in 3.20.0 as shown:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

If HTTP compression is enabled, the quarkus.http.compress-media-types configuration property defines the list of media types to compress. In Red Hat build of Quarkus 3.20, the default value of this property has changed. Newly compressed media types now include application/json and application/xhtml+xml.

In Red Hat build of Quarkus 3.20, the REST Client Configuration became more strict to reduce the number of lookups and combinations required to retrieve the configuration:

Starting in Red Hat build of Quarkus 3.20, the quarkus-qute extension automatically escapes double quotes ("), backslashes (\), and control characters (U+0000 through U+001F) in JSON templates if a corresponding template variant is set. The extension automatically assigns a variant to templates located in the src/main/resources/templates directory.

By default, java.net.URLConnection#getFileNameMap() determines the content type of a template file. You can define additional suffix-to-content-type mappings by using the quarkus.qute.content-types configuration.

To render the unescaped value, use the raw or safe properties, which are implemented as extension methods of java.lang.Object, or wrap the string value in the io.quarkus.qute.RawString class.

For more information, see the Character escapes section of the Quarkus "Qute reference" guide.

In Red Hat build of Quarkus 3.20, with the quarkus-rest-jackson extension, only ObjectMapperCustomizer beans without qualifiers are applied to the default ObjectMapper instance of the Jackson JSON processor.

In earlier versions, all customizer beans, including those with custom qualifiers, were applied to the default ObjectMapper instance.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

For more information, see the following resources:

In earlier releases, with the quarkus-rest extension, query parameters with empty values, such as ?foo=, were deserialized as follows:

In Red Hat build of Quarkus 3.20, this behavior has changed:

Update your code accordingly.

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.

Red Hat build of Quarkus 3.20 deprecates the quarkus-websockets and quarkus-websockets-client extensions, which implement the Jakarta WebSocket specification.

Red Hat build of Quarkus plans to stop supporting these extensions in a future release.

To ensure compatibility with upcoming versions, migrate to the Quarkus WebSockets Next extension,quarkus-websockets-next, which offers a modern, more efficient WebSocket API.

For more information, see the following Quarkus resources:

This change requires manual intervention. It is not included in the automated update process described in the Migrating applications to Red Hat build of Quarkus 3.20 guide.