Extensible Service Proxy V2 の起動オプション

OpenAPI   |  gRPC

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

構成フラグの設定

ESPv2 構成フラグを設定する方法は、以下のセクションで説明するように、デプロイするプラットフォームによって異なります。

Compute Engine VM

Compute Engine の ESPv2 構成フラグは、docker run コマンドで指定します。例:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

この例では、--service、--rollout_strategy、--backend は ESPv2 ベータ版の構成フラグです。

GKE と Kubernetes

デプロイ マニフェスト ファイルの args フィールドで GKE と Kubernetes の構成フラグを指定できます。例:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

この例では、--listener_port、--backend、--service、--rollout_strategy は ESPv2 ベータ版の構成フラグです。

サーバーレス プラットフォーム用の Cloud Run

サーバーレス プラットフォーム用の Cloud Run の起動オプションを指定するには、ESPv2_ARGS 環境変数を使用します。この変数は、--set-env-vars オプションを使用して gcloud run deploy コマンドで設定できます。

例:

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

この例では、--enable_debug は ESPv2 ベータ版の構成フラグです。

gcloud run deploy コマンドについて詳しくは、Cloud Functions for OpenAPI、Cloud Run for OpenAPI、Cloud Run for gRPC をご覧ください。

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

設定するフラグにカンマが含まれている場合は、gcloud_build_image スクリプトで ESPv2_ARGS 環境変数を設定する必要があります。

たとえば、次のようにフラグ --cors_allow_methods=PUT,POST,GET を追加します。

• gcloud_build_image スクリプトをダウンロードします。
• 次のように 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 スクリプトを実行して、イメージをビルドします。

ESPv2 構成フラグ

ESPv2 構成フラグは、次のカテゴリに分類できます。

• サーバーレス以外の構成
• ロギング
• トレース
• ヘルスチェック
• デバッグ
• ローカルテスト
• Google Cloud 以外のデプロイ
• クライアント IP の抽出
• CORS サポート
• TLS サポート
• タイムアウトと再試行
• gRPC コード変換
• リクエストとレスポンスの変更
• セキュリティ対策
• JWT 認証

ESPv2 のフラグに関するその他の一般的な例とヘルプテキストについては、GitHub リポジトリをご覧ください。

サーバーレス以外の構成

これらのフラグは、GKE、Compute Engine、Kubernetes などのサーバーレス以外のプラットフォームで ESPv2 を実行するために必要です。サーバーレス プラットフォーム用に Cloud Run にデプロイする場合は、これらを設定できません。

注: Kubernetes ユーザーの場合、構成ファイルでフィールド値を引用符で囲まないでください。たとえば、--cors_allow_origin="http://example.com" では、目的の文字列値 http://example.com ではなく、文字列値 \"http://example.com\" がフィールド cor_allow_origin に割り当てられます。

``

フラグ	説明
--service	Endpoints サービスの名前を設定します。
--version	Endpoints サービスのサービス構成 ID を設定します。
--rollout_strategy	サービス構成ロールアウト戦略を指定します（[fixed|managed]）。 デフォルトは fixed です。
--listener_port	ダウンストリーム接続を受け入れるポートを指定します。HTTP/1.x、HTTP/2、gRPC 接続がサポートされます。デフォルトは 8080 です。
--backend	ローカル バックエンド アプリケーション サーバーのアドレスを指定します。有効なスキームは http、https、grpc、grpcs です（含まれている場合）。デフォルトのスキームは >http です。

ロギング

これらのフラグを使用して、追加情報を 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 オブジェクトと配列はログに記録されません。
--access_log	指定した場合、アクセス ログ エントリを書き込むローカル ファイルへのパス。
--access_log_format	アクセスログの形式を指定する文字列形式。設定しなかった場合は、>デフォルトの形式文字列が使用されます。形式の文法の詳細については、形式文字列リファレンスをご覧ください。

トレース

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

