You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by me...@apache.org on 2020/02/24 05:52:39 UTC
[incubator-apisix] branch master updated: doc: make admin API doc
friendly. (#1145)
This is an automated email from the ASF dual-hosted git repository.
membphis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 06ed0eb doc: make admin API doc friendly. (#1145)
06ed0eb is described below
commit 06ed0eb5c105e8fdc0782703422cf7a79e7d3c12
Author: WenMing <mo...@gmail.com>
AuthorDate: Mon Feb 24 13:52:29 2020 +0800
doc: make admin API doc friendly. (#1145)
---
README.md | 5 +++--
README_CN.md | 5 +++--
doc/README_CN.md | 1 +
doc/admin-api-cn.md | 17 ++++++++++-------
doc/architecture-design-cn.md | 15 +++++++++++----
5 files changed, 28 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
index 77613b7..a84b637 100644
--- a/README.md
+++ b/README.md
@@ -101,11 +101,12 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against
- [Stand-alone mode](doc/stand-alone.md): Supports to load route rules from local yaml file, it is more friendly such as under the kubernetes(k8s).
- Global Rule: Allows to run any plugin for all request, eg: limit rate, IP filter etc.
- High performance: The single-core QPS reaches 18k with an average delay of less than 0.2 milliseconds.
- - [REST admin API](doc/admin-api.md)
- [Fault Injection](doc/plugins/fault-injection.md)
+ - [REST Admin API](doc/admin-api.md)
+ - [Python SDK](https://github.com/api7/apache-apisix-python-sdk)
- **Highly scalable**
- - [Custom plugins]((doc/plugin-develop.md)): Allows hooking of common phases, such as `rewrite`, `access`, `header filer`, `body filter` and `log`, also allows to hook the `balancer` stage.
+ - [Custom plugins](doc/plugin-develop.md): Allows hooking of common phases, such as `rewrite`, `access`, `header filer`, `body filter` and `log`, also allows to hook the `balancer` stage.
- Custom load balancing algorithms: You can use custom load balancing algorithms during the `balancer` phase.
- Custom routing: Support users to implement routing algorithms themselves.
diff --git a/README_CN.md b/README_CN.md
index 288f278..ab7290c 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -91,7 +91,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- [限制并发](doc/plugins/limit-conn-cn.md)
- 防御 ReDoS(正则表达式拒绝服务)：内置策略，无需配置即可抵御 ReDoS。
-- **可运维**
+- **运维友好**
- OpenTracing 可观测性: [支持 Apache Skywalking 和 Zipkin](doc/plugins/zipkin-cn.md)。
- 监控和指标: [Prometheus](doc/plugins/prometheus-cn.md)
- 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://github.com/etcd-io/etcd/blob/master/Documentation/v2/clustering.md)。
@@ -101,8 +101,9 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- [单机模式](doc/stand-alone-cn.md): 支持从本地配置文件中加载路由规则，在 kubernetes(k8s) 等环境下更友好。
- 全局规则：允许对所有请求执行插件，比如黑白名单、限流限速等。
- 高性能：在单核上 QPS 可以达到 18k，同时延迟只有 0.2 毫秒。
- - [REST admin API](doc/admin-api-cn.md)
- [故障注入](doc/plugins/fault-injection-cn.md)
+ - [REST Admin API](doc/admin-api-cn.md)
+ - [Python SDK](https://github.com/api7/apache-apisix-python-sdk)
- **高度可扩展**
- [自定义插件](doc/plugin-develop-cn.md): 允许挂载常见阶段，例如`init`, `rewrite`，`access`，`balancer`,`header filer`，`body filter` 和 `log` 阶段。
diff --git a/doc/README_CN.md b/doc/README_CN.md
index a60d558..07ff451 100644
--- a/doc/README_CN.md
+++ b/doc/README_CN.md
@@ -49,6 +49,7 @@ Reference document
* [limit-count](plugins/limit-count-cn.md)：基于“固定窗口”的限速实现。
* [limit-req](plugins/limit-req-cn.md)：基于漏桶原理的请求限速实现。
* [limit-conn](plugins/limit-conn-cn.md)：限制并发请求（或并发连接）。
+* [proxy-rewrite](plugins/proxy-rewrite-cn.md): 支持自定义修改 proxy 到上游的信息。
* [prometheus](plugins/prometheus-cn.md)：以 Prometheus 格式导出 APISIX 自身的状态信息，方便被外部 Prometheus 服务抓取。
* [OpenTracing](plugins/zipkin-cn.md)：支持 Zikpin 和 Apache SkyWalking。
* [grpc-transcode](plugins/grpc-transcoding-cn.md)：REST <--> gRPC 转码。
diff --git a/doc/admin-api-cn.md b/doc/admin-api-cn.md
index 99d0fa9..6a449e5 100644
--- a/doc/admin-api-cn.md
+++ b/doc/admin-api-cn.md
@@ -50,8 +50,14 @@
|名字 |可选项 |类型 |说明 |示例|
|---------|---------|----|-----------|----|
+|uri |与 `uris` 二选一 |匹配规则|除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design-cn.md#router) 还允许更高级匹配，更多见 [Router](architecture-design-cn.md#router)。|"/hello"|
+|uris |与 `uri` 二选一 |匹配规则|数组形式，可以匹配多个 `uri`|["/hello", "/world"]|
+|plugins |`plugins`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Plugin|详见 [Plugin](architecture-design-cn.md#plugin) ||
+|upstream |`plugins`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Upstream|启用的 Upstream 配置，详见 [Upstream](architecture-design-cn.md#upstream)||
+|upstream_id|`plugins`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Upstream|启用的 upstream id，详见 [Upstream](architecture-design-cn.md#upstream)||
+|service_id|`plugins`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Service|绑定的 Service 配置，详见 [Service](architecture-design-cn.md#service)||
+|service_protocol|可选|上游协议类型|只可以是 "grpc", "http" 二选一。|默认 "http"，使用gRPC proxy 或gRPC transcode 时，必须用"grpc"|
|desc |可选 |辅助 |标识路由名称、使用场景等。|客户 xxxx|
-|uri |必须 |匹配规则|除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design-cn.md#router) 还允许更高级匹配，更多见 [Router](architecture-design-cn.md#router)。|"/hello"|
|host |可选 |匹配规则|当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。|"foo.com"|
|hosts |可选 |匹配规则|列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。|{"foo.com", "*.bar.com"}|
|remote_addr|可选 |匹配规则|客户端请求 IP 地址: `192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`, `fe80::1/64` 等。|"192.168.1.0/24"|
@@ -60,13 +66,10 @@
|priority |可选 |匹配规则|如果不同路由包含相同 `uri`，根据属性 `priority` 确定哪个 `route` 被优先匹配，默认值为 0。|priority = 10|
|vars |可选 |匹配规则(仅支持 `radixtree` 路由)|由一个或多个`{var, operator, val}`元素组成的列表，类似这样：`{{var, operator, val}, {var, operator, val}, ...}`。例如：`{"arg_name", "==", "json"}`，表示当前请求参数 `name` 是 `json`。这里的 `var` 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host` 等；对于 `operator` 部分，目前已支持的运算符有 `==`、`~=`、`>`、`<` 和 `~~`。对于`>`和`<`两个运算符，会把结果先转换成 number 然后再做比较。查看支持的[运算符列表](#运算符列表)|{{"arg_name", "==", "json"}, {"arg_age", ">", 18}}|
|filter_func|可选|匹配规则|用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 vars 的输入参数，可以用它来获取 Nginx 变量。|function(vars) return vars["arg_name"] == "json" end|
-|plugins |可选 |Plugin|详见 [Plugin](architecture-design-cn.md#plugin) ||
-|upstream |可选 |Upstream|启用的 Upstream 配置，详见 [Upstream](architecture-design-cn.md#upstream)||
-|upstream_id|可选 |Upstream|启用的 upstream id，详见 [Upstream](architecture-design-cn.md#upstream)||
-|service_id|可选 |Service|绑定的 Service 配置，详见 [Service](architecture-design-cn.md#service)||
-|service_protocol|可选|上游协议类型|只可以是 "grpc", "http" 二选一。|默认 "http"，使用gRPC proxy 或gRPC transcode 时，必须用"grpc"|
-对于同一类参数比如 `host` 与 `hosts`，`remote_addr` 与 `remote_addrs`，是不能同时存在，二者只能选择其一。如果同时启用，接口会报错。
+有两点需要特别注意：
+- 除了 `uri`/`uris` 是必选的之外，`plugins`、`upstream`/`upstream_id`、`service_id` 这三类必须选择其中至少一个。
+- 对于同一类参数比如 `uri`与 `uris`，`upstream` 与 `upstream_id`，`host` 与 `hosts`，`remote_addr` 与 `remote_addrs` 等，是不能同时存在，二者只能选择其一。如果同时启用，接口会报错。
示例：
diff --git a/doc/architecture-design-cn.md b/doc/architecture-design-cn.md
index 8a4a3f0..227ba25 100644
--- a/doc/architecture-design-cn.md
+++ b/doc/architecture-design-cn.md
@@ -235,14 +235,21 @@ APISIX 的 Upstream 除了基本的复杂均衡算法选择外，还支持对上
|名字 |可选|说明|
|------- |-----|------|
-|type |必需|`roundrobin` 支持权重的负载，`chash` 一致性哈希，两者是二选一的|
-|nodes |必需|哈希表，内部元素的 key 是上游机器地址列表，格式为`地址 + Port`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重，特别的，当权重值为 `0` 有特殊含义，通常代表该上游节点失效，永远不希望被选中。|
-|hash_on |可选|该选项只有 `type` 是 `chash` 才有效。`hash_on` 支持的类型有 `vars`（Nginx内置变量），`header`（自定义header），`cookie`，`consumer`，默认值为 `vars`|
-|key |必需|该选项只有 `type` 是 `chash` 才有效，需要配合 `hash_on` 来使用，通过 `hash_on` 和 `key` 来查找对应的 node `id`。`hash_on` 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自URL的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html)；`hash_on` 设为 `header` 时, `key` 为必传参数，自定义的 `header name`；`hash_on` 设为 `cookie` 时, `key` 为必传参数， 自定义的 `cookie name`；`hash_on` 设为 `consumer` 时，`key` 不需 [...]
+|type |必填|`roundrobin` 支持权重的负载，`chash` 一致性哈希，两者是二选一的|
+|nodes |必填|哈希表，内部元素的 key 是上游机器地址列表，格式为`地址 + Port`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80` 等。value 则是节点的权重。当权重值为 `0` 代表该上游节点失效，不会被选中，可以用于暂时摘除节点的情况。|
+|key |可选|在 `type` 等于 `chash` 是必选项。 `key` 需要配合 `hash_on` 来使用，通过 `hash_on` 和 `key` 来查找对应的 node `id`|
+|hash_on |可选|`hash_on` 支持的类型有 `vars`（Nginx内置变量），`header`（自定义header），`cookie`，`consumer`，默认值为 `vars`|
|checks |可选|配置健康检查的参数，详细可参考[health-check](health-check.md)|
|retries |可选|使用底层的 Nginx 重试机制将请求传递给下一个上游，默认 APISIX 会启用重试机制，根据配置的后端节点个数设置重试次数，如果此参数显式被设置将会覆盖系统默认设置的重试次数。|
|enable_websocket|可选| 是否启用 `websocket`（布尔值），默认不启用|
+`hash_on` 比较复杂，这里专门说明下：
+1. 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自URL的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html)
+1. 设为 `header` 时, `key` 为必传参数，其值为自定义的 header name, 即 "http_`key`"
+1. 设为 `cookie` 时, `key` 为必传参数，其值为自定义的 cookie name，即 "cookie_`key`"
+1. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_id`。
+1. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。
+
创建上游对象用例：
```json