運用ガイド

このページの内容は ApigeeApigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

API キーを取得する方法

以下の例では、API 呼び出しの検証に使用できる、API キーを取得する方法を示します。ここでは、Apigee Adapter for Envoy でプロキシされたターゲット サービスに対する API 呼び出しを対象としています。

1. Apigee にログインする

  1. Apigee UI にログインします。
  2. Apigee Adapter for Envoy のプロビジョニングに使用した同じ組織を選択します。

2. デベロッパーを作成する

デベロッパーは、既存のものをテスト用に使用するか、次のように操作して新しく作成できます。

  1. サイド ナビゲーション メニューで、[Publish] > [Developers] を選択します。
  2. [+ Developer] をクリックします。
  3. ダイアログに入力して、新しいデベロッパーを作成します。任意のデベロッパー名 / メールを使用できます。

3. API プロダクトを作成する

以下のプロダクト作成例に沿って操作します。

  1. サイド ナビゲーション メニューで、[Publish] > [API Products] を選択します。
  2. [+Create] をクリックします。
  3. [Product details] ページに、次のように入力します。次の表に必要なフィールドのみを示します。
    フィールド 説明
    名前 httpbin-product API プロダクトの一意の名前。
    表示名 httpbin product UI またはその他の表示コンテキストに表示するわかりやすい名前。
    アクセス Public この例では、[Public] を選択することをおすすめします。
  4. [Operations] セクションで、[+Add an Operation] をクリックします。
  5. [Source] セクションで [Remote Service] を選択します。
  6. [Source] 切り替えを切り替えて、[Remote Service] フィールドにリモート サービスの名前を手動で入力できるようにします。
  7. [Remote Service] フィールドに、リモート サービスの名前を入力します。これはアダプタが受信 HTTP リクエストをプロキシするターゲット サービスです。テスト目的の場合は、Kubernetes で httpbin.org または httpbin.default.svc.cluster.local を使用します。

    [Remote Service] ラジオボタンが選択されています。手動テキスト入力の有効化が有効になっており、リモート サービス フィールドにリモート サービス httpbin.org が入力されています。

  8. [Operation] セクションで、パスに「/」と入力します。パスオプションの詳細については、リソースパスの構成をご覧ください。
  9. [Save] をクリックして、オペレーションを保存します。
  10. [Save] をクリックして、API プロダクトを保存します。

詳細については、API プロダクトの管理をご覧ください。

4. デベロッパー アプリを作成する

デベロッパー アプリには、アダプタを介して API プロキシ呼び出しを行うために必要な API キーが含まれています。

  1. サイド ナビゲーション メニューで、[Publish Apps] を選択します。
  2. [+ App] をクリックします。
  3. [App Details] セクションに、次のように入力します。次の表に必要なフィールドのみを示します。
  4. 名前 httpbin-app
    Developer 以前に作成したデベロッパーを選択するか、使用したいデベロッパーをリストから選択します。
  5. [Credentials] セクションで [+ Add product] をクリックし、構成したばかりのプロダクト(httpbin-product)を選択します。
  6. [Create] をクリックします。
  7. [Credentials] で、[Key] の横にある [Show] をクリックします。
  8. コンシューマ キーの値をコピーします。この値は、Apigee Adapter for Envoy を通じて httpbin サービスに対して API 呼び出しを行う API キーです。

JWT ベースの認証の使用

API キーではなく、JWT トークンを使用して、認証済みの API プロキシ呼び出しを行えます。このセクションでは、apigee-remote-service-cli token コマンドを使用して JWT トークンの作成、検査、ローテーションを行う方法について説明します。Apigee ハイブリッド環境では、このコマンドを使用して、JWT を保持する Kubernetes Secret を作成できます。

概要

JWT の検証と認証は、JWT 認証フィルタを使用して Envoy によって処理されます。

認証されると、Envoy の ext-authz フィルタでリクエスト ヘッダーと JWT が apigee-remote-service-envoy に送信されます。これは、JWT の api_product_list クレームと scope クレームを Apigee API プロダクトと照合し、リクエストのターゲットに対して JWT を認可します。

Apigee JWT トークンの作成

Apigee JWT トークンは CLI を使用して作成されます。

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

または、標準の OAuth トークン エンドポイントを使用して作成されます。curl の例を次に示します。

curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

JWT トークンの使用

トークンを作成したら、そのトークンを単純に Authorization ヘッダーで Envoy へ渡します。例:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

JWT トークンの障害

