Red Hat Summit11.8. 3scale WebAssembly モジュール設定
WasmPlugin カスタムリソース仕様は、Proxy-WASM モジュールが読み取る設定を提供します。
仕様はホストに組み込まれ、Proxy-WASM モジュールによって読み取られます。通常は、モジュールが解析するように設定は JSON ファイル形式です。ただし、WasmPlugin リソースは仕様値を YAML として解釈し、モジュールで使用できるように JSON に変換できます。
スタンドアロンモードで Proxy-WASM モジュールを使用する場合は、JSON 形式を使用して設定を作成する必要があります。JSON 形式を使用する場合は、host 設定ファイル内の必要な場所で、エスケープと引用を使用できます (例:Envoy)。WasmPlugin リソースで WebAssembly モジュールを使用する場合、設定は YAML 形式になります。この場合は、無効な設定により、JSON 表現に基づいて診断がモジュールによって強制的にサイドカーコンテナーのロギングストリームに表示されます。
EnvoyFilter カスタムリソースは一部の 3scale Istio アダプターまたは Service Mesh リリースで使用できますが、このカスタムリソースはサポートされる API ではありません。EnvoyFilter カスタムリソースの使用は推奨されていません。EnvoyFilter カスタムリソースの代わりに WasmPlugin API を使用します。EnvoyFilter カスタムリソースを使用する必要がある場合は、仕様を JSON 形式で指定する必要があります。
11.8.1. 3scale WebAssembly モジュールの設定
3scale の WebAssembly モジュール設定のアーキテクチャーは、3scale アカウントおよび承認サービスや処理するサービスのリストによって異なります。
前提条件
前提条件は、すべてのケースで最小の必須フィールドのセットです。
-
3scale アカウントおよび承認サービス:
backend-listenerURL。 - 処理するサービスリスト: サービス ID と少なくとも 1 つの認証情報の検索方法、およびその検索場所。
-
userkey、appid、appkey、および OpenID Connect (OIDC) パターンを処理する例があります。 -
WebAssembly モジュールは、静的設定で指定した設定を使用します。たとえば、モジュールにマッピングルール設定を追加する場合は、3scale 管理ポータルにこのようなマッピングルールが設定されていない場合でも、常に適用されます。残りの
WasmPluginリソースはspec.pluginConfigYAML エントリーに存在します。
11.8.2. 3scale WebAssembly モジュール api オブジェクト
3scale WebAssembly モジュールからの api 最上位文字列は、モジュールが使用する設定のバージョンを定義します。
存在しないバージョンまたはサポート対象外のバージョンの api オブジェクトの場合、レンダリングされた 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 を使用するモジュールが処理できない追加のロジックが必要な新しい設定には、別の値が必要になります。
11.8.3. 3scale WebAssembly モジュール system オブジェクト
system 最上位オブジェクトは、特定のアカウントの 3scale Account Management API にアクセスする方法を指定します。upstream フィールドは、オブジェクトの最も重要な部分です。system オブジェクトはオプションですが、3scale WebAssembly モジュールに完全に静的な設定を提供する場合を除き、推奨されます。後者は、3scale の システム コンポーネントへの接続を提供したくない場合のオプションです。
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
...| 名前 | 説明 | 必須 |
|---|---|---|
|
| 3scale サービスの識別子 (現在、参照されていません)。 | 任意 |
|
|
問い合わせるネットワークホストの詳細。 | はい |
|
| 読み取り権限を持つ 3scale の個人アクセストークン。 | はい |
|
| 新規の変更を取得する前に、このホストから取得した設定を有効なものと見なす最小時間 (秒数)。デフォルトは 600 秒 (10 分) です。注記: 最大の期間はありませんが、モジュールは通常、この TTL が経過した後に妥当な時間内に設定を取得します。 | 任意 |
11.8.4. 3scale WebAssembly モジュール upstream オブジェクト
upstream オブジェクトは、プロキシーが呼び出しを実行できる外部ホストを説明しています。
apiVersion: maistra.io/v1
upstream:
name: outbound|443||multitenant.3scale.net
url: "https://myaccount-admin.3scale.net/"
timeout: 5000
...| 名前 | 説明 | 必須 |
|---|---|---|
|
|
| はい |
|
| 記述されたサービスにアクセスするための完全な URL。スキームによって暗示されていない限り、TCP ポートが含まれている必要があります。 | はい |
|
| 応答にかかる時間がこの設定を超えたこのサービスへの接続がエラーとみなされるためのタイムアウト (ミリ秒単位)。デフォルトは 1000 秒です。 | 任意 |
11.8.5. 3scale WebAssembly モジュール backend オブジェクト
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>
...| 名前 | 説明 | 必須 |
|---|---|---|
|
| 3scale バックエンドの識別子 (現在、参照されていません)。 | 任意 |
|
| 問い合わせるネットワークホストの詳細。これは、system として知られる 3scale Account Management API ホストを参照する必要があります。 | 有効。最も重要な必須フィールドです。 |
11.8.6. 3scale WebAssembly モジュール services オブジェクト
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 サービスを表します。
| 名前 | 説明 | 必須 |
|---|---|---|
|
| この 3scale サービスの識別子 (現在、参照されていません)。 | はい |
|
|
この
| 任意 |
|
| 文字列の配列。それぞれが一致する URL の認証局 を表します。これらの文字列は、アスタリスク (*)、正符号 (+)、および疑問符 (?) マッチャーに対応する glob パターンを受け入れます。 | はい |
|
| 検索する認証情報の種類と場所を定義するオブジェクト。 | はい |
|
| ヒットするマッピングルールおよび 3scale メソッドを表すオブジェクトの配列。 | 任意 |
11.8.7. 3scale WebAssembly モジュール credentials オブジェクト
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>
...| 名前 | 説明 | 必須 |
|---|---|---|
|
| これは、3scale ユーザーキーを定義する検索クエリーの配列です。ユーザーキーは、一般に API キーと呼ばれます。 | 任意 |
|
|
これは、3scale のアプリケーション識別子を定義する検索クエリーの配列です。アプリケーションの識別子は、3scale または Red Hat Single Sign-On (RH-SS0) や OpenID Connect (OIDC) などのアイデンティティープロバイダーを使用して提供されます。成功して 2 つの値に解決するたびに、ここで指定された検索クエリーの解決で、 | 任意 |
|
|
これは、3scale のアプリケーションキーを定義する検索クエリーの配列です。解決される | 任意 |
11.8.8. 3scale WebAssembly モジュール検索クエリー
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 として参照されるオブジェクトフィールド名は、以下のいずれかになります。
-
header: 検索クエリーは、HTTP リクエストヘッダーを入力として受け取ります。 -
query_string:lookup queryは、URL クエリー文字列パラメーターを入力として受け取ります。 -
filter:lookup queryは、フィルターメタデータをインプットとして受け取ります。
すべての source-type オブジェクトには、少なくとも以下の 2 つのフィールドがあります。
| 名前 | 説明 | 必須 |
|---|---|---|
|
|
文字列の配列。それぞれが | はい |
|
|
| 任意 |
|
|
データの検索に使用されるメタデータ内のパスを表示します。ただし、 | 任意 |
キーが 入力データと一致する場合は、残りの鍵は評価されず、ソース解決アルゴリズムは、指定した operations (ops) の実行にジャンプします。ops を指定しないと、一致する key の結果値 (ある場合) が返されます。
Operations は、最初のフェーズが key を検索した後に、入力に対する特定の条件および変換を指定する方法を提供します。プロパティーを変換、デコード、および要求する必要があるときに、operations を使用しますが、すべてのニーズに対応する成熟した言語は提供されず、Turing-completeness はありません。
スタックは operations の出力を保存します。評価されると、認証情報が消費する値の数に応じて、スタックの下部に値を割り当てて、lookup query は終了します。
11.8.9. 3scale WebAssembly モジュール operations オブジェクト
特定の source type に属する ops 配列の各要素は、値に変換を適用するか、テストを実行する operation オブジェクトです。このようなオブジェクトに使用するフィールド名は operation 自体の名前で、値は operation に対するパラメーターです。これは、フィールドと値のマップ、リスト、または文字列など、構造化オブジェクトになります。
ほとんどの operations は、1 つ以上の入力を処理し、1 つ以上の出力を生成します。入力を使用したり、出力を生成したりする場合、それらは値のスタックで作業します。操作によって消費される各値は、値のスタックからポップアップされ、source マッチと共に初期入力されます。出力される値はスタックにプッシュされます。他の operations は、特定のプロパティーを要求する以外、出力を使用または生成しませんが、値のスタックを検査します。
解決が完了すると、次の手順 (値を app_id、app_key、または user_key に割り当てるなど) でピックアップされる値はスタックの下部の値から取得されます。
operations カテゴリーはいくつかあります。
-
decode: 別の形式を取得するために、入力値をデコードして変換します。 -
string: 文字列値を入力として取り、変換を実行し、確認します。 -
stack: 入力の値のセットを取得し、複数のスタック変換とスタック内の特定の位置の選択を実行します。 -
check: 影響を及ぼさない方法で、操作セットに関するプロパティーを要求します。 -
control: 評価フローを変更できる操作を実施します。 -
format: 入力値の形式固有の構造を解析し、その値を検索します。
すべての操作は、name 識別子で文字列として指定されます。
11.8.10. 3scale WebAssembly モジュール mapping_rules オブジェクト
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 になります。
11.8.11. 3scale WebAssembly モジュール mapping_rule オブジェクト
mapping_rule オブジェクトは mapping_rules オブジェクトの配列の一部です。
mapping_rule オブジェクトフィールドは、以下の情報を指定します。
- 照合する HTTP 要求メソッド。
- パスに一致するパターン。
- 報告する量と共にレポートする 3scale メソッド。フィールドを指定する順番により、評価順序が決定されます。
| 名前 | 説明 | 必須 |
|---|---|---|
|
| HTTP リクエストメソッド (動詞) を表す文字列を指定します。許可される値は、許可される HTTP メソッド名の 1 つと一致し、大文字と小文字を区別しません。すべてのマッチのすべてのメソッドの特殊な値。 | はい |
|
|
HTTP リクエストの URI パスコンポーネントに一致するパターン。このパターンは、3scale で説明されている構文に従います。ワイルドカード、アスタリスク (*) 文字の使用、中括弧間の任意の文字シーケンスの使用 ( | はい |
|
|
以下の必須フィールドに
| はい |
|
| このルールが正常にマッチした場合に、それ以外のマッピングルールの評価を停止する必要があるかどうか。 |
任意のブール値。デフォルトは |
以下の例は、3scale のメソッド間の既存の階層とは独立しています。つまり、3scale 側で実行されたすべての内容はこれには影響しません。たとえば、Hits メトリックは、それらすべての親となる可能性があるため、承認されたリクエストで報告されたすべてのメソッドの合計により 4 ヒットを保管し、3scale Authrep API エンドポイントを呼び出します。
以下の例では、すべてのルールに一致する、パス /products/1/sold への GET リクエストを使用します。
mapping_rules 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 に実施するリクエストに追加されます。
- Hits: 1
- products: 2
- sales: 1
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}