This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new a71f41025 docs: update consumer and upstream docs (#8223)
a71f41025 is described below
commit a71f41025f3cf37469a821a193b071184363c64e
Author: Fei Han <[email protected]>
AuthorDate: Tue Nov 29 15:26:53 2022 +0800
docs: update consumer and upstream docs (#8223)
---
docs/en/latest/terminology/api-gateway.md | 5 +
docs/en/latest/terminology/consumer.md | 159 +++++++------
docs/en/latest/terminology/upstream.md | 67 +++---
docs/zh/latest/admin-api.md | 20 +-
docs/zh/latest/terminology/api-gateway.md | 5 +
docs/zh/latest/terminology/consumer.md | 204 ++++++++++-------
docs/zh/latest/terminology/upstream.md | 356 ++++++++++++++++--------------
7 files changed, 467 insertions(+), 349 deletions(-)
diff --git a/docs/en/latest/terminology/api-gateway.md
b/docs/en/latest/terminology/api-gateway.md
index 435c2260a..0a9e3d69b 100644
--- a/docs/en/latest/terminology/api-gateway.md
+++ b/docs/en/latest/terminology/api-gateway.md
@@ -1,5 +1,10 @@
---
title: API Gateway
+keywords:
+ - APISIX
+ - API Gateway
+ - Gateway
+description: This article mainly introduces the role of the API gateway and
why it is needed.
---
<!--
diff --git a/docs/en/latest/terminology/consumer.md
b/docs/en/latest/terminology/consumer.md
index 3cd665fbd..0b2a1ad3e 100644
--- a/docs/en/latest/terminology/consumer.md
+++ b/docs/en/latest/terminology/consumer.md
@@ -1,5 +1,11 @@
---
title: Consumer
+keywords:
+ - Apache APISIX
+ - API Gateway
+ - APISIX Consumer
+ - Consumer
+description: This article describes the role of the Apache APISIX Consumer
object and how to use the Consumer.
---
<!--
@@ -25,6 +31,8 @@ title: Consumer
For an API gateway, it is usually possible to identify the type of the
requester by using things like their request domain name and client IP address.
A gateway like APISIX can then filter these requests using
[Plugins](./plugin.md) and forward it to the specified
[Upstream](./upstream.md).
+It has the highest priority: Consumer > Route > Plugin Config > Service.
+
But this level of depth can be insufficient on some occasions.
@@ -37,8 +45,8 @@ The fields for defining a Consumer are defined as below.
| Field | Required | Description
|
| ---------- | -------- |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-| `username` | Yes | Name of the consumer
|
-| `plugins` | No | Plugin configuration of the **Consumer**. It has the
highest priority: Consumer > Route > Service. For specific Plugin
configurations, refer the [Plugins](./plugin.md) section. |
+| `username` | True | Name of the consumer.
|
+| `plugins` | False | Plugin configuration of the **Consumer**. For
specific Plugin configurations, please refer the [Plugins](./plugin.md). |
## Identifying a Consumer
@@ -54,83 +62,102 @@ Consumers are useful when you have different consumers
requesting the same API a
Refer to the documentation for the [key-auth](../plugins/key-auth.md)
authentication Plugin to further understand the concept of a Consumer.
+:::note
+
+For more information about the Consumer object, you can refer to the [Admin
API Consumer](../admin-api.md#consumer) object resource introduction.
+
+:::
+
## Example
The example below shows how you can enable a Plugin for a specific Consumer.
-```shell
-# Create a Consumer, specify the authentication plugin key-auth, and enable
the specific plugin limit-count
-$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- },
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+1. Create a Consumer, specify the authentication plugin `key-auth`, and enable
the specific plugin `limit-count`.
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/consumers \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-one"
+ },
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-
-# Create a Router, set routing rules and enable plugin configuration
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+2. Create a Router, set routing rules and enable plugin configuration.
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "key-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
},
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "uri": "/hello"
+ }'
+ ```
-# Send a test request, the first two return to normal, did not reach the speed
limit threshold
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-...
+3. Send a test request, the first two return to normal, did not reach the
speed limit threshold.
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-...
+ ```shell
+ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
+ ```
-# The third test returns 503 and the request is restricted
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-HTTP/1.1 503 Service Temporarily Unavailable
-...
+ The third test returns `503` and the request is restricted.
-```
+ ```shell
+ HTTP/1.1 503 Service Temporarily Unavailable
+ ...
+ ```
We can use the [consumer-restriction](../plugins/consumer-restriction.md)
Plugin to restrict our user "Jack" from accessing the API.
-```shell
-# Add Jack to the blacklist
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "key-auth": {},
- "consumer-restriction": {
- "blacklist": [
- "jack"
- ]
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
+1. Add Jack to the blacklist.
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "key-auth": {},
+ "consumer-restriction": {
+ "blacklist": [
+ "jack"
+ ]
+ }
},
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/hello"
+ }'
+ ```
+
+2. Repeated tests, all return `403`; Jack is forbidden to access this API.
-# Repeated tests, all return 403; Jack is forbidden to access this API
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-HTTP/1.1 403
-...
+ ```shell
+ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
+ ```
-```
+ ```shell
+ HTTP/1.1 403
+ ...
+ ```
diff --git a/docs/en/latest/terminology/upstream.md
b/docs/en/latest/terminology/upstream.md
index b559735d6..923effbf1 100644
--- a/docs/en/latest/terminology/upstream.md
+++ b/docs/en/latest/terminology/upstream.md
@@ -1,5 +1,11 @@
---
title: Upstream
+keywords:
+ - Apache APISIX
+ - API Gateway
+ - APISIX Upstream
+ - Upstream
+description: This article describes the role of the Apache APISIX Upstream
object and how to use the Upstream.
---
<!--
@@ -35,12 +41,13 @@ An Upstream configuration can be directly bound to a Route
or a Service, but the
## Configuration
-In addition to the equalization algorithm selections, Upstream also supports
passive health check and retry for the upstream. You can learn more about this
[here](../admin-api.md#upstream).
+In addition to the equalization algorithm selections, Upstream also supports
passive health check and retry for the upstream. You can learn more about this
[Admin API Upstream](../admin-api.md#upstream).
-To create an Upstream object, you can use the Admin API as shown below:
+To create an Upstream object, you can use the Admin API as shown below.
```shell
-curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"type": "chash",
"key": "remote_addr",
@@ -51,20 +58,22 @@ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H
'X-API-KEY: edd1c9f034335
}'
```
-After creating an Upstream object, it can be referenced by a specific Route or
Service as shown below:
+After creating an Upstream object, it can be referenced by a specific Route or
Service as shown below.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream_id": 1
}'
```
-For convenience, you can directly bind the upstream address to a Route or
Service:
+For convenience, you can directly bind the upstream address to a Route or
Service.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -86,10 +95,11 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
## Example
-The example below shows how you can configure a health check:
+The example below shows how you can configure a health check.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -124,16 +134,17 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-You can learn more about health checks [here](../tutorials/health-check.md).
+You can learn more about health checks
[health-check](../tutorials/health-check.md).
The examples below show configurations that use different `hash_on` types.
-#### Consumer
+### Consumer
-Creating a Consumer object:
+Creating a Consumer object.
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -144,10 +155,11 @@ curl http://127.0.0.1:9180/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-Creating a Route object and enabling the `key-auth` authentication Plugin:
+Creating a Route object and enabling the `key-auth` authentication Plugin.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {}
@@ -170,12 +182,13 @@ To test the request, the `consumer_name` passed for
authentication will be used
curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
```
-#### Cookie
+### Cookie
-Creating a Route and an upstream object:
+Creating a Route and an upstream object.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hash_on_cookie",
"upstream": {
@@ -190,18 +203,20 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-The client can then send a request with a cookie:
+The client can then send a request with a cookie.
```shell
- curl http://127.0.0.1:9080/hash_on_cookie -H "Cookie:
sid=3c183a30cffcda1408daf1c61d47b274"
+ curl http://127.0.0.1:9080/hash_on_cookie \
+ -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
```
-#### Header
+### Header
-Creating a Route and an upstream object:
+Creating a Route and an upstream object.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hash_on_header",
"upstream": {
@@ -216,8 +231,10 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-The client can now send requests with a header. The example below shows using
the header `Content-Type`:
+The client can now send requests with a header. The example below shows using
the header `Content-Type`.
```shell
- curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"
+ curl http://127.0.0.1:9080/hash_on_header \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
+ -H "Content-Type: application/json"
```
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index d2ede2957..d65bf59d8 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -158,7 +158,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10"; \
}
```
-### 支持过滤资源 {#support filtering query}
+### 支持过滤资源 {#support-filtering-query}
在 APISIX v3 版本中，在获取资源列表时，你可以使用 `name`、`label` 和 `uri` 参数过滤资源。支持参数如下：
@@ -209,7 +209,7 @@ Route 也称之为路由，可以通过定义一些规则来匹配客户端的
| GET | /apisix/admin/routes | 无 | 获取资源列表。
|
| GET | /apisix/admin/routes/{id} | 无 | 获取资源。
|
| PUT | /apisix/admin/routes/{id} | {...} | 根据 id 创建资源。
|
-| POST | /apisix/admin/routes | {...} | 创建资源，id 将会自动生成成。
|
+| POST | /apisix/admin/routes | {...} | 创建资源，id 将会自动生成。
|
| DELETE | /apisix/admin/routes/{id} | 无 | 删除指定资源。
|
| PATCH | /apisix/admin/routes/{id} | {...} | 标准 PATCH，修改指定 Route
的部分属性，其他不涉及的属性会原样保留；如果你需要删除某个属性，可以将该属性的值设置为 `null`；当需要修改属性的值为数组时，该属性将全量更新。 |
| PATCH | /apisix/admin/routes/{id}/{path} | {...} | SubPath PATCH，通过
`{path}` 指定 Route 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。两种 PATCH 的区别，请参考使用示例。
|
@@ -542,7 +542,7 @@ Service 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。
| PUT | /apisix/admin/services/{id} | {...} | 创建指定 id 资源。
|
| POST | /apisix/admin/services | {...} | 创建资源，id 由后台服务自动生成。
|
| DELETE | /apisix/admin/services/{id} | 无 | 删除资源。
|
-| PATCH | /apisix/admin/services/{id} | {...} | 标准 PATCH ，修改已有
Service 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
+| PATCH | /apisix/admin/services/{id} | {...} | 标准 PATCH，修改已有
Service 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
| PATCH | /apisix/admin/services/{id}/{path} | {...} | SubPath PATCH，通过
{path} 指定 Service 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。
|
### body 请求参数 {#service-request-body-parameters}
@@ -739,11 +739,11 @@ Consumer 资源请求地址：/apisix/admin/consumers/{username}
| ----------- | ----- | ------- |
-------------------------------------------------------------------------------------------------------------------------------
| ------------------------------------------------ |
| username | 是 | 辅助 | Consumer 名称。
|
|
| group_id | 否 | 辅助 | Consumer Group 名称。
|
|
-| plugins | 否 | Plugin | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route
> Service。对于具体插件配置，请可以参考 [Plugins](#plugin)。 |
|
+| plugins | 否 | Plugin | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route
> Plugin Config > Service。对于具体插件配置，请参考 [Plugins](#plugin)。 |
|
| desc | 否 | 辅助 | consumer 描述。
|
|
| labels | 否 | 匹配规则 | 标识附加属性的键值对。
|
{"version":"v2","build":"16","env":"production"} |
-| create_time | 否 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建。
| 1602883670
|
-| update_time | 否 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建。
| 1602883670
|
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。
| 1602883670
|
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。
| 1602883670
|
Consumer 对象 JSON 配置示例：
@@ -814,7 +814,7 @@ Upstream 资源请求地址：/apisix/admin/upstreams/{id}
| PUT | /apisix/admin/upstreams/{id} | {...} | 创建指定 id 的资源。
|
| POST | /apisix/admin/upstreams | {...} | 创建资源，id
由后台服务自动生成。
|
| DELETE | /apisix/admin/upstreams/{id} | 无 | 删除资源。
|
-| PATCH | /apisix/admin/upstreams/{id} | {...} | 标准 PATCH ，修改已有
Upstream 的部分属性，其他不涉及的属性会原样保留；如果需要删除某个属性，可将该属性的值设置为
`null`；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
+| PATCH | /apisix/admin/upstreams/{id} | {...} | 标准 PATCH，修改已有
Upstream 的部分属性，其他不涉及的属性会原样保留；如果需要删除某个属性，可将该属性的值设置为
`null`；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
| PATCH | /apisix/admin/upstreams/{id}/{path} | {...} | SubPath PATCH，通过
`{path}` 指定 Upstream 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。
|
### body 请求参数 {#upstream-body-request-methods}
@@ -869,7 +869,7 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
- `scheme` 可以设置成 `tls`，表示 `TLS over TCP`。
- `tls.client_cert/key` 可以用来跟上游进行 mTLS 通信。他们的格式和 SSL 对象的 `cert` 和 `key` 一样。
- `tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client
时才能被引用，否则请求会被 APISIX 拒绝。另外，SSL 对象中只有 `cert` 和 `key` 会被使用。
-- `keepalive_pool` 允许 Upstream 有自己单独的连接池。它下属的字段，比如
`requests`，可以用于配置上游连接保持的参数。该特性需要 APISIX 运行于
[APISIX-Base](./FAQ.md#如何构建-apisix-base-环境) 中。
+- `keepalive_pool` 允许 Upstream 有自己单独的连接池。它下属的字段，比如 `requests`，可以用于配置上游连接保持的参数。
Upstream 对象 JSON 配置示例：
@@ -1164,7 +1164,7 @@ Global Rule 资源请求地址：/apisix/admin/global_rules/{id}
| GET | /apisix/admin/global_rules/{id} | 无 | 获取资源。
|
| PUT | /apisix/admin/global_rules/{id} | {...} | 将创建指定 id 的资源。
|
| DELETE | /apisix/admin/global_rules/{id} | 无 | 删除资源。
|
-| PATCH | /apisix/admin/global_rules/{id} | {...} | 标准 PATCH ，修改已有
Global Rule 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
+| PATCH | /apisix/admin/global_rules/{id} | {...} | 标准 PATCH，修改已有
Global Rule 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
| PATCH | /apisix/admin/global_rules/{id}/{path} | {...} | SubPath
PATCH，通过 `{path}` 指定 Global Rule 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。
|
### body 请求参数 {#global-rule-body-request-parameters}
@@ -1220,7 +1220,7 @@ Plugin Config 资源请求地址：/apisix/admin/plugin_configs/{id}
| GET | /apisix/admin/plugin_configs/{id} | 无 | 获取资源。
|
| PUT | /apisix/admin/plugin_configs/{id} | {...} | 根据 id 创建资源。
|
| DELETE | /apisix/admin/plugin_configs/{id} | 无 | 删除资源。
|
-| PATCH | /apisix/admin/plugin_configs/{id} | {...} | 标准 PATCH
，修改已有 Plugin Config 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
+| PATCH | /apisix/admin/plugin_configs/{id} | {...} | 标准
PATCH，修改已有 Plugin Config 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null
即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
| PATCH | /apisix/admin/plugin_configs/{id}/{path} | {...} | SubPath
PATCH，通过 {path} 指定 Plugin Config 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。
|
### body 请求参数 {#plugin-config-body-request-parameters}
diff --git a/docs/zh/latest/terminology/api-gateway.md
b/docs/zh/latest/terminology/api-gateway.md
index 27f5dc034..e3e0ca60d 100644
--- a/docs/zh/latest/terminology/api-gateway.md
+++ b/docs/zh/latest/terminology/api-gateway.md
@@ -1,5 +1,10 @@
---
title: API Gateway
+keywords:
+ - APISIX
+ - API 网关
+ - 网关
+description: 本文主要介绍了 API 网关的作用以及为什么需要 API 网关。
---
<!--
diff --git a/docs/zh/latest/terminology/consumer.md
b/docs/zh/latest/terminology/consumer.md
index 02c15f5ae..cb869a221 100644
--- a/docs/zh/latest/terminology/consumer.md
+++ b/docs/zh/latest/terminology/consumer.md
@@ -1,5 +1,11 @@
---
title: Consumer
+keywords:
+ - APISIX
+ - API 网关
+ - 消费者
+ - Consumer
+description: 本文介绍了 Apache APISIX Consumer 对象的作用以及如何使用 Consumer。
---
<!--
@@ -21,107 +27,137 @@ title: Consumer
#
-->
-对于 API 网关通常可以用请求域名、客户端 IP 地址等字段识别到某类请求方，
-然后进行插件过滤并转发请求到指定上游，但有时候这个深度不够。
+## 描述
+
+Consumer 是某类服务的消费者，需要与用户认证配合才可以使用。当不同的消费者请求同一个 API 时，APISIX 会根据当前请求的用户信息，对应不同的
Plugin 或 Upstream 配置。如果
[Route](./route.md)、[Service](./service.md)、[Consumer](./consumer.md) 和 [Plugin
Config](./plugin-config.md) 都绑定了相同的插件，只有消费者的插件配置会生效。插件配置的优先级由高到低的顺序是：Consumer >
Route > Plugin Config > Service。
+
+对于 API 网关而言，一般情况可以通过请求域名、客户端 IP
地址等字段识别到某类请求方，然后进行插件过滤并转发请求到指定上游。但有时候该方式达不到用户需求，因此 APISIX 支持了 Consumer 对象。
如上图所示，作为 API 网关，需要知道 API Consumer（消费方）具体是谁，这样就可以对不同 API Consumer 配置不同规则。
-| 名称 | 必选项 | 说明
|
-| -------- | ---- |
--------------------------------------------------------------------------------------------------------------------------------
|
-| username | 是 | Consumer 名称。
|
-| plugins | 否 | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route >
Service。对于具体插件配置，可以参考 [Plugins](plugin.md) 章节。 |
+## 配置选项
+
+定义 Consumer 的字段如下：
+
+| 名称 | 必选项 | 描述
|
+| -------- | ---- |
------------------------------------------------------------------------------|
+| username | 是 | Consumer 名称。
|
+| plugins | 否 | Consumer 对应的插件配置。详细信息，请参考 [Plugins](./plugin.md)。 |
+
+## 识别消费者
在 APISIX 中，识别 Consumer 的过程如下图：
-1. 授权认证：比如有 [key-auth](../plugins/key-auth.md)、[JWT](../plugins/jwt-auth.md) 等。
-2. 获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识。
+1. 授权认证：比如有 [key-auth](../plugins/key-auth.md)、[JWT](../plugins/jwt-auth.md) 等；
+2. 获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识；
3. 获取 Consumer 上绑定的 Plugin 或 Upstream 信息：完成对不同 Consumer 做不同配置的效果。
-概括一下，Consumer 是某类服务的消费者，需与用户认证体系配合才能使用。
-比如不同的 Consumer 请求同一个 API，网关服务根据当前请求用户信息，对应不同的 Plugin 或 Upstream 配置。
+你可以参考 [key-auth](../plugins/key-auth.md) 认证授权插件的调用逻辑，进一步理解 Consumer 概念和使用。
-此外，大家也可以参考 [key-auth](../plugins/key-auth.md) 认证授权插件的调用逻辑，辅助大家来进一步理解 Consumer
概念和使用。
+:::note 注意
-如何对某个 Consumer 开启指定插件，可以看下面例子：
+如需了解更多关于 Consumer 对象的信息，你可以参考 [Admin API Consumer](../admin-api.md#consumer)
资源介绍。
-```shell
-# 创建 Consumer ，指定认证插件 key-auth ，并开启特定插件 limit-count
-$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- },
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+:::
+
+## 使用示例
+
+以下示例介绍了如何对某个 Consumer 开启指定插件：
+
+1. 创建 Consumer，指定认证插件 `key-auth`，并开启特定插件 `limit-count`。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/consumers \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-one"
+ },
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-
-# 创建 Router，设置路由规则和启用插件配置
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+2. 创建路由，设置路由规则和启用插件配置。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "key-auth": {}
},
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-
-# 发测试请求，前两次返回正常，没达到限速阈值
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-...
-
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-...
-
-# 第三次测试返回 503，请求被限制
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-HTTP/1.1 503 Service Temporarily Unavailable
-...
-
-```
-
-结合 [consumer-restriction](../plugins/consumer-restriction.md) 插件，限制 jack 对该
route 的访问
-
-```shell
-# 设置黑名单，禁止 jack 访问该 API
-
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "key-auth": {},
- "consumer-restriction": {
- "blacklist": [
- "jack"
- ]
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
},
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "uri": "/hello"
+ }'
+ ```
+
+3. 测试插件。
+
+ 连续发送三次测试请求，前两次返回正常，没达到限速阈值。
+
+ ```shell
+ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
+ ```
+
+ 第三次测试返回 `503`，请求被限制：
+
+ ```shell
+ HTTP/1.1 503 Service Temporarily Unavailable
+ ...
+ ```
+
+通过 [consumer-restriction](../plugins/consumer-restriction.md) 插件，限制用户 `jack`
对该 Route 的访问。
+
+1. 设置黑名单，禁止 jack 访问该 API。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "key-auth": {},
+ "consumer-restriction": {
+ "blacklist": [
+ "jack"
+ ]
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/hello"
+ }'
+ ```
+
+2. 通过以下命令访问该路由，均返回 `403`，`jack` 被禁止访问。
+
+ ```shell
+ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
+ ```
-# 反复测试，均返回 403，jack 被禁止访问
-$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
-HTTP/1.1 403
-...
+ 返回结果：
-```
+ ```
+ HTTP/1.1 403
+ ...
+ ```
diff --git a/docs/zh/latest/terminology/upstream.md
b/docs/zh/latest/terminology/upstream.md
index 88bc251a1..65ef3b5e6 100644
--- a/docs/zh/latest/terminology/upstream.md
+++ b/docs/zh/latest/terminology/upstream.md
@@ -1,5 +1,11 @@
---
title: Upstream
+keywords:
+ - APISIX
+ - API 网关
+ - 上游
+ - Upstream
+description: 本文介绍了 Apache APISIX Upstream 对象的作用以及如何使用 Upstream。
---
<!--
@@ -21,197 +27,219 @@ title: Upstream
#
-->
-Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或
`Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。
+## 描述
-
+Upstream（也称之为上游）是对虚拟主机抽象，即应用层服务或节点的抽象。你可以通过 Upstream 对象对多个服务节点按照配置规则进行负载均衡。
-如上图所示，通过创建 Upstream 对象，在 `Route` 用 ID 方式引用，就可以确保只维护一个对象的值了。
+上游的地址信息可以直接配置到[路由](./route.md)（或[服务](./service.md)）中。
-Upstream 的配置可以被直接绑定在指定 `Route` 中，也可以被绑定在 `Service` 中，不过 `Route`
中的配置优先级更高。这里的优先级行为与 `Plugin` 非常相似。
+
-### 配置参数
+如上图所示，当多个路由（或服务）使用该上游时，你可以单独创建上游对象，在路由中通过使用 `upstream_id` 的方式引用资源，减轻维护压力。
-APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑，具体看这个
[链接](../admin-api.md#upstream)。
+你也可以将上游的信息直接配置在指定路由或服务中，不过路由中的配置优先级更高，优先级行为与[插件](./plugin.md) 非常相似。
-创建上游对象用例：
+## 配置参数
-```shell
-curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "type": "chash",
- "key": "remote_addr",
- "nodes": {
- "127.0.0.1:80": 1,
- "foo.com:80": 2
- }
-}'
-```
-
-上游对象创建后，均可以被具体 `Route` 或 `Service` 引用，例如：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/index.html",
- "upstream_id": 1
-}'
-```
+APISIX 的 Upstream 对象除了基本的负载均衡算法外，还支持对上游做主被动健康检查、重试等逻辑。更多信息，请参考 [Admin API 中的
Upstream 资源](../admin-api.md#upstream)。
-为了方便使用，也可以直接把上游地址直接绑到某个 `Route` 或 `Service` ，例如：
+1. 创建上游对象用例。
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/index.html",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
- }
- },
- "upstream": {
- "type": "roundrobin",
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "type": "chash",
+ "key": "remote_addr",
"nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
-```
-
-下面是一个配置了健康检查的示例：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/index.html",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+ "127.0.0.1:80": 1,
+ "httpbin.org:80": 2
}
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+ 上游对象创建后，可以被路由或服务引用。
+
+2. 在路由中使用创建的上游对象。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/index.html",
+ "upstream_id": 1
+ }'
+ ```
+
+3. 为方便使用，你也可以直接把上游信息直接配置在某个路由或服务。
+
+以下示例是将上游信息直接配置在路由中：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/index.html",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- "type": "roundrobin",
- "retries": 2,
- "checks": {
- "active": {
- "http_path": "/status",
- "host": "foo.com",
- "healthy": {
- "interval": 2,
- "successes": 1
- },
- "unhealthy": {
- "interval": 1,
- "http_failures": 2
+ }'
+ ```
+
+## 使用示例
+
+- 配置健康检查的示例。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/index.html",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ "type": "roundrobin",
+ "retries": 2,
+ "checks": {
+ "active": {
+ "http_path": "/status",
+ "host": "foo.com",
+ "healthy": {
+ "interval": 2,
+ "successes": 1
+ },
+ "unhealthy": {
+ "interval": 1,
+ "http_failures": 2
+ }
}
}
}
- }
-}'
-```
+ }'
+ ```
-更多细节可以参考 [健康检查的文档](../health-check.md)。
+ 更多信息，请参考[健康检查的文档](../tutorials/health-check.md)。
-下面是几个使用不同 `hash_on` 类型的配置示例：
+以下是使用不同 [`hash_on`](../admin-api.md#upstream-body-request-methods) 类型的配置示例：
-#### Consumer
+### Consumer
-创建一个 consumer 对象：
+1. 创建一个 Consumer 对象。
-```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-jack"
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/consumers \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-jack"
+ }
}
- }
-}'
-```
+ }'
+ ```
-新建路由，打开 `key-auth` 插件认证，`upstream` 的 `hash_on` 类型为 `consumer`：
+2. 创建路由，启用 `key-auth` 插件，配置 `upstream.hash_on` 的类型为 `consumer`。
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "key-auth": {}
},
- "type": "chash",
- "hash_on": "consumer"
- },
- "uri": "/server_port"
-}'
-```
-
-测试请求，认证通过后的 `consumer_name` 将作为负载均衡哈希算法的哈希值：
-
-```shell
-curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
-```
-
-##### Cookie
-
-新建路由和 `Upstream`，`hash_on` 类型为 `cookie`：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/hash_on_cookie",
- "upstream": {
- "key": "sid",
- "type": "chash",
- "hash_on": "cookie",
- "nodes": {
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 1
+ },
+ "type": "chash",
+ "hash_on": "consumer"
+ },
+ "uri": "/server_port"
+ }'
+ ```
+
+3. 测试请求，认证通过后的 `consumer_name` 将作为负载均衡哈希算法的哈希值。
+
+ ```shell
+ curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
+ ```
+
+### Cookie
+
+1. 创建路由并配置 `upstream.hash_on` 的类型为 `cookie`。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/hash_on_cookie",
+ "upstream": {
+ "key": "sid",
+ "type": "chash",
+ "hash_on": "cookie",
+ "nodes": {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 1
+ }
}
- }
-}'
-```
-
-客户端请求携带 `Cookie`：
-
-```shell
- curl http://127.0.0.1:9080/hash_on_cookie -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -H "Cookie:
sid=3c183a30cffcda1408daf1c61d47b274"
-```
-
-##### Header
-
-新建路由和 `Upstream`，`hash_on` 类型为 `header`，`key` 为 `content-type`：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/hash_on_header",
- "upstream": {
- "key": "content-type",
- "type": "chash",
- "hash_on": "header",
- "nodes": {
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
+ }'
+ ```
+
+2. 客户端请求携带 `Cookie`。
+
+ ```shell
+ curl http://127.0.0.1:9080/hash_on_cookie \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
+ -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
+ ```
+
+### Header
+
+1. 创建路由并配置 `upstream.hash_on` 的类型为 `header`，`key` 为 `content-type`。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/hash_on_header",
+ "upstream": {
+ "key": "content-type",
+ "type": "chash",
+ "hash_on": "header",
+ "nodes": {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 1
+ }
}
- }
-}'
-```
+ }'
+ ```
-客户端请求携带 `content-type` 的 `header`：
+2. 客户端请求携带 `content-type` 的 `header`。
```shell
- curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"
+ curl http://127.0.0.1:9080/hash_on_header \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
+ -H "Content-Type: application/json"
```
