You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by to...@apache.org on 2021/05/31 01:05:24 UTC
[apisix] branch master updated: docs(ext-plugin): init docs (#4321)
This is an automated email from the ASF dual-hosted git repository.
tokers 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 11b5ec7 docs(ext-plugin): init docs (#4321)
11b5ec7 is described below
commit 11b5ec7b2fcf32656a15673ec1fd8e9e21958d3f
Author: 罗泽轩 <sp...@gmail.com>
AuthorDate: Mon May 31 09:05:17 2021 +0800
docs(ext-plugin): init docs (#4321)
Signed-off-by: spacewander <sp...@gmail.com>
---
docs/assets/images/external-plugin.png | Bin 0 -> 617453 bytes
docs/en/latest/config.json | 8 ++-
docs/en/latest/external-plugin.md | 91 +++++++++++++++++++++++
docs/en/latest/plugin-develop.md | 3 +
docs/en/latest/plugins/ext-plugin-post-req.md | 29 ++++++++
docs/en/latest/plugins/ext-plugin-pre-req.md | 100 ++++++++++++++++++++++++++
6 files changed, 230 insertions(+), 1 deletion(-)
diff --git a/docs/assets/images/external-plugin.png b/docs/assets/images/external-plugin.png
new file mode 100644
index 0000000..bc5a3f5
Binary files /dev/null and b/docs/assets/images/external-plugin.png differ
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index aec85b6..709791f 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -43,7 +43,9 @@
"plugins/serverless",
"plugins/redirect",
"plugins/echo",
- "plugins/server-info"
+ "plugins/server-info",
+ "plugins/ext-plugin-pre-req",
+ "plugins/ext-plugin-post-req"
]
},
{
@@ -208,6 +210,10 @@
},
{
"type": "doc",
+ "id": "external-plugin"
+ },
+ {
+ "type": "doc",
"id": "plugin-interceptors"
},
{
diff --git a/docs/en/latest/external-plugin.md b/docs/en/latest/external-plugin.md
new file mode 100644
index 0000000..0eea264
--- /dev/null
+++ b/docs/en/latest/external-plugin.md
@@ -0,0 +1,91 @@
+---
+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.
+#
+-->
+
+## What are external plugin and plugin runner
+
+APISIX supports writing plugins in Lua. This type of plugins will be executed
+inside APISIX. Sometimes you want to develop plugin in other languages, so APISIX
+provides sidecars that loading your plugins and run them when the requests hit
+APISIX. These sidecars are called plugin runners and your plugins are called
+external plugins.
+
+## How does it work
+
+
+
+When you configure a plugin runner in APISIX, APISIX will run the plugin runner
+as a subprocess. The process will belong to the same user of the APISIX
+process. When we restart or reload APISIX, the plugin runner will be restarted too.
+
+Once you have configured `ext-plugin-*` plugins for a given route, the requests
+which hit the route will trigger RPC call from APISIX to the plugin runner via
+unix socket.
+
+The plugin runner will handle the RPC call, create a fake request at its side,
+run external plugins and return the result back to APISIX.
+
+The target external plugins and the execution order are configured in the `ext-plugin-*`
+plugins. Like other plugins, they can be enabled and reconfigured on the fly.
+
+## Supported plugin runners
+
+Java: https://github.com/apache/apisix-java-plugin-runner
+Go: https://github.com/apache/apisix-go-plugin-runner
+
+## Configuration for plugin runner in APISIX
+
+To run plugin runner in the prod, add the section below to `config.yaml`:
+
+```yaml
+ext-plugin:
+ cmd: ["blah"] # replace it to the real runner executable according to the runner you choice
+```
+
+Then APISIX will manage the runner as its subprocess.
+
+Note: APISIX can't manage the runner on the Mac. It is fine, we can run the runner by ourselves
+during development.
+
+During development, we want to run the runner separately so that we can restart it without
+restarting APISIX first.
+
+By specifying the environment variable `APISIX_LISTEN_ADDRESS`, we can force the runner to
+listen to a fixed address.
+For instance:
+
+```bash
+APISIX_LISTEN_ADDRESS=unix:/tmp/x.sock ./the_runner
+```
+
+will force the runner to listen to `/tmp/x.sock`.
+
+Then you need to configure APISIX to send RPC to the fixed address:
+
+```yaml
+ext-plugin:
+ # cmd: ["blah"] # don't configure the executable!
+ path_for_test: "/tmp/x.sock" # without 'unix:' prefix
+```
+
+In the prod environment, `path_for_test` should not be used and the unix socket
+path will be generated dynamically.
diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md
index df072c0..bf6d263 100644
--- a/docs/en/latest/plugin-develop.md
+++ b/docs/en/latest/plugin-develop.md
@@ -37,6 +37,9 @@ title: Plugin Develop
- [Register public API](#register-public-api)
- [Register control API](#register-control-api)
+This documentation is about developing plugin in Lua. For other languages,
+see [external plugin](./external-plugin.md).
+
## where to put your plugins
There are two ways to add new features based on APISIX.
diff --git a/docs/en/latest/plugins/ext-plugin-post-req.md b/docs/en/latest/plugins/ext-plugin-post-req.md
new file mode 100644
index 0000000..7aac1bd
--- /dev/null
+++ b/docs/en/latest/plugins/ext-plugin-post-req.md
@@ -0,0 +1,29 @@
+---
+title: ext-plugin-post-req
+---
+
+<!--
+#
+# 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-req` is almost the same as `ext-plugin-pre-req`.
+
+The only difference is that it runs after executing builtin Lua plugins and
+before proxying to the upstream.
+
+See the documentation of [ext-plugin-pre-req](./ext-plugin-pre-req.md) for how to configure it.
diff --git a/docs/en/latest/plugins/ext-plugin-pre-req.md b/docs/en/latest/plugins/ext-plugin-pre-req.md
new file mode 100644
index 0000000..e5a6fb7
--- /dev/null
+++ b/docs/en/latest/plugins/ext-plugin-pre-req.md
@@ -0,0 +1,100 @@
+---
+title: ext-plugin-pre-req
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Summary
+
+- [**Name**](#name)
+- [**Attributes**](#attributes)
+- [**How To Enable**](#how-to-enable)
+- [**Test Plugin**](#test-plugin)
+- [**Disable Plugin**](#disable-plugin)
+
+## Name
+
+The `ext-plugin-pre-req` runs specific external plugins in the plugin runner, before
+executing any builtin Lua plugins.
+
+To know what is the plugin runner, see [external plugin](../external-plugin.md) section.
+
+The result of external plugins execution will affect the behavior of the current request.
+
+## Attributes
+
+| Name | Type | Requirement | Default | Valid | Description |
+| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| conf | array | optional | | [{"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}] | The plugins list which will be executed at the plugin runner with their configuration |
+
+## How To Enable
+
+Here's an example, enable this plugin on the specified 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-pre-req": {
+ "conf" : [
+ {"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}
+ ]
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "39.97.63.215:80": 1
+ }
+ }
+}'
+```
+
+## Test Plugin
+
+Use curl to access:
+
+```shell
+curl -i http://127.0.0.1:9080/index.html
+```
+
+You will see the configured plugin runner will be hit and plugin `ext-plugin-A`
+is executed at that side.
+
+## Disable Plugin
+
+When you want to disable this plugin, it is very simple,
+you can delete the corresponding json configuration in the plugin configuration,
+no need to restart the service, it will take effect immediately:
+
+```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": {
+ "39.97.63.215:80": 1
+ }
+ }
+}'
+```
+
+This plugin has been disabled now. It works for other plugins.