Migrate applications from HSF to Dubbo3

Terms

• HSF2 application: An application that declares service providers or consumers using HSF annotations or XML and is deployed using EDAS Container 3.x.

• HSF3 application: An application that declares service providers or consumers using HSF annotations or XML and is deployed using EDAS Container 5.x or later. EDAS Container 4.x is also considered HSF3 but does not support dual registration and discovery.

• Dubbo3 application: An application that declares service providers or consumers using Dubbo and depends exclusively on open source Dubbo3.

• Config Server: The service registry used by HSF applications in EDAS.

Usage notes

HSF3 (EDAS Container 5.x) uses both Config Server and Nacos as service registries, allowing services to be registered to both simultaneously. HSF3 also provides service ports for both the HSF and Dubbo protocols. HSF2 applications do not require code modification. When deployed directly with the HSF3 container, they can communicate with both HSF2 and Dubbo3 applications, ensuring a smooth migration.

How it works

As shown in the figure, the migration process has three stages.

1. Initial state: All applications are HSF2 applications. They use Config Server as the service registry.

2. Migration state: Applications are in a hybrid deployment phase, which includes the following sub-stages:

   1. HSF2 and HSF3 applications: Some applications are deployed using HSF3. At this stage, both HSF2 and HSF3 applications use Config Server as the service registry. They can discover and invoke services from each other. For more information, see Step 1: Upgrade the application runtime environment.

   2. All HSF3 applications: All applications are redeployed using HSF3. At this stage, no HSF2 applications remain in the system.

   3. HSF3 and Dubbo3 applications: Enable dual service registration and discovery for HSF3 applications. Then, declare services using Dubbo3 and deploy application instances. For more information, see Step 2: Create an application. At this stage, HSF3 and Dubbo3 applications can discover and invoke services from each other.

3. Final state: All HSF applications are migrated to Dubbo3.

Migration steps

Step 1: Upgrade the application runtime environment

• For ECS applications deployed in EDAS, use the Upgrade/Downgrade Runtime feature to upgrade the Pandora version to 5.X.

• For Kubernetes applications deployed in EDAS using WAR or JAR packages, upgrade the application runtime environment to EDAS-Container 5.X by redeploying the application.

• For Kubernetes applications deployed in EDAS using images, rebuild the image to upgrade the image version to 5.0.0. Add the following configuration to the Dockerfile of the HSF application to upgrade the EDAS-Container (Pandora) runtime environment to version 5.0.0. For more information, see Dockerfile example for HSF applications.

  # Add the upgrade script after WORKDIR/home/admin
  # Set the EDAS-Container/Pandora application container version
  ENV UPGRADED_CONTAINER_VERSION 5.0.0
  RUN /home/admin/bin/upgradecontainer.sh

Modify the application startup parameters or configuration and complete the deployment. For more information, see Configure dual registration and publishing for HSF3 applications.

Step 2: Create an application

Use the new deployment package to create a Java application in the same microservices namespace in EDAS.

• ECS application:

• Kubernetes application:

Configuration reference

Configure dual registration and publishing for HSF3 applications

Requirements and methods

1. Deploy the application using EDAS Container 5.x.

2. Enable dual publishing and discovery.

   • Method 1: Use the JVM parameter -Ddubbo.config.hsf.exportNativeDubbo=true to enable dual publishing, and -Ddubbo.config.hsf.referNativeDubbo=true to enable dual discovery.

   • Method 2: In the dubbo.properties file, specify dubbo.config.hsf.exportNativeDubbo=true to enable dual publishing and dubbo.config.hsf.referNativeDubbo=true to enable dual discovery.

By default, HSF3 applications publish and discover HSF services. After you enable these settings, the application also registers services to Nacos, publishes Dubbo services, discovers services through Nacos, and invokes Dubbo services. This allows HSF3 applications to use Nacos as the service registry and the Triple protocol for communication to provide Dubbo services.

Routing policy for dual discovery

• Calls are balanced based on the number of providers. For example, if there is one HSF service node and three Dubbo nodes, the probability of invoking the HSF service node is 1/4, and the probability of invoking a Dubbo service node is 3/4. An HSF3 node with dual publishing enabled acts as both an HSF and a Dubbo service node.

• If nodes of one type are unavailable, nodes of the available type are invoked.

• If nodes of both types are unavailable, HSF nodes are invoked by default.

Dubbo3 application configuration example