Envoy の拒否

Envoy によってトークンが拒否されると、次のようなメッセージが表示されます。

Jwks remote fetch has failed

その場合、Envoy の構成で remote_jwks セクションに有効な URI が含まれていること、Envoy から到達可能であること、Apigee プロキシのインストール時に証明書を適切に設定していることを確認してください。GET 呼び出しで URI を直接呼び出し、有効な JSON レスポンスを受信できるはずです。

例:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Envoy からのその他のメッセージには、次のようなものがあります。

  • 「Jwt のオーディエンスは許可されていません」
  • 「Jwt 発行元が構成されていません」

これらは Envoy 構成の要件によるものです。このような構成は変更する必要があるかもしれません。

トークンを検査する

トークンは、CLI を使用して検査できます。例

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

あるいは

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

デバッグ

有効な API キーが失敗するをご覧ください。

独自の ID プロバイダを使用する

デフォルトでは、Apigee Adapter for Envoy は、remote-token API プロキシを ID プロバイダ サービスとして使用し、クライアント アプリケーションを認証し、OAuth 2.0 クライアント認証情報の権限付与タイプに基づいて JWT トークンを渡します。ただし、remote-token プロキシを使用できない場合もあります。Apigee から提供されていない ID プロバイダを使用する必要がある場合は、別の ID プロバイダを使用するようにアダプタを構成できます。この Apigee 以外の ID プロバイダのユースケースと必要な構成について詳しくは、Apigee コミュニティの記事 Apigee Envoy Adapter で独自の ID プロバイダを使用するをご覧ください。

ロギング

ロギングレベルは、$REMOTE_SERVICE_HOME/apigee-remote-service-envoy サービスで調整できます。すべてのロギングは stderr に送信されます。

要素 必須 説明
-l、--log-level 有効なレベル: debug、info、warning、error ロギングレベルを調整します。デフォルトは、info です。
-j、--json-log ロギング出力を JSON レコードとして送信します。

Envoy はロギングを提供します。詳細については、次の Envoy のドキュメントのリンクをご覧ください。

ポリシーのシークレット名の変更

クラスタにデプロイされた Kubernetes Secret には、アダプタがリモート サービス プロキシとの通信を認証するために必要な認証情報が含まれています。この Secret には、構成可能なボリュームのマウント ポイントが必要です。デフォルトのマウント ポイントは /policy-secret です。マウント ポイントを変更するには、次の手順を行います。

  1. 次のコマンドを実行します。
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    次に例を示します。

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. エディタで $CLI_HOME/samples/apigee-envoy-adapter.yaml を開きます。
  3. マウント ポイント名を新しい名前に変更します。
    volumeMounts:
      - mountPath: /config
        name: apigee-remote-service-envoy
        readOnly: true
      - mountPath: /opt/apigee/tls
        name: tls-volume
        readOnly: true
      - mountPath: /my-mount-point
        name: policy-secret
        readOnly: true
  4. ファイルを保存し、サービス メッシュに適用します。
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

ネットワーク プロキシの使用

apigee-remote-service-envoy バイナリの環境では、HTTP_PROXY 環境変数と HTTPS_PROXY 環境変数を使用することで、HTTP プロキシの挿入が可能です。これらを使用する場合は、NO_PROXY 環境変数を使用して、プロキシ経由での送信から特定のホストを除外することもできます。

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

このプロキシは apigee-remote-service-envoy から到達可能である必要があります。

指標と分析について

Prometheus 指標エンドポイントは、:5001/metrics で入手できます。このポート番号は構成可能です。構成ファイルをご覧ください。

Envoy 分析

次のリンクでは、Envoy プロキシ分析データの取得に関する情報を提供しています。

Istio 分析

次のリンクでは、Envoy プロキシ分析データの取得に関する情報を提供しています。

Apigee Analytics

Apigee Remote Service for Envoy は、分析の処理のためにリクエスト統計を Apigee に送信します。これらのリクエストは、Apigee によって関連する API プロダクト名で報告されます。

Apigee Analytics の詳細については、Analytics サービスの概要をご覧ください。

マルチテナント環境のサポート

アダプタを有効にして、Apigee 組織内の複数の環境にサービスを提供できるようになりました。この機能を使用すると、1 つの Apigee 組織に関連付けられた 1 つの Apigee Adapter for Envoy を使用して複数の環境にサービスを提供できます。以前は、1 つのアダプタが常に 1 つの Apigee 環境に関連付けられていました。

