Extensible Service Proxy の起動オプション

OpenAPI | gRPC

Extensible Service Proxy（ESP）は、Cloud Endpoints で API 管理機能を提供できるようにする NGINX ベースのプロキシです。ESP を構成するには、ESP Docker コンテナを起動するときにオプションを指定します。ESP コンテナは起動時に start_esp という名前のスクリプトを実行します。このスクリプトは指定されたオプションを使用して NGINX 構成ファイルを作成し、ESP を起動します。

docker run コマンドで ESP 起動オプションを指定します。次に例を示します。

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

ESP を Kubernetes にデプロイする場合は、デプロイメンﾄマニフェストファイル内の args フィールドで起動オプションを指定します。次に例を示します。

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

次の表に、ESP の起動オプションを記載します。

短縮オプション	詳細オプション	説明
`-s SERVICE_NAME`	`--service SERVICE_NAME`	Endpoints サービスの名前を設定します。
`-R ROLLOUT_STRATEGY`	`--rollout_strategy ROLLOUT_STRATEGY`	ESP バージョン 1.7.0 以降で使用できます。`managed` または `fixed` を指定します。`--rollout_strategy=managed` オプションを指定すると、デプロイ済みの最新のサービス構成を使用するように ESP が構成されます。このオプションを指定すると、新しいサービス構成をデプロイしてから 5 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。`--rollout_strategy` を `managed` に設定した場合、`--version` オプションを指定する必要はありません。
`-v CONFIG_ID`	`--version CONFIG_ID`	ESP がサービス構成 ID を使用するように設定します。このオプションの設定に必要な情報については、サービス名と構成 ID を取得するをご覧ください。`--rollout_strategy=fixed` を指定する場合、または `--rollout_strategy` オプションを含めない場合は、`--version` オプションを含めて構成 ID を指定する必要があります。この場合、新しい Endpoints 構成をデプロイするたびに、新しい構成 ID を使用して ESP を再起動する必要があります。
`-p HTTP1_PORT`	`--http_port HTTP1_PORT`	ESP が公開する HTTP/1.x 接続用ポートを設定します。¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	ESP が公開する HTTP/2 接続用ポートを設定します。¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	ESP が公開する HTTPS 接続用ポートを設定します。¹
`-a BACKEND`	`--backend BACKEND`	HTTP/1.x アプリケーションバックエンドサーバーのアドレスを設定します。バックエンドアドレスのデフォルト値は `http://127.0.0.1:8081` です。プロトコルプレフィックスを指定できます。たとえば、次のようになります。 `--backend=https://127.0.0.1:8000` プロトコルプレフィックスを指定しない場合、デフォルトの `http` が使用されます。バックエンドサーバーがコンテナ内の Compute Engine で実行されている場合は、コンテナ名とポートを指定できます。次に例を示します。 `--backend=my-api-container:8000` バックエンドで gRPC トラフィックを受け入れるように指定するには、接頭辞 `grpc://` を追加します。次に例を示します。 `--backend=grpc://127.0.0.1:8000` バックエンドサーバーがコンテナ内の Compute Engine で実行され、gRPC トラフィックを受け入れる場合は、コンテナ名とポートを指定できます。次に例を示します。 `--backend=grpc://my-api-container:8000`
`-N STATUS_PORT`	`--status_port STATUS_PORT`	ステータスポートを設定します（デフォルト: `8090`）。
なし	`--disable_cloud_trace_auto_sampling`	デフォルトでは、ESP は 1,000 個あたり 1 個のリクエストをサンプリングします。あるいは、10 秒ごとに 1 個のリクエストが Cloud Trace で有効になります。こうした自動サンプリングを無効にするには、このフラグを設定します。このフラグ値に関係なく、Cloud Trace は、トレースコンテキストを含むリクエストの HTTP ヘッダーで有効にできます。詳細については、API のトレースをご覧ください。
`-n NGINX_CONFIG`	`--nginx_config NGINX_CONFIG`	カスタム NGINX 構成ファイルの場所を設定します。このオプションを指定すると、ESP は指定された構成ファイルを取得してからすぐに、指定されたカスタム構成ファイルで NGINX を起動します。詳細については、GKE のカスタム nginx 構成の使用をご覧ください。
`-k SERVICE_ACCOUNT_KEY`	`--service_account_key SERVICE_ACCOUNT_KEY`	サービスアカウント認証情報の JSON ファイルを設定します。指定されている場合、ESP はサービスアカウントを使用して、Service Infrastructure API を呼び出すためのアクセストークンを生成します。このオプションを指定する必要があるのは、ローカルデスクトップ、Kubernetes、あるいは別のクラウドプロバイダなど、Google Cloud 以外のプラットフォームで ESP を実行しているときだけです。詳細については、サービスアカウントの作成をご覧ください。
`-z HEALTHZ_PATH`	`--healthz HEALTHZ_PATH`	アプリケーションバックエンドと同じポートにヘルスチェックのエンドポイントを定義します。たとえば、`-z healthz` は、リクエストをバックエンドに転送する代わりに、ロケーション `/healthz` に対する ESP 戻りコードを `200` にします。デフォルト: 使用されません。
なし	`--dns DNS_RESOLVER`	DNS リゾルバを指定します。たとえば、`--dns 169.254.169.254` は GCP メタデータサーバーを DNS リゾルバとして使用します。指定しない場合、デフォルトは `8.8.8.8` になります。

