1.21. 3scale Istio アダプターの使用

3scale Istio アダプターはオプションのアダプターであり、これを使用すると、Red Hat OpenShift Service Mesh 内で実行中のサービスにラベルを付け、そのサービスを 3scale API Management ソリューションと統合できます。これは Red Hat OpenShift Service Mesh には必要ありません。

重要

3scale Istio アダプターは、Red Hat OpenShift Service Mesh バージョン 2.0 以前でのみ使用できます。Mixer コンポーネントはリリース 2.0 で非推奨となり、リリース 2.1 で削除されました。Red Hat OpenShift Service Mesh バージョン 2.1.0 以降では、3scale WebAssembly モジュールを使用する必要があります。

3scale Istio アダプターで 3scale バックエンドキャッシュを有効にする必要がある場合は、Mixer ポリシーと Mixer Telemetry も有効にする必要があります。Red Hat OpenShift Service Mesh コントロールプレーンのデプロイを参照してください。

1.21.1. 3scale アダプターと Red Hat OpenShift Service Mesh の統合

これらの例を使用して、3scale Istio アダプターを使用してサービスに対する要求を設定できます。

前提条件

Red Hat OpenShift Service Mesh バージョン 2.x
稼働している 3scale アカウント (SaaS または 3scale 2.9 On-Premises)
バックエンドキャッシュを有効にするには 3scale 2.9 以上が必要です。
Red Hat OpenShift Service Mesh の前提条件
Mixer ポリシーの適用が有効になっていることを確認します。「Mixer ポリシー適用の更新」セクションでは、現在の Mixer ポリシーの適用ステータスをチェックし、ポリシーの適用を有効にする手順が説明されています。
Mixer プラグインを使用している場合は、Mixer ポリシーと Telemetry は有効にする必要があります。
- アップグレード時に、Service Mesh コントロールプレーン (SMCP) を適切に設定する必要があります。

注記

3scale Istio アダプターを設定するために、アダプターパラメーターをカスタムリソースファイルに追加する手順は、Red Hat OpenShift Service Mesh カスタムリソースを参照してください。

注記

kind: handler リソースにとくに注意してください。これを 3scale アカウントの認証情報を使用して更新する必要があります。オプションで service_id をハンドラーに追加できますが、この設定は 3scale アカウントの 1 つのサービスに対してのみ有効で、後方互換性を確保するためにだけ維持されています。service_id をハンドラーに追加し、他のサービスに対して 3scale を有効にする必要がある場合は、別の service_ids で追加のハンドラーを作成する必要があります。

以下の手順に従って、3scale アカウントごとに単一のハンドラーを使用します。

手順

3scale アカウントのハンドラーを作成し、アカウントの認証情報を指定します。サービス識別子を省略します。
```
  apiVersion: "config.istio.io/v1alpha2"
  kind: handler
  metadata:
   name: threescale
  spec:
   adapter: threescale
   params:
     system_url: "https://<organization>-admin.3scale.net/"
     access_token: "<ACCESS_TOKEN>"
   connection:
     address: "threescale-istio-adapter:3333"
```
オプションで、params セクション内の backend_url フィールドを指定して、3scale 設定によって提供される URL を上書きできます。これは、アダプターが 3scale のオンプレミスインスタンスと同じクラスターで実行され、内部クラスター DNS を利用する必要がある場合に役立ちます。
3scale アカウントに属するサービスの Deployment リソースを編集するか、パッチを適用します。
1. 有効な service_id に対応する値を使用して "service-mesh.3scale.net/service-id" ラベルを追加します。
2. 手順 1 の ハンドラーリソースの名前 の値を使用して "service-mesh.3scale.net/credentials" ラベルを追加します。
他のサービスを追加する場合は、手順 2 を実行して、3scale アカウントの認証情報とそのサービス識別子にリンクします。

3scale 設定でルールの設定を変更し、ルールを 3scale ハンドラーにディスパッチします。

ルール設定の例

  apiVersion: "config.istio.io/v1alpha2"
  kind: rule
  metadata:
    name: threescale
  spec:
    match: destination.labels["service-mesh.3scale.net"] == "true"
    actions:
      - handler: threescale.handler
        instances:
          - threescale-authorization.instance

