Chapter 4. Upgrading your applications from Red Hat build of Quarkus 1.7 to Red Hat build of Quarkus 1.11

This section provides an overview of breaking changes that you must address when you upgrade your applications from Red Hat build of Quarkus 1.7 to Red Hat build of Quarkus 1.11.

4.1. Change of configuration properties for the Quarkus Quartz extension

The release of Red Hat build of Quarkus 1.11 introduces several changes to the configuration properties available for the Quarkus Quartz extension.

New configuration properties introduced in Red Hat build of Quarkus 1.11

  • quarkus.quartz.cluster-checkin-interval
  • quarkus.quartz.instance-name
  • quarkus.quartz.start-mode

Configuration properties removed in Red Hat build of Quarkus 1.11

  • quarkus.quartz.force-start

Table 4.1. Configuration properties renamed in Red Hat build of Quarkus 1.11

Property name in Quarkus 1.7Property name in Quarkus 1.11

quarkus.quartz.triggerListener."namedTriggerListener".class

quarkus.quartz.trigger-listeners."listener-name".class

quarkus.quartz.triggerListener."namedTriggerListener"

quarkus.quartz.trigger-listeners."listener-name".properties

quarkus.quartz.jobListener."namedJobListener".class

quarkus.quartz.job-listeners."listener-name".class

quarkus.quartz.jobListener."namedJobListener"

quarkus.quartz.job-listeners."listener-name".properties

quarkus.quartz.plugin."namedPlugin".class

quarkus.quartz.plugins."plugin-name".class

quarkus.quartz.plugin."namedPlugin"

quarkus.quartz.plugins."plugin-name".properties

4.2. Change of naming strategy for Spring Boot configuration properties

In Red Hat build of Quarkus 1.11 the naming strategy used for Spring Boot configuration properties that contain a combination of uppercase and lowercase characters in Quarkus application is no longer set to verbatim.

Instead you can set the quarkus.arc.config-properties-default-naming-strategy property to one of the following values in the application.properties file of your project:

from-config
the naming convention is specified in your application configuration
verbatim
the name of the configuration property matches the name of the field or method to which the property applies
kebab
the name of the configuration property is uses lowercase characters with spaces replaced by hyphens. For example: application-name

If you do not set the quarkus.arc.config-properties-default-naming-strategy property for your application, kebab is used as the default value.

If you are using Spring Boot configuration properties that are formatted according to the verbatim naming strategy in your application, ensure that you make one of the following changes:

  • Set the value of the quarkus.arc.config-properties-default-naming-strategy to verbatim in the application.properties or application.yml file of your project. For example:

    application.properties

    quarkus.arc.config-properties-default-naming-strategy=verbatim

  • Convert then names of configuration properties that you use in application to match the kebab naming strategy.

4.3. Removal of support for the quarkus.datasource.url and quarkus.datasource.driver data source configuration properties

Red Hat build of Quarkus 1.11 no longer supports properties for configuring the connection URLs and drivers of data sources introduced in Red Hat build of Quarkus 1.3.

You must replace the unsupported configuration properties with properties compatible with Quarkus 1.11 to ensure that your data source configuration works properly when you upgrade your application to Quarkus 1.11.

See Configuring data sources in your Quarkus applications for details on how to configure your data sources in Quarkus 1.11 applications.

4.4. Change of default media type to JSON for Quarkus applications

Warning

This change might break the REST endpoints in your application when you upgrade your application from Red Hat build of Quarkus 1.7 to Red Hat build of Quarkus 1.11. Update the format of the return types used by your the REST endpoint in your application to ensure that your REST endpoints continue to work correctly after your upgrade your application.

In the Red Hat build of Quarkus 1.11 release, the default format for serializing application data is changed to JSON.

You can disable the default use of the JSON as content-type format for REST endpoints in your application, and use annotations to explictly enable the use of JSON only for interfaces that you want to use it for:

  1. Set the value of the quarkus.resteasy-json.default-json property to false in the application.properties file of your application.

    application.properties

    quarkus.resteasy-json.default-json=false

  2. Add the @Produces(MediaType.APPLICATION_JSON) and @Consumes(MediaType.APPLICATION_JSON) annotations to the REST endpoints of your applications for which you want to use JSON as the content type format.

4.5. The FAIL_ON_UNKNOWN_PROPERTIES feature is disabled in Jackson by default

In Red Hat build of Quarkus 1.11, Jackson is configured to ignore unknown properties by having the DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES disabled by default to avoid failures while attempting to deserialize JSON data objects containing properties not recognized by your application.

Set the value of the quarkus.jackson.fail-on-unknown-properties to true in the application.properties file of your application to enable the FAIL_ON_UNKNOWN_PROPERTIES feature. You must enable this feature separately for each class of your applications:

application.properties

<fully-qualified-class-name>.quarkus.jackson.fail-on-unknown-properties=true

See the Quarkus REST JSON extension guide for more details about using and customizing Jackson in your {PrductName} REST application.

4.6. Changes to configuring the minimum logging level at the DEBUG and TRACE levels

In Quarkus 1.11, you must set the minimum logging level when you configure your logger to log messages at the DEBUG and TRACE level. You must set the minimum log level before you start your application. If you do not set the minimum logging level in your logger configuration, messages at the DEBUG and TRACE log level will not appear in your log output. For example, if you configure your logger to log at TRACE level, you must minimum log level to TRACE. Otherwise, messages at TRACE level will not appear in your log output.