フラグ	説明
--disable_tracing	トレースを無効にします。デフォルトでは、トレースは有効になっています。 有効にすると、ESPv2 は Stackdriver Trace に送信するトレースを取得するため、API に対するリクエストの少数を 1 秒ごとにサンプリングします。デフォルトでは、1, 000 件中 1 件のリクエストをサンプリングします。サンプリング レートを変更するには、--tracing_sample_rate フラグを使用します。
--tracing_project_id	Stackdriver トレース用の Google プロジェクト ID。 トレースは有料サービスです。指定されたプロジェクトに、トレースの料金が課金されます。 デフォルトでは、デプロイされた ESPv2 サービスのプロジェクト ID に料金が請求されます。 プロジェクト ID は、起動時に Google Cloud インスタンス メタデータ サーバーを呼び出すことによって決定されます。--non_gcp フラグを使って Google Cloud の外部に ESPv2 をデプロイする場合、このフラグを明示的に設定しなければ、トレースは自動的に無効になります。
--tracing_sample_rate	トレースのサンプリング レートを 0.0 から 1.0 までの値で設定します。この値は、サンプリングされるリクエストの割合を表します。 デフォルト値は 0.001 で、これは 1,000 件中 1 件のリクエストに相当します。
--tracing_incoming_context	このフラグは、トレース コンテキストを確認する HTTP ヘッダーを指定します。フラグの値が複数ある場合は、スペースを入れずにカンマで区切って指定します。 順序は重要です。トレース コンテキストは、一致する最初のヘッダーから派生します。 可能な値は traceparent、x-cloud-trace-context、grpc-trace-bin などです。 省略した場合は、traceparent ヘッダーと x-cloud-trace-context ヘッダーが順番にチェックされます。 詳細については、API のトレースをご覧ください。
--tracing_outgoing_context	バックエンド サービスに送信されたリクエストでトレース コンテキスト ヘッダーを設定します。 このフラグには、設定する HTTP ヘッダーを指定します。フラグの値を指定する際は、スペースを入れずカンマで区切って指定します。 可能な値は traceparent、x-cloud-trace-context、grpc-trace-bin などです。 省略した場合は、traceparent ヘッダーと x-cloud-trace-context ヘッダーが送信されます。 詳細については、API のトレースをご覧ください。

ヘルスチェック

ESPv2 でのヘルスチェックを構成するには、以下のフラグを使用します。最初のフラグを使用して、ヘルスチェックの呼び出しに応答するヘルスハンドラを設定できます。他のフラグを使用して、gRPC バックエンドのヘルスチェックを有効にできます。

/tbody>

フラグ	説明
-z, --healthz	ヘルスチェック エンドポイントを定義します。たとえば、-z healthz を指定すると、ESPv2 はパス /healthz に対してコード 200 を返します。
--health_check_grpc_backend	フラグ --backend で指定されたバックエンドに対して gRPC ヘルスチェック サービスを定期的にチェックするには、ESPv2 を有効にします。 バックエンドでは、gRPC プロトコルを使用し、gRPC ヘルスチェック プロトコルを実装する必要があります。 フラグ --healthz で有効になっているヘルスチェック エンドポイントには、バックエンド ヘルスチェックの結果が反映されます。
--health_check_grpc_backend_service	バックエンド gRPC ヘルスチェック プロトコルを呼び出す際のサービス名を指定します。このフラグの値は、フラグ --health_check_grpc_backend が使用されている場合にのみ適用されます。これは省略可能です。設定しない場合、デフォルトでは空になります。空のサービス名は、gRPC サーバーの全体的なヘルス ステータスをクエリするために使用します。
--health_check_grpc_backend_interval	バックエンド gRPC ヘルスサービスを呼び出す際のチェック間隔とリクエスト タイムアウトを指定します。このフラグの値は、フラグ --health_check_grpc_backend が使用されている場合にのみ適用されます。デフォルトは 1 秒です。使用できる形式は、10 進数のシーケンスで、小数と単位接尾辞がオプションで含まれます（例: 5s、100ms、2m など）。有効な時間単位は、「m」（分）、「s」（秒）、「ms」（ミリ秒）になります。

