Skip to content

Migration Guide 3.18

Jump to bottom
Guillaume Smet edited this page Feb 8, 2025 · 19 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.

Management interface

In dev and test mode, the management interface will now listen on the localhost interface by default (instead of 0.0.0.0) to be made consistent with the behavior of the main interface.

Note that similarly to what has been done for the main interface, on Windows with WSL, it will continue to listen to 0.0.0.0.

Qute

Character Escapes

For JSON templates the ", \ and the control characters (U+0000 through U+001F) are escaped by default if a corresponding template variant is set. In Quarkus, a variant is set automatically for templates located in the src/main/resources/templates. By default, the java.net.URLConnection#getFileNameMap() is used to determine the content-type of a template file. The additional map of suffixes to content types can be set via quarkus.qute.content-types. If you need to render the unescaped value use the raw or safe properties implemented as extension methods of the java.lang.Object, or wrap the String value in a io.quarkus.qute.RawString.

SmallRye Fault Tolerance

This release of Quarkus includes SmallRye Fault Tolerance 6.7.0. This version technically does not contain any breaking changes, but:

  • The first version of the programmatic API (FaultTolerance, @ApplyFaultTolerance) is deprecated and will be removed in SmallRye Fault Tolerance 7.0. The second version (Guard, TypedGuard, @ApplyGuard) is relatively similar, but there are still significant differences.

  • The specification-defined configuration properties can still be used, but there are Quarkus-native configuration properties now.