The application must declare dependencies on dubbo-registry-nacos and dubbo-rpc-triple. You must use versions between 3.0.5 and 3.0.12.

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-registry-nacos</artifactId>
    <version>${dubbo.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-rpc-triple</artifactId>
    <version>${dubbo.version}</version>
</dependency>

For the nacos-client dependency, use only version 2.0.3 or versions 2.1.2 and later. Versions from 2.0.4 to 2.1.1 do not support the EDAS shared registry or the MSE registry.

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>2.1.2</version>
</dependency>

Dubbo declaration requirements

HSF3 supports only service-level publishing and discovery. Therefore, you must configure Dubbo to enforce the service discovery mode. You can do this in one of the following ways:

• Method 1: Declare the JVM parameter: -Ddubbo.application.service-discovery.migration=FORCE_INTERFACE.

• Method 2: Configure dubbo.application.service-discovery.migration=FORCE_INTERFACE in the dubbo.properties file.

  The following is an example of the configuration in a spring boot yaml file:

  Important

  You must declare the use of the Triple protocol.

  dubbo:
    application:
        name: ....
      protocol:
        # This configuration is required because HSF3 uses the Triple protocol to publish services.
      name: tri
      port: -1
    # Declare the use of Nacos for the service registry and configuration center. This will be automatically replaced after deployment on EDAS.
    registry:
      id: nacos-registry
      address: nacos://127.0.0.1:8848
    config-center:
      address: nacos://127.0.0.1:8848
    metadata-report:
      address: nacos://127.0.0.1:8848

  The following is an example of the configuration in an XML file:

  <dubbo:metadata-report address="nacos://127.0.0.1:8848"/>
  <dubbo:registry address="nacos://127.0.0.1:8848"/>
  <dubbo:config-center address="nacos://127.0.0.1:8848"/>
  <dubbo:protocol id="tri" name="tri" />

Demo reference

Download the Demo.

This demo includes the following project modules:

The figure above shows four demo project groups. The first group is deployed using HSF2 and HSF3 containers.

Select and deploy a demo group for your experiment. After the deployment is complete, access any consumer and run the following command.

curl 'http://127.0.0.1:8080/index.htm?name=abc'

The following response is returned:

# xth call
Item Id: 1, Name: Protocol=HSF,LocalIP=172.17.48.116,Name=default,Date=2022-11-22 19:45:19:372,TraceId=ac11303616691175193702012d003f
# (x+1)th call
Item Id: 1, Name: Protocol=TRI,LocalIP=172.17.48.116,Name=default,Date=2022-11-22 19:45:15:741,TraceId=ac11303616691175157392011d003f

Response description:

• Protocol: The protocol used by the service provider. HSF indicates the HSF protocol, and TRI indicates the Triple protocol.

• LocalIP: The IP address of the service provider.

FAQ

How do I use an MSE Nacos instance as the Dubbo service registry for an HSF3 application?

If you continue to use the EDAS shared registry, you do not need to perform the following steps.

1. Create an instance and add a namespace in the MSE Management Console. For more information, see Create an MSE instance and Create a namespace.

2. In the resources directory of the application's Maven source code, add a dubbo.properties file. Add the following content to the dubbo.properties file and then build the application package.

   dubbo.config.hsf.nativeDubbo.registry=nacos://mse-xxxx-nacos-ans.mse.aliyuncs.com:8848?namespace=msenamespace01

   • mse-xxxx-nacos-ans.mse.aliyuncs.com: The endpoint of the instance.

   • msenamespace01: The ID of the created namespace.

3. Configure the service registry in the program.

   • Method 1: Add the JVM startup parameter -Dnacos.use.endpoint.parsing.rule=false -Dnacos.use.cloud.namespace.parsing=false.

   • Method 2: As shown in the following figure, when you deploy the application, on the Advanced Settings page, expand Microservice Governance and select Use the registry configured in the program (Do not use the Nacos registry provided by EDAS).

4. After you deploy the application, go to the MSE engine instance and check whether your service is in the service list.

How do I check if the application started normally?

• For Spring Boot and Kubernetes applications, check the standard Kubernetes output.

• For applications deployed using Tomcat or EDAS Container, check the tomcat/logs/localhost.log.xxx file.

How do I check if the service is registered to Nacos?

Run the grep REGISTER-SERVICE ~/logs/nacos/naming.log | grep service_name command. If the service is registered, the output is similar to the following:

How do I check if the service is discovered correctly through Nacos?

Run the find ~/nacos/naming -name "*service_name*" command. The formatted content of the file is as follows.

{
  "name": "providers:com.alibaba.edas.carshop.itemcenter.ItemService:1.0.0:HSF",
  "groupName": "DEFAULT_GROUP",
  "clusters": "",
  "cacheMillis": 10000,
  "hosts": [
    {
      "instanceId": "172.17.XX.XX#50051#null#DEFAULT_GROUP@@providers:com.alibaba.edas.carshop.itemcenter.ItemService:1.0.0:HSF",
      "ip": "172.17.XX.XX",
      "port": 50051,
      "weight": 1.0,
      "healthy": true,
      "enabled": true,
      "ephemeral": true,
      "clusterName": "DEFAULT",
      "serviceName": "DEFAULT_GROUP@@providers:com.alibaba.edas.carshop.itemcenter.ItemService:1.0.0:HSF",
      "metadata": {
        "release": "3.0.12",
        "methods": "getItemByName,getItemById,getItemByIdAndName",
        "deprecated": "false",
        "dubbo": "2.0.2",
        "pid": "1",

• com.alibaba.edas.carshop.itemcenter.ItemService: The service name.

• 1.0.0: The version number.

• HSF: The group name.

• hosts: The service providers.

• 172.17.XX.XX: The IP address and service port of the service provider.

The service name, version number, and group name are critical because they form the unique identity of the service. If any of these items do not match what the provider registered, the consumer cannot find the service. If the service is not found, you can run the cat ~/logs/nacos/naming.log | grep ItemService command to check whether the log shows a subscription trigger.