1.21.1.1. 3scale カスタムリソースの生成

アダプターには、handler、instance、および rule カスタムリソースの生成を可能にするツールが含まれます。

表1.29 使用法
オプション	説明	必須	デフォルト値
`-h, --help`	利用可能なオプションのヘルプ出力を生成します	いいえ
`--name`	この URL の一意の名前、トークンのペア	はい
`-n, --namespace`	テンプレートを生成する namespace	いいえ	istio-system
`-t, --token`	3scale アクセストークン	はい
`-u, --url`	3scale 管理ポータル URL	はい
`--backend-url`	3scale バックエンド URL。これが設定されている場合は、システム設定から読み込まれる値がオーバーライドされます。	いいえ
`-s, --service`	3scale API/サービス ID	いいえ
`--auth`	指定する 3scale 認証パターン (1=API Key, 2=App Id/App Key, 3=OIDC)	いいえ	ハイブリッド
`-o, --output`	生成されたマニフェストを保存するファイル	いいえ	標準出力
`--version`	CLI バージョンを出力し、即座に終了する	いいえ

1.21.1.1.1. URL サンプルからのテンプレートの生成

注記

デプロイされたアダプターからのマニフェストの生成で、3scale アダプターコンテナーイメージからの oc exec を使用して以下のコマンドを実行します。
3scale-config-gen コマンドを使用すると、YAML 構文とインデントエラーを回避するのに役立ちます。
このアノテーションを使用する場合は --service を省略できます。
このコマンドは、oc exec を使用してコンテナーイメージ内から起動する必要があります。

手順

3scale-config-gen コマンドを使用して、トークンと URL のペアを 1 つのハンドラーとして複数のサービスで共有できるようにテンプレートを自動生成します。
```
$ 3scale-config-gen --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"
```

以下の例では、ハンドラーに埋め込まれたサービス ID を使用してテンプレートを生成します。

$ 3scale-config-gen --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"

関連情報

トークン

1.21.1.2. デプロイされたアダプターからのマニフェストの生成

注記

NAME は、3scale で管理するサービスの識別に使用する識別子です。
CREDENTIALS_NAME 参照は、ルール設定の match セクションに対応する識別子です。CLI ツールを使用している場合は、NAME 識別子に自動設定されます。
この値は具体的なものでなくても構いませんが、ラベル値はルールの内容と一致させる必要があります。詳細は、アダプター経由でのサービストラフィックのルーティングを参照してください。

このコマンドを実行して、istio-system namespace でデプロイされたアダプターからマニフェストを生成します。

$ export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"
oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \
-it -- ./3scale-config-gen \
--url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS}

これでターミナルにサンプル出力が生成されます。必要に応じて、これらのサンプルを編集し、oc create コマンドを使用してオブジェクトを作成します。
要求がアダプターに到達すると、アダプターはサービスが 3scale の API にどのようにマッピングされるかを認識している必要があります。この情報は、以下のいずれかの方法で提供できます。
1. ワークロードにラベルを付ける (推奨)
2. ハンドラーを service_id としてハードコーディングする

必要なアノテーションでワークロードを更新します。

注記

ハンドラーにまだ組み込まれていない場合は、このサンプルで提供されたサービス ID のみを更新する必要があります。ハンドラーの設定が優先されます。

$ export CREDENTIALS_NAME="replace-me"
export SERVICE_ID="replace-me"
export DEPLOYMENT="replace-me"
patch="$(oc get deployment "${DEPLOYMENT}"
patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''

1.21.1.3. アダプター経由でのサービストラフィックのルーティング

以下の手順に従って、3scale アダプターを使用してサービスのトラフィックを処理します。

前提条件

3scale 管理者から受け取る認証情報とサービス ID

手順

kind: rule リソース内で、以前に設定で作成した destination.labels["service-mesh.3scale.net/credentials"] == "threescale" ルールと一致させます。
上記のラベルを、ターゲットワークロードのデプロイメントで PodTemplateSpec に追加し、サービスを統合します。値 threescale は生成されたハンドラーの名前を参照します。このハンドラーは、3scale を呼び出すのに必要なアクセストークンを保存します。
destination.labels["service-mesh.3scale.net/service-id"] == "replace-me" ラベルをワークロードに追加し、要求時にサービス ID をインスタンス経由でアダプターに渡します。