See the SmallRye Fault Tolerance 6.7.0 release announcement (https://smallrye.io/blog/fault-tolerance-6-7-0/) for more information, including links to the migration guides for the programmatic API and a description of the new configuration properties. The Quarkus guide for SmallRye Fault Tolerance includes a full reference of the new configuration properties as well.

Quarkus REST

Empty query parameter values of type String

Query parameters set to an empty value (for example: ?foo=) used to produce an empty String value ("") when deserialised as @RestQuery String foo or a collection of size one with an empty string value when deserialised as @RestQuery List<String> foo.

This has been changed in https://github.com/quarkusio/quarkus/pull/42468#issuecomment-2302312141 to produce a null value when deserialised as @RestQuery String foo and an empty collection when deserialised as @RestQuery List<String> foo.

Flyway

cleanOnValidationError configuration removed

This release is now updated to Flyway 11, which removes the cleanOnValidationError configuration.

The Quarkus team initially decided to delete the configuration instead of deprecating it, but in 3.18.2, we introduced quarkus.flyway.validate-at-start.clean-on-validation-error which allows to get a similar behavior (implemented in Quarkus itself) but only for validate-at-start.

Jackson

With Quarkus 3.18, only ObjectMapperCustomizer beans that don’t use any qualifiers are applied to the default ObjectMapper Quarkus creates. Previously all customizers beans - even ones with custom qualifers - were applied to the default ObjectMapper.

Kubernetes Client (Fabric8)

This release includes the version upgrade for the Fabric8 Kubernetes Client from version 6.13 to version 7.0.

The client is used and exposed by the quarkus-kubernetes-client and quarkus-openshift-client extensions. And by the quarkus-kubernetes and quarkus-openshift extensions, however, for these no changes should be required.

The complete and original upstream migration guide can be found at fabric8io/kubernetes-client/doc/MIGRATION-v7.md.

With respect to Quarkus, the most important change is the removal of the io.quarkus:quarkus-test-openshift-client module. You should use instead the standard io.quarkus:quarkus-test-kubernetes-client which provides the same functionality. Please check the guide for additional information.

Additionally, some of the model classes have moved to different modules. Make sure to check the migration guide to locate the new module in case a class is no longer found.

WebAuthn

The quarkus-security-webauthn module has been reimplemented on top of WebAuthn4J. As a result, it is not binary or source compatible with the previous versions, and you must update the following code:

  • All userName references have been replaced with username

  • The Authenticator type

    • The Authenticator class (from Vert.x) is no longer used, and has been replaced functionally with WebAuthnCredentialRecord. It holds similar data to the previous class, but as it is a subtype of a WebAuthn4J type, accessing its content is slightly different.

    • Its replacing type WebAuthnCredentialRecord now has a getRequiredPersistedData() method which returns a RequiredPersistedData record holding all the data you need to persist to your data source (database, or anything persistent), to make it easier.

    • The static method WebAuthnCredentialRecord.fromRequiredPersistedData(RequiredPersistedData) allows you to turn your stored data into a WebAuthnCredentialRecord for the opposite operation.

    • If you had any JPA entities or database tables storing the old Authenticator format of data, you will need to update them to the new set of data. Open an issue if you need help for that.

  • The WebAuthnUserProvider type that you had to implement has been restructured:

    • findWebAuthnCredentialsByUserName() was renamed to findByUsername()

    • findWebAuthnCredentialsByCredID() was renamed to findByCredentialId()

    • updateOrStoreWebAuthnCredentials was split into the two methods it represented: update(String credentialId, long counter) and store(WebAuthnCredentialRecord credentialRecord)

  • Default endpoints:

    • /q/webauthn/login was renamed to /q/webauthn/login-options-challenge

    • /q/webauthn/register was renamed to /q/webauthn/register-options-challenge

    • /q/webauthn/callback was split into the two operations it represented: /q/webauthn/login and /q/webauthn/register. These endpoints are now disabled by default (for security reasons) and can be enabled using the quarkus.webauthn.enable-registration-endpoint and quarkus.webauthn.enable-login-endpoint configuration properties.

    • /q/webauthn/register now requires a username query parameter.

    • /.well-known/webauthn was added to return the list of allowed related origins

    • The user name for login and login-options-challenge is now optional

    • The /q/webauthn/login-options-challenge and /q/webauthn/register endpoints moved from POST to GET methods and now take their parameters via query parameters instead of JSON bodies

  • WebAuthnSecurity

    • Two methods have been added to WebAuthnSecurity: getLoginOptionsChallenge() and getRegisterOptionsChallenge() to make it easier to call and customise them.

    • The user name parameter for login() and loginOptionsChallenge() is now optional

    • The register() method now takes an additional username parameter (due to the removal of the username cookie)

  • Configuration:

    • The quarkus.webauthn.require-resident-key (boolean defaulting to false) setting has been replaced by the quarkus.webauthn.resident-key (enum defaulting to REQUIRED)

    • The quarkus.webauthn.challenge-username-cookie-name setting has been removed along with its related cookie.

    • The quarkus.webauthn.load-metadata (boolean defaulting to false) setting has been added to control loading of FIDO metadata.

    • The quarkus.webauthn.user-presence-required (boolean defaulting to true) setting has been added to control the requirement of user presence.

    • The quarkus.webauthn.user-verification setting has changed default from DISCOURAGED to REQUIRED.

    • The quarkus.webauthn.timeout default has increased from 1 minute to 5 minutes as specified in the WebAuthn standard

    • The quarkus.webauthn.pub-key-cred-params setting has been renamed to quarkus.webauthn.public-key-credential-parameters

    • The quarkus.webauthn.origin setting has been renamed to quarkus.webauthn.origins (plural) and now allows more than one origin (as required by spec)

    • The new quarkus.webauthn.enable-registration-endpoint boolean configuration (defaults to false) enables the default registration endpoint.

    • The new quarkus.webauthn.enable-login-endpoint boolean configuration (defaults to false) enables the default login endpoint.

  • The verification of WebAuthn credential attestations may differ slightly for settings of quarkus.security.webauthn.attestation other than NONE (the default).

  • In the quarkus-test-security-webauthn test module:

    • The WebAuthnHardware contructor now requires a URL to represent the location of your endpoints, you can obtain in your test classes it using @TestHTTPResource URL url

    • The WebAuthnEndpointHelper.invokeRegistration method was renamed to obtainRegistrationChallenge

    • The WebAuthnEndpointHelper.invokeLogin method was renamed to obtainLoginChallenge

    • The WebAuthnEndpointHelper.invokeCallback method was split into the two operations it represented: WebAuthnEndpointHelper.invokeRegistration and WebAuthnEndpointHelper.invokeLogin

    • The WebAuthnEndpointHelper.invokeLogin and WebAuthnEndpointHelper.obtainLoginChallenge user name parameter is now optional

    • The WebAuthnEndpointHelper.invokeRegistration method now takes a username parameter

  • JavaScript library:

    • The registerOnly method has been renamed to registerClientSteps

    • The loginOnly method has been renamed to loginClientSteps

    • The login and loginClientSteps method’s user parameter is now optional

    • The constructor’s registerPath has been renamed to registerOptionsChallengePath and has the default value /q/webauthn/register-options-challenge

    • The constructor’s loginPath has been renamed to loginOptionsChallengePath and has the default value /q/webauthn/login-options-challenge

    • The constructor’s callbackPath has been split into its two components registerPath (default value /q/webauthn/register) and loginPath (default value /q/webauthn/login

    • The constructor now accepts a csrf option of type JsonObject with two keys: header for the header name to use to add the CSRF token, and value for the CSRF token value. This is mostly useful when using quarkus-csrf and using custom endpoints that are protected by CSRF (unlike the default endpoints).

We have also downgraded its status from preview to experimental to allow extra bake time with those changes.

Testing

Quarkus uses a specific JUnit ClassOrderer to reduce restarts of Quarkus, but it is also possible to set a custom one. In previous versions, to replace the Quarkus JUnit ClassOrderer it required excluding the dependency io.quarkus:quarkus-junit5-properties and setting one in junit-platform.properties. Now, to override the Quarkus JUnit ClassOrderer, set the FQCN in the configuration property quarkus.test.class-orderer in any configuration source. If the class cannot be found, it falls back to JUnit default behaviour, which does not set a ClassOrderer.

OpenTelemetry and Metrics

For a long time, the metrics and spans for non-application endpoints such as /q/arc/ or /q/openapi/ were reported without the /q prefix (e.g. /arc/ or openapi).

It has now been fixed and they are properly reported with the /q prefix.

Note that they will also be properly suppressed from the metrics and spans if the suppression of non application URLs is enabled (which is the default).

IBM Db2

The driver and container image (used for Dev Services) were upgraded to version 12.

It comes with some changes on how to register your license. See https://www.ibm.com/support/pages/features-behavior-change-while-upgrading-db2connect-121-driver for more information.

Migration guides

Current version

LTS versions

Next version in main

Clone this wiki locally