第7章 3scale アダプター

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

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

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

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

前提条件:

  • Red Hat OpenShift Service Mesh 0.12.0+
  • 稼働している 3scale アカウント (SaaS または 3scale 2.5 On-Premises)
  • Red Hat OpenShift Service Mesh の前提条件
  • Mixer ポリシーの適用が有効になっていることを確認します。Mixer ポリシー適用の更新についてのセクションでは、現在の Mixer ポリシーの適用ステータスをチェックし、ポリシーの適用を有効にする手順が説明されています。
注記

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

注記

kind: handler リソースにとくに注意してください。3scale の認証情報と管理する API のサービス ID を使用して、これを更新する必要があります。

  1. 3scale 設定でハンドラー設定を変更します。

    ハンドラー設定の例

      apiVersion: "config.istio.io/v1alpha2"
  kind: handler
  metadata:
   name: threescale
  spec:
   adapter: threescale
   params:
     service_id: "<SERVICE_ID>"
     system_url: "https://<organization>-admin.3scale.net/"
     access_token: "<ACCESS_TOKEN>"
   connection:
     address: "threescale-istio-adapter:3333"

オプションで、params セクション内の backend_url フィールドを指定して、3scale 設定によって提供される URL を上書きできます。これは、アダプターが 3scale のオンプレミスインスタンスと同じクラスターで実行され、内部クラスター DNS を利用する必要がある場合に役立ちます。

  1. 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

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

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

表7.1 使用法

オプション説明必須デフォルト値

-h, --help

利用可能なオプションについてのヘルプ出力を生成します

No

 

--name

この URL の一意の名前、トークンのペア

Yes

 

-n, --namespace

テンプレートを生成する namespace

No

istio-system

-t, --token

3scale アクセストークン

Yes

 

-u, --url

3scale 管理ポータル URL

Yes

 

--backend-url

3scale バックエンド URL。これが設定されている場合、システム設定から読み込まれる値がオーバーライドされます。

No

 

-s, --service

3scale API/サービス ID

No

 

--auth

指定する 3scale 認証パターン (1=Api Key、2=App Id/App Key、3=OIDC)

No

ハイブリッド

-o, --output

生成されたマニフェストを保存するファイル

No

標準出力

--version

CLI バージョンを出力し、即座に終了する

No

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

  • この例では、トークンと URL のペアを 1 つのハンドラーとして複数のサービスで共有できるようにテンプレートを生成します。 

    $ 3scale-gen-config --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"

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

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

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

  1. このコマンドを実行して、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}
  2. これでターミナルにサンプル出力が生成されます。必要に応じて、これらのサンプルを編集し、oc create コマンドを使用してオブジェクトを作成します。

  3. 要求がアダプターに到達すると、アダプターはサービスが 3scale の API にどのようにマッピングされるかを認識している必要があります。この情報は、以下のいずれかの方法で提供できます。

    1. ワークロードにラベルを付ける (推奨)
    2. ハンドラーを service_id としてハードコーディングする

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

    注記

    ハンドラーにまだ組み込まれていない場合は、このサンプルで提供されたサービス 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}"''

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

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

前提条件

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

手順

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

7.1.2. 3scale での統合設定

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

注記

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

手順

  1. [your_API_name] → Integration → Configuration の順に移動します。
  2. Integration ページの上部で、右上隅の edit integration settings をクリックします。
  3. Service Mesh の見出しで、Istio オプションをクリックします。
  4. ページの下部までスクロールし、Update Service をクリックします。

7.1.3. キャッシング動作

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

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

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

7.1.4. 認証要求

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

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

7.1.4.1. 認証パターンの適用

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

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

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

7.1.4.1.1. API キー認証方法

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

この例では、サービスメッシュは user_key クエリーパラメーターの API キーを検索します。API キーがクエリーパラメーターにない場合、サービスメッシュは x-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"] に変更します。

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

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

この例では、サービスメッシュは最初にクエリーパラメーターのアプリケーション 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"] に変更します。

7.1.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 ヘッダーに渡されます。

以下で定義されるサンプル Policy では、issuer と jwksUri を適宜置き換えます。

OpenID Policy の例

  apiVersion: authentication.istio.io/v1alpha1
  kind: Policy
  metadata:
    name: jwt-example
    namespace: bookinfo
  spec:
    origins:
      - jwt:
          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
    principalBinding: USE_ORIGIN
    targets:
      - name: productpage

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

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

この例では、サービスメッシュがクエリーパラメーターの 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"] | ""

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

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