第7章 3scale での Kafka Bridge の使用

Red Hat 3scale API Management をデプロイし、AMQ Streams の Kafka Bridge と統合できます。

7.1. 3scale での Kafka Bridge の使用

Kafka Bridge のプレーンデプロイメントでは、認証または承認のプロビジョニングがなく、TLS 暗号化による外部クライアントへの接続はサポートされません。

3scale を使用すると、TLS によって Kafka Bridge のセキュリティーが保護され、認証および承認も提供されます。また、3scale との統合により、メトリクス、流量制御、請求などの追加機能も利用できるようになります。

3scale では、AMQ Streams へのアクセスを希望する外部クライアントからのリクエストに対して、各種タイプの認証を使用できます。3scale では、以下のタイプの認証がサポートされます。

標準 API キー
識別子およびシークレットトークンとして機能する、ランダムな単一文字列またはハッシュ。
アプリケーション ID とキーのペア
イミュータブルな識別子およびミュータブルなシークレットキー文字列。
OpenID Connect
委譲された認証のプロトコル。

既存の 3scale デプロイメントを使用する場合

3scale がすでに OpenShift にデプロイされており、Kafka Bridge と併用する場合は、正しく設定されていることを確認してください。

設定については、「Kafka Bridge を使用するための 3scale のデプロイメント」 を参照してください。

7.1.1. Kafka Bridge のサービス検出

3scale は、サービス検出を使用して統合されますが、これには 3scale が AMQ Streams および Kafka Bridge と同じ OpenShift クラスターにデプロイされている必要があります。

AMQ Streams Cluster Operator デプロイメントには、以下の環境変数が設定されている必要があります。

  • STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_LABELS
  • STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_ANNOTATIONS

Kafka Bridge をデプロイすると、Kafka Bridge の REST インターフェースを公開するサービスは、3scale による検出にアノテーションとラベルを使用します。

  • 3scale によって discovery.3scale.net=true ラベルが使用され、サービスが検出されます。
  • アノテーションによってサービスに関する情報が提供されます。

OpenShift コンソールで設定を確認するには、Kafka Bridge インスタンスの Services に移動します。Annotations に、Kafka Bridge の OpenAPI 仕様へのエンドポイントが表示されます。

7.1.2. 3scale APIcast ゲートウェイポリシー

3scale は 3scale APIcast と併用されます。3scale APIcast は、Kafka Bridge の単一エントリーポイントを提供する 3scale とデプロイされる API ゲートウェイです。

APIcast ポリシーは、ゲートウェイの動作をカスタマイズするメカニズムを提供します。3scale には、ゲートウェイ設定のための標準ポリシーのセットが含まれています。また、独自のポリシーを作成することもできます。

APIcast ポリシーの詳細は、3scale ドキュメントの「API ゲートウェイの管理」を参照してください。

Kafka Bridge の APIcast ポリシー

3scale と Kafka Bridge との統合のポリシー設定例は policies_config.json ファイルに含まれており、このファイルでは以下を定義します。

  • Anonymous Access (匿名アクセス)
  • Header Modification (ヘッダー変更)
  • Routing (ルーティング)
  • URL Rewriting (URL の書き換え)

ゲートウェイポリシーは、このファイルを使用して有効または無効に設定します。

この例をひな形として使用し、独自のポリシーを定義できます。

Anonymous Access (匿名アクセス)
Anonymous Access ポリシーでは、認証をせずにサービスが公開され、HTTP クライアントがデフォルトのクレデンシャル (匿名アクセス用) を提供しない場合に、このポリシーによって提供されます。このポリシーは必須ではなく、認証が常に必要であれば無効または削除できます。
Header Modification (ヘッダー変更)

Header Modification ポリシーを使用すると、既存の HTTP ヘッダーを変更したり、ゲートウェイを通過するリクエストまたはレスポンスへ新規ヘッダーを追加したりすることができます。3scale の統合では、このポリシーによって、HTTP クライアントから Kafka Bridge までゲートウェイを通過するすべてのリクエストにヘッダーが追加されます。

Kafka Bridge は、新規コンシューマー作成のリクエストを受信すると、URI のある base_uri フィールドが含まれる JSON ペイロードを返します。コンシューマーは後続のすべてのリクエストにこの URI を使用する必要があります。以下に例を示します。

{
  "instance_id": "consumer-1",
  "base_uri":"http://my-bridge:8080/consumers/my-group/instances/consumer1"
}

APIcast を使用する場合、クライアントは以降のリクエストをすべてゲートウェイに送信し、Kafka Bridge には直接送信しません。そのため URI には、ゲートウェイの背後にある Kafka Bridge のアドレスではなく、ゲートウェイのホスト名が必要です。

Header Modification ポリシーを使用すると、ヘッダーが HTTP クライアントからリクエストに追加されるので、Kafka Bridge はゲートウェイホスト名を使用します。

たとえば、Forwarded: host=my-gateway:80;proto=http ヘッダーを適用すると、Kafka Bridge は以下をコンシューマーに提供します。

{
    "instance_id": "consumer-1",
    "base_uri":"http://my-gateway:80/consumers/my-group/instances/consumer1"
}

