1.20. 3scale WebAssembly モジュールの使用

Service Mesh は、WasmPlugin と呼ばれるサイドカープロキシーに Proxy-WASM 拡張機能を指定して適用するためのカスタムリソース定義を提供します。Service Mesh は、3scale での HTTP API 管理を必要とするワークロードのセットにこのカスタムリソースを適用します。

詳細は、カスタムリソース定義 を参照してください。

3scale の WebAssembly モジュール設定のアーキテクチャーは、3scale アカウントおよび承認サービスや処理するサービスの一覧によって異なります。

3scale WebAssembly モジュールからの api 最上位文字列は、モジュールが使用する設定のバージョンを定義します。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
  namespace: <info>
spec:
  pluginConfig:
    api: v1
...

api エントリーは、設定の残りの値を定義します。許可される値は v1 のみです。現在の設定との互換性を壊す、または v1 を使用するモジュールが処理できないロジックを必要とする新しい設定には、異なる値が必要になります。

system 最上位オブジェクトは、特定のアカウントの 3scale Account Management API にアクセスする方法を指定します。upstream フィールドは、オブジェクトの最も重要な部分です。system オブジェクトはオプションですが、3scale のsystemコンポーネントへの接続を提供しない場合のオプションである 3scale WebAssembly モジュールに完全な静的設定を提供する場合を除き、推奨されます。

system オブジェクトに加えて静的設定オブジェクトを指定する場合は、静的な設定オブジェクトが優先されます。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    system:
      name: <saas_porta>
      upstream: <object>
      token: <my_account_token>
      ttl: 300
  ...

upstream オブジェクトは、プロキシーが呼び出しを実行できる外部ホストについて説明しています。

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
...

backend 最上位オブジェクトは、HTTP リクエストの承認および報告のために 3scale Service Management API にアクセスする方法を指定します。このサービスは、3scale の バックエンド コンポーネントによって提供されます。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    backend:
      name: backend
      upstream: <object>
    ...

services の最上位オブジェクトは、module のこの特定のインスタンスで処理されるサービス識別子を指定します。

アカウントには複数のサービスがあるため、どのサービスを処理するかを指定する必要があります。残りの設定は、サービスの設定方法に関するものです。

services フィールドは必須です。有用とするサービスを少なくとも 1 つ含める必要がある配列です。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
    ...

services 配列の各要素は、3scale サービスを表します。

credentials オブジェクトは service オブジェクトのコンポーネントです。credentials は、検索する認証情報の種類と、このアクションを実行する手順を指定します。

すべてのフィールドはオプションですが、少なくとも 1 つの user_key または app_id を指定する必要があります。各認証情報を指定する順番は、モジュールによって事前確立されているために無関係です。各認証情報の 1 つのインスタンスのみを指定します。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key: <array_of_lookup_queries>
    ...

lookup query オブジェクトは、credentials オブジェクトのフィールドの一部になります。特定の認証情報フィールドが検出され、処理される方法を指定します。評価されると、解決に成功すると、1 つ以上の値が見つかったことを意味します。解決に失敗したことは、値が見つからなかったことを意味します。

lookup queries の配列は、ショートサーキットまたは関係を定義しています。いずれかのクエリーの正常な解決により、残りのクエリーの評価が停止され、値を指定の credential-type に割り当てます。アレイの各クエリーは、互いに独立しています。

lookup query は、1 つのフィールド (ソースオブジェクト) で設定されています。これは、複数のソースタイプの 1 つになります。以下の例を参照してください。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key:
          - <source_type>: <object>
          - <source_type>: <object>
          ...
        app_id:
          - <source_type>: <object>
          ...
        app_key:
          - <source_type>: <object>
          ...
    ...

source オブジェクトは、任意の credentials オブジェクトフィールド内のソースの配列の一部として存在します。source-type として参照されるオブジェクトフィールド名は、以下のいずれかになります。

すべての source-type オブジェクトには、少なくとも以下の 2 つのフィールドがあります。

filter フィールド名には、データの検索に使用するメタデータのパスを表示するのに必要な path エントリーがあります。

キーが 入力データと一致する場合は、残りの鍵は評価されず、ソース解決アルゴリズムは、指定した operations (ops) の実行にジャンプします。ops を指定しないと、一致する key の結果値 (ある場合) が返されます。

Operations は、最初のフェーズが key を検索した後に、入力に対する特定の条件および変換を指定する方法を提供します。プロパティーを変換、デコード、および要求する必要があるときに、operations を使用しますが、すべてのニーズに対応する成熟した言語は提供されず、Turing-completeness はありません。

スタックは operations の出力を保存します。評価されると、認証情報が消費する値の数に応じて、スタックの下部に値を割り当てて、lookup query は終了します。

特定の source type に属する ops 配列の各要素は、値に変換を適用するか、テストを実行する operation オブジェクトです。このようなオブジェクトに使用するフィールド名は operation 自体の名前で、値は operation に対するパラメーターです。これは、フィールドと値のマップ、リスト、または文字列など、構造化オブジェクトになります。

ほとんどの operations は、1 つ以上の入力を処理し、1 つ以上の出力を生成します。入力を使用したり、出力を生成したりする場合、それらは値のスタックで作業します。操作によって消費される各値は、値のスタックからポップアップされ、source マッチと共に初期入力されます。出力される値はスタックにプッシュされます。他の operations は、特定のプロパティーを要求する以外、出力を使用または生成しませんが、値のスタックを検査します。

operations カテゴリーはいくつかあります。

すべての操作は、name 識別子で文字列として指定されます。

mapping_rules オブジェクトは service オブジェクトの一部です。これは、REST パスパターンのセットならびに関連する 3scale メトリクスおよびパターンが一致する時に使用するカウント増分を指定します。

