Extensible Service Proxy 启动选项

OpenAPI   |  gRPC

Extensible Service Proxy (ESP) 是一种基于 NGINX 的代理，可让 Cloud Endpoints 提供 API 管理功能。您可以通过在启动 ESP Docker 容器时指定相应选项来配置 ESP。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 配置为使用最新部署的服务配置。指定此选项后，在部署新的服务配置后，ESP 最多会在 5 分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项，而不是指定特定配置 ID 供 ESP 使用。将 --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 连接的端口。^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 如需指定后端接受 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	默认情况下，通过 Cloud Trace 启用 ESP，每 10 秒中每 1000 个或 1 个请求中的 1 个请求。设置此标志可停用此类自动采样。无论此标记值如何，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 的访问令牌。 仅当 ESP 在 Google Cloud 以外的平台（例如本地桌面设备、Kubernetes 或其他云服务商平台）上运行时，您才需要指定此选项。如需了解详情，请参阅创建服务账号。
-z HEALTHZ_PATH	--healthz HEALTHZ_PATH	定义应用后端所在端口上的健康检查端点。例如，若设为 -z healthz，ESP 会返回代码 200（表示位置 /healthz），而不会将请求转发给后端。默认值：不使用。
无	--dns DNS_RESOLVER	指定 DNS 解析器。例如，--dns 169.254.169.254 使用 GCP 元数据服务器作为 DNS 解析器。如果未指定，则默认值为 8.8.8.8。

¹ 这些端口是可选的，且不可重复。如果您未指定任何端口选项，则 ESP 将接受使用端口 8080 进行的 HTTP/1.x 连接。对于 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

要使用服务账号凭据文件来获取服务配置并连接到 Service Control，从而通过自定义 NGINX 配置启动 ESP，请运行以下命令：

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 将包含服务账号私钥的 JSON 文件和自定义 NGINX 配置文件作为卷装载到 ESP 的 Docker 容器内部。上述示例将本地计算机上的 $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 天（1728000 秒）。

• 将响应标头设置为以下值：

  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 后，您可以通过指定以下一个或多个选项来替换其他响应标头的默认值：

选项	说明
--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 文件。如需了解详情，请参阅创建自定义 nginx.conf 以支持 CORS。

后续步骤

了解：

• 将 ESP 和 API 后端部署到 Google Cloud
• 在本地或其他平台上运行 ESP
• GitHub 上的 start_esp 脚本