This is an automated email from the ASF dual-hosted git repository.
spacewander 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 edd3e0ee5 docs(ext-plugin-post-resp): add ext-plugin-post-resp plugin
documentation (#7306)
edd3e0ee5 is described below
commit edd3e0ee5052b3068bb13214dea6667563cec181
Author: soulbird <[email protected]>
AuthorDate: Thu Jun 23 14:27:39 2022 +0800
docs(ext-plugin-post-resp): add ext-plugin-post-resp plugin documentation
(#7306)
---
docs/assets/images/external-plugin.png | Bin 330391 -> 301675 bytes
docs/en/latest/config.json | 3 +-
docs/en/latest/plugins/ext-plugin-post-resp.md | 109 ++++++++++++++++++++++++
docs/zh/latest/config.json | 3 +-
docs/zh/latest/external-plugin.md | 1 +
docs/zh/latest/plugins/ext-plugin-post-resp.md | 111 +++++++++++++++++++++++++
6 files changed, 225 insertions(+), 2 deletions(-)
diff --git a/docs/assets/images/external-plugin.png
b/docs/assets/images/external-plugin.png
index a0b3d94c1..38c3cdebc 100644
Binary files a/docs/assets/images/external-plugin.png and
b/docs/assets/images/external-plugin.png differ
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 081ba7ec0..0e853b539 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -49,7 +49,8 @@
"plugins/real-ip",
"plugins/server-info",
"plugins/ext-plugin-pre-req",
- "plugins/ext-plugin-post-req"
+ "plugins/ext-plugin-post-req",
+ "plugins/ext-plugin-post-resp"
]
},
{
diff --git a/docs/en/latest/plugins/ext-plugin-post-resp.md
b/docs/en/latest/plugins/ext-plugin-post-resp.md
new file mode 100644
index 000000000..9a79dba91
--- /dev/null
+++ b/docs/en/latest/plugins/ext-plugin-post-resp.md
@@ -0,0 +1,109 @@
+---
+title: ext-plugin-post-resp
+keywords:
+ - APISIX
+ - Plugin
+ - ext-plugin-post-resp
+description: This document contains information about the Apache APISIX
ext-plugin-post-resp Plugin.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Description
+
+The `ext-plugin-post-resp` Plugin is for running specific external Plugins in
the Plugin Runner before executing the built-in Lua Plugins.
+
+The `ext-plugin-post-resp` plugin will be executed after the request gets a
response from the upstream.
+
+After enabling this plugin, APISIX will use the
[lua-resty-http](https://github.com/api7/lua-resty-http) library to make
requests to the upstream, this results in:
+
+- [proxy-control](./proxy-control.md) plugin is not available
+- [proxy-mirror](./proxy-mirror.md) plugin is not available
+- [proxy-cache](./proxy-cache.md) plugin is not available
+- [mTLS Between APISIX and
Upstream](../mtls.md#mtls-between-apisix-and-upstream) function is not
available yet
+
+See [External Plugin](../external-plugin.md) to learn more.
+
+:::note
+
+Execution of External Plugins will affect the response of the current request.
+
+External Plugin does not yet support getting request context information.
+
+External Plugin does not yet support getting the response body of an upstream
response.
+
+:::
+
+## Attributes
+
+| Name | Type | Required | Default | Valid values
| Description
|
+|-------------------|---------|----------|---------|-----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| conf | array | False | | [{"name": "ext-plugin-A",
"value": "{\"enable\":\"feature\"}"}] | List of Plugins and their
configurations to be executed on the Plugin Runner.
|
+| allow_degradation | boolean | False | false |
| Sets Plugin degradation when the Plugin
Runner is not available. When set to `true`, requests are allowed to continue. |
+
+## Enabling the Plugin
+
+The example below enables the `ext-plugin-post-resp` Plugin on a specific
Route:
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "ext-plugin-post-resp": {
+ "conf" : [
+ {"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}
+ ]
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+## Example usage
+
+Once you have configured the External Plugin as shown above, you can make a
request to execute the Plugin:
+
+```shell
+curl -i http://127.0.0.1:9080/index.html
+```
+
+This will reach the configured Plugin Runner and the `ext-plugin-A` will be
executed.
+
+## Disable Plugin
+
+To disable the `ext-plugin-post-resp` Plugin, you can delete the corresponding
JSON configuration from the Plugin configuration. APISIX will automatically
reload and you do not have to restart for this to take effect.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 940f16015..92b2967f3 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -48,7 +48,8 @@
"plugins/real-ip",
"plugins/server-info",
"plugins/ext-plugin-post-req",
- "plugins/ext-plugin-pre-req"
+ "plugins/ext-plugin-pre-req",
+ "plugins/ext-plugin-post-resp"
]
},
{
diff --git a/docs/zh/latest/external-plugin.md
b/docs/zh/latest/external-plugin.md
index 3e8049f86..07b8fbaa3 100644
--- a/docs/zh/latest/external-plugin.md
+++ b/docs/zh/latest/external-plugin.md
@@ -32,6 +32,7 @@ APISIX 支持使用 Lua 语言编写插件，这种类型的插件在 APISIX 内
当你在 APISIX 中配置了一个 Plugin Runner ，APISIX 将以子进程的方式运行该 Plugin Runner 。
+
该子进程与 APISIX 进程从属相同用户。当重启或者重新加载 APISIX 时，该 Plugin Runner 也将被重启。
一旦你为指定路由配置了 `ext-plugin-*` 插件，
diff --git a/docs/zh/latest/plugins/ext-plugin-post-resp.md
b/docs/zh/latest/plugins/ext-plugin-post-resp.md
new file mode 100644
index 000000000..2027e3e83
--- /dev/null
+++ b/docs/zh/latest/plugins/ext-plugin-post-resp.md
@@ -0,0 +1,111 @@
+---
+title: ext-plugin-post-resp
+keywords:
+ - APISIX
+ - Plugin
+ - ext-plugin-post-resp
+description: 本文介绍了关于 Apache APISIX `ext-plugin-post-resp` 插件的基本信息及使用方法。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+`ext-plugin-post-resp` 插件用于在执行内置 Lua 插件之前和在 Plugin Runner 内运行特定的 External
Plugin。
+
+`ext-plugin-post-resp` 插件将在请求获取到上游的响应之后执行。
+
+启用本插件之后，APISIX 将使用 [lua-resty-http](https://github.com/api7/lua-resty-http)
库向上游发起请求，这会导致：
+
+- [proxy-control](./proxy-control.md) 插件不可用
+- [proxy-mirror](./proxy-mirror.md) 插件不可用
+- [proxy-cache](./proxy-cache.md) 插件不可用
+- [APISIX 与上游间的双向认证](../mtls.md#apisix-与上游间的双向认证) 功能尚不可用
+
+如果你想了解更多关于 External Plugin 的信息，请参考 [External Plugin](../external-plugin.md) 。
+
+:::note
+
+External Plugin 执行的结果会影响当前请求的响应。
+
+External Plugin 尚不支持获取请求的上下文信息。
+
+External Plugin 尚不支持获取上游响应的响应体。
+
+:::
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| ----------------- | ------ | ------ | ------- |
--------------------------------------------------------------- |
--------------------------------------------------------------------------------
|
+| conf | array | 否 | | [{"name": "ext-plugin-A",
"value": "{\"enable\":\"feature\"}"}] | 在 Plugin Runner 内执行的插件列表的配置。
|
+| allow_degradation | boolean| 否 | false | [false, true]
| 当 Plugin Runner 临时不可用时是否允许请求继续，当值设置为
`true` 时则自动允许请求继续。 |
+
+## 启用插件
+
+以下示例展示了如何在指定路由中启用 `ext-plugin-post-resp` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "ext-plugin-post-resp": {
+ "conf" : [
+ {"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}
+ ]
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+## 测试插件
+
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
+
+```shell
+curl -i http://127.0.0.1:9080/index.html
+```
+
+在返回结果中可以看到刚刚配置的 Plugin Runner 已经被触发，同时 `ext-plugin-A` 插件也已经被执行。
+
+## 禁用插件
+
+当你需要禁用 `ext-plugin-post-resp` 插件时，可通过以下命令删除相应的 JSON 配置，APISIX
将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