X-Forwarded-Path ヘッダーには、クライアントからゲートウェイへのリクエストに含まれる元のパスが含まれています。このヘッダーは、ゲートウェイが複数の Kafka Bridge インスタンスをサポートする場合に適用される Routing ポリシーに密接に関連します。

Routing (ルーティング)

Routing ポリシーは、複数の Kafka Bridge インスタンスがある場合に適用されます。コンシューマーが最初に作成された Kafka Bridge インスタンスにリクエストを送信する必要があるため、適切な Kafka Bridge インスタンスにリクエストを転送するようゲートウェイのルートをリクエストに指定する必要があります。

Routing ポリシーは各ブリッジインスタンスに名前を付け、ルーティングはその名前を使用して実行されます。Kafka Bridge のデプロイ時に、KafkaBridge カスタムリソースで名前を指定します。

たとえば、コンシューマーから以下への各リクエスト (X-Forwarded-Path を使用) について考えてみましょう。

http://my-gateway:80/my-bridge-1/consumers/my-group/instances/consumer1

この場合、各リクエストは以下に転送されます。

http://my-bridge-1-bridge-service:8080/consumers/my-group/instances/consumer1

URL Rewriting ポリシーはブリッジ名を削除しますが、これは、リクエストをゲートウェイから Kafka Bridge に転送するときにこのポリシーが使用されないからです。

URL Rewriting (URL の書き換え)

URL Rewiring ポリシーは、ゲートウェイから Kafka Bridge にリクエストが転送されるとき、クライアントから特定の Kafka Bridge インスタンスへのリクエストにブリッジ名が含まれないようにします。

ブリッジ名は、ブリッジが公開するエンドポイントで使用されません。

7.1.3. TLS の検証

TLS の検証用に APIcast を設定できます。これにはテンプレートを使用した APIcast の自己管理によるデプロイメントが必要になります。apicast サービスがルートとして公開されます。

TLS ポリシーを Kafka Bridge API に適用することもできます。

TLS 設定の詳細は、3scale ドキュメントの「API ゲートウェイの管理」を参照してください。

7.1.4. 3scale ドキュメント

3scale を Kafka Bridge と使用するためにデプロイする手順は、3scale をある程度理解していることを前提としています。

詳細は、3scale の製品ドキュメントを参照してください。

7.2. Kafka Bridge を使用するための 3scale のデプロイメント

3scale を Kafka Bridge で使用するには、まず 3scale をデプロイし、次に Kafka Bridge API の検出を設定します。

また、3scale APIcast および 3scale toolbox も使用します。

  • APIcast は、HTTP クライアントが Kafka Bridge API サービスに接続するための NGINX ベースの API ゲートウェイとして、3scale により提供されます。
  • 3scale toolbox は設定ツールで、Kafka Bridge サービスの OpenAPI 仕様を 3scale にインポートするために使用されます。

このシナリオでは、AMQ Streams、Kafka、Kafka Bridge、および 3scale/APIcast を、同じ OpenShift クラスターで実行します。

注記

3scale がすでに Kafka Bridge と同じクラスターにデプロイされている場合は、デプロイメントの手順を省略して、現在のデプロイメントを使用できます。

3scale デプロイメントの場合:

  • 「Red Hat 3scale API Management Supported Configurations」を確認します。
  • インストールには、cluster-admin ロール (system:admin など) を持つユーザーが必要です。
  • 以下が記述されている JSON ファイルにアクセスできる必要があります。

    • Kafka Bridge OpenAPI 仕様 (openapiv2.json)
    • Kafka Bridge のヘッダー変更および Routing ポリシー (policies_config.json)

      GitHub で JSON ファイルを探します。

