From 8a2c868ac7554f1cefb7f4a9b0bc5858e76ee5f9 Mon Sep 17 00:00:00 2001 From: hexiaofeng Date: Thu, 30 May 2024 16:17:52 +0800 Subject: [PATCH] Add governance.md --- docs/architect.md | 4 + docs/cn/architect.md | 4 + docs/cn/governance.md | 307 ++++++++++++++++++++++++++++++++++++++++++ docs/governance.md | 306 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 621 insertions(+) create mode 100644 docs/cn/governance.md create mode 100644 docs/governance.md diff --git a/docs/architect.md b/docs/architect.md index c841ad0dd..5b3e6a44a 100644 --- a/docs/architect.md +++ b/docs/architect.md @@ -16,3 +16,7 @@ See [Plugin System](plugin.md) ## 4. Link Transmission See [Link Transmission](transmission.md) + +## 5. Service Governance Model + +See [Service Governance Model](governance.md) diff --git a/docs/cn/architect.md b/docs/cn/architect.md index 12cbcb29c..7655f6443 100644 --- a/docs/cn/architect.md +++ b/docs/cn/architect.md @@ -16,3 +16,7 @@ ## 4. 全链路透传 查看[全链路透传](transmission.md) + +## 5. 服务治理模型 + +查看[服务治理模型](governance.md) diff --git a/docs/cn/governance.md b/docs/cn/governance.md new file mode 100644 index 000000000..8903c6cff --- /dev/null +++ b/docs/cn/governance.md @@ -0,0 +1,307 @@ +服务治理模型 +=== + +## 1. 统一治理层级 + +统一HTTP和传统RPC的治理策略配置层级 +``` +. +└── 服务 + ├── 分组* + │   ├── 路径* + │   │   ├── 方法* + +``` +服务治理策略放在分组、路径和方法上，可以逐级设置，下级默认继承上级的配置 + +服务的默认策略设置到默认分组`default`上 + +| 类型 | 服务 | 分组 | 路径 | 方法 | +|-----------|-----|----|-------|--------| +| HTTP | 域名 | 分组 | URL路径 | HTTP方法 | +| RPC 应用级注册 | 应用名 | 分组 | 接口名 | 方法名 | +| RPC 接口级注册 | 接口名 | 分组 | / | 方法名 | + +## 2. 服务策略 +### 2.1 服务多活策略 + +| 元素 | 说明 | +|----------|----------------------------| +| 参与 | 是否写方法，需要在容灾切换的时候禁止写数据 | +| 变量表达式 | 单元化场景，可设置从方法参数获取路由变量 | +| 单元策略 | 非单元化、本单元优先、单元化和中心 | +| 默认单元容错阈值 | 本单元优先策略下，当单元指标小于该阈值可以跨单元访问 | +| 单元容错阈值 | 设置每个单元的容错阈值 | +| 分区策略 | 本分区优先、不限 | +| 默认分区容错阈值 | 本分区优先策略下，当分区指标小于该阈值可以跨单元访问 | +| 分区容错阈值 | 设置每个分区的容错阈值 | + +```json +{ + "writeProtect": false, + "variableExpression": null, + "unitPolicy": "PREFER_LOCAL_UNIT", + "defaultUnitThreshold": 1, + "unitRemotes": [ + { + "name": "unit2", + "type": "INSTANCES", + "threshold": 1 + } + ], + "cellPolicy": "PREFER_LOCAL_CELL", + "defaultCellThreshold": 3, + "cellRemotes": [ + { + "name": "cell1", + "type": "INSTANCES", + "threshold": 4 + } + ] +} +``` + +### 2.2 服务泳道策略 + +| 元素 | 说明 | +|----------|----------------------------| +| 泳道空间 | 配置参与那些泳道空间 | + +```json +{ + "lanePolicies": [ + { + "laneSpaceId": "lane-space-1" + } + ] +} +``` + +### 2.3 服务集群策略 + +| 元素 | 说明 | +|------|-----------------------------------------------| +| 类型 | 故障切换、快速失败、失败可容忍 | +| 重试策略 | 当类型为故障切换，可配置重试策略，包括重视次数、重试时间间隔、超时时间、重试状态和重试异常 | + +```json +{ + "clusterPolicy": { + "type": "failover", + "retryPolicy": { + "retry": 10, + "retryInterval": 1000, + "timeout": 5000, + "retryStatuses": [ + 500, + 502 + ], + "retryExceptions": [ + "java.lang.NullPointException" + ] + } + } +} +``` + +### 2.4 服务负载均衡策略 + +| 元素 | 说明 | +|----|---------| +| 类型 | 随机权重和轮询 | +| 粘连 | 是否开启粘连 | + +```json +{ + "loadBalancePolicy": { + "policyType": "ROUND_ROBIN", + "stickyType": "NONE" + } +} +``` + +### 2.5 服务限流策略 + +| 元素 | 说明 | +|--------|---------------------------------------| +| 名称 | 限流策略名称 | +| 类型 | 限流实现类型，包括`Resilience4j`和`TokenBucket` | +| 滑动窗口 | 配置滑动窗口信息，包括调用次数和时间窗 | +| 最大等待时间 | 最大等待时间 | +| 参数 | 限流操作需要的参数 | +| 条件 | 限流开启的条件 | + +```json +{ + "rateLimitPolicies": [ + { + "name": "limit-rule-1", + "version": 1704038400000, + "strategyType": "Resilience4j", + "slidingWindows": [ + { + "threshold": 1, + "timeWindowInMs": 1000 + }, + { + "threshold": 3, + "timeWindowInMs": 2000 + } + ], + "maxWaitMs": 100, + "actionParameters": { + }, + "relationType": "AND", + "conditions": [ + { + "type": "header", + "opType": "EQUAL", + "key": "x-live-ext-demo", + "value": [ + "abc" + ] + } + ] + } + ] +} +``` + +### 2.6 服务并发控制策略 + +| 元素 | 说明 | +|-------|-------------------------| +| 名称 | 并发控制策略名称 | +| 类型 | 限流实现类型，包括`Resilience4j` | +| 最大并发数 | 最大并发数 | +| 最大等待时间 | 最大等待时间 | +| 参数 | 限流操作需要的参数 | +| 条件 | 限流开启的条件 | + +```json +{ + "concurrencyLimitPolicies": [ + { + "name": "limit-rule-2", + "version": 1704038400000, + "strategyType": "Resilience4j", + "maxConcurrency": 10, + "maxWaitMs": 100, + "actionParameters": { + }, + "relationType": "AND", + "conditions": [ + { + "type": "header", + "opType": "EQUAL", + "key": "x-live-ext-demo", + "value": [ + "abc" + ] + } + ] + } + ] +} +``` + +### 2.7 服务标签路由策略 + +| 元素 | 说明 | +|----|-----------------------------| +| 名称 | 策略名称 | +| 规则 | 定义多个规则，每个规则包括开启条件、目标权重和目标标签 | + +```json +{ + "routePolicies": [ + { + "name": "route1", + "tagRules": [ + { + "order": 5, + "relationType": "AND", + "conditions": [ + { + "opType": "EQUAL", + "type": "header", + "key": "x-live-unit", + "values": [ + "unit1" + ] + } + ], + "destinations": [ + { + "weight": 100, + "relationType": "AND", + "conditions": [ + { + "opType": "EQUAL", + "key": "unit", + "values": [ + "unit1" + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +### 3. 服务策略完整骨架 + +下面以json格式展示了服务策略 + +```json +[ + { + "name": "service-provider", + "serviceType": "HTTP", + "version": 0, + "groups": [ + { + "name": "default", + "defaultGroup": true, + "servicePolicy": { + "livePolicy": { + }, + "lanePolicies": [ + ], + "clusterPolicy": { + }, + "loadBalancePolicy": { + }, + "rateLimitPolicies": [ + ], + "concurrencyLimitPolicies": [ + ], + "routePolicies": [ + ] + }, + "paths": [ + { + "path": "/echo", + "matchType": "EQUAL", + "servicePolicy": { + }, + "methods": [ + { + "name": "GET", + "servicePolicy": { + } + } + ] + } + ] + } + ] + } +] +``` + + diff --git a/docs/governance.md b/docs/governance.md new file mode 100644 index 000000000..e5665e1e7 --- /dev/null +++ b/docs/governance.md @@ -0,0 +1,306 @@ +Service Governance Model +=== + +## 1. Unified Governance Hierarchy + +Unified governance strategy configuration hierarchy for HTTP and traditional RPC. + +``` +. +└── Service + ├── Group* + │   ├── Path* + │   │   ├── Method* + +``` +Service governance strategies are placed on groups, paths, and methods. They can be set step by step, with lower levels inheriting the configurations of higher levels by default. + +The default strategy for a service is set on the default group `default`. + +| Type | Service | Group | Path | Method | +|-------------|----------|-------|---------|------------| +| HTTP | Domain | Group | URL Path| HTTP Method| +| RPC App-Level Registration | App Name | Group | Interface Name | Method Name | +| RPC Interface-Level Registration | Interface Name | Group | / | Method Name | + +## 2. Service Strategies +### 2.1 Multi-Active Service Strategy + +| Element | Description | +|---------------|-------------------------------------| +| Write Protect | Whether to write methods, needs to be disabled during disaster recovery | +| Variable Expression | In unitization scenarios, can set routing variables from method parameters | +| Unit Policy | Non-unitized, Local Unit Preferred, Unitized and Central | +| Default Unit Fault Tolerance Threshold | Under the local unit preferred strategy, cross-unit access is allowed when unit metrics are below this threshold | +| Unit Fault Tolerance Threshold | Set the fault tolerance threshold for each unit | +| Partition Policy | Local Partition Preferred, Unlimited | +| Default Partition Fault Tolerance Threshold | Under the local partition preferred strategy, cross-unit access is allowed when partition metrics are below this threshold | +| Partition Fault Tolerance Threshold | Set the fault tolerance threshold for each partition | + +```json +{ + "writeProtect": false, + "variableExpression": null, + "unitPolicy": "PREFER_LOCAL_UNIT", + "defaultUnitThreshold": 1, + "unitRemotes": [ + { + "name": "unit2", + "type": "INSTANCES", + "threshold": 1 + } + ], + "cellPolicy": "PREFER_LOCAL_CELL", + "defaultCellThreshold": 3, + "cellRemotes": [ + { + "name": "cell1", + "type": "INSTANCES", + "threshold": 4 + } + ] +} +``` + +### 2.2 Lane Service Strategy + +| Element | Description | +|---------------|-------------------------------------| +| Lane Space | Configure participating lane spaces | + +```json +{ + "lanePolicies": [ + { + "laneSpaceId": "lane-space-1" + } + ] +} +``` + +### 2.3 Service Cluster Strategy + +| Element | Description | +|-----------|--------------------------------------------------------| +| Type | Failover, Fast Fail, Fail Tolerance | +| Retry Policy | When type is failover, configure retry policy including retry count, retry interval, timeout, retry statuses, and retry exceptions | + +```json +{ + "clusterPolicy": { + "type": "failover", + "retryPolicy": { + "retry": 10, + "retryInterval": 1000, + "timeout": 5000, + "retryStatuses": [ + 500, + 502 + ], + "retryExceptions": [ + "java.lang.NullPointerException" + ] + } + } +} +``` + +### 2.4 Service Load Balancing Strategy + +| Element | Description | +|---------|------------------| +| Type | Random Weight and Round Robin | +| Sticky | Whether to enable sticky sessions | + +```json +{ + "loadBalancePolicy": { + "policyType": "ROUND_ROBIN", + "stickyType": "NONE" + } +} +``` + +### 2.5 Service Rate Limiting Strategy + +| Element | Description | +|-------------|-----------------------------------------------| +| Name | Rate limiting strategy name | +| Type | Rate limiting implementation type, including `Resilience4j` and `TokenBucket` | +| Sliding Windows | Configure sliding window information including call count and time window | +| Max Wait Time | Maximum wait time | +| Parameters | Parameters required for rate limiting operations | +| Conditions | Conditions for enabling rate limiting | + +```json +{ + "rateLimitPolicies": [ + { + "name": "limit-rule-1", + "version": 1704038400000, + "strategyType": "Resilience4j", + "slidingWindows": [ + { + "threshold": 1, + "timeWindowInMs": 1000 + }, + { + "threshold": 3, + "timeWindowInMs": 2000 + } + ], + "maxWaitMs": 100, + "actionParameters": { + }, + "relationType": "AND", + "conditions": [ + { + "type": "header", + "opType": "EQUAL", + "key": "x-live-ext-demo", + "value": [ + "abc" + ] + } + ] + } + ] +} +``` + +### 2.6 Service Concurrency Control Strategy + +| Element | Description | +|------------|----------------------------------| +| Name | Concurrency control strategy name| +| Type | Rate limiting implementation type, including `Resilience4j` | +| Max Concurrency | Maximum concurrency | +| Max Wait Time | Maximum wait time | +| Parameters | Parameters required for rate limiting operations | +| Conditions | Conditions for enabling rate limiting | + +```json +{ + "concurrencyLimitPolicies": [ + { + "name": "limit-rule-2", + "version": 1704038400000, + "strategyType": "Resilience4j", + "maxConcurrency": 10, + "maxWaitMs": 100, + "actionParameters": { + }, + "relationType": "AND", + "conditions": [ + { + "type": "header", + "opType": "EQUAL", + "key": "x-live-ext-demo", + "value": [ + "abc" + ] + } + ] + } + ] +} +``` + +### 2.7 Service Tag Routing Strategy + +| Element | Description | +|---------|--------------------------------------| +| Name | Strategy name | +| Rules | Define multiple rules, each including enabling conditions, target weights, and target tags | + +```json +{ + "routePolicies": [ + { + "name": "route1", + "tagRules": [ + { + "order": 5, + "relationType": "AND", + "conditions": [ + { + "opType": "EQUAL", + "type": "header", + "key": "x-live-unit", + "values": [ + "unit1" + ] + } + ], + "destinations": [ + { + "weight": 100, + "relationType": "AND", + "conditions": [ + { + "opType": "EQUAL", + "key": "unit", + "values": [ + "unit1" + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +### 3. Complete Service Strategy Skeleton + +Below is the complete service strategy in JSON format. + +```json +[ + { + "name": "service-provider", + "serviceType": "HTTP", + "version": 0, + "groups": [ + { + "name": "default", + "defaultGroup": true, + "servicePolicy": { + "livePolicy": { + }, + "lanePolicies": [ + ], + "clusterPolicy": { + }, + "loadBalancePolicy": { + }, + "rateLimitPolicies": [ + ], + "concurrencyLimitPolicies": [ + ], + "routePolicies": [ + ] + }, + "paths": [ + { + "path": "/echo", + "matchType": "EQUAL", + "servicePolicy": { + }, + "methods": [ + { + "name": "GET", + "servicePolicy": { + } + } + ] + } + ] + } + ] + } +] +``` \ No newline at end of file