[servicecomb-docs] branch master updated: [SCB-2354]add document reference for new feature (#266)

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git


The following commit(s) were added to refs/heads/master by this push:
     new ee8552d  [SCB-2354]add document reference for new feature (#266)
ee8552d is described below

commit ee8552d4acf01c789c5faf7f0bc6932e65fd7239
Author: ette <et...@gmail.com>
AuthorDate: Sat Apr 16 17:45:03 2022 +0800

    [SCB-2354]add document reference for new feature (#266)
    
    Co-authored-by: w00517030 <ku...@huawei.com>
---
 .../en_US/docs/references-handlers/loadbalance.md  | 32 ++++++++++++++++++++
 .../zh_CN/docs/references-handlers/loadbalance.md  | 34 ++++++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/java-chassis-reference/en_US/docs/references-handlers/loadbalance.md b/java-chassis-reference/en_US/docs/references-handlers/loadbalance.md
index 3fdd73d..3a5e20a 100644
--- a/java-chassis-reference/en_US/docs/references-handlers/loadbalance.md
+++ b/java-chassis-reference/en_US/docs/references-handlers/loadbalance.md
@@ -68,6 +68,38 @@ This rule needs to be configured separately for each service. Global rule for al
 
 This rule is enabled by default, it can be disabled by setting `servicecomb.loadbalance.filter.instanceProperty.enabled` to false. The instance attributes based routing policy is implemented in `InstancePropertyDiscoveryFilter`.
 
+## Routing and forwarding by instance attributes with hierarchy value
+This is a extension of the feature above.
+
+You can specify the properties of microservice instances in microservice.yaml with hierarchy value, which is separated by `.` symbol.
+```yaml
+instance_description:
+  properties:
+    KEY: a.b.c
+```
+
+Consumer need to specify the key of instance which is used to match provider, the default key is `environment`
+
+```yaml
+servicecomb:
+  loadbalance:
+    filter:
+      priorityInstanceProperty:
+        key: KEY
+```
+
+Assuming there is a consumer instance with property value `a.b.c`, the match priority of provider will be `a.b.c`>`a.b`>`a`>`[empty]` and the table shown below gives detail match priority.
+| consumer | match priority of provider|
+| :--- | :--- | 
+|a.b.c|a.b.c>a.b>a>[empty]|
+|a.b|a.b>a>[empty]|
+|a|a>[empty]|
+|[empty]|[empty]|
+
+> Note that [empty] is represent for the instances which is not set value of this property key
+
+This rule is **NOT** enabled by default, which can be enabled by setting `servicecomb.loadbalance.filter.priorityInstanceProperty.enabled` to true. The policy is implemented in `PriorityInstancePropertyDiscoveryFilter`.
+
 ## Instance isolation
 Developers can configure instance-isolated parameters to temporarily drop access to the wrong instance, improving system reliability and performance. Below are the configuration items and default values:
 ```yaml
diff --git a/java-chassis-reference/zh_CN/docs/references-handlers/loadbalance.md b/java-chassis-reference/zh_CN/docs/references-handlers/loadbalance.md
index 31cd220..4e8c5ce 100644
--- a/java-chassis-reference/zh_CN/docs/references-handlers/loadbalance.md
+++ b/java-chassis-reference/zh_CN/docs/references-handlers/loadbalance.md
@@ -65,6 +65,40 @@ servicecomb:
 
 该规则默认启用，如果不需要使用，可以通过`servicecomb.loadbalance.filter.instanceProperty.enabled`进行关闭。根据实例属性进行路由转发功能在`InstancePropertyDiscoveryFilter`实现。
 
+## 根据实例属性值的层级进行路由转发
+实例属性优先级匹配可以看做是针对实例属性匹配的一种逻辑扩展。
+
+微服务的实例属性可以定义为具备优先级的格式，通过`.`符号进行分割。
+
+```yaml
+instance_description:
+  properties:
+    KEY: a.b.c
+```
+
+消费者需要指定用于优先级匹配的实例属性key，默认的key为`environment`。
+
+```yaml
+servicecomb:
+  loadbalance:
+    filter:
+      priorityInstanceProperty:
+        key: KEY
+```
+
+假设某个consumer的属性值为`a.b.c`，那么将会按照`a.b.c`>`a.b`>`a`>`[空]` 这样的优先级顺序匹配provider的实例，一旦匹配到即终止，下面的表格给出了不同情况的具体示例
+
+| consumer | match priority of provider|
+| :--- | :--- | 
+|a.b.c|a.b.c>a.b>a>[空]|
+|a.b|a.b>a>[空]|
+|a|a>[空]|
+|[空]|[空]|
+
+> 注意[空]是一种特殊情况，即未设置该属性的实例
+
+该规则默认关闭，如果需要开启，可以通过`servicecomb.loadbalance.filter.priorityInstanceProperty.enabled`配置打开。该功能在`PriorityInstancePropertyDiscoveryFilter`中实现。
+
 ## 实例隔离功能
 
 开发者可以配置实例隔离的参数，以暂时屏蔽对于错误实例的访问，提升系统可靠性和性能。下面是其配置项和缺省值