Upgrade from 2.x to 3.x

Dubbo 3 Upgrade and Compatibility Guide

Benefits of Upgrading to Dubbo 3.X

Dubbo 3 maintains the classic architecture of 2.x, focusing on inter-process communication for microservices and providing rich service governance capabilities (such as address discovery, traffic management, etc.) to better manage microservice clusters. The upgrade of Dubbo3 comprehensively enhances stability, performance, scalability, and usability throughout core Dubbo features.

architecture-1

  • Universal communication protocol. The new RPC protocol discards proprietary protocol stacks in favor of the more universal HTTP/2, leveraging the standardized features of the HTTP protocol to address issues like traffic generality and penetration, better adapting to scenarios like front-end and back-end interfacing and gateway proxies; it supports Stream communication modes, achieving greater throughput for clusters while meeting different business communication model demands.
  • Highly scalable for millions of cluster instances. With the promotion of microservice practices, the scale of microservice cluster instances is constantly expanding, benefiting from the lightweight nature and horizontal scalability of microservices, but also placing a burden on overall cluster capacity, especially for centralized service governance components; Dubbo 3 needs to address resource bottleneck issues arising from instance scale expansion, achieving truly infinite horizontal scalability.
  • Full embrace of cloud-native.

New Features in Dubbo 3.0

New features in Dubbo 3.0 include:

Compatibility Check Before Upgrade

During the cross-version upgrade process, the risk points from greatest to least are: directly modifying Dubbo source code -> extending based on Dubbo SPI extension points -> using APIs or Spring.

1. Direct Modification of Dubbo Source Code

For direct modifications to the Dubbo source code, it is up to the modifying party to determine if it functions correctly in the higher version; Dubbo cannot guarantee previous compatibility for these non-standard behaviors. Additionally, modifications made to Dubbo at runtime via javagent or asm also fall within this scope. Most of these modifications can be detected using the scanning tools provided later.

2. SPI Extensions

Incompatibilities

For SPI extensions, except for the destructive changes to application-level service direction and EventDispatcher mechanisms in 3.x, most extensions provided in 2.7.x are also available in 3.x. Areas of concern include:

  • Event Bus: Due to the complexity of event management, support for EventDispatcher and EventListener has been removed in Dubbo 3.x. If there are corresponding extension mechanisms in use, consider refactoring them to match the corresponding Dubbo features.
  • Application-level service discovery: The overall mechanism for application-level service discovery in Dubbo 2.7 has been completely restructured in Dubbo 3.x, significantly improving performance and stability. Therefore, we recommend not using the application-level service discovery mechanism from Dubbo 2.7; if there are corresponding extensions, you can validate and implement them based on the new code after upgrading to Dubbo 3.x (most application-level service discovery APIs are forward compatible).

Optimizations (Optional)

In addition, Dubbo 3.x has optimized the working mechanisms of certain extension points, which can significantly enhance application performance.

    1. Interceptor mechanism In Dubbo, requests can be intercepted using the Filter interceptor. In Dubbo 2.7, interception occurs after routing selection. Dubbo 3.x abstracts a new ClusterFilter mechanism, significantly reducing memory usage, which is beneficial for large-scale clusters. If you have some Consumer-side interceptors based on the Filter mechanism without strong binding to remote IP addresses, we recommend migrating the corresponding org.apache.dubbo.rpc.Filter SPI extension point to the new org.apache.dubbo.rpc.cluster.filter.ClusterFilter SPI extension point. The method definitions of the two interfaces are identical.
    1. Router -> StateRouter Dubbo offers Router capabilities for dynamic routing, and most service governance capabilities are implemented based on this Router extension point. In Dubbo 3.x, Dubbo has abstracted a new StateRouter mechanism based on Router, greatly optimizing routing performance and memory usage. More information about StateRouter will be released in subsequent documentation.

3. API / Spring Usage

For API or Spring usage, the methods used in Dubbo 3.x and 2.7.x are aligned, and Dubbo 3.x has strong validation for invalid configurations; errors in this regard will be reported during startup, and adjustments should be made as prompted.

Upgrade Process

1. Dependency Upgrade

If using Nacos as the registry center, due to the supported features of Nacos, Nacos Server must be upgraded to 2.x before upgrading to Dubbo 3.x (refer to https://nacos.io/zh-cn/docs/v2/upgrading/2.0.0-upgrading.html), and then upgrade the application’s Nacos Client accordingly. If using Zookeeper as the registry center, no action is required. If you are using Spring Cloud Alibaba Dubbo, please upgrade to xxx due to changes in some internal Dubbo APIs.

Please upgrade Dubbo dependencies to the latest version 3.1.3, with the following GAV for Dubbo and the corresponding springboot starter.

  1. <dependency>
  2.   <groupId>org.apache.dubbo</groupId>
  3.   <artifactId>dubbo</artifactId>
  4.   <version>3.1.3</version>
  5. </dependency>
  7. <dependency>
  8.   <groupId>org.apache.dubbo</groupId>
  9.   <artifactId>dubbo-spring-boot-starter</artifactId>
  10.   <version>3.1.3</version>
  11. </dependency>

2. Grayscale Upgrade

The upgrade to Dubbo 3 does not impose special restrictions on the release process; it can be done according to normal business releases. Since Dubbo undergoes cross-major version changes, please perform multiple phased releases and extend the time gap between the first and second batch of releases to allow for thorough observation. During the release process, we recommend upgrading the downstream applications (i.e., service providers) first and continue subsequent releases after verifying normal service handling.

3. Upgrade Observation Metrics

During the release process, there are several dimensions of metrics to assess whether issues occur during the upgrade.

  • CPU and memory usage on the machines
  • Interface request success rate
  • Interface request RT
  • Error messages in the logs
  • Whether custom extension behaviors meet expectations

Notes

1. Application-level Service Discovery

Due to design issues with the application-level service discovery model in Dubbo 2.7, there have been significant format changes in Dubbo 3.x, which may cause incompatibility between application-level service discovery in 2.7.x and 3.x. Although Dubbo will filter out unrecognizable instances, for stability’s sake, if you have enabled the application-level service discovery feature in 2.7.x (which is non-default registered in 2.7.x), we recommend disabling it in 2.7.x and re-enabling it after upgrading to 3.x.

Feedback

Was this page helpful?

Yes No

Last modified September 30, 2024: Update & Translate Overview Docs (#3040) (d37ebceaea7)