¹ これらのポートは省略可能ですが、指定する場合はそれぞれ異なるポートにする必要があります。ポートオプションを指定しない場合、ESP は HTTP/1.x 接続をポート 8080 で受け入れます。HTTPS 接続では、ESP は TLS シークレットが /etc/nginx/ssl/nginx.crt と /etc/nginx/ssl/nginx.key にあるものと想定します。

コマンドラインの呼び出し例

以下の例に、いくつかのコマンドライン引数を使用する方法を示します。

ESP を起動して、受信リクエストを HTTP/1.x ポート 80 と HTTPS ポート 443 で処理し、それらのリクエストを 127.0.0.1:8000 にある API バックエンドに送信する場合:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1
     --service=echo-api.endpoints.example-project-12345.cloud.goog \
        --rollout_strategy=managed \
        --http_port=80 \
        --ssl_port=443 \
        --backend=127.0.0.1:8000

ESP をカスタム NGINX 構成で起動し、サービスアカウント認証情報ファイルを使用してサービス構成を取得してサービスコントロールに接続する場合:

sudo docker run \
    --detach \
    --volume=$HOME/Downloads:/esp \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=echo-api.endpoints.example-project-12345.cloud.goog \
    --rollout_strategy=managed \
    --service_account_key=/esp/serviceaccount.json \
    --nginx_config=/esp/nginx.conf

Docker フラグ --volume または --mount を使用して、ESP の Docker コンテナ内のボリュームとして、サービスアカウントの秘密鍵とカスタム NGINX 構成ファイルを含む JSON ファイルをマウントする必要があります。上記の例では、ローカル PC の $HOME/Downloads ディレクトリをコンテナ内の esp ディレクトリにマッピングしています。サービスアカウントの秘密鍵ファイルを保存すると、通常は Downloads ディレクトリにダウンロードされます。必要に応じて、秘密鍵ファイルを別のディレクトリにコピーできます。詳細については、Docker のデータの管理をご覧ください。

ESP に CORS サポートを追加する

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

ESP で CORS サポートを有効にするには、--cors_preset オプションを追加してその値を basic または cors_with_regex のいずれかに設定します。--cors_preset=basic または --cors_preset=cors_with_regex を設定すると、ESP は次のように動作します。

すべての場所のパスで同じ 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` のすべてのサブドメインが許可されます。

--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`

ESP CORS 起動オプションがアプリケーションのニーズに合わない場合は、アプリケーションに必要な CORS サポートを含めたカスタム nginx.conf ファイルを作成できます。詳細については、CORS をサポートするカスタム nginx.conf の作成をご覧ください。

次のステップ

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