デバッグ

ESPv2 のデバッグを構成するには、以下のフラグを使用します。以下のフラグを使用して、Envoy 管理ポートを設定して構成と統計情報を取得したり、デバッグモードで Envoy を実行してデバッグレベルの情報をログに書き出したりできます。

フラグ	説明
--status_port、--admin_port	このポートで ESPv2 Envoy 管理者を有効にします。詳細については、Envoy 管理インターフェースのリファレンスをご覧ください。管理ポートはデフォルトで無効になっています。
--enable_debug	デバッグレベルのログを有効にして、デバッグ ヘッダーを追加します。

Google Cloud 以外のデプロイ

ESPv2 が Google Cloud 以外の環境にデプロイされる場合は、次のフラグが必要になることがあります。

フラグ	説明
--service_account_key	Google サービスにアクセスするためのサービス アカウント キーの JSON ファイルを指定します。 オプションを省略すると、プロキシは Google Cloud メタデータ サーバーに接続してアクセス トークンを取得します。
--dns_resolver_addresses	DNS リゾルバのアドレス。各アドレスは IP_ADDR または IP_ADDR:PORT の形式で指定し、セミコロン（;）で区切る必要があります。IP_ADDR には、デフォルトの DNS ポート 52 が使用されます。例: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000）。設定されなかった場合、ESPv2 では /etc/resolv.conf で構成されているデフォルトのリゾルバが使用されます。
--backend_dns_lookup_family	すべてのバックエンドの DNS ルックアップ ファミリーを定義します。オプションは、auto、v4only、v6only、v4preferred、all です。デフォルトは v4preferred です。なお、auto は以前の値です。フラグを auto に設定すると、v6preferred と同等の動作になります。
--non_gcp	デフォルトでは、プロキシが Google Cloud メタデータ サーバーへの接続を試み、最初の複数のリクエストで VM のロケーションを取得します。この手順を省略するには、このフラグを true に設定します。

ローカルテスト

ESPv2 は、テストのためにワークステーションにローカルにデプロイできます。詳細については、ESP をローカルまたは別のプラットフォームで実行するをご覧ください。

これらのフラグと Google Cloud 以外のデプロイのフラグを使用すると、継続的インテグレーションで簡単にローカル デプロイとテストを行うことができます。

フラグ	説明
--service_json_path	ESPv2 がエンドポイント サービス構成ファイルを読み込むパスを指定します。このフラグを指定すると、ESPv2 は「固定」ロールアウト方式を使用し、次のフラグは無視されます。 --service --version --rollout_strategy このフラグにより、ESPv2 は Service Management API の割り当てを使用できなくなります。
--enable_backend_address_override	バックエンド アドレスは、サービス構成の --backend フラグまたは backend.rule.address フィールドを使用して指定できます。OpenAPI ユーザーの場合、backend.rule.address フィールドは x-google-backend 拡張機能の address フィールドによって設定されることに注意してください。 サービス構成のオペレーションごとの backend.rule.address は、通常、サーバーレス ルーティングに対して指定されます。デフォルトでは、backend.rule.address は個々のオペレーションで --backend フラグよりも優先されます。 --backend フラグを優先する場合は代わりに、このフラグを有効にします。これは、ローカル ワークステーションで開発している場合に役立ちます。その場合、同じ本番環境のサービス構成を使用できますが、ローカルテストでは --backend フラグを使用してバックエンド アドレスをオーバーライドします。 注: オーバーライドされるのはアドレスだけです。backend.rule の他のすべてのコンポーネント（期限、バックエンド認証、パス変換など）は引き続き適用されます。

クライアント IP の抽出

これらのフラグを使用して、ESPv2 でのクライアント IP の抽出を構成します。

