diff --git a/README.md b/README.md index 0793576..014165a 100644 --- a/README.md +++ b/README.md @@ -19,3 +19,40 @@ # Python Plugin Runner for Apache APISIX +[![Build Status](https://github.com/apache/apisix-python-plugin-runner/actions/workflows/runner-test.yml/badge.svg?branch=master)](https://github.com/apache/apisix-python-plugin-runner/actions) +[![Build Status](https://github.com/apache/apisix-python-plugin-runner/actions/workflows/runner-lint.yml/badge.svg?branch=master)](https://github.com/apache/apisix-python-plugin-runner/actions) + +Runs [Apache APISIX](http://apisix.apache.org/) plugins written in Python. Implemented as a sidecar that accompanies +APISIX. + +![apisix-plugin-runner-overview](./docs/assets/images/apisix-plugin-runner-overview.png) + +# Why apisix-python-plugin-runner + +APISIX offers many full-featured plugins covering areas such as authentication, security, traffic control, serverless, +analytics & monitoring, transformations, logging. + +It also provides highly extensible API, allowing common phases to be mounted, and users can use these api to develop +their own plugins. + +APISIX supports writing plugins in multiple languages in +version [2.7.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#270), this project is APISIX Python side +implementation that supports writing plugins in Python. + +# Use apisix-python-plugin-runner + +For configuration and use, please refer to the [Getting Started](./docs/en/latest/getting-started.md) document. + +# Get Involved in Development + +Welcome to make contributions, but before you start, please check out +[Developer Guide](./docs/en/latest/developer-guide.md) to learn how to run and debug `apisix-python-plugin-runner` +in your own environment. + +# Status + +This project is currently in the experimental stage and it is not recommended to be used in a production environment. + +# License + +[Apache 2.0 LICENSE](./LICENSE) \ No newline at end of file diff --git a/docs/assets/images/apisix-plugin-runner-overview.png b/docs/assets/images/apisix-plugin-runner-overview.png new file mode 100644 index 0000000..702a09d Binary files /dev/null and b/docs/assets/images/apisix-plugin-runner-overview.png differ diff --git a/docs/en/latest/developer-guide.md b/docs/en/latest/developer-guide.md new file mode 100644 index 0000000..2d1efb8 --- /dev/null +++ b/docs/en/latest/developer-guide.md @@ -0,0 +1,96 @@ +--- +title: Developer Guide +--- + + + +## Overview + +This documentation explains how to develop this project. + + +## Prerequisites + +* Python 3.6+ +* APISIX 2.7.0 + + +## Debug + +- Run `make setup` Installation dependencies +- Run `export PYTHONPATH=$PYTHONPATH:/path/to/apisix-python-plugin-runner` loading project path +- Run `APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py start` +to start it. + + +## Plugin + +#### Plugin directory +``` +/path/to/apisix-python-plugin-runner/apisix/plugin +``` +the `.py` files in this directory autoload + + +#### Plugin example +``` +/path/to/apisix-python-plugin-runner/apisix/plugin/say.py +``` + +#### Plugin Format +```python +from apisix.runner.plugin.base import Base +from apisix.runner.http.request import Request +from apisix.runner.http.response import Response + + +class Say(Base): + def __init__(self): + super(Say, self).__init__(self.__class__.__name__) + + def filter(self, request: Request, response: Response): + headers = request.headers + headers["X-Resp-A6-Runner"] = "Python" + response.body = "Hello, Python Runner of APISIX" + response.headers = headers +``` +- The plugin must inherit the `Base` class +- The plugin must implement the `filter` function +- `filter` function parameters can only contain `Request` and `Response` classes as parameters +- Request parameter can get request information +- Response parameter can set response information +- `self.config` can get plug-in configuration information + + +## Test + +Run `make test`. + + +## Data Format + +[FlatBuffers](https://github.com/google/flatbuffers) + + +## Data Protocol + +``` +1 byte of type + 3 bytes of length + data +``` diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/getting-started.md new file mode 100644 index 0000000..1550e46 --- /dev/null +++ b/docs/en/latest/getting-started.md @@ -0,0 +1,124 @@ +--- +title: Getting started +--- + + + +## Overview +This document explains how to use Python Runner + +## Prerequisites + +* Python 3.6+ +* APISIX 2.7.0 + + +## Installation + +```bash +$ git clone https://github.com/apache/apisix-python-plugin-runner.git +$ cd apisix-python-plugin-runner +$ make install +``` + +## Launch + +### Configuration Python Runner + +> Development Mode + +#### Run APISIX Python Runner +```bash +$ cd /path/to/apisix-python-plugin-runner +$ APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py start +``` + +#### Modify APISIX configuration file +```bash +$ vim /path/to/apisix/conf/config.yaml +apisix: + admin_key: + - name: "admin" + key: edd1c9f034335f136f87ad84b625c8f1 + role: admin +ext-plugin: + path_for_test: /tmp/runner.sock +``` + +> Production Mode + +#### Modify APISIX configuration file +```bash +$ vim /path/to/apisix/conf/config.yaml +apisix: + admin_key: + - name: "admin" + key: edd1c9f034335f136f87ad84b625c8f1 + role: admin +ext-plugin: + cmd: [ "python3", "/path/to/apache/apisix-python-plugin-runner/apisix/main.py", "start" ] +``` + +### Start or Restart APISIX +```bash +$ cd /path/to/apisix +# Start or Restart +$ ./bin/apisix [ start | restart ] +``` + +### Configure APISIX Routing Rule +```bash +$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri": "/get", + "plugins": { + "ext-plugin-pre-req": { + "conf": [ + { "name": "say", "value":"{\"body\":\"hello\"}"} + ] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "127.0.0.1:1980": 1 + } + } +} +' +``` + + +# Testing +```bash +$ curl http://127.0.0.1:9080/get -i +HTTP/1.1 200 OK +Date: Fri, 13 Aug 2021 13:39:18 GMT +Content-Type: text/plain; charset=utf-8 +Transfer-Encoding: chunked +Connection: keep-alive +host: 127.0.0.1:9080 +accept: */* +user-agent: curl/7.64.1 +X-Resp-A6-Runner: Python +Server: APISIX/2.7 + +Hello, Python Runner of APISIX +```