1.21.2. 3scale での統合設定

以下の手順に従って、3scale の統合設定を行います。

注記

3scale SaaS を使用している場合は、Red Hat OpenShift Service Mesh は Early Access プログラムの一部として有効になっています。

手順

[your_API_name] Integration の順に移動します。
Settings をクリックします。
Deployment で Istio オプションを選択します。
- デフォルトでは Authentication の API Key (user_key) オプションが選択されます。
Update Product をクリックして選択内容を保存します。
Configuration をクリックします。
設定の更新 をクリックします。

1.21.3. キャッシング動作

3scale System API からの応答は、アダプター内でデフォルトでキャッシュされます。cacheTTLSeconds 値よりも古いと、エントリーはキャッシュから消去されます。また、デフォルトでキャッシュされたエントリーの自動更新は、cacheRefreshSeconds 値に基づいて、期限が切れる前に数秒間試行されます。cacheTTLSeconds 値よりも高い値を設定することで、自動更新を無効にできます。

cacheEntriesMax を正の値以外に設定すると、キャッシングを完全に無効にできます。

更新プロセスを使用すると、到達不能になるホストのキャッシュされた値が、期限が切れて最終的に消去される前に再試行されます。

1.21.4. 認証要求

このリリースでは、以下の認証方法をサポートします。

標準 API キー: 単一のランダム文字列またはハッシュが識別子およびシークレットトークンとして機能します。
アプリケーション ID とキーのペア: イミュータブルな識別子とミュータブルなシークレットキー文字列。
OpenID 認証方法: JSON Web トークンから解析されるクライアント ID 文字列。

1.21.4.1. 認証パターンの適用

以下の認証方法の例に従って instance カスタムリソースを変更し、認証動作を設定します。認証情報は、以下から受け取ることができます。

要求ヘッダー
要求パラメーター
要求ヘッダーとクエリーパラメーターの両方

注記

ヘッダーの値を指定する場合、この値は小文字である必要があります。たとえば、ヘッダーを User-Key として送信する必要がある場合、これは設定で request.headers["user-key"] として参照される必要があります。

1.21.4.1.1. API キー認証方法

Service Mesh は、subject カスタムリソースパラメーターの user オプションで指定されたクエリーパラメーターと要求ヘッダーで API キーを検索します。これは、カスタムリソースファイルで指定される順序で値をチェックします。不要なオプションを省略することで、API キーの検索をクエリーパラメーターまたは要求ヘッダーに制限できます。

この例では、Service Mesh は user_key クエリーパラメーターの API キーを検索します。API キーがクエリーパラメーターにない場合、Service Mesh は user-key ヘッダーを確認します。

API キー認証方法の例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

アダプターが異なるクエリーパラメーターまたは要求ヘッダーを検査するようにする場合は、名前を適宜変更します。たとえば、“key” というクエリーパラメーターの API キーを確認するには、request.query_params["user_key"] を request.query_params["key"] に変更します。

1.21.4.1.2. アプリケーション ID およびアプリケーションキーペアの認証方法

Service Mesh は、subject カスタムリソースパラメーターの properties オプションで指定されるように、クエリーパラメーターと要求ヘッダーでアプリケーション ID とアプリケーションキーを検索します。アプリケーションキーはオプションです。これは、カスタムリソースファイルで指定される順序で値をチェックします。不要なオプションを含めないことで、認証情報の検索をクエリーパラメーターまたは要求ヘッダーのいずれかに制限できます。

この例では、Service Mesh は最初にクエリーパラメーターのアプリケーション ID とアプリケーションキーを検索し、必要に応じて要求ヘッダーに移動します。

アプリケーション ID およびアプリケーションキーペアの認証方法の例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

アダプターが異なるクエリーパラメーターまたは要求ヘッダーを検査するようにする場合は、名前を適宜変更します。たとえば、identification という名前のクエリーパラメーターのアプリケーション ID を確認するには、request.query_params["app_id"] を request.query_params["identification"] に変更します。

1.21.4.1.3. OpenID 認証方法

OpenID Connect (OIDC) 認証方法 を使用するには、subject フィールドで properties 値を使用して client_id および任意で app_key を設定します。

