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

プラグインプロジェクトの設定

以下の手順は、最初のビルド、テスト、 Luaを使用した Kong Gatewayカスタムプラグイン実行を迅速に行うために記述されています。このセクションの残りのページでは、プラグインの開発とベストプラクティスに関連するその他の高度なトピックについて詳しく説明します。

前提条件

このガイドを完了するには、次の開発ツールが必要です。

Docker（またはDockerと同等のもの）はKong Gatewayの実行とコードのテストに使用されます
curlはWebリソースをダウンロードするために使用されます。
gitは、ホストマシンにソフトウェアをインストールおよび更新するために使用されます。

段階的な手順

この章では、まず単純な Kong Gateway カスタムプラグインプロジェクトを作成します。必要なフォルダとファイルを作成し、次に簡単な Lua コードを書いて基本的な機能を持つプラグインを作成します。

新しいプラグインリポジトリを初期化する

まず、ターミナルを開き、ディレクトリをソースコードを格納する場所に変更します。

プラグイン用の新しいフォルダを作成し、その中に移動します。

mkdir -p my-plugin && \
  cd my-plugin

次に、プラグインフォルダ構造を作成します。

重要： このガイドで紹介されている特定にツリー構造とファイル名は、プラグインの開発と実行がKong Gatewayで正常に機能するために重要です。このガイドのこれらの名前から逸脱しないでください。

mkdir -p kong/plugins/my-plugin && \
  mkdir -p spec/my-plugin

プラグインは、以下の個別ファイル内で定義されたLuaモジュールで構成されています。

まず、機能するプラグインに最低限必要なモジュールである空のhandler.luaファイルとschema.luaファイルを作成します。

touch kong/plugins/my-plugin/handler.lua
touch kong/plugins/my-plugin/schema.lua

これで、新しいプラグインの基本構造ができました。これらのモジュールのコードの作成方法を見てみましょう。

スキーマモジュールを初期化

schema.luaファイルは、プラグインの設定データモデルを定義します。以下は、有効なプラグインに必要な最小構造です。

次のコードをschema.luaファイルに追加します。

local PLUGIN_NAME = "my-plugin"

local schema = {
  name = PLUGIN_NAME,
  fields = {
    { config = {
        type = "record",
        fields = {
        },
      },
    },
  },
}

return schema

これにより、プラグインの構成用の空の基本テーブルが作成されます。このガイドの後半では、実行時にプラグインを構成するための構成可能な値をテーブルに追加します。

次に、プラグインのハンドラコードを追加します。

ハンドラモジュールを初期化

handler.lua モジュールには、新しいプラグインのコアロジックが含まれています。まず、handler.lua ファイルに以下の Lua コードを記述します。

local MyPluginHandler = {
    PRIORITY = 1000,
    VERSION = "0.0.1",
}

return MyPluginHandler

このコードは、有効なプラグインの必須フィールドのセットを指定するLuaテーブルを定義します。

PRIORITYフィールドは、他の読み込まれたプラグインに対して相対的に実行されるタイミングを決定する、プラグインの静的な実行順序を設定します。
VERSIONフィールドはこのプラグインのバージョンを設定し、 major.minor.revision形式に従う必要があります。

これで有効なプラグインができましたが、現在は何も実行しません。

次に、プラグインにロジックを追加し、それを検証する方法を学びます。

ハンドラロジックを追加する

プラグインロジックは、HTTP リクエスト、TCP ストリーム、および Kong Gateway 自体のライフサイクルにおけるいくつかの重要なポイントで実行されるように定義されています。

handler.luaモジュール内で、よく知られた名前が付いた関数をプラグインテーブルに追加して、プラグインロジックが実行される必要のあるポイントを示すことができます。

この例では、アップストリームサービスから応答を受信し、クライアントに返す前に実行されるresponse関数を追加します。

レスポンスをクライアントに返す前に、レスポンスにヘッダーを追加しましょう。return MyPluginHandlerステートメントの前のhandler.luaファイルに、以下のファンクション実装を追加します。

function MyPluginHandler:response(conf)
    kong.response.set_header("X-MyPlugin", "response")
end

kong.responseモジュールはKong PDKに、クライアントに返されるレスポンスを操作するための関数を提供します。上記のコードは、 X-MyPluginという名前とresponseの値を持つすべてのレスポンスに、新たなヘッダーを設定します。

完全なhandler.luaファイルのリストは次のようになります。

local MyPluginHandler = {
  PRIORITY = 1000,
  VERSION = "0.0.1",
}

function MyPluginHandler:response(conf)
    kong.response.set_header("X-MyPlugin", "response")
end

return MyPluginHandler

重要: Kong PDK は、カスタムプラグイン開発のための安定したインターフェイスと一連の関数を提供します。PDK の一部 ではない Kong Gateway コードベースのモジュールを使用しないことが重要です。これらのモジュールは、安定したインターフェイスまたは動作を提供する保証はなく、プラグインコードで使用すると予期しない動作を引き起こす可能性があります。

次の手順

この段階で、Kong Gateway用の機能的なプラグインができました。ただし、どの開発プロジェクトもテストなしでは不完全です。次の章では、テストツールをインストールし、自動テストルーチンを作成する方法を学習します。

前へ導入

次へプラグインテストを追加