Extensible Service Proxy V2 ベータ版の起動オプション

Extensible Service Proxy V2 ベータ版(ESPv2 ベータ版)は、Cloud Endpoints で API 管理機能を提供できるようにする Envoy ベースのプロキシです。ESPv2 ベータ版を構成するには、ESPv2 ベータ版 Cloud Run サービスのデプロイ時に構成フラグを指定します。

ESPv2 ベータ版のフラグは次のカテゴリで使用できます。

構成フラグの設定

gcloud run deploy コマンドを使用して、ESPv2 ベータ版を Cloud Run にデプロイします。ESPv2 ベータ版を構成するには、ESPv2_ARGS 環境変数を使用して、gcloud --set-env-vars オプションに構成フラグを指定します。

例:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

gcloud run deploy コマンドの詳細については、Cloud Functions または Cloud Run をご覧ください。

ESPv2_ARGS 環境変数に複数の引数を設定する必要がある場合は、カンマを区切り文字として使用しないでください。カスタム区切り文字を指定して、その区切り文字で複数の引数を区切ります。キャレットで囲まれた ESPv2_ARGS 環境変数の先頭にカスタム区切り文字を配置します。

次の例では、++ を区切り文字として使用しています。

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

フラグにカンマが含まれる場合(たとえば、--cors_allow_methods=PUT,POST,GET)、ダウンロードした gcloud_build_image スクリプトに ESPv2_ARGS 環境変数を設定する必要があります。次のように gcloud_build_image を編集します。複数の引数を区切る場合にもカスタム区切り文字を使用します。

cat <<EOF > Dockerfile
FROM ${BASE_IMAGE}

ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
COPY service.json \${ENDPOINTS_SERVICE_PATH}

ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials

ENTRYPOINT ["/env_start_proxy.py"]
EOF

gcloud_build_image スクリプトを実行して、イメージをビルドします。

ロギング

追加情報を Stackdriver ログに書き込むように ESPv2 ベータ版を構成します。

フラグ 説明
--log_request_headers

指定されたリクエスト ヘッダーの値をカンマ区切りでログに記録します。たとえば、このフラグを次のように設定します。

--log_request_headers=foo,bar

foo ヘッダーと bar ヘッダーの値がリクエストで使用可能な場合、Endpoints ログには次の情報が含まれます。

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

指定されたレスポンス ヘッダーの値をカンマ区切りでログに記録します。たとえば、このフラグを次のように設定します。

--log_response_headers=baz,bing

baz ヘッダーと bing ヘッダーの値がレスポンスで使用可能な場合、Endpoints ログには次の情報が含まれます。

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

指定された JWT ペイロード プリミティブ フィールドの値をカンマ区切りでログに記録します。たとえば、このフラグを次のように設定します。

--log_jwt_payload=sub,project_id,foo.foo_name

値が JWT ペイロードで使用可能な場合、Endpoints ログには次の情報が含まれます。

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

JWT ペイロードの値は、プリミティブ フィールド(string、integer)でなければなりません。JSON オブジェクトと配列はログに記録されません。

トレース

Stackdriver に送信される ESPv2 ベータ版トレースデータを構成します。これらのフラグは、トレースが有効な場合にのみ適用されます。

フラグ 説明
--disable_tracing

トレースを無効にします。デフォルトでは、トレースは有効になっています。

有効にすると、ESPv2 ベータ版は Stackdriver Trace に送信するトレースを取得するため、API に対するリクエストの少数を 1 秒ごとにサンプリングします。デフォルトでは、1, 000 件中 1 件のリクエストをサンプリングします。サンプリング レートを変更するには、--tracing_sample_rate フラグを使用します。

--tracing_project_id

Stackdriver トレース用の Google プロジェクト ID。

トレースは有料サービスです。指定されたプロジェクトに、トレースの料金が課金されます。

デフォルトでは、デプロイされた ESPv2 ベータ版サービスのプロジェクト ID に料金が請求されます。

--tracing_sample_rate

トレースのサンプリング レートを 0.0 から 1.0 までの値で設定します。この値は、サンプリングされるリクエストの割合を表します。

デフォルト値は 0.001 で、1,000 件中 1 件のリクエストがサンプリングされます。

--tracing_incoming_context

分散トレースの場合、リクエスト ヘッダーにトレース ID を表すトレース コンテキストが含まれる場合があります。このトレース ID は、ESPv2 が新しいトレーススパンを作成し、トレース バックエンド(Stackdriver)に送信するときに使用されます。このトレース ID を使用すると、すべての分散コンポーネントからのリクエストについてすべてのトレーススパンを検索できます。リクエストにトレース コンテキストがなく、トレースが有効になっている場合は、すべてのトレーススパンに対してトレース ID がランダムに生成されます。

このフラグには、トレース コンテキストを確認する HTTP ヘッダーを指定します。指定する際は、スペースを入れずにカンマで区切って指定します。たとえば、このフラグを次のように設定します。

--tracing_incoming_context=x-cloud-trace-context

可能な値は traceparentx-cloud-trace-context です。

省略した場合、トレース コンテキストに対するチェックは行われません。