system 最上位オブジェクトに動的設定が提供されていない場合、値が必要です。system 最上位エントリーに加えてオブジェクトが提供されると、mapping_rules オブジェクトが最初に評価されます。

mapping_rules は配列オブジェクトです。そのアレイの各要素は mapping_rule オブジェクトです。受信したリクエストの評価されたマッチするマッピングルールにより、承認およびAPIManager へのレポート用の 3scale methods のセットが提供されます。複数のマッチングルールが同じ methods を参照する場合、3scale への呼び出し時に deltas の合算があります。たとえば、2 つのルールが、1 と 3 の deltas で Hits メソッドを 2 回増やすと、3scale にレポートする Hits の単一のメソッドエントリーの delta は 4 になります。

mapping_rule オブジェクトは mapping_rules オブジェクトの配列の一部です。

mapping_rule オブジェクトフィールドは、以下の情報を指定します。

以下の例は、3scale のメソッド間の既存の階層とは独立しています。つまり、3scale 側で実行されたすべての内容はこれには影響しません。たとえば、Hits メトリクスは、それらすべての親となる可能性があるため、承認されたリクエストで報告されたすべてのメソッドの合計により 4 ヒットを保管し、3scale Authrep API エンドポイントを呼び出します。

以下の例では、すべてのルールに一致する、パス /products/1/sold への GET リクエストを使用します。

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    mapping_rules:
      - method: GET
        pattern: /
        usages:
          - name: hits
            delta: 1
      - method: GET
        pattern: /products/
        usages:
          - name: products
            delta: 1
      - method: ANY
        pattern: /products/{id}/sold
        usages:
          - name: sales
            delta: 1
          - name: products
            delta: 1
    ...

すべての usages は、モジュールが使用状況データを使用して 3scale に実施するリクエストに追加されます。

以下の例では、クエリー文字列パラメーターまたは同じ名前のヘッダーで user_key を検索します。

credentials:
  user_key:
    - query_string:
        keys:
          - user_key
    - header:
        keys:
          - user_key

以下の例では、クエリーまたはヘッダーの app_key および app_id 認証情報を検索します。

credentials:
  app_id:
    - header:
        keys:
          - app_id
    - query_string:
        keys:
          - app_id
  app_key:
    - header:
        keys:
          - app_key
    - query_string:
        keys:
          - app_key

リクエストには、authorization ヘッダーに app_id および app_key が含まれます。最後に出力される値が 1 つまたは 2 つある場合は、app_key を割り当てることができます。

ここでの解決は、最後に出力された 1 つまたは 2 つの出力がある場合は app_key を割り当てます。

authorization ヘッダーは承認の種類で値を指定し、その値は Base64 としてエンコードされます。つまり、値を空白文字で分割し、2 番目の出力を取得して、コロン (:) をセパレーターとして使用して再度分割できます。たとえば、app_id:app_key という形式を使用する場合、ヘッダーは以下の credential の例のようになります。

aladdin:opensesame:  Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

以下の例のように、小文字のヘッダーフィールド名を使用する必要があります。

credentials:
  app_id:
    - header:
        keys:
          - authorization
        ops:
          - split:
              separator: " "
              max: 2
          - length:
              min: 2
          - drop:
              head: 1
          - base64_urlsafe
          - split:
              max: 2
  app_key:
    - header:
        keys:
          - app_key

前述のユースケースの例は、authorization のヘッダーを確認します。

最後の操作は assert で、スタックに副作用がないことを示します。その後、スタックを変更することができます。

Service Mesh および 3scale Istio アダプターの場合、以下の例のように RequestAuthentication をデプロイし、独自のワークロードデータおよび jwtRules を入力する必要があります。

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: info
spec:
  selector:
    matchLabels:
      app: productpage
  jwtRules:
  - issuer: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
    jwksUri: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs

RequestAuthentication を適用するとき、JWT トークンを検証するためにネイティブプラグインで Envoy を設定します。プロキシーは、モジュールを実行する前にすべてを検証します。したがって、失敗したリクエストが 3scale WebAssembly モジュールに実行されません。

JWT トークンが検証されると、プロキシーはそのコンテンツを内部メタデータオブジェクトに格納します。エントリーのキーは、プラグインの特定の設定に依存します。このユースケースでは、不明なキー名が含まれる単一のエントリーを持つ構造化オブジェクトを検索することができます。

OIDC の 3scale app_id は、OAuth client_id と一致します。これは JWT トークンの azp フィールドまたは aud フィールドにあります。

Envoy のネイティブ JWT 認証フィルターから app_id フィールドを取得するには、以下の例を参照してください。

credentials:
  app_id:
    - filter:
        path:
          - envoy.filters.http.jwt_authn
          - "0"
        keys:
          - azp
          - aud
        ops:
          - take:
              head: 1

この例では、モジュールに対し、filter ソースタイプを使用して Envoy 固有の JWT 認証ネイティブプラグインからオブジェクトのフィルターメタデータを検索するよう指示します。このプラグインには、1 つのエントリーと事前に設定された名前を持つ構造化オブジェクトの一部として JWT トークンが含まれます。0 を使用して、単一のエントリーのみにアクセスするように指定します。

結果の値は、以下の 2 つのフィールドを解決する構造です。

この操作により、割り当て用に 1 つの値のみが保持されます。

設定によっては、JWT トークンの検証プロセスがある場合があります。この場合、検証されたトークンが JSON 形式のヘッダーを介してこのモジュールに到達します。

app_id を取得するには、以下の例を参照してください。

credentials:
  app_id:
    - header:
        keys:
          - x-jwt-payload
        ops:
          - base64_urlsafe
          - json:
            - keys:
              - azp
              - aud
          - take:
              head: 1