External Plugin

什么是 External Plugin 和 Plugin Runner

APISIX 支持使用 Lua 语言编写插件，这种类型的插件在 APISIX 内部执行。 有时候你想使用其他语言来开发插件，因此，APISIX 支持以 Sidecar 的方式加载和运行你写的插件。 这里的 Sidecar 就是 Plugin Runner，你写的插件叫做 External Plugin。

它是如何工作的

当你在 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 内部实现感兴趣，请参考这份文档： The Implementation of Plugin Runner

支持的 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
• JavaScript: https://github.com/zenozeng/apisix-javascript-plugin-runner

在 APISIX 中配置 Plugin Runner

在生产环境运行 Plugin Runner，添加以下配置到 config.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 监听一个固定的地址。 例如：

APISIX_LISTEN_ADDRESS=unix:/tmp/x.sock

此时，Plugin Runner 将监听 /tmp/x.sock

同时，你需要配置 APISIX 发送 RPC 请求到该固定的地址：

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 中声明环境变量：

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。