Service discovery samples enhancement (#417)

dubbo-samples-cloud-native/README.md

@@ -1,29 +1,17 @@
-# Dubbo Demo
+# Showcasing smooth upgrading of Dubbo3
 
-This directory contains basic usages of Dubbo to help Dubbo developers for debugging and smoke test purpose. If you are looking for Dubbo samples for study purpose, you should look into [here](https://github.com/apache/dubbo-samples) where you will find comprehensive usages for how to use Dubbo in different scenarios with the different features.
+## Start Dubbo3 Provider
 
-## How To Build
+Test both interface-level and application-level are registered successfully and are ready for subscription.
 
-To build all demo applications from the source code, simply step into '*dubbo-demo*' directory and use maven to build:
+## Start Dubbo2 Consumer
 
-```bash
-mvn clean package
-```
+Test Dubbo2 Consumer using version 2.7.15 can find interface-level addresses provided by Dubbo3 provider.
 
-After build completes, a couple of fat jars are generated under '*target*' directory under each module directories, for example: '*dubbo-demo-api-provider-${project.version}.jar*' can be found under the directory '*dubbo-demo/dubbo-demo-api/dubbo-demo-api-provider/target*'.
+## Start Dubbo3 Consumer
 
-## How To Run
+Test Dubbo3 Consumer can find application-level addresses provided by Dubbo3 provider.
 
-Since the generated artifacts are fat jars backed by spring boot maven plugin, they can be executed directly with '*java -jar*', and since multicast is used for service registration, a necessary system property '**-Djava.net.preferIPv4Stack=true**' is required in order to registry and discover the demo service properly. 
 
-Use '*dubbo-demo/dubbo-demo-api*' as an example, to start the provider '*dubbo-demo-api-provider*', execute the following command:
 
-```bash
-java -Djava.net.preferIPv4Stack=true -jar dubbo-demo-api-provider-${project.version}.jar
-```
 
-To run the consumer '*dubbo-demo-api-consumer*', execute the following command:
-
-```bash
-java -Djava.net.preferIPv4Stack=true -jar dubbo-demo-api-consumer-${project.version}.jar
-```

dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-consumer/README.md

@@ -0,0 +1,81 @@
+## Consumer behavior of upgrading to Dubbo3
+
+Below is one normal registry configuration of Dubbo2, if upgrading to Dubbo3 without adding any changes, Dubbo3 will try
+to subscribe both app-level and interface-level addresses by default.
+
+After received address notifications from both side, the Consumer will decide to use which one as the valid address pool
+based on some default conditions pre-set by the framework or users, the whole subscription and decision made process is
+called `APPLICATION_FIRST`.
+
+> 1 The checking conditions can be set through an SPI called `org.apache.dubbo.registry.client.migration.MigrationAddressComparator`
+> 2 There are 3 ways of migration, thery are `FORCE_APPLICATION`, `FORCE_INTERFACE`, `APPLICATION_FIRST`, based on how many apps have been upgraded to Dubbo3. And `APPLICATION_FIRST` is the most convenient way to achieve that.
+
+```xml
+<!-- Subscribe both interface-level and app-level addresses from registry by default -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181"/>
+```
+
+By changing the registry address to `zookeeper://127.0.0.1:2181?registry-type=service`, the Consumer will only subscribe
+application-level addresses from the registry, regardless all other migration rules and configurations. This can be
+useful for
+
+## More details
+
+You can change the default subscription behaviour by specifying using different ways, for example by using xml,
+properties or config center.
+
+The main difference is if you want to change the subscription behavior on the fly or not, simply put is:
+
+* By using dynamic migration rule, with the help of config center like Zookeeper or Nacos, you will be able to control
+  the Consumer without restarting it.
+* By using xml, properties and JVM args, you need to restart the process to make it work.
+
+### Using xml, properties or JVM args
+
+```xml
+<!-- Register app-level address only -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" >
+    <!-- the migration step to use -->
+    <dubbo:parameter key="migration.step" value="FORCE_APPLICATION"/>
+    <!-- wait for address notification before migration -->
+    <dubbo:parameter key="migration.delay" value="10000"/>
+    <!-- check or not before migration -->
+    <dubbo:parameter key="migration.force" value="true"/>
+    <!-- only works when migration.force=false is set -->
+    <dubbo:parameter key="migration.threshold" value="1"/>
+</dubbo:registry>
+```
+
+```properties
+dubbo.registry.parameters.migration.step=FORCE_APPLICATION
+dubbo.registry.parameters.migration.delay=10000
+dubbo.registry.parameters.migration.force=true
+```
+
+### Using dynamic migration rule
+
+Users can choose to use dynamic migration rule by using Dubbo Admin or by writing to config center server directly.
+
+Following is one demo rule:
+
+```yaml
+# key = demo-consumer.migration
+# group = DUBBO_SERVICEDISCOVERY_MIGRATION
+# content
+key: demo-consumer
+step: APPLICATION_FIRST
+threshold: 1.0
+proportion: 60
+delay: 60
+force: false
+interfaces: # Interface level migration
+  - serviceKey: org.apache.dubbo.demo.DemoService:1.0.0
+    threshold: 1
+    delay: 30
+    step: APPLICATION_FIRST
+  - serviceKey: org.apache.dubbo.demo.GreetingService:1.0.0
+    step: FORCE_APPLICATION
+applications: # Application level migration
+ - serviceKey: demo-provider # app name of provider
+   step: FORCE_APPLICATION
+```

dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-consumer/src/main/resources/spring/dubbo-consumer.xml

@@ -23,11 +23,12 @@
 
     <dubbo:application name="demo-consumer"/>
 
-    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181?registry-type=service"/>
-<!--    <dubbo:registry address="nacos://${nacos.address:127.0.0.1}:8848?registry-type=service"/>-->
+    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>
+    <!--    <dubbo:registry address="nacos://${nacos.address:127.0.0.1}:8848?registry-type=service"/>-->
 
-    <dubbo:metadata-report address="zookeeper://${zookeeper.address:127.0.0.1}:2181" />
+    <dubbo:metadata-report address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>
 
-    <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.demo.DemoService" provided-by="demo-provider"/>
+    <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.demo.DemoService"/>
+    <!--    <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.demo.DemoService" provided-by="demo-provider"/>-->
 
 </beans>

dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/README.md

@@ -0,0 +1,32 @@
+## Provider behavior of upgrading to Dubbo3
+
+Below is the normal registry config of Dubbo2, if upgrading to Dubbo3 without adding any change, Dubbo3 will register
+both interface-level and app-level addresses to the registry by default.
+
+```xml
+<!-- Register both interface-level and app-level addresses by default -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181"/>
+```
+
+You can change the default behaviour by specifying `register-mode` through different ways, like xml, properties or JVM
+args.
+
+Take xml as an example:
+
+```xml
+<!-- Register app-level address only -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="instance"/>
+```
+
+```xml
+<!-- Register interface-level address only -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="interface"/>
+```
+
+```xml
+<!-- The default value, register both interface-level and app-level addresses -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="all"/>
+```
+
+Further more, users can choose to set the default behaviour that could apply to all applications by using global config
+center. Check [migration doc](https://dubbo.apache.org/zh/docs/migration/migration-service-discovery/) for more details.

dubbo-samples-cloud-native/dubbo-demo-servicediscovery-xml/servicediscovery-provider/src/main/resources/spring/dubbo-provider.xml

@@ -21,18 +21,16 @@
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd
        http://dubbo.apache.org/schema/dubbo http://dubbo.apache.org/schema/dubbo/dubbo.xsd">
 
-    <dubbo:application name="demo-provider" metadata-type="remote"/>
+    <dubbo:application name="demo-provider"/>
 
     <dubbo:provider token="true"/>
 
-    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181?registry-type=service"/>
+    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181" use-as-metadata-center="true"
+                    use-as-config-center="true"/>
 <!--    <dubbo:registry address="nacos://${nacos.address:127.0.0.1}:8848?registry-type=service"/>-->
 
     <dubbo:protocol name="dubbo" port="20880"/>
 
-<!--    <dubbo:metadata-report address="nacos://${nacos.address:127.0.0.1}:8848" />-->
-    <dubbo:metadata-report address="zookeeper://${zookeeper.address:127.0.0.1}:2181" />
-
     <bean id="demoService" class="org.apache.dubbo.demo.provider.DemoServiceImpl"/>
 
     <dubbo:service interface="org.apache.dubbo.demo.DemoService" ref="demoService" weight="12"/>

dubbo-samples-cloud-native/servicediscovery-transfer/case-configuration.yml

@@ -0,0 +1,81 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+services:
+  zookeeper:
+    image: zookeeper:latest
+
+  servicediscovery-provider:
+    type: app
+    basedir: servicediscovery-provider
+    mainClass: org.apache.dubbo.demo.provider.Application
+    systemProps:
+      - zookeeper.address=zookeeper
+    waitPortsBeforeRun:
+      - zookeeper:2181
+    checkPorts:
+      - 20880
+    checkLog: "dubbo service started"
+    depends_on:
+      - zookeeper
+
+  servicediscovery-provider-instance:
+    type: app
+    basedir: servicediscovery-provider-instance
+    mainClass: org.apache.dubbo.demo.provider.Application
+    systemProps:
+      - zookeeper.address=zookeeper
+    waitPortsBeforeRun:
+      - zookeeper:2181
+    checkPorts:
+      - 20881
+    checkLog: "dubbo service started"
+    depends_on:
+      - zookeeper
+
+  servicediscovery-consumer-test-old:
+    type: test
+    basedir: servicediscovery-consumer-old
+    tests:
+      - "**/*IT.class"
+    systemProps:
+      - zookeeper.address=zookeeper
+    waitPortsBeforeRun:
+      - zookeeper:2181
+      - servicediscovery-provider:20880
+      - servicediscovery-provider-instance:20881
+    depends_on:
+      - zookeeper
+      - servicediscovery-provider
+      - servicediscovery-provider-instance
+
+  servicediscovery-consumer-test:
+    type: test
+    basedir: servicediscovery-consumer
+    tests:
+      - "**/*IT.class"
+    systemProps:
+      - zookeeper.address=zookeeper
+    waitPortsBeforeRun:
+      - zookeeper:2181
+      - servicediscovery-provider:20880
+      - servicediscovery-provider-instance:20881
+    depends_on:
+      - zookeeper
+      - servicediscovery-provider
+      - servicediscovery-provider-instance
+

dubbo-samples-cloud-native/servicediscovery-transfer/case-versions.conf

@@ -0,0 +1,24 @@
+#
+#
+#   Licensed to the Apache Software Foundation (ASF) under one or more
+#   contributor license agreements.  See the NOTICE file distributed with
+#   this work for additional information regarding copyright ownership.
+#   The ASF licenses this file to You under the Apache License, Version 2.0
+#   (the "License"); you may not use this file except in compliance with
+#   the License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+
+# Supported component versions of the test case
+
+# Spring app
+dubbo.version=3.*
+spring.version=4.*, 5.*

dubbo-samples-cloud-native/servicediscovery-transfer/pom.xml

@@ -30,6 +30,7 @@
     <modules>
         <module>servicediscovery-transfer-api</module>
         <module>servicediscovery-transfer-provider</module>
+        <module>servicediscovery-transfer-provider-instance</module>
         <module>servicediscovery-transfer-consumer-old</module>
         <module>servicediscovery-transfer-consumer</module>
     </modules>

dubbo-samples-cloud-native/servicediscovery-transfer/servicediscovery-transfer-consumer-old/src/main/java/org/apache/dubbo/demo/consumer/Application.java

@@ -17,7 +17,6 @@
 package org.apache.dubbo.demo.consumer;
 
 import org.apache.dubbo.demo.DemoService;
-import org.apache.dubbo.demo.GreetingService;
 
 import org.springframework.context.support.ClassPathXmlApplicationContext;
 
@@ -27,8 +26,6 @@ public static void main(String[] args) {
         context.start();
         DemoService demoService = context.getBean("demoService", DemoService.class);
         String hello = demoService.sayHello("world");
-        System.out.println("result: " + hello);
-        GreetingService greetingService = context.getBean("greetingService", GreetingService.class);
-        System.out.print("greetings: " + greetingService.hello());
+        System.out.println("result from interface-level address: " + hello);
     }
 }

dubbo-samples-cloud-native/servicediscovery-transfer/servicediscovery-transfer-consumer-old/src/main/resources/spring/dubbo-consumer.xml

@@ -23,9 +23,8 @@
 
     <dubbo:application name="servicediscovery-transfer-consumer-old"/>
 
-    <dubbo:registry address="zookeeper://127.0.0.1:2181"/>
+    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>
 
     <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.demo.DemoService"/>
-    <dubbo:reference id="greetingService" check="false" interface="org.apache.dubbo.demo.GreetingService"/>
 
 </beans>

dubbo-samples-cloud-native/servicediscovery-transfer/servicediscovery-transfer-consumer/src/main/java/org/apache/dubbo/demo/consumer/Application.java

@@ -26,6 +26,6 @@ public static void main(String[] args) {
         context.start();
         GreetingService greetingService = context.getBean("greetingService", GreetingService.class);
         String hello = greetingService.hello();
-        System.out.println("result: " + hello);
+        System.out.println("result from application-level address: " + hello);
     }
 }

dubbo-samples-cloud-native/servicediscovery-transfer/servicediscovery-transfer-consumer/src/main/resources/spring/dubbo-consumer.xml

@@ -23,7 +23,7 @@
 
     <dubbo:application name="servicediscovery-transfer-consumer"/>
 
-    <dubbo:registry address="zookeeper://127.0.0.1:2181?registry-type=service"/>
+    <dubbo:registry address="zookeeper://${zookeeper.address:127.0.0.1}:2181"/>
 
     <dubbo:reference id="greetingService" check="false" interface="org.apache.dubbo.demo.GreetingService"/>
 

dubbo-samples-cloud-native/servicediscovery-transfer/servicediscovery-transfer-provider-instance/README.md

@@ -0,0 +1,34 @@
+## Provider
+
+Below is the normal registry config of Dubbo2, if upgrading to Dubbo3 without adding any change, Dubbo3 will register
+both interface-level and app-level addresses to the registry by default.
+
+```xml
+<!-- Register both interface-level and app-level addresses by default -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181"/>
+```
+
+## More Details
+
+You can also change the default behaviour by specifying `register-mode` through different ways, like xml, properties or
+JVM args.
+
+Take xml as an example:
+
+```xml
+<!-- Register app-level address only -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="instance"/>
+```
+
+```xml
+<!-- Register interface-level address only -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="interface"/>
+```
+
+```xml
+<!-- The default value, register both interface-level and app-level addresses -->
+<dubbo:registry address="zookeeper://127.0.0.1:2181" register-mode="all"/>
+```
+
+Further more, users can choose to set the default behaviour that could apply to all applications by using global config
+center. Check [migration doc](https://dubbo.apache.org/zh/docs/migration/migration-service-discovery/) for more details.