手順

  1. 3scale API Management を OpenShift クラスターにデプロイします。

    1. 新規プロジェクトを作成するか、または既存プロジェクトを使用します。

      oc new-project my-project \
          --description="description" --display-name="display_name"
    2. 3scale をデプロイします。

      「3scale のインストール」 ガイドに記載の情報に従い、テンプレートまたは Operator を使用して OpenShift に 3scale をデプロイします。

      どの方法を使用する場合も、WILDCARD_DOMAIN パラメーターが OpenShift クラスターのドメインに設定されていることを確認してください。

      3scale 管理ポータルにアクセスするために表示される URL およびクレデンシャルを書き留めておきます。

  2. 3scale が Kafka Bridge サービスを検出するように承認を付与します。

    oc adm policy add-cluster-role-to-user view system:serviceaccount:my-project:amp
  3. 3scale が OpenShift コンソールまたは CLI から Openshift クラスターに正常にデプロイされたことを確認します。

    以下に例を示します。

    oc get deployment 3scale-operator
  4. 3scale toolbox を設定します。

    1. 『Operating 3scale』 に記載の情報を使用して、3scale toolbox をインストールします。
    2. 3scale と対話できるように環境変数を設定します。

      export REMOTE_NAME=strimzi-kafka-bridge 1
      export SYSTEM_NAME=strimzi_http_bridge_for_apache_kafka 2
      export TENANT=strimzi-kafka-bridge-admin 3
      export PORTAL_ENDPOINT=$TENANT.3scale.net 4
      export TOKEN=3scale access token 5
      1
      REMOTE_NAME は、3scale 管理ポータルのリモートアドレスに割り当てられた名前です。
      2
      SYSTEM_NAME は、3scale toolbox で OpenAPI 仕様をインポートして作成される 3scale サービス/API の名前です。
      3
      TENANT は、3scale 管理ポータルのテナント名です (https://$TENANT.3scale.net)。
      4
      PORTAL_ENDPOINT は、3scale 管理ポータルを実行するエンドポイントです。
      5
      TOKEN は、3scale toolbox または HTTP リクエストを介して対話するために 3scale 管理ポータルによって提供されるアクセストークンです。
    3. 3scale toolbox のリモート Web アドレスを設定します。

      3scale remote add $REMOTE_NAME https://$TOKEN@$PORTAL_ENDPOINT/

      これで、toolbox を実行するたびに、3scale 管理ポータルのエンドポイントアドレスを指定する必要がなくなりました。

  5. Cluster Operator デプロイメントに、3scale が Kafka Bridge サービスを検出するために必要なラベルプロパティーおよびアノテーションプロパティーがあることを確認します。

    #...
    env:
    - name: STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_LABELS
        value: |
        discovery.3scale.net=true
    - name: STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_ANNOTATIONS
        value: |
        discovery.3scale.net/scheme=http
        discovery.3scale.net/port=8080
        discovery.3scale.net/path=/
        discovery.3scale.net/description-path=/openapi
    #...

    これらのプロパティーがない場合は、OpenShift コンソールからプロパティーを追加するか、Cluster Operator および Kafka Bridge を再デプロイします。

  6. 3scale で Kafka Bridge API サービスを検出します。

    1. 3scale をデプロイしたときに提供されたクレデンシャルを使用して、3scale 管理ポータルにログインします。
    2. 3scale 管理ポータルから、New APIImport from OpenShiftに移動します。ここで、Kafka Bridge サービスが表示されます。
    3. Create Service をクリックします。

      ページを更新して Kafka Bridge サービスを表示することが必要な場合もあります。

      ここで、サービスの設定をインポートする必要があります。エディターからインポートしますが、ポータルを開いたまま正常にインポートされたことを確認します。

  7. OpenAPI 仕様 (JSON ファイル) の Host フィールドを編集して、Kafka Bridge サービスのベース URL を使用します。

    以下に例を示します。

    "host": "my-bridge-bridge-service.my-project.svc.cluster.local:8080"

    host URL に以下が正しく含まれることを確認します。

    • Kafka Bridge 名 (my-bridge)
    • プロジェクト名 (my-project)
    • Kafka Bridge のポート (8080)
  8. 3scale toolbox を使用して、更新された OpenAPI 仕様をインポートします。

    3scale import openapi -k -d $REMOTE_NAME openapiv2.json -t myproject-my-bridge-bridge-service
  9. サービスの Header Modification および Routing ポリシー (JSON ファイル) をインポートします。

    1. 3scale で作成したサービスの ID を特定します。

      ここでは、`jq` ユーティリティー を使用します。

      export SERVICE_ID=$(curl -k -s -X GET "https://$PORTAL_ENDPOINT/admin/api/services.json?access_token=$TOKEN" | jq ".services[] | select(.service.system_name | contains(\"$SYSTEM_NAME\")) | .service.id")

      ポリシーをインポートするときにこの ID が必要です。

    2. ポリシーをインポートします。

      curl -k -X PUT "https://$PORTAL_ENDPOINT/admin/api/services/$SERVICE_ID/proxy/policies.json" --data "access_token=$TOKEN" --data-urlencode policies_config@policies_config.json
  10. 3scale 管理ポータルから、IntegrationConfiguration に移動し、Kafka Bridge サービスのエンドポイントとポリシーが読み込まれていることを確認します。
  11. アプリケーションプランを作成するために、ApplicationsCreate Application Plan に移動します。
  12. アプリケーションを作成するために、AudienceDeveloperApplicationsCreate Application に移動します。

    認証のユーザーキーを取得するためにアプリケーションが必要になります。

  13. 実稼働環境用の手順: 実稼働環境のゲートウェイで API を利用可能にするには、設定をプロモートします。

    3scale proxy-config promote $REMOTE_NAME $SERVICE_ID
  14. API テストツールを使用して、コンシューマーの作成に呼び出しを使用する APIcast ゲートウェイと、アプリケーションに作成されたユーザーキーで、Kafka Bridge にアクセスできることを検証します。

    以下に例を示します。

    https//my-project-my-bridge-bridge-service-3scale-apicast-staging.example.com:443/consumers/my-group?user_key=3dfc188650101010ecd7fdc56098ce95

    Kafka Bridge からペイロードが返されれば、コンシューマーが正常に作成されています。

    {
      "instance_id": "consumer1",
      "base uri": "https//my-project-my-bridge-bridge-service-3scale-apicast-staging.example.com:443/consumers/my-group/instances/consumer1"
    }

    ベース URI は、クライアントが以降のリクエストで使用するアドレスです。