複数環境のサポートを構成するには、config.yaml ファイルで tenant:env_name の値を "*" に変更します。例:

  1. エディタで config.yaml ファイルを開きます。
  2. tenant.env_name の値を "*" に変更します。次に例を示します。
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee
    data:
      config.yaml: |
        tenant:
          remote_service_api: https://apitest.mydomain.net/remote-service
          org_name: my-org
          env_name: "*""
          allow_unverified_ssl_cert: true
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.mydomain.net/remote-token/token
  3. ファイルを保存します。
  4. ファイルを適用します。
    kubectl apply -f $CLI_HOME/config.yaml

マルチ環境モードを構成する場合は、envoy-config.yaml ファイルの virtual_hosts:routes セクションに次のメタデータを追加して、アダプタに適切な環境値を送信するように Envoy を構成する必要もあります。例:

  1. CLI を使用して envoy-config.yaml ファイルを生成します。例:
    $CLI_HOME/apigee-remote-service-cli samples create \
      -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. 生成されたファイル(envoy-config.yaml という名前)を開きます。
  3. ファイルの virtual_host セクションまたは routes セクションに、次のメタデータを追加します。
    typed_per_filter_config:
      envoy.filters.http.ext_authz:
        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
        check_settings:
          context_extensions:
            apigee_environment: test

    次の例では、複数のルートが定義された virtual_host の構成を示します。ここで、各ルートは、特定の環境にトラフィックを送信します。

    filter_chains:
        - filters:
          - name: envoy.filters.network.http_connection_manager
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
              stat_prefix: ingress_http
              route_config:
                virtual_hosts:
                - name: default
                  domains: "*"
                  routes:
                  - match: { prefix: /test }
                    route:
                      cluster: httpbin
                    typed_per_filter_config:
                      envoy.filters.http.ext_authz:
                        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                        check_settings:
                          context_extensions:
                             apigee_environment: test
                  - match: { prefix: /prod }
                    route:
                      cluster: httpbin
                    typed_per_filter_config:
                      envoy.filters.http.ext_authz:
                        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                        check_settings:
                          context_extensions:
                             apigee_environment: prod
  4. 必要に応じて、最後のステップを繰り返して環境を追加します。
  5. ファイルを保存して適用します。

カスタム レポートのデータ キャプチャ

アダプタでは、Envoy メタデータを Apigee のデータ キャプチャ機能に渡すことができます。これにより、指定した変数でキャプチャされたデータが、カスタム レポートで使用するために Apigee アナリティクスに送信されます。この機能は、Apigee データ キャプチャ ポリシーに似た機能を提供します。

この機能を使用するには:

  1. Data Collector REST リソースを作成します。
  2. Apigee Datacollectors API を使用してデータ キャプチャ変数を定義します。
  3. まだ生成していない場合は、CLI を使用して envoy-config.yaml ファイルを生成します。例:
    $CLI_HOME/apigee-remote-service-cli samples create \
      -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. 生成されたファイル(envoy-config.yaml という名前)を開きます。
  5. Envoy フィルタを使用して、envoy.filters.http.apigee.datacapture 名前空間にカスタム変数の値を設定します。たとえば、Header to Metadata フィルタや Lua フィルタを使用できます。これらのフィルタの詳細については、Header-To-MetadataLua をご覧ください。

    カスタム変数の名前は、dc.XXXXX としてフォーマットする必要があります。

    Header to Metadata フィルタの例を次に示します。

     - name: envoy.filters.http.header_to_metadata
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
        request_rules:
          - header: "Host"
            on_header_present:
              metadata_namespace: envoy.filters.http.apigee.datacapture
              key: dc.host  # host (without the prefix) also works
              type: STRING
            remove: false

    Lua フィルタの例を次に示します。

    - name: envoy.filters.http.lua
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
        inline_code: |
          function envoy_on_request(request_handle)
            metadata = request_handle:streamInfo():dynamicMetadata()
            metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
          end
  6. 必要なフィルタをファイルに追加します。下記の例をご覧ください。
  7. ファイルを保存して適用します。

アダプタと Apigee ランタイム間の mTLS の構成

アダプタと Apigee ランタイムの間で mTLS を使用するために、アダプタの config.yaml ファイルの tenant セクションでクライアント側 TLS 証明書を指定できます。この変更は、サポートされているすべての Apigee プラットフォームに適用されます。また、それにより、Apigee Edge for Private Cloud プラットフォームの分析用の mTLS も有効化されます。例:

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false