フラグ	説明
--envoy_use_remote_address	Envoy の HttpConnectionManager の構成について詳しくは、Envoy のリファレンスをご覧ください。デフォルトではオフになっています。
--envoy_xff_num_trusted_hops	Envoy の HttpConnectionManager の構成について詳しくは、Envoy のリファレンスをご覧ください。デフォルト値は 2 です。

CORS サポート

使用可能な CORS サポート オプションの説明については、CORS のサポートをご覧ください。このセクションでは、ESPv2 の起動フラグを使用して CORS をサポートすることについて説明します。

ESPv2 で CORS サポートを有効にするには、--cors_preset オプションを含めて、次のいずれかのフラグを設定します。

• --cors_preset=basic
• --cors_preset=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-Max-Age: 1728000

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$" Cloud Run の gcloud_build_image スクリプトでこのオプションを設定した場合、エスケープ文字とバックスラッシュの使用を避けようとすると、起動時に bash スクリプトからプロキシに正しく渡されない可能性があります。メタシーケンスの代わりに文字クラスを使用します。例: Original: \d Recommended: [0-9]

--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
--cors_max_age	Access-Control-Max-Age を指定した期間に設定します。使用できる形式は、10 進数のシーケンスで、小数と単位接尾辞がオプションで含まれます（例: 300m、1.5h、2h45m など）。有効な時間単位は、「m」（分）、「h」（時間）です。設定しない場合、デフォルト値の「480h」になります。 例: --cors_preset=basic --cors_max_age=24h

TLS サポート

以下のフラグを使用して、TLS 接続を使用するように ESPv2 を構成します。

フラグ	説明
--ssl_server_cert_path	プロキシのサーバー証明書のパス。構成すると、ESPv2 が listener_port で HTTP/1.x と HTTP/2 で保護された接続のみを受け入れます。このパスには、証明書ファイル「server.crt」と鍵ファイル「server.key」が必要です。
--ssl_server_cipher_suites	ダウンストリーム接続に使用する暗号スイート。カンマ区切りのリストとして指定します。暗号スイートの構成をご覧ください。
--ssl_backend_client_cert_path	プロキシのクライアント証明書へのパス。構成した場合、ESPv2 では HTTPS バックエンドの TLS 相互認証が有効になります。このパスには証明書と鍵ファイル「client.crt」と「client.key」が必要です。
--ssl_backend_client_root_certs_file	ESPv2 がバックエンド サーバー証明書の検証に使用するルート証明書へのファイルパス。指定しない場合、ESPv2 はデフォルトで「/etc/ssl/certs/ca-certificates.crt」を使用します。
--ssl_backend_client_cipher_suites	HTTPS バックエンドに使用する暗号スイート。カンマ区切りのリストとして指定します。暗号スイートの構成をご覧ください。
--ssl_minimum_protocol	クライアント側接続での最小 TLS プロトコル バージョン。詳しくはこちらをご覧ください。
--ssl_maximum_protocol	クライアント側接続での最大 TLS プロトコル バージョン。詳しくはこちらをご覧ください。
--enable_strict_transport_security	HSTS（HTTP Strict Transport Security）を有効にします。「Strict-Transport-Security」のレスポンス ヘッダー（値は「max-age=31536000; includeSubdomains」）は、すべてのレスポンスに追加されます。
--generate_self_signed_cert	起動時に自己署名証明書と鍵を生成し、「/tmp/ssl/endpoints/server.crt」と「/tmp/ssl/endpoints/server.key」に保存します。これは、HTTPS リクエストの処理にランダムな自己署名証明書のみが必要な場合に有用です。生成された証明書には共通名「localhost」が割り当てられ、10 年間有効です。

タイムアウトと再試行

以下のフラグを使用して、ESPv2 でのリモート HTTP 呼び出しのタイムアウトと再試行を構成します。

