Version: 3.1

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#

在 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 。