2.x to 3.x Operation Guide
Benefits of upgrading to Dubbo 3.X
Dubbo3 still maintains the classic architecture of 2.x. Its main responsibility is to solve the communication between microservice processes, and to better manage and control microservice clusters through rich service governance (such as address discovery, traffic management, etc.); The upgrade of the framework is comprehensive, reflected in almost every aspect of the core Dubbo features, through the upgrade to achieve a comprehensive improvement in stability, performance, scalability, and ease of use.
- **Universal communication protocol. ** The new RPC protocol should abandon the private protocol stack, use the more general HTTP/2 protocol as the transport layer carrier, and use the standardized features of the HTTP protocol to solve the problems of traffic versatility and penetration, so that the protocol can better respond Scenarios such as front-end and back-end docking, gateway proxy, etc.; supports the Stream communication mode, which meets the demands of different business communication models and brings greater throughput to the cluster.
- **For millions of cluster instances, the cluster is highly scalable. ** With the promotion of micro-service practices, the scale of micro-service cluster instances is also constantly expanding, which benefits from the characteristics of light-weight micro-services and easy horizontal expansion, but also brings a burden to the entire cluster capacity, especially It is some centralized service governance components; Dubbo3 needs to solve various resource bottlenecks caused by the expansion of instance scale, and realize truly unlimited horizontal expansion.
- **Comprehensively embrace cloud native. **
Dubbo 3.0 new features
The new features provided by Dubbo 3.0 include:
- ** New address discovery model (application-level service discovery). **
- **The next generation of the HTTP/2-based Triple protocol. **
- **Unified routing rules. **
Compatibility check before upgrade
In the process of cross-version upgrade, the existing risks are from big to small: directly modify Dubbo source code -> expand based on Dubbo SPI extension points -> use methods based on API or Spring.
1. Directly modify Dubbo source code
For those who need to directly modify this part of Dubbo source code, the modifying party must judge whether it works normally in the higher version. For this non-standard behavior, Dubbo cannot guarantee its previous compatibility. In addition, the modification of Dubbo at runtime through javagent or asm is also within this scope. Most of these modifications can be detected by the scanning tools provided below.
2. SPI extension
Incompatibilities
For SPI extensions, except that the two mechanisms of application-level service direction and EventDispatcher have been destructively modified in 3.x, most of the extensions provided in 2.7.x are also provided in 3.x. There are two areas to focus on in this section:
- Event bus: Due to the complexity of event management, the support of EventDispatcher and EventListener in Dubbo 3.x has been removed. If there is a use of the corresponding extension mechanism, please consider refactoring to an extension corresponding to the Dubbo function.
- Application-level service discovery: The overall mechanism of application-level service discovery in Dubbo 2.7 has been completely refactored in Dubbo 3.x, and the performance and stability of functions have been greatly improved. Therefore, we recommend that you do not use the application-level service discovery mechanism in Dubbo 2.7. If there is a corresponding extension, you can re-verify the implementation based on the new code after upgrading to Dubbo 3.x (most APIs for application-level service discovery are forward Compatible).
Optimization items (optional)
In addition, Dubbo 3.x has optimized the working mechanism of some extension points, which can greatly improve the performance of the application.
- Interceptor mechanism
Dubbo can intercept requests based on Filter interceptors. In Dubbo 2.7, it is supported to intercept the request after the routing address is selected. In Dubbo 3.x, a new ClusterFilter mechanism is abstracted, which can greatly reduce the memory usage, and has great benefits for ultra-large-scale clusters.
If you have some interceptors on the consumer side that are implemented based on the Filter mechanism, and if there is no logic that is strongly bound to the remote IP address, we recommend that you add the corresponding org.apache.dubbo.rpc.Filter SPI extension point Migrated to the new SPI extension point org.apache.dubbo.rpc.cluster.filter.ClusterFilter. The method definitions of the two interfaces are exactly the same.
- Router -> StateRouter
Dubbo provides Router, the ability to dynamically select and route, and most of the service governance capabilities are also implemented based on this Router extension point. In Dubbo 3.x, Dubbo abstracts a new StateRouter mechanism based on Router, which can greatly optimize address selection performance and memory usage. We will publish more about StateRouter in subsequent documents.
3. API / Spring usage
For the use based on API or Spring, Dubbo 3.x and 2.7.x are used in the same way. In Dubbo 3.x, some invalid configurations are strongly checked, and this part of the exception will directly report an error during the startup process. , please follow the prompts to modify.
Upgrade process
1. Dependency upgrade
If you use Nacos as the registration center, due to the support of Nacos features, you need to upgrade Nacos Server to 2.x before upgrading to Dubbo 3.x (refer to the document https://nacos.io/zh-cn/docs/v2 /upgrading/2.0.0-upgrading.html), and then upgrade the Nacos Client of the application . No processing is required if using a Zookeeper registry. If you are using Spring Cloud Alibaba Dubbo for access, please upgrade to xxx due to changes in some internal APIs of Dubbo.
Please upgrade to the latest version 3.1.3 for Dubbo dependencies. Dubbo and the corresponding springboot starter GAV are as follows.
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo</artifactId>
<version>3.1.3</version>
</dependency>
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-spring-boot-starter</artifactId>
<version>3.1.3</version>
</dependency>
2. Gray scale upgrade
The Dubbo 3 upgrade has no special restrictions on the release process, and it can be released according to normal business. Since Dubbo is undergoing changes and upgrades across major versions, please release as many batches as possible during the release, and at the same time increase the time interval between the first batch and the second batch of releases, and make sufficient observations. During the publishing process, we recommend that you first upgrade the downstream of the application (that is, the service provider), and then proceed with subsequent publishing after verifying that the service is processed normally.
3. Upgrade observation indicators
During the release process, there are the following latitude indicators to judge whether there is a problem with the upgrade.
- CPU, memory usage of the machine
- Interface request success rate
- Interface Request RT
- Log error message
- Does the custom extension behave as expected
Precautions
1. Application-level service discovery
Due to design problems in the application-level service discovery model of Dubbo 2.7, a large number of format changes have been made in Dubbo 3.x, so the application-level service discovery of 2.7.x and 3.x may not be able to subscribe to each other. sex. Although Dubbo will eliminate unrecognized instances, from the perspective of stability, if you enable the application-level service discovery feature in 2.7.x (not registered by default in 2.7.x), we recommend first Turn it off, and turn it on again after upgrading to 3.x.