-
Notifications
You must be signed in to change notification settings - Fork 2.7k
Migration Guide 2.6
Once upon a time, Quarkus was a young project and we didn't have a lot of infrastructure around it to host extensions. Thus all the extensions created then ended up in the main repository (called Core).
Since then, we have invested a lot in setting up the Quarkiverse Hub infrastructure which allows easy collaboration on extensions that live outside of the Core repository.
The Core repository is very large now and we have started moving extensions outside of it to make it smaller (easier to import in IDEs, faster local builds, shorter CI runs...) and also to lower the barrier to entry to contribute to these extensions: they are in small independent projects, far easier to build and contribute to.
For all these extensions, we have put in place relocations so migration should be seamless but in any case you need to adjust your project for the future. If you are using one of these moved out extensions, you will see a warning when building your project instructing you how to fix the issue.
If you are a user of these extensions, have a look at their respective project and don't hesitate to contribute to them and provide feedback.
These moved out extensions are not handled the same and there are three categories.
These extensions are not in the Quarkus Platform BOM anymore and you need to define the version yourself in your build file:
⚠️ if you are using theorg.apache.activemq:artemis-serverororg.apache.activemq:artemis-amqp-protocoldependencies for your Artemis testing without defining a version, you will have build errors (their versions used to be defined in the Quarkus BOM but they have been removed from there). To solve this issue, you can importio.quarkiverse.artemis:quarkus-artemis-bom:1.0.2as a BOM in your project. It will define the versions of these dependencies.
These extensions have been included into the Platform BOM so if you are using the io.quarkus.platform:quarkus-bom BOM, you don't need to set the version but you still need to change the groupId.
| Component | New groupId | New artifactId | Current version | Repository |
|---|---|---|---|---|
| Consul Config | io.quarkiverse.config |
quarkus-config-consul |
1.0.1 |
https://github.com/quarkiverse/quarkus-config-extensions |
| Vault | io.quarkiverse.vault |
same | 1.0.1 |
https://github.com/quarkiverse/quarkus-vault |
⚠️ The artifactId for the Consul Config extension has changed fromquarkus-consul-configtoquarkus-config-consulto be more consistent with the other Config extensions.
These extensions have their own specific BOM in the Quarkus Platform. If you want to use them, you need to add it to your project.
| Component | New groupId | BOM | Repository |
|---|---|---|---|
| Amazon Services | io.quarkiverse.amazonservices |
io.quarkus.platform:quarkus-amazon-services-bom:your quarkus version
|
https://github.com/quarkiverse/quarkus-amazon-services |
ℹ️ The Amazon Services extensions are the extensions connecting to AWS services such as DynamoDB, IAM, S3...
The SQL Server integration was moved to a separate dependency. See https://flywaydb.org/documentation/database/sqlserver#java-usage. SQL Server users need to add the following dependency from now on:
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-sqlserver</artifactId>
</dependency>Deprecated OIDC TokenConfigResolver and TokenStateManager methods, quarkus.oidc.authentication.auto-refresh-timeout property removed
OIDC TokenConfigResolver methods deprecated in 2.2 and TokenStateManager methods deprecated in 2.3 have now been removed.
It should have a minimum impact if any at all since only TokenConfigResolver and TokenStateManager methods returning Uni can work without blocking the IO thread and thus should be used in the real world applications.
A long time deprecated quarkus.oidc.authentication.auto-refresh-timeout property has also been removed - please use a better named quarkus.oidc.authentication.refresh-token-time-skew from now on.
The way a Vert.x RoutingContext can be accessed in the custom OIDC SecurityIdentityAugmentors has changed.
If it is required then please access it as a SecurityIdentity attribute which will be more portable:
import javax.enterprise.context.ApplicationScoped;
import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.SecurityIdentityAugmentor;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import io.smallrye.mutiny.Uni;
import io.vertx.ext.web.RoutingContext;
@ApplicationScoped
public class CustomOidcSecurityIdentityAugmentor implements SecurityIdentityAugmentor {
@Override
public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
// Instead of
// IdTokenCredential cred = identity.getCredential(IdTokenCredential.class);
// RoutingContext context = cred.getRoutingContext();
RoutingContext context = identity.getAttribute(RoutingContext.class.getName());
QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder(identity);
// Use RoutingContext as required
return Uni.createFrom().item(builder.build);
}
}
The old way of accessing RoutingContext as an OIDC IdTokenCredential or AccessTokenCredential property prevents the use of OIDC tokens for running the background tasks when no RoutingContext is available.
The produces attribute of the @Route annotation was only used for content negotiation.
Starting Quarkus 2.6, it is also used to indicate how Multi instances need to be serialized in the HTTP response.
When a route returns a Multi<T>, it can:
- send the item one by one, without any modification (raw stream)
- wrap the
Multias a JSON Array, where each item is sent one by one - produce a server-sent-event stream
- produce JSON (also named ND-JSON) stream
Before Quarkus 2.6, to express the three last possibilities you had to wrap the produced Multi using ReactiveRoutes.asJsonArray, ReactiveRoutes.asEventStream and ReactiveRoutes.asJsonStream. Unfortunately, this approach does not work when Quarkus security is enabled.
To work around that problem, starting Quarkus 2.6, you can indicate the serialization you need using the produces attribute of @Route. If the first value of the produces array is application/json, text/event-stream, application/x-ndjson (or application/stream+json), the associated serialization is used.
So, instead of:
- returning
ReactiveRoutes.asJsonArray(multi), returnmultidirectly and setproduces="application/json" - returning
ReactiveRoutes.asEventStream(multi), returnmultidirectly and setproduces="text/event-stream" - returning
ReactiveRoutes.asJsonStream(multi), returnmultidirectly and setproduces="application/x-ndjson"
The format of a JSON response produced when a constraint violation occurs was changed in an incompatible way.
If a parameter of a reactive route method violates the rules defined by Bean Validation then an HTTP 400 response is produced.
And if the request accepts the JSON payload then the response should follow the Problem format.
However, prior to version 2.6 the produced JSON included an incorrect property: details.
The payload now follows the format, i.e. the property is called detail.
The native image builders ubi-quarkus-native-image and ubi-quarkus-mandrel are now based on ubi-micro:8.5 (instead of ubi-micro:8.4).
In addition, both images provide the upx tool which can be used to compress native executable.
gRPC metrics are now handled by the quarkus-micrometer extension.
gRPC server and clients metrics are automatically enabled when your application depends on the quarkus-micrometer extension.
In the case you do not want to collect these metrics, you can disable them using:
quarkus.micrometer.binder.grpc-client.enabled=false
quarkus.micrometer.binder.grpc-server.enabled=falseThe quarkus.grpc.metrics.enabled property has no effect anymore.
Global gRPC client interceptors must be annotated with @io.quarkus.grpc.GlobalInterceptor since 2.6.
Prior to Quarkus 2.6, all the CDI beans implementing io.grpc.ClientInterceptor were considered global interceptors, i.e. applied to all injected gRPC clients. Since 2.6, it is possible to make a client-specific interceptor, by annotating the injection point of a gRPC client with the @io.quarkus.grpc.RegisterClientInterceptor annotation.
To avoid having a split package between the smallrye-reactive-messaging-api and smallrye-reactive-messaging-provider, the classes from io.smallrye.reactive.messaging from the smallrye-reactive-messasing-provider have been moved to io.smallrye.reactive.messaging.provider. These classes are internal / implementation-specific classes and should not have been used directly.