このオブジェクトは、前述の方法を使用して操作できます。以下の設定例では、クライアント識別子 (アプリケーション ID) は、azp ラベルの JSON Web Token (JWT) から解析されます。これは必要に応じて変更できます。

OpenID 認証方法の例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
spec:
  template: threescale-authorization
  params:
    subject:
      properties:
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
        client_id: request.auth.claims["azp"] | ""
      action:
        path: request.url_path
        method: request.method | "get"
        service: destination.labels["service-mesh.3scale.net/service-id"] | ""

この統合を正常に機能させるには、クライアントがアイデンティティープロバイダー (IdP) で作成されるよう OIDC を 3scale で実行する必要があります。保護するサービスと同じ namespace でサービスのに要求の認証を作成する必要があります。JWT は要求の Authorization ヘッダーに渡されます。

以下に定義されるサンプル RequestAuthentication で、issuer、jwksUri、および selector を適宜置き換えます。

OpenID Policy の例

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

1.21.4.1.4. ハイブリッド認証方法

特定の認証方法を適用せず、いずれかの方法の有効な認証情報を受け入れる方法を選択できます。API キーとアプリケーション ID/アプリケーションキーペアの両方が提供される場合は、Service Mesh は API キーを使用します。

この例では、Service Mesh がクエリーパラメーターの API キーをチェックし、次に要求ヘッダーを確認します。API キーがない場合は、クエリーパラメーターのアプリケーション ID とキーをチェックし、次に要求ヘッダーを確認します。

ハイブリッド認証方法の例

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] |
      properties:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
        client_id: request.auth.claims["azp"] | ""
    action:
      path: request.url_path
      method: request.method | "get"
      service: destination.labels["service-mesh.3scale.net/service-id"] | ""

1.21.5. 3scale アダプターメトリクス

アダプターはデフォルトで、/metrics エンドポイントのポート 8080 で公開されるさまざまな Prometheus メトリクスを報告します。これらのメトリクスは、アダプターと 3scale の間の相互作用がどのように実行されているかに関する洞察を提供します。サービスには、自動的に検出され、Prometheus によって収集されるようにラベルが付けられます。

注記

3scale Istio Adapter メトリクスには、Service Mesh 1.x の以前のリリース以降、互換性のない変更があります。

Prometheus では、以下のメトリクスが Service Mesh 2.0 の時点で使用できるように、バックエンドキャッシュの 1 つの追加と共にメトリクスの名前が変更されています。

表1.30 Prometheus メトリクス
メトリクス	型	説明
`threescale_latency`	ヒストグラム	アダプターと 3scale 間の要求レイテンシーです。
`threescale_http_total`	カウンター	3scale バックエンドへの要求に関する HTTP ステータスの応答コード。
`threescale_system_cache_hits`	カウンター	設定キャッシュからフェッチされる 3scale システムへの要求の合計数。
`threescale_backend_cache_hits`	カウンター	バックエンドキャッシュからフェッチされる 3scale バックエンドへの要求の合計数。

1.21.6. 3scale バックエンドキャッシュ

3scale バックエンドキャッシュは、3scale Service Management API のクライアントの認証およびレポートキャッシュを提供します。このキャッシュはアダプターに組み込まれ、管理者がトレードオフを受け入れることが予想される特定の状況での応答の低レイテンシーが可能になります。

注記

3scale バックエンドキャッシュはデフォルトで無効になっています。3scale バックエンドキャッシュ機能では、低レイテンシーとプロセッサーおよびメモリーのリソースの高い使用率と引き換えに、速度制限における不正確な状況が生じたり、フラッシュの最後の実行からのヒットを失う可能性があります。

1.21.6.1. バックエンドキャッシュを有効にする利点

バックエンドキャッシュを有効にする利点には以下が含まれます。

