You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/11/10 09:23:13 UTC
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #8262: docs: update global-rule/plugin-config/plugin/ docs
SylviaBABY commented on code in PR #8262:
URL: https://github.com/apache/apisix/pull/8262#discussion_r1018833398
##########
docs/zh/latest/terminology/plugin.md:
##########
@@ -21,15 +27,29 @@ title: Plugin
#
-->
-`Plugin` 表示将在 `HTTP` 请求/响应生命周期期间执行的插件配置。
+## 描述
-`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service`、`Consumer` 或 `Plugin Config` 上。而对于同一个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Plugin Config` > `Service`。
+Plugin 表示将在 HTTP 请求/响应生命周期期间执行的插件配置。Plugin 的配置信息可以直接绑定在 [Route](./route.md) 上，也可以被绑定在 [Service](./service.md)、[Consumer](./consumer.md) 或 [Plugin Config](./plugin-config.md) 上。
-在 `conf/config.yaml` 中，可以声明本地 APISIX 节点都支持哪些插件。这是个白名单机制，不在该白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
-如果你想在现有插件的基础上新增插件，注意需要拷贝 `conf/config-default.yaml` 的插件节点内容到 `conf/config.yaml` 的插件节点中。
+你也可以参考 [Admin API](../admin-api.md#plugin) 了解如何使用该资源。
-一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。
-插件运行先后顺序是根据插件自身的优先级来决定的，例如：
+:::note 注意
+
+对于同一个插件的配置，只能有一个是有效的，优先级为 Consumer > Route > Plugin Config > Service。
+
+:::
+
+## 配置简介
+
+如果你想在现有插件的基础上新增插件，请复制 `./conf/config-default.yaml` 中的 `plugins` 参数下的插件列表到 `./conf/config.yaml` 的 `plugins` 参数中。
+
+:::tip 提示
+
+在 `./conf/config.yaml` 中的 `plugins` 参数中，可以声明本地 APISIX 节点支持了哪些插件。这是个白名单机制，不在该白名单的插件配置，都将会被自动忽略。该特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
Review Comment:
```suggestion
在 `./conf/config.yaml` 中的 `plugins` 参数中，可以声明本地 APISIX 节点支持了哪些插件。这是个白名单机制，不在该白名单的插件配置将被自动忽略。该特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
```
##########
docs/zh/latest/terminology/plugin.md:
##########
@@ -21,15 +27,29 @@ title: Plugin
#
-->
-`Plugin` 表示将在 `HTTP` 请求/响应生命周期期间执行的插件配置。
+## 描述
-`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service`、`Consumer` 或 `Plugin Config` 上。而对于同一个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Plugin Config` > `Service`。
+Plugin 表示将在 HTTP 请求/响应生命周期期间执行的插件配置。Plugin 的配置信息可以直接绑定在 [Route](./route.md) 上，也可以被绑定在 [Service](./service.md)、[Consumer](./consumer.md) 或 [Plugin Config](./plugin-config.md) 上。
-在 `conf/config.yaml` 中，可以声明本地 APISIX 节点都支持哪些插件。这是个白名单机制，不在该白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
-如果你想在现有插件的基础上新增插件，注意需要拷贝 `conf/config-default.yaml` 的插件节点内容到 `conf/config.yaml` 的插件节点中。
+你也可以参考 [Admin API](../admin-api.md#plugin) 了解如何使用该资源。
-一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。
-插件运行先后顺序是根据插件自身的优先级来决定的，例如：
+:::note 注意
+
+对于同一个插件的配置，只能有一个是有效的，优先级为 Consumer > Route > Plugin Config > Service。
Review Comment:
```suggestion
对于同一个插件的配置，只能有一个是有效的，其插件配置优先级为 Consumer > Route > Plugin Config > Service。
```
##########
docs/en/latest/terminology/plugin-config.md:
##########
@@ -26,45 +26,60 @@ description: Plugin Config in Apache APISIX.
#
-->
+## Description
+
Plugin Configs are used to extract commonly used [Plugin](./plugin.md) configurations and can be bound directly to a [Route](./route.md).
+While configuring the same plugin, only one copy of the configuration is valid. The order of precedence is always `Consumer` > `Consumer Group` > `Route` > `plugin_config` > `Service`.
+
+## Example
+
The example below illustrates how to create a Plugin Config and bind it to a Route:
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "desc": "blah",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "desc": "blah",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503
+ }
}
- }
-}'
-```
+ }'
+ ```
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uris": ["/index.html"],
- "plugin_config_id": 1,
- "upstream": {
- "type": "roundrobin",
- "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 -i -d '
+ {
+ "uris": ["/index.html"],
+ "plugin_config_id": 1,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
-```
+ }'
+ ```
-When APISIX can't find the Plugin Config with the `id`, the requests reaching this Route are terminated with a status code of 503.
+When APISIX can't find the Plugin Config with the `id`, the requests reaching this Route are terminated with a status code of `503`.
-If a Route already has the `plugins` field configured, the plugins in the Plugin Config will effectively be merged to it. The same plugin in the Plugin Config will not override the ones configured directly in the Route.
+:::note
-For example, if we configure a Plugin Config as shown below
+If a Route already has the `plugins` field configured, the plugins in the Plugin Config will effectively be merged to it.
-```
+The same plugin in the Plugin Config will not override the ones configured directly in the Route. For more information, see [Plugin](./plugin.md).
+
+:::
+
+For example, if you configure a Plugin Config as shown below
Review Comment:
```suggestion
For example, if you configure a Plugin Config as shown below:
```
##########
docs/zh/latest/terminology/plugin.md:
##########
@@ -60,24 +77,30 @@ local _M = {
}
```
-并不是所有插件都有具体配置项，比如 `prometheus` 下是没有任何具体配置项，这时候用一个空的对象标识即可。
+并不是所有插件都有具体配置项，比如 `[prometheus](../plugins/prometheus.md)` 下是没有任何具体配置项，此时可以使用一个空对象启用该插件。
+
+如果一个请求因为某个插件而被拒绝，会有类似如下 `warn` 级别的日志：
-如果一个请求因为某个插件而被拒绝，会有类似这样的 warn 日志：`ip-restriction exits with http status code 403`。
+```shell
-## 插件通用配置
+ip-restriction exits with http status code 403
-通过 `_meta` 配置项可以将一些通用的配置应用于插件，具体配置项如下：
+```
-| 名称 | 类型 | 描述 |
-|--------------|------|----------------|
-| disable | boolean | 是否禁用该插件。 |
-| error_response | string/object | 自定义错误响应。 |
-| priority | integer | 自定义插件优先级。 |
-| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var, operator, val} 元素组成列表，类似：{{var, operator, val}, {var, operator, val}, ...}}。例如 `{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与 NGINX 内部自身变量命名是保持一致。操作符的具体用法请看[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的 operator-list 部分。|
+## 通用配置
-### 禁用插件
+通过 `_meta` 配置项可以将一些通用的配置应用于插件，你可以参考下文使用这些通用配置。通用配置如下：
-通过 `disable` 配置，你可以新增一个处于禁用状态的插件，请求不会经过该插件。
+| 名称 | 类型 | 描述 |
+|--------------- |-------------- |----------------|
+| disable | boolean | 当设置为 `true` 时，则禁用该插件。可选值为 `true` 和 `false`。 |
+| error_response | string/object | 自定义错误响应。 |
+| priority | integer | 自定义插件优先级。 |
+| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var, operator, val} 元素组成列表，类似：`{{var, operator, val}, {var, operator, val}, ...}}`。例如 `{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与 NGINX 内部自身变量命名是保持一致。操作符的使用方法，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)。|
+
+### 禁用指定插件
+
+通过 `disable` 参数，你可以新增一个处于禁用状态的插件，请求不会经过该插件。
Review Comment:
```suggestion
通过 `disable` 参数，你可以将某个插件调整为“禁用状态”，即请求不会经过该插件。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org