You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2021/09/08 05:20:43 UTC
[apisix] branch master updated: docs: add external-plugin and update README (#4995)

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 717760c  docs: add external-plugin and update README (#4995)
717760c is described below

commit 717760c2dfb9dcd31b2072cf805a852e200798d8
Author: okaybase <75...@users.noreply.github.com>
AuthorDate: Wed Sep 8 13:20:07 2021 +0800

    docs: add external-plugin and update README (#4995)
    
    Co-authored-by: 罗泽轩 <sp...@gmail.com>
---
 README.md                         |   6 +--
 docs/zh/latest/README.md          |  21 ++++----
 docs/zh/latest/config.json        |   4 ++
 docs/zh/latest/external-plugin.md | 104 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 123 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 83b0bc8..e3e3920 100644
--- a/README.md
+++ b/README.md
@@ -124,9 +124,9 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against
 
   - Zipkin tracing: [Zipkin](docs/en/latest/plugins/zipkin.md)
   - Open source APM: support [Apache SkyWalking](docs/en/latest/plugins/skywalking.md)
-  - works with external service discovery：In addition to the built-in etcd, it also supports [Consul](docs/en/latest/discovery/consul_kv.md) and [Nacos](docs/en/latest/discovery/nacos.md), and [Eureka](docs/en/latest/discovery.md)
+  - Works with external service discovery: In addition to the built-in etcd, it also supports [Consul](docs/en/latest/discovery/consul_kv.md) and [Nacos](docs/en/latest/discovery/nacos.md), and [Eureka](docs/en/latest/discovery.md)
   - Monitoring And Metrics: [Prometheus](docs/en/latest/plugins/prometheus.md)
-  - Clustering: APISIX nodes are stateless, creates clustering of the configuration center, please refer to [etcd Clustering Guide](https://etcd.io/docs/v3.4.0/op-guide/clustering/).
+  - Clustering: APISIX nodes are stateless, creates clustering of the configuration center, please refer to [etcd Clustering Guide](https://etcd.io/docs/v3.5/op-guide/clustering/).
   - High availability: Support to configure multiple etcd addresses in the same cluster.
   - [Dashboard](https://github.com/apache/apisix-dashboard)
   - Version Control: Supports rollbacks of operations.
@@ -141,7 +141,7 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against
 
 - **Highly scalable**
   - [Custom plugins](docs/en/latest/plugin-develop.md): Allows hooking of common phases, such as `rewrite`, `access`, `header filter`, `body filter` and `log`, also allows to hook the `balancer` stage.
-  - [Plugin can be writtern in Java/Go](docs/en/latest/external-plugin.md)
+  - [Plugin can be written in Java/Go/Python](docs/en/latest/external-plugin.md)
   - 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/docs/zh/latest/README.md b/docs/zh/latest/README.md
index 50e1ebf..15443ab 100644
--- a/docs/zh/latest/README.md
+++ b/docs/zh/latest/README.md
@@ -44,12 +44,15 @@ Apache APISIX 的技术架构如下图所示：
 - ![Twitter Follow](https://img.shields.io/twitter/follow/ApacheAPISIX?style=social) - 使用标签 `#ApacheAPISIX` 关注我们并与我们互动。
 - [哔哩哔哩](https://space.bilibili.com/551921247)
 - **新手任务列表**
-  - [Apache APISIX](https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-  - [Apache APISIX ingress controller](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-  - [Apache APISIX dashboard](https://github.com/apache/apisix-dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-  - [Apache APISIX Helm Chart](https://github.com/apache/apisix-helm-chart/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-  - [Docker distribution for APISIX](https://github.com/apache/apisix-docker/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-  - [Apache APISIX Website](https://github.com/apache/apisix-website/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX®](https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Ingress Controller](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX® dashboard](https://github.com/apache/apisix-dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Helm Chart](https://github.com/apache/apisix-helm-chart/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Docker distribution for Apache APISIX®](https://github.com/apache/apisix-docker/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Website](https://github.com/apache/apisix-website/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Java Plugin Runner](https://github.com/apache/apisix-java-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Go Plugin Runner](https://github.com/apache/apisix-go-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+  - [Apache APISIX® Python Plugin Runner](https://github.com/apache/apisix-python-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
 - **微信公众号**
    <br/>![](../../assets/images/OA.jpg)
 - **微信视频号**
@@ -108,7 +111,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
 
   - 多种身份认证方式: [key-auth](plugins/key-auth.md), [JWT](plugins/jwt-auth.md), [basic-auth](plugins/basic-auth.md), [wolf-rbac](plugins/wolf-rbac.md)。
   - [IP 黑白名单](plugins/ip-restriction.md)
-  - [Referer 白名单](plugins/referer-restriction.md)
+  - [Referer 黑白名单](plugins/referer-restriction.md)
   - [IdP 支持](plugins/openid-connect.md): 支持外部的身份认证服务，比如 Auth0，Okta，Authing 等，用户可以借此来对接 Oauth2.0 等认证方式。
   - [限制速率](plugins/limit-req.md)
   - [限制请求数](plugins/limit-count.md)
@@ -123,7 +126,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
   - OpenTracing 可观测性: 支持 [Apache Skywalking](plugins/skywalking.md) 和 [Zipkin](plugins/zipkin.md)。
   - 对接外部服务发现：除了内置的 etcd 外，还支持 [Consul](../../en/latest/discovery/consul_kv.md) 和 [Nacos](../../en/latest/discovery/nacos.md)，以及 [Eureka](discovery.md)。
   - 监控和指标: [Prometheus](plugins/prometheus.md)
-  - 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://etcd.io/docs/v3.4.0/op-guide/clustering/)。
+  - 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://etcd.io/docs/v3.5/op-guide/clustering/)。
   - 高可用：支持配置同一个集群内的多个 etcd 地址。
   - [控制台](https://github.com/apache/apisix-dashboard): 操作 APISIX 集群。
   - 版本控制：支持操作的多次回滚。
@@ -138,7 +141,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
 
 - **高度可扩展**
   - [自定义插件](plugin-develop.md): 允许挂载常见阶段，例如`init`, `rewrite`，`access`，`balancer`,`header filter`，`body filter` 和 `log` 阶段。
-  - [插件可以用 Java/Go 编写](../../en/latest/external-plugin.md)
+  - [插件可以用 Java/Go/Python 编写](../../zh/latest/external-plugin.md)
   - 自定义负载均衡算法：可以在 `balancer` 阶段使用自定义负载均衡算法。
   - 自定义路由: 支持用户自己实现路由算法。
 
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 051dd71..93cd5a8 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -152,6 +152,10 @@
         },
         {
           "type": "doc",
+          "id": "external-plugin"
+        },
+        {
+          "type": "doc",
           "id": "health-check"
         },
         {
diff --git a/docs/zh/latest/external-plugin.md b/docs/zh/latest/external-plugin.md
new file mode 100644
index 0000000..8ca6d8d
--- /dev/null
+++ b/docs/zh/latest/external-plugin.md
@@ -0,0 +1,104 @@
+---
+title: External 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.
+#
+-->
+
+## 什么是 External Plugin 和 Plugin Runner
+
+APISIX 支持使用 Lua 语言编写插件，这种类型的插件在 APISIX 内部执行。
+有时候你想使用其他语言来开发插件，因此，APISIX 支持以 `Sidecar` 的方式加载和运行你写的插件。
+这里的 `Sidecar` 就是 Plugin Runner ，你写的插件叫做 External Plugin 。
+
+## 它是如何工作的
+
+![external-plugin](../../assets/images/external-plugin.png)
+
+当你在 APISIX 中配置了一个 Plugin Runner ，APISIX 将以子进程的方式运行该 Plugin Runner 。
+该子进程与 APISIX 进程从属相同用户。当重启或者重新加载 APISIX 时，该 Plugin Runner 也将被重启。
+
+一旦你为指定路由配置了 `ext-plugin-*` 插件，
+匹配该路由的请求将触发从 APISIX 到  Plugin Runner 的 RPC 调用。
+
+ Plugin Runner 将处理该 RPC 调用，在其侧创建一个请求，运行 External Plugin 并将结果返回给 APISIX 。
+
+ External Plugin 及其执行顺序在这里 `ext-plugin-*` 配置。与其他插件一样， External Plugin 可以动态启用和重新配置。
+
+## 支持的 Plugin Runner
+
+- Java: https://github.com/apache/apisix-java-plugin-runner
+- Go: https://github.com/apache/apisix-go-plugin-runner
+- Python: https://github.com/apache/apisix-python-plugin-runner
+
+## 在 APISIX 中配置 Plugin Runner
+
+在生产环境运行 Plugin Runner ，添加以下配置到 `config.yaml`：
+
+```yaml
+ext-plugin:
+  cmd: ["blah"] # replace it to the real runner executable according to the runner you choice
+```
+
+APISIX 将以子进程的方式管理该 Plugin Runner 。
+
+注意：在 Mac 上，APISIX `v2.6` 无法管理该 Plugin Runner 。
+
+在开发过程中，我们希望单独运行 Plugin Runner ，这样就可以重新启动它，而无需先重新启动 APISIX 。
+
+通过指定环境变量 `APISIX_LISTEN_ADDRESS`, 我们可以使 Plugin Runner 监听一个固定的地址。
+例如：
+
+```bash
+APISIX_LISTEN_ADDRESS=unix:/tmp/x.sock
+```
+
+此时， Plugin Runner 将监听 `/tmp/x.sock`
+
+同时，你需要配置 APISIX 发送 RPC 请求到该固定的地址：
+
+```yaml
+ext-plugin:
+  # cmd: ["blah"] # don't configure the executable!
+  path_for_test: "/tmp/x.sock" # without 'unix:' prefix
+```
+
+在生产环境，不应该使用 `path_for_test`，此时监听的地址将动态生成。
+
+## 常见问题
+
+### 由 APISIX 管理时， Plugin Runner 无法访问我的环境变量
+
+自 `v2.7`，APISIX 可以将环境变量传递给 Plugin Runner 。
+
+然而，默认情况下，Nginx 将隐藏所有环境变量。所以你需要首先在 `conf/config.yaml` 中声明环境变量：
+
+```yaml
+nginx_config:
+  envs:
+    - MY_ENV_VAR
+```
+
+### APISIX 使用 SIGKILL 终止 Plugin Runner ，而不是使用 SIGTERM！
+
+自 `v2.7`，当跑在 OpenResty 1.19+ 时，APISIX 将使用 SIGTERM 来停止 Plugin Runner 。
+
+但是，APISIX 需要等待 Plugin Runner 退出，这样我们才能确保资源得以被释放。
+
+因此，我们先发送 SIGTERM 。然后在 1 秒后，如果 Plugin Runner 仍然在运行，我们将发送 SIGKILL 。