運用ガイド

<ph type="x-smartling-placeholder"></ph> 現在、Apigee Edge のドキュメントが表示されています。
Apigee X のドキュメント
詳細

API キーを取得する方法

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

1. Apigee にログインする

  1. ブラウザで Apigee UI を開きます。
  2. UI が表示されたら、Apigee Adapter for Envoy の構成に使用したのと同じ組織を選択します。

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

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

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

3. API プロダクトの作成

以下のプロダクト作成例に従ってください。API のプロダクト構成についてもご覧ください。

  1. サイド ナビゲーション メニューで、[Publish] > [API Products] を選択します。
  2. [+API Product] をクリックします。
  3. [Product details] ページに、次のように入力します。
  4. フィールド
    名前 httpbin-product
    Display Name httpbin product
    環境 your_environment

    Apigee Adapter for Envoy をプロビジョニングしたときに使用した環境に設定します。

    アクセス Private
    Quota 5 requests every 1 minute

    割り当てもご覧ください。

  5. [Apigee remote service targets] セクションで、[Add an Apigee remote service target] をクリックします。
  6. [Apigee remote service target] ダイアログで、次の値を追加します。
    属性 説明
    Target name ターゲット サービスの名前を入力します。例: httpbin.org Envoy プロキシによって前面に配置されているターゲット エンドポイント。
    [Path] 照合するサービスのリソースパスを入力します。対象 例: /headers ターゲット エンドポイントで一致するリクエストパス。このパスへの API プロキシ呼び出しは、この API プロダクトと一致します。
  7. [保存] をクリックします。

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

  1. サイド ナビゲーション メニューで、[Publish] > [Apps] を選択します。
  2. [+ App] をクリックします。
  3. [Developer App] ページに、次のように入力します。指示があるまで、保存しないでください。
  4. 名前 httpbin-app
    Display Name httpbin app
    Developer 以前に作成したデベロッパーを選択するか、使用したいデベロッパーをリストから選択します。
  5. 次に、API プロダクトをアプリに追加します。 <ph type="x-smartling-placeholder">
      </ph>
    1. [Credentials] セクションで [+ Add product] をクリックし、構成したばかりのプロダクト(httpbin-product)を選択します。
    2. [作成] をクリックします。
    3. [Credentials] で、[Key] の横にある [Show] をクリックします。
    4. コンシューマ キーの値をコピーします。この値は、httpbin サービスに対して API 呼び出しを行うために使用する API キーです。

    API プロダクトについて

    API プロダクトは、Apigee Remote Service の主要なコントロール ポイントです。API プロダクトを作成してターゲット サービスにバインドするときに、Apigee Adapter for Envoy を構成して処理するすべてのリクエストに適用されるポリシーを作成します。

    API プロダクトの定義

    Apigee で API プロダクトを定義する際には、リクエストの評価に使用されるパラメータの数を設定できます。

    • ターゲット
    • リクエストパス
    • 割り当て
    • OAuth スコープ

    リモート サービス ターゲット

    API プロダクト定義は、リクエストがターゲット バインディング(httpbin.org など)とリクエストパス(/httpbin など)の両方に一致する場合に、そのリクエストに適用されます。可能性のあるターゲットのリストは、API プロダクト上の属性として保存されます。

    デフォルトでは、Apigee Remote Service により、Envoy の特別な :authority (host) ヘッダーがターゲットのリストと照合されます。ただし、他のヘッダーを使用するように構成することもできます。

    API リソースパス

    入力されたパスの一致は次のルールに基づいて判断されます。

    • シングル スラッシュ(/)は、それだけですべてのパスに一致します。
    • * はスラッシュに囲まれたセグメント内のどの場所でも有効で、任意の文字列に一致します。
    • ** は末尾に使うことができ、行末までのすべての文字列に一致します。

    割り当て

    割り当ては、アプリで 1 時間、1 日、1 週間、または 1 か月に API に送信できるリクエスト メッセージの数を指定します。アプリで割り当ての上限に達すると、後続の API 呼び出しは拒否されます。

    割り当ての使用例

    割り当てを使用すると、クライアントがサービスに対して一定の期間内に行えるリクエストの数を強制できます。割り当ては、運用上のトラフィック管理ではなく、デベロッパーやパートナーとの業務契約または SLA を適用するためによく使用されます。たとえば、無料サービスに対してはトラフィックを制限する一方で、有料ユーザーに対しては完全アクセス権を付与する場合などです。

    割り当ては API プロダクトで定義される

    割り当てパラメータは、API プロダクトで構成されます。たとえば、API プロダクトを作成するときに、必要に応じて、割り当て上限、時間単位、間隔を設定できます。

    API キーは API プロダクトにマッピングされるため、API キーが検証されるたびに、該当する割り当てカウンタが減少します(割り当てが関連プロダクトで定義されている場合)。

    Apigee ランタイム内とは異なり、プロダクト定義に入力された割り当ては、Apigee Remote Service によって自動的に適用されます。リクエストが承認された場合、そのリクエストは許可された割り当てに対してカウントされます。

    割り当てが保持される場所

    割り当ては、Remote Service プロセスによってローカルで維持されて確認され、Apigee ランタイムで非同期的に維持されます。これは、割り当てが正確ではなく、割り当てられている可能性が高いことを意味します。 割り当てを維持しているリモート サービスが複数ある場合は、オーバーランが発生します。Apigee ランタイムへの接続が中断された場合、ローカルの割り当ては、Apigee ランタイムに再接続できるまでの間など、スタンドアロンの割り当てとして継続されます。

    OAuth スコープ

    JWT トークンを使用している場合は、許可された OAuth スコープのサブセットにトークンを制限できます。発行済み JWT トークンに割り当てられたスコープは、API プロダクトのスコープに対して確認されます。

    デベロッパー アプリについて

    API プロダクトの構成が完了したら、デベロッパーに関連付けられるアプリを作成します。このアプリを使用すると、クライアントは API キーまたは JWT トークンを使用して、関連付けられた API プロダクトにアクセスできます。

    JWT ベースの認証の使用

    API キーではなく、JWT トークンを使用して、認証済みの API プロキシ呼び出しを行えます。この このセクションでは、apigee-remote-service-cli token コマンドを使用して次のことを行う方法について説明します。 JWT トークンの作成、検査、ローテーションを行えます。

    概要

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

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

    Apigee JWT トークンの作成

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

    $CLI_HOME/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 is 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 を使用して検査できます。例

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

    または

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

    デバッグ

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

    ロギング

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

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

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

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

    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://myorg-myenv.apigee.net/remote-service
            org_name: apigee-docs-hybrid-a
            env_name: *
            allow_unverified_ssl_cert: true
          analytics:
            collection_interval: 10s
          auth:
            jwt_provider_key: https://myorg-myenv.apigee.net.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. ファイルを保存して適用します。

    アダプタと 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