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

WebAssembly

KongのWebAssembly

Luaプラグインに加えて、Kong Gateway はプロキシ機能を拡張し、カスタムビジネスロジックを実行する手段としてWebAssemblyをサポートしています。これは、Proxy-Wasm仕様のKongのオープンソース実装で可能になります。

コンセプト

フィルター

Proxy-Wasmのコンテキストでは、「フィルター」はリクエスト/応答処理の特定の段階で実行される、特定のコンポーネントまたはモジュールを指します。フィルターは次のようなアクションを実行できます。

リクエストヘッダーまたは応答ヘッダーの読み取りまたは書き込み
リクエストボディまたは応答本文の読み取りまたは書き込み
リクエストを早期に終了し、自分で生成した応答を送信する

KongのLuaプラグインサポートに精通している場合は、フィルターをプラグインに部分的に類似したものとして捉えることができます。

フィルターとLuaプラグインでは、実行時のファイル形式が異なります。Luaプラグインは、通常、複数の異なるLuaソースコードファイルにまたがり、すべてパッケージ化され、テキスト形式でデプロイされます。フィルターはソースコードから、.wasm拡張子の付いた単一のバイナリファイルにコンパイルされる必要があります。

Kong Gatewayで使用するには、すべてのフィルターファイルがディスク上の単一のディレクトリに存在しており、 wasm_filters_path構成ディレクティブで示されている必要があります。

フィルターチェーン

フィルターチェーンは、特定のサービスやルートへの各リクエストに対して実行される一つ以上のフィルターを表すデータベースエンティティであり、それぞれに設定があります。

以下に例を示します。

---
filter_chains:
  name: my-filter-chain
  # Filter Chains can be toggled on/off for testing
  enabled: true
  filters:
    # this maps to $wasm_filters_path/my_filter.wasm
    - name: my_filter
      # at runtime, configuration is passed to the filter as a byte array
      #
      # filter configuration is inherently untyped--schema and
      # encoding/serialization are left up to the filter code itself
      config: "foo=bar baz=bat"

    - name: my_other_filter
      # individual filters within a chain can be toggled on/off for testing
      enabled: false
      config: >-
          {
            "some_settings": {
              "a": "b",
              "c": "d"
            },
            "foo": "bar"
          }

    # the same filter may occur more than once in a single chain, and all   entries will be
    # executed
    - name: my_filter
      config: "foo=123 baz=456"

関係

フィルターチェーンはサービスまたはルートにリンクする 必要があり 、Kong Gatewayバージョン3.4では 1対1の関係になっています。

サービスまたはルートは、単一のフィルターチェーンにのみリンクできます。
フィルターチェーンは、単一のサービスまたはルートにのみリンクできます。

フィルター実行動作

特定のリクエストに対して実行されるフィルターのリストは、Luaプラグインの実行後のaccessフェーズ中に決定されます。リクエストのサービスエンティティがフィルターチェーンにリンクされている場合、フィルターが実行されます。もしリクエストに一致したルートエンティティがフィルターチェーンにリンクされている場合は、サービス関連のフィルター（もしあれば）が実行された後でそのフィルターが実行されます。Admin APIのエンドポイント/routes/{route_name_or_id}/filters/enabledを介して、特定のルートの完全なフィルター実行プランを調べることができます。

フィルターは常にフィルターチェーン内で定義された順序で実行されます。同じフィルターが、サービスチェーンやルートチェーンから、あるいは同じフィルターチェーン内で、複数回実行計画に現れる可能性があります。各エントリは、独自の構成で実行されます。

LuaプラグインとProxy-Wasmフィルターを同時に使用できますか？

はい。しかし、各リクエストフェーズにおいて、LuaプラグインはWasmフィルターより前に実行されることに注意してください。

この順序には、注意すべき重要な副作用が1つあります。Lua プラグインが access フェーズ中またはその前にリクエストを終了した場合（例外をスローするか、明示的に kong.response.exit() または他のPDK関数でレスポンスを送信することによる）、他のフェーズを含め、 リクエストに対してWasmフィルタは実行されません （例：header_filterなど）。

制限事項と既知の問題

Kong PDK

この記事の執筆時点では、フィルターはKongの Lua-land PDKユーティリティで利用できず、Proxy-Wasmで定義される機能により制限されています。

フィルター構成スキーマ

フィルター構成が型指定されていません。つまり、Admin APIを使用してフィルターチェーンインスタンスを作成する場合などに、Kongは事前にフィルター構成を確認できなくなります。これはProxy-Wasm仕様の制限であるため、Kongの実装にとってはそれほど大きな制限とはなりません。

Proxy-Wasm機能

Proxy-Wasm仕様は比較的新しいものであり、現在も進化を続けています。この仕様の一部の動作はまだ完全に実装されていない可能性があります。また、Kong Gatewayや他のProxy-Wasm実装との間で動作が一致しない場合もあります。

詳細については、ngx_wasm_module Proxy-Wasmドキュメントを参照してください。