x-cloud-trace-context の詳細については、このトラブルシューティングの記事をご覧ください。traceparent の詳細については、トレース コンテキスト HTTP ヘッダー形式をご覧ください。

--tracing_outgoing_context

Cloud Functions や Cloud Run など、バックエンド サービスに送信されるリクエストにトレース コンテキス トヘッダーを設定します。トレース コンテキストの詳細については、上記の --tracing_incoming_context の説明をご覧ください。

このフラグには、設定する HTTP ヘッダーを指定します。指定する際は、スペースを入れずカンマで区切って指定します。たとえば、このフラグを次のように設定します。

--tracing_outgoing_context=traceparent

可能な値は traceparentx-cloud-trace-context です。

省略した場合、トレース コンテキスト ヘッダーは送信されません。

x-cloud-trace-context の詳細については、このトラブルシューティングの記事をご覧ください。traceparent の詳細については、トレース コンテキスト HTTP ヘッダー形式をご覧ください。

デバッグモードの有効化

デバッグモードで実行してデバッグレベルの情報をログに書き込むように、ESPv2 ベータ版を構成します。

フラグ 説明
--enable_debug Envoy のデバッグレベル モードのログを有効にして、ConfigManager がサービス構成の詳細を記録できるようにします。

CORS サポートの追加

CORS(クロスオリジン リソース シェアリング)は、ウェブページ内で実行される XMLHttpRequest(XHR)呼び出しが、それとはオリジンが異なるリソースとやり取りできるようにするための標準メカニズムです。CORS を使用しない場合、すべてのブラウザで適用されている同一オリジン ポリシーにより、クロスオリジン リクエストが阻止されます。CORS の詳しい背景情報については、Mozilla Developer Network(MDN)ウェブ ドキュメントをご覧ください。

バックエンドが CORS をサポートし、ESPv2 ベータ版が CORS リクエストをバックエンドに渡す必要がある場合は、API の OpenApi 仕様に次のように指定できます。

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

バックエンドが CORS をサポートせず、ESPv2 ベータ版で CORS をサポートする必要がある場合は、ESPv2 ベータ版で CORS サポートを有効にする必要があります。

ESPv2 ベータ版で CORS サポートを有効にするには、--cors_preset オプションを追加し、basic または cors_with_regex に設定します。--cors_preset=basic または --cors_preset=cors_with_regex を追加すると、ESPv2 ベータ版は次の処理を行います。

  • すべての場所のパスで同じ CORS ポリシーが適用されていると想定します。
  • 単純なリクエストとプリフライト HTTP OPTIONS リクエストの両方に応答します。
  • プリフライト OPTIONS リクエストの結果を最大 20 日間(1,728,000 秒)キャッシュに保存します。
  • レスポンス ヘッダーを次の値に設定します。

    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
    Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
    Access-Control-Expose-Headers: Content-Length,Content-Range
    

Access-Control-Allow-Origin のデフォルト値をオーバーライドするには、次のいずれかのオプションを指定します。

オプション 説明
--cors_allow_origin --cors_preset=basic と一緒に使用して、Access-Control-Allow-Origin に特定のオリジンを設定します。
例:
--cors_preset=basic
--cors_allow_origin="http://example.com"
--cors_allow_origin_regex --cors_preset=cors_with_regex と一緒に使用します。正規表現を使用して Access-Control-Allow-Origin を設定できます。
例:
--cors_preset=cors_with_regex
--cors_allow_origin_regex='^https?://.+\.example\.com$'

上記の例の正規表現では、http または https を使用するオリジンと example.com のすべてのサブドメインが許可されます。

Kubernetes 構成ファイルでオプションを設定する場合は、追加のバックスラッシュ文字を使用して、文字列内の \. の両方のインスタンスをエスケープする必要があります。たとえば、次のようにします。

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

--cors_preset=basic または --cors_preset=cors_with_regex を設定して CORS を有効にした後に、次の 1 つ以上のオプションを指定すると、他のレスポンス ヘッダーのデフォルト値をオーバーライドできます。

オプション 説明
--cors_allow_methods Access-Control-Allow-Methods を指定の HTTP メソッドに設定します。対象とする HTTP メソッドを、各 HTTP メソッドをカンマで区切った文字列として指定します。
例:
--cors_preset=basic
--cors_allow_methods="GET,POST,PUT,OPTIONS"
--cors_allow_headers Access-Control-Allow-Headers を指定の HTTP ヘッダーに設定します。対象とする HTTP ヘッダーを、各 HTTP ヘッダーをカンマで区切った文字列として指定します。
例:
--cors_preset=basic
--cors_allow_headers="Origin,Content-Type,Accept"
--cors_allow_credentials レスポンスに Access-Control-Allow-Credentials ヘッダーを追加し、値 true を設定します。デフォルトでは、Access-Control-Allow-Credentials ヘッダーはレスポンスに含まれません。
例:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Access-Control-Expose-Headers を特定のヘッダーに設定します。レスポンスの一部として公開可能なヘッダーを指定します。対象とするヘッダーを、各ヘッダーをカンマで区切った文字列として指定します。
例:
--cors_preset=basic
--cors_expose_headers="Content-Length"

次のステップ

以下の内容について学習します。