From a71f41025f3cf37469a821a193b071184363c64e Mon Sep 17 00:00:00 2001 From: Fei Han <97138894+hf400159@users.noreply.github.com> Date: Tue, 29 Nov 2022 15:26:53 +0800 Subject: [PATCH] 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 435c2260a8b9..0a9e3d69b18c 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. --- -对于 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 对象。 ![Consumer](../../../assets/images/consumer-who.png) 如上图所示，作为 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 的过程如下图： ![Consumer Internal](../../../assets/images/consumer-internal.png) -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 88bc251a1a69..65ef3b5e6135 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。 --- -Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。 +## 描述 -![Upstream 示例](../../../assets/images/upstream-example.png) +Upstream（也称之为上游）是对虚拟主机抽象，即应用层服务或节点的抽象。你可以通过 Upstream 对象对多个服务节点按照配置规则进行负载均衡。 -如上图所示，通过创建 Upstream 对象，在 `Route` 用 ID 方式引用，就可以确保只维护一个对象的值了。 +上游的地址信息可以直接配置到[路由](./route.md)（或[服务](./service.md)）中。 -Upstream 的配置可以被直接绑定在指定 `Route` 中，也可以被绑定在 `Service` 中，不过 `Route` 中的配置优先级更高。这里的优先级行为与 `Plugin` 非常相似。 +![Upstream 示例](../../../assets/images/upstream-example.png) -### 配置参数 +如上图所示，当多个路由（或服务）使用该上游时，你可以单独创建上游对象，在路由中通过使用 `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" ```