You can set the minimum log level for a specific category in the application.properties file of your application. application.properties. For example, to enable logging at the TRACE level for the io.quarkus.smallrye.jwt and io.undertow.request.security categories in your logger configuration, you can set the following properties

application.properties

quarkus.log.file.enable=true
# Send output to a trace.log file under the /tmp directory
quarkus.log.file.path=/tmp/trace.log
quarkus.log.file.level=TRACE
quarkus.log.file.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Set 2 categories (io.quarkus.smallrye.jwt, io.undertow.request.security) to TRACE level
quarkus.log.min-level=TRACE
quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE

4.7. Changes to the internal structure of the Red Hat build of Quarkus BOM

In Red Hat build of Quarkus 1.11, the com.redhat.quarkus:quarkus-universe-bom no longer directly contains the goupId, artifactID and version of all extensions and dependencies. Instead, the com.redhat.quarkus:quarkus-universe-bom imports the com.redhat.quarkus quarkus-product-bom that contains the dependency declarations for all Red Hat build of Quarkus extensions supported by Red Hat and the io.quarkus:quarkus-universe-bom that contains all the community Quarkus extensions.

This change does not impact the way that you can use the Red Hat build of Quarkus BOM in your Maven project. However, if you are using custom scripts to parse the BOM, you must update them to ensure that the parsing continues to work correctly after you upgrade your application to Red Hat build of Quarkus 1.11.

4.8. Change in REST endpoint path resolution

Warning

This change might break the REST endpoints in your application when you upgrade your application from Red Hat build of Quarkus 1.7 to Red Hat build of Quarkus 1.11. Ensure that you update your endpoint paths after migrating your application.

In Red Hat build of Quarkus 1.11, paths of application and non-application REST endpoints are resolved relative to the common absolute root path. The default common root path for REST endpoints is set to:

  • / for REST endpoints directly exposed by the main REST controller class of your application. You can change the default path for application endpoints by changing the value of the quarkus.http.root-path property in the application.properties file of your project.
  • q for REST endpoints for services provided by tools integrated with your application (for purposes such as application health monitoring or metrics collection). You can change the default path for application endpoints by changing the value of the quarkus.http.non-application-root-path property in the application.properties file of your project.

Note, that relative root paths are nested under the root path defined by the quarkus.http.root-path property. This means that, for example, if the root path defined in the quarkus.http.root-path property is set to /, and the root path for non-application endpoints defined by the quarkus.http.non-applicationroot-path property is set to q, the absolute endpoint path for the non-application endpoint is /q/<non-application-endpoint-name>.

However, you can also configure the paths of individual non-application endpoints explicitly to be located at /q/<non-application-endpoint-name>.

Because endpoint paths are interpreted as relative to the the root paths set by quarkus.http.root-path and quarkus.http.non-application-root-path you must exclude the leading slash (/) character from the custom paths and sub-paths that you configure for endpoints in your application.

For example, when you expose a metrics endpoint for Prometheus in a REST Controller your application, you must set the endpoint path in the @Path annotation to metrics to ensure that your endpoint is exposed at /q/metrics. Setting the same path value to /metrics exposes your metrics endpoint at /metrics.

Example of configuring non-application endpoints under a separate namespace

For example, you can set the following properties in the application.properties file of your project to expose a hello endpoint application at the /api root path, and the metrics endpoint at the /api/q path:

application.properties

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=q

In this configuration, both the /api/hello and the /api/q/metrics are public. This means that any user with the permission to access the /api/hello can also send a request to the /api/q/metrics endpoint and receive a valid response.

When you want to make the health endpoint non-public, you can set the root path for non-application endpoints in the application.properties to the /q namespace:

application.properties

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=/q

In this configuration, the /api/hello endpoint is public, but the /q/metrics is exposed in a separate namespace for which you can configure different access permissions.

In Red Hat build of Quarkus 1.11, requests sent to the original non-application endpoint paths are automatically redirected to the new paths in the /q namespace.

You can set the following attribute in the application.properties file of your project to disable the automatic redirection of non-application endpoint paths:

quarkus.http.redirect-to-non-application-root-path=false

You can switch your applications to using the absolute endpoint root path for all endpoints by setting the value of the quarkus.http.non-application-root-path to a variable that resolves to the value of the absolute application endpoint root:

quarkus.http.non-application-root-path=${quarkus.http.root-path}

4.9. Additional Configuration properties are required when processing ConfigMap objects for deploying REST application to Red Hat OpenShift Container Platform

Warning

This change might break the configuration that you use to deploy your applications to OpenShift when you upgrade your application from Red Hat build of Quarkus 1.7 to Red Hat build of Quarkus 1.11. You must update the applications.properties file of your application to ensure that configuration parameters provided in your ConfigMap are recognized by your application.

In Red Hat build of Quarkus 1.11, when you configure a Quarkus application based on Resteasy to Red Hat OpenShift Container Platform, and provide the configuration parameters for the application in a ConfigMap that is specified in the quarkus.openshift, you must also specify the quarkus.openshift.app-secret and quarkus-openshift.app-configmap properties in your application.properties file to ensure that your application recognizes and processes the ConfigMap.

  • Add the following properties in the application.properties file of your application to ensure that your application recognizes the ConfigMap:

    application.properties

    quarkus.openshift.app-secret=<secret-name>
    quarkus-openshift.app-configmap=<configmap-name>

    You must replace the <secret-name> with the name of the secret that you want to use, and you must replace <configmap-name> with the name of the ConfigMap that you want to use.