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 以降で使用できます。 |
-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 接続用ポートを設定します。1 |
-P HTTP2_PORT |
--http2_port HTTP2_PORT |
ESP が公開する HTTP/2 接続用ポートを設定します。1 |
-S SSL_PORT |
--ssl_port SSL_PORT |
ESP が公開する HTTPS 接続用ポートを設定します。1 |
-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 |
-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 になります。 |
1 これらのポートは省略可能ですが、指定する場合はそれぞれ異なるポートにする必要があります。ポート オプションを指定しない場合、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_regex |
--cors_preset=cors_with_regex と一緒に使用します。正規表現を使用して Access-Control-Allow-Origin を設定できます。例:
--cors_preset=cors_with_regex
上記の例の正規表現では、 |
--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_headers |
Access-Control-Allow-Headers を指定の HTTP ヘッダーに設定します。対象とする HTTP ヘッダーを、各 HTTP ヘッダーをカンマで区切った文字列として指定します。例:
--cors_preset=basic
|
--cors_allow_credentials |
レスポンスに Access-Control-Allow-Credentials ヘッダーを追加し、値 true を設定します。デフォルトでは、Access-Control-Allow-Credentials ヘッダーはレスポンスに含まれません。例:
--cors_preset=basic
|
--cors_expose_headers |
Access-Control-Expose-Headers を特定のヘッダーに設定します。レスポンスの一部として公開可能なヘッダーを指定します。対象とするヘッダーを、各ヘッダーをカンマで区切った文字列として指定します。例:
--cors_preset=basic
|
ESP CORS 起動オプションがアプリケーションのニーズに合わない場合は、アプリケーションに必要な CORS サポートを含めたカスタム nginx.conf ファイルを作成できます。詳細については、CORS をサポートするカスタム nginx.conf の作成をご覧ください。
次のステップ
以下の内容について学習します。