フラグ	説明
--http_request_timeout_s	バックエンドと Google Service Control 以外の外部サービスに対するリクエストの場合は、タイムアウトを秒単位で設定します。 Google ServiceManagement、メタデータ サーバー、Google IAM サーバーが含まれています。 1 以上にする必要があります。設定しない場合、デフォルトは 30 秒です。
--service_control_network_fail_open	Google Service Control への接続時にネットワーク障害が発生した際に、このフラグがオンになっている場合は、リクエストが許可されます。デフォルトはオンです。
--service_control_check_timeout_ms	Service Control Check リクエストのタイムアウトをミリ秒単位で設定します。 1 以上にする必要があります。設定されていない場合、デフォルトは 1000 になります。
--service_control_report_timeout_ms	Service Control Report リクエストのタイムアウトをミリ秒単位で設定します。1 以上にする必要があります。設定されていない場合、デフォルトは 1000 になります。
--service_control_quota_timeout_ms	Service Control Quota リクエストのタイムアウトをミリ秒単位で設定します。 1 以上にする必要があります。設定されていない場合、デフォルトは 1000 になります。
--service_control_check_retries	Service Control Check リクエストの再試行時間を設定します。 0 以上にする必要があります。設定されていない場合、デフォルトは 3 になります。
--service_control_report_retries	Service Control Report リクエストの再試行時間を設定します。 0 以上にする必要があります。設定されていない場合、デフォルトは 5 になります。
--service_control_quota_retries	Service Control Quota リクエストの再試行時間を設定します。 0 以上にする必要があります。設定されていない場合、デフォルトは 1 になります。
--backend_retry_ons	ESPv2 がバックエンドで再試行する場合の条件。1 つ以上の retryOn 条件をカンマ区切りリストを使用して指定できます。デフォルトは reset,connect-failure,refused-stream です。このフラグを空に設定して、再試行を無効にします。 適用される条件については、次のリンクを参照してください。 x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	再試行回数の上限です。0 以上の値を指定する必要があります。デフォルトは 1 です。

gRPC コード変換

これらのフラグを使用して、HTTP / JSON から gRPC へのコード変換に対して ESPv2 を構成します。

フラグ	説明
--transcoding_always_print_primitive_fields	grpc-json コード変換のプリミティブ フィールドを印刷するかどうかを指定します。デフォルトでは、デフォルト値を持つプリミティブ フィールドは JSON 出力で省略されます。たとえば、int32 フィールドが 0 に設定されている場合は無視されます。このフラグを true に設定すると、デフォルトの動作がオーバーライドされ、プリミティブ フィールドの値に関係なくプリミティブ フィールドが印刷されます。デフォルトは false です。
--transcoding_always_print_enums_as_ints	列挙型を grpc-json のコード変換の int として出力するかどうかを指定します。デフォルトでは、文字列としてレンダリングされます。デフォルトは false です。
--transcoding_stream_newline_delimited	true の場合、新しい行区切り文字を使用してレスポンス ストリーミング メッセージを区切ります。false の場合、すべてのレスポンス ストリーミング メッセージは JSON 配列にコード変換されます。
--transcoding_case_insensitive_enum_parsing	通常、JSON で使用する場合、proto 列挙値は大文字にする必要があります。JSON リクエストで大文字以外の列挙値を使用する場合は、このフラグを true に設定します。
--transcoding_preserve_proto_field_names	grpc-json のコード変換の proto フィールド名を保持するかどうかを指定します。デフォルトでは、protobuf は json_name オプションまたはそれより下位のキャメルケースをその順に使用して、JSON フィールド名を生成します。このフラグを設定すると、元のフィールド名が保持されます。デフォルトは false です。
--transcoding_ignore_query_parameters	grpc-json のコード変換で無視されるコード変換メソッド マッピングのカンマ区切りクエリ パラメータのリスト。デフォルトでは、コード変換フィルタでは、クエリ パラメータが不明または無効なリクエストはコード変換されません。
--transcoding_ignore_unknown_query_parameters	grpc-json のコード変換で対応する protobuf フィールドにマッピングできないクエリ パラメータを無視するかどうかを指定します。このオプションは、クエリ パラメータを制御できないが、クエリ パラメータが事前にわからない場合に使用します。それ以外の場合は、--transcoding_ignore_query_parameters を使用します。デフォルトは false です。
--transcoding_query_parameters_disable_unescape_plus	デフォルトでは、クエリ パラメータのプラス記号 "+" は、grpc-json のコード変換でスペース " " にエスケープされません。これは HTML 2.0 をサポートするためです。 これが望ましくない場合は、このフラグを true に設定してこの機能を無効にします。