3scale Istio Adapter が管理するサービスへのアクセス時にレイテンシーが高くなる場合にバックエンドキャッシュを有効にします。
バックエンドキャッシュを有効にすると、アダプターは 3scale API マネージャーによるリクエストの承認の継続的なチェックを停止し、レイテンシーが短縮されます。
- これにより、3scale API マネージャーにアクセスして認証を試行する前に、3scale Istio アダプターが保存し、再利用する 3scale 認証のインメモリーキャッシュが作成されます。これにより、認証の許可または拒否にかかる時間が大幅に少なくなります。
バックエンドキャッシュは、3scale Istio アダプターを実行する Service Mesh とは異なる地理的な場所で 3scale API マネージャーをホストする場合に役立ちます。
- 通常、これは 3scale のホスト型 (SaaS) プラットフォームに該当しますが、ユーザーが異なるアベイラビリティーゾーンの地理的に異なる場所にある別のクラスターで 3scale API マネージャーをホストする場合や、3scale API マネージャーに到達するためのネットワークのオーバーヘッドを考慮する必要がある場合にも使用できます。

1.21.6.2. 低レイテンシーを確保するためのトレードオフ

以下は、低レイテンシーを確保するためのトレードオフです。

フラッシュが発生するたびに、3scale アダプターの承認状態が更新されます。
- つまり、アダプターのインスタンスが 2 つ以上あると、フラッシュ期間の間隔に関する不正確さがさらに大きくなることを意味します。
- 要求が過剰になり、制限を超過し、誤った動作を生じさせ、さらには各要求を処理するアダプターによって処理される要求と処理されない要求とが発生する高い可能性があります。
データをフラッシュできず、その認証情報を更新できないアダプターキャッシュは、その情報を API マネージャーに報告せずにシャットダウンまたはクラッシュする可能性があります。
アダプターのキャッシュで、API マネージャーと通信する際のネットワーク接続が原因と予想される問題などにより、要求を許可/拒否する必要があるかどうかを判別できない場合に、fail open または fail closed ポリシーが適用されます。
キャッシュミスが発生すると、通常はアダプターの起動直後、または接続なしの状態が長く続いた後に、API マネージャーのクエリーを行うためにレイテンシーが増加します。
アダプターキャッシュでは、キャッシュを有効にしない場合よりも、認証の計算により多くの作業が必要になります。これにより、より多くのプロセッサーリソースが必要になります。
メモリー要件は、キャッシュで管理される制限、アプリケーションおよびサービスの量の組み合わせに比例して増加します。

1.21.6.3. バックエンドキャッシュ設定

以下では、バックエンドキャッシュの設定を説明します。

3scale 設定オプションでバックエンドキャッシュを設定するための設定を見つけます。
最後の 3 つの設定では、バックエンドキャッシュの有効化を制御します。
- PARAM_USE_CACHE_BACKEND: バックエンドキャッシュを有効にするには true に設定します。
- PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS: キャッシュデータの API マネージャーへのフラッシュの試行間の時間 (秒単位) を設定します。
- PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED: キャッシュされたデータが十分になく、3scale API マネージャーに到達できない場合にサービスへの要求を許可/オープン/または拒否/クローズするかどうかを設定します。

1.21.7. 3scale Istio Adapter APIcast エミュレーション

3scale Istio アダプターは、以下の条件が満たされる場合に APIcast と同様に動作します。

要求が定義されるマッピングルールと一致しない場合、返される HTTP コードは 404 Not Found になります。これは、以前は 403 Forbidden でした。
要求が制限を超えるために拒否されると、返される HTTP コードは 429 Too Many Requests になります。これは、以前は 403 Forbidden でした。
CLI でデフォルトのテンプレートを生成する場合、ヘッダーにはハイフンではなくアンダースコアが使用されます (例: user-key ではなく user_key が使用されます)。

1.21.8. 3scale Istio Adapter の検証

3scale Istio Adapter が予想通りに機能しているかどうかを確認します。アダプターが機能しない場合は、以下の手順に従って問題のトラブルシューティングを行うことができます。

手順

3scale-adapter Pod が Service Mesh コントロールプレーン namespace で実行されていることを確認します。
```
$ oc get pods -n istio-system
```
そのバージョンなど、3scale-adapter Pod が起動に関する情報を出力したことを確認します。
```
$ oc logs istio-system
```
3scale アダプターの統合で保護されているサービスに対して要求を実行すると、正しい認証情報がかけているという要求を必ず試し、その要求が失敗することを確認します。3scale Adapter ログをチェックして、追加情報を収集します。