旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

Pythonでプラグインを書く

Python PDK

Pythonプラグイン開発の Kong Gatewayサポートは、kong-python-pdkライブラリによって提供されます。ライブラリは、プラグインサーバーとKong GatewayのインターフェイスとなるKong固有の関数を提供します。

インストール

プラグインサーバーと PDK をグローバルにインストールするには、 pipを使用します。

pip3 install kong-pdk

開発

Kong GatewayPythonプラグインの実装には次の属性があります。

Schema = (
    { "message": { "type": "string" } },
)
version = '0.1.0'
priority = 0
class Plugin(object):
  pass

Pluginという名前のクラスは、このプラグインを実装するクラスを定義します。
Schemaという名のディクショナリで、プラグインに期待される値とデータ型を定義します。
バージョン番号とそれぞれの実行の優先順位を定義する変数versionとpriority。

注：このリポジトリには、サンプルのPythonプラグインとAPIリファレンスが含まれています。

フェーズハンドラ

リクエスト処理ライフサイクルのさまざまなポイントで実行されるカスタムロジックを実装できます。アクセスフェーズ中にカスタムコードを実行するには、 access という名前の関数を定義します。

class Plugin(object):
    def __init__(self, config):
        self.config = config
    def access(self, kong):
      pass

同じ関数シグネチャを使用して、以下のフェーズでカスタムロジックを実装できます。

certificate
rewrite
access
response
preread
log

responseハンドラが存在すると、プロキシでのバッファリングモードが自動的に有効になります。

注：フェーズハンドラメソッドの定義には、位置引数が必要です。以下の例では、位置引数はkongと呼ばれます。位置引数はPDK関数のルートオブジェクトとして使用できます。つまり、この引数を使用して kong.log.infoやkong.request.get_headerなどの特定のPDK関数を呼び出すことができます。

型ヒント

タイプヒントのサポートが利用可能です。タイプヒンとIDEのオートコンプリートトを使用するには、フェーズハンドラー関数に kong パラメータを追加します。

import kong_pdk.pdk.kong as kong
class Plugin(object):
    def __init__(self, config):
        self.config = config
    def access(self, kong: kong.kong):
        host, err = kong.request.get_header("host")

警告: kong_pdk.pdk.kongモジュール内のクラスと関数は型ヒントにのみ使用されるため、直接使用することはできません。PDK 関数を呼び出すには、フェーズハンドラーのパラメータとして渡されるkongオブジェクトを使用します。PDK関数をフェーズハンドラーの外部で呼び出す場合は、外部コードに kong オブジェクトも渡す必要があることを覚えておいてください。

Pluginクラス以外でPDK関数を使用する例を次に示します。

import kong_pdk.pdk.kong as kong

def example_access_phase(kong: kong.kong):
    host_header, err = kong.request.get_header("host")
    kong.log.info(host_header)

class Plugin(object):
    def __init__(self, config):
        self.config = config
    def access(self, kong: kong.kong):
        example_access_phase(kong)

組み込みサーバー

組み込みサーバーを使用するには、次のコードを使用します。

if __name__ == "__main__":
    from kong_pdk.cli import start_dedicated_server
    start_dedicated_server("py-hello", Plugin, version, priority)

start_dedicated_server の最初の引数はプラグイン名を定義するもので、すべての言語で一意にする必要があります。

構成例

kong.conf構成ファイルを使用してプラグインを読み込むには、既存のKong Gatewayプロパティをプラグインの側面にマッピングする必要があります。kong.conf内でプラグインを読み込む例を以下に示します。

pluginserver_names = my-plugin,other-one
pluginserver_my_plugin_socket = /usr/local/kong/my-plugin.socket
pluginserver_my_plugin_start_cmd = /path/to/my-plugin.py
pluginserver_my_plugin_query_cmd = /path/to/my-plugin.py --dump
pluginserver_other_one_socket = /usr/local/kong/other-one.socket
pluginserver_other_one_start_cmd = /path/to/other-one.py
pluginserver_other_one_query_cmd = /path/to/other-one.py -dump

ソケットと開始コマンドの設定はデフォルトと一致しているため省略できます。

pluginserver_names = my-plugin,other-one
pluginserver_my_plugin_query_cmd = /path/to/my-plugin --dump
pluginserver_other_one_query_cmd = /path/to/other-one --dump

詳細ログを開く場合は、以下のように -v引数をstartコマンドラインに渡します。

pluginserver_my_plugin_start_cmd = /path/to/my-plugin.py -v

並行性モデル

Pythonプラグインサーバーと組み込みサーバーは、同時実行をサポートします。デフォルトでは、サーバーはマルチスレッドモードで起動します。

ワークロードが IO 集約型の場合は、kong.confで-gフラグをstart_cmdに渡すことでGeventモデルを使用できます。ワークロードが CPU を集中的に使用する場合は、kong.confで-mフラグをstart_cmdに渡して、マルチプロセッシングモデルを検討してください。