リクエストとレスポンスの変更

ESPv2 でリクエストとレスポンスを部分的に変更するように構成するには、これらのフラグを使用します。

フラグ	説明
--add_request_header	上流のバックエンドに送信する前に、リクエストに HTTP ヘッダーを追加します。ヘッダーがすでにリクエストに含まれている場合、その値は新しい値に置き換えられます。 Envoy カスタム変数をサポートしています。 この引数は、複数回繰り返して複数のヘッダーを指定できます。次に例を示します。 --add_request_header=key1=value1 --add_request_header=key2=value2
--append_request_header	上流のバックエンドに送信する前に、リクエストに HTTP ヘッダーを追加します。ヘッダーがすでにリクエストに含まれている場合は、新しい値が追加されます。 Envoy カスタム変数をサポートしています。 この引数は、複数回繰り返して複数のヘッダーを指定できます。次に例を示します。 --append_request_header=key1=value1 --append_request_header=key2=value2
--add_response_header	下流のクライアントに送信する前に、レスポンスに HTTP ヘッダーを追加します。ヘッダーがすでにレスポンスに含まれている場合、ヘッダーは新しいヘッダーに置き換えられます。 Envoy カスタム変数をサポートしています。 この引数は、複数回繰り返して複数のヘッダーを指定できます。次に例を示します。 --add_response_header=key1=value1 --add_response_header=key2=value2
--append_response_header	下流のクライアントに送信する前に、レスポンスに HTTP ヘッダーを追加します。ヘッダーがすでにレスポンスに含まれている場合は、新しいヘッダーが追加されます。 Envoy カスタム変数をサポートしています。 この引数は、複数回繰り返して複数のヘッダーを指定できます。次に例を示します。 --append_response_header=key1=value1 --append_response_header=key2=value2

セキュリティ対策

以下のフラグを使用して、ESPv2 が許可するリクエストをさらに絞り込みます。

