Upgrade to Triple Protocol

This document is suitable for users whose services are already running on the Dubbo protocol. Please first refer to the previous document How to Upgrade from Dubbo2 to Dubbo3 to complete the framework version upgrade, and then follow these steps for a smooth migration to the Triple protocol with minimal changes.

Here is the architecture diagram for the protocol upgrade, showing the states of different Dubbo applications during a smooth upgrade process:

In order, the basic upgrade steps are as follows:

1. Provider side configuration for dual-protocol (Dubbo, Triple) publishing on a single port
2. Provider side configuration to set the preferred protocol to Triple (at this time, the provider’s registered URL is dubbo://host:port/DemoService?preferred-protocol=tri)
3. Consumer upgrade, which can be done in two ways depending on the situation:
   • Upgrade the consumer to version 3.3, which will prioritize calling the Triple protocol based on preferred-protocol=tri
   • For consumer applications that cannot upgrade to version 3.3, configure @DubboReference(protocol="tri") to call the Triple protocol
4. Push all applications to upgrade to the latest Dubbo3 version so that all traffic uses the Triple protocol

Step 1: Dual-Protocol Publishing on the Provider Side

Assuming we have the following application configuration, which publishes the Dubbo protocol on port 20880:

dubbo:
  protocol:
    name: dubbo
    port: 20880

We need to add two configuration items as follows:

dubbo:
  protocol:
    name: dubbo
    port: 20880
    ext-protocol: tri
    preferred-protocol: tri

Where:

• ext-protocol: tri specifies that the Triple protocol is additionally published on the original port 20880, which is single-port dual-protocol publishing.
• preferred-protocol: tri will synchronize to the Consumer side with the registration center, informing the consumer to prioritize using the Triple protocol for calls.

Step 2: Switching Protocols on the Consumer Side

After the provider completes the configuration in Step 1 and restarts, the consumer may be in one of the following three states depending on version and configuration:

1. Consumer is version 3.3.0 or later

This type of consumer will automatically recognize the preferred-protocol: tri tag on the provider’s URL. If this tag is found, the consumer will automatically use the Triple protocol to call the service; otherwise, it will continue using the Dubbo protocol.

2. Consumer is version 2.x or earlier than 3.3.0

Due to the low version of the Dubbo framework being unable to recognize the preferred-protocol: tri parameter, these consumers are not affected by the provider’s multi-protocol publishing and will continue to call the Dubbo protocol.

3. Consumer is version 2.x or earlier than 3.3.0, but explicitly specifies the protocol to call

Similar to the second case, but users can explicitly specify which RPC protocol to use for certain services, such as:

@DubboReference(protocol="tri")
private DemoService demoService;

or

<dubbo:reference protocol="tri" />

After configuring protocol="tri", the service call will use the Triple protocol. It is important to ensure that the provider has already published support for the Triple protocol before configuring protocol="tri"; otherwise, the call will fail.

Step 3: Fully Converging to the Triple Protocol

Steps 1 and 2 are very straightforward and ensure a smooth process. Through single-port dual-protocol and automatic switching on the consumer side, the entire upgrade process is ensured to be smooth.

Smooth upgrading means we will go through an intermediate state where both the Dubbo and Triple protocols coexist for a certain period, meaning some service communications are done using the Dubbo protocol while others use the Triple protocol. How can we promote achieving the end goal, which is for all service calls to use the Triple protocol? We recommend using the following two methods to achieve this goal:

• Transition all Dubbo applications in the cluster to the latest 3.3.x version so that consumers can automatically switch to the Triple protocol.
• Observe whether a certain application (acting as a provider) is still handling Dubbo traffic through the metrics logging of the Dubbo framework and govern the upstream and downstream of these applications.