フラグ	説明
--underscores_in_headers	パススルーするために、ヘッダー名にアンダースコアを含めることを許可します。デフォルトは false です。 RFC-7230 では、ヘッダー名にアンダースコア文字を使用できます。ただし、一部のシステムでは _ と - はどちらを使っても同じものとして扱うため、この動作がセキュリティ対策として実装されます。
--envoy_connection_buffer_limit_bytes	リクエスト / レスポンスの本文ごとにバッファに格納されるデータの最大量をバイト単位で構成します。設定しない場合は、Envoy によってデフォルトが決定されます。Envoy のリスナー構成をご覧ください。
--disable_normalize_path	RFC 3986 に基づく path HTTP ヘッダーの正規化を無効にします。デフォルトでバックエンドによりパスの正規化が実行される場合は、このオプションを有効にしておくことをおすすめします。 次の表に、このフラグの構成に基づいて、バックエンドが ESPv2 から受信するリクエスト path の例を示します。 ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello/../world | Rejected | /world | | /%4A | /%4A | /J | | /%4a | /%4a | /J | ----------------------------------------------------------------- デフォルトでは、ESPv2 はパスを正規化します。この機能は、正規化することによってトラフィックに影響が出る場合にのみ無効にしてください。 注: RFC 3986 に従い、このオプションでは、パーセントでエンコードされたスラッシュ文字のエスケープ解除は行いません。この非準拠の動作を有効にする場合は、フラグ --disallow_escaped_slashes_in_path をご覧ください。 注: RFC 3986 の 大文字小文字の正規化は、このオプションを有効にしている場合でも、サポートされません。 詳細については、パス テンプレートについてをご覧ください。
--disable_merge_slashes_in_path	path HTTP ヘッダーで隣接するスラッシュの結合を無効にします。デフォルトでバックエンドにより結合が行われる場合は、このオプションを有効にしておくことをおすすめします。 次の表に、このフラグの構成に基づいて、バックエンドが ESPv2 から受信するリクエスト path の例を示します。 ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello//world | Rejected | /hello/world | | /hello/// | Rejected | /hello | ----------------------------------------------------------------- デフォルトでは、ESPv2 はスラッシュを結合します。この機能は、正規化することによってトラフィックに影響が出る場合にのみ無効にしてください。 詳細については、パス テンプレートについてをご覧ください。
--disallow_escaped_slashes_in_path	スラッシュがパーセントエンコードでエスケープされたリクエストを禁止します。 %2F や %2f は、/ として処理されます。 %5C や %5c は、\ として処理されます。 有効の場合、この動作は使用するプロトコルによって異なります。 OpenAPI バックエンドでは、パーセントエンコードによりエスケープされたスラッシュを含むリクエストパスは、リダイレクトで自動的にエスケープ解除されます。 gRPC バックエンドの場合、パーセントエンコードによりエスケープされたスラッシュを含むリクエストパスは、拒否されます（gRPC はリダイレクトをサポートしていません）。 このオプションは RFC 3986 に準拠していないため、デフォルトで無効になっています。バックエンドが RFC 3986 に準拠しておらず、スラッシュをエスケープする場合は、ESPv2 でこのオプションを有効にする必要があります。これにより、セキュリティ要件が適用されなくなるパスかく乱攻撃を防ぐことができます。 詳細については、パス テンプレートについてをご覧ください。

JWT 認証

以下のフラグを使用して、再試行によってリモート Jwks を取得するように ESPv2 を構成します。

フラグ	説明
--jwks_fetch_num_retries	リモート JWKS 取得再試行に関するポリシーで再試行回数を指定します。デフォルトは 0 です。再試行しません。
--jwks_fetch_retry_back_off_base_interval_ms	JWKS 取得再試行指数バックオフの基本間隔をミリ秒単位で指定します。設定しない場合、デフォルトは 200 ミリ秒です。
--jwks_fetch_retry_back_off_max_interval_ms	JWKS 取得再試行指数バックオフの最大間隔をミリ秒単位で指定します。設定しない場合、デフォルトは 32 秒です。
--jwks_cache_duration_in_s	JWT 公開鍵キャッシュ期間（秒）を指定します。設定しない場合、デフォルトは 5 分です。
--jwks_async_fetch_fast_listener	--disable_jwks_async_fetch フラグが設定されていない場合にのみ適用されます。このフラグは、ESPv2 が最初の jwks 取得が完了するまで待機してから、リスナーポートをバインドするかどうかを決定します。false の場合、待機します。デフォルト値は False です。
--jwt_cache_size	JWT キャッシュ サイズの上限として、一意の JWT トークンの数を指定します。キャッシュに保存されるのは確認済みのトークンのみです。0 の場合、JWT キャッシュは無効になります。このフラグは、JWT キャッシュのメモリ使用量を制限します。キャッシュで使用されるメモリは、トークンあたり（トークンサイズ + 64 バイト）です。指定しない場合、デフォルトは 100000 です。
--disable_jwt_audience_service_name_check	通常、JWT aud フィールドは、OpenAPI の x-google-audiences フィールドで指定されたオーディエンスと照合されます。このフラグは、x-google-audiences フィールドが指定されていない場合の動作を変更します。 x-google-audiences フィールドが指定されておらず、このフラグが使用されていない場合、サービス名を使用して JWT aud フィールドを確認します。 このフラグを使用すると、JWT aud フィールドは確認されません。

次のステップ

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

• Extensible Service Proxy V2 に移行する
• OpenAPI の拡張