Extensible Service Proxy 启动选项

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 及更高版本。指定 managedfixed--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
-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。
-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),而不会将请求转发给后端。默认值:不使用。

1 这些端口是可选的,且不可重复。 如果您未指定任何端口选项,则 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(跨源资源共享)是一种标准机制,允许在网页中执行的 XMLHttpRequest (XHR) 调用与来自不同来源的资源进行交互。如果没有 CORS,所有浏览器强制执行的同源政策会阻止跨源请求。如需详细了解 CORS 的背景信息,请参阅 Mozilla 开发者网络 (MDN) Web 文档

如需在 ESP 中启用 CORS 支持,请添加 --cors_preset 选项,并将其设置为 basiccors_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$'

上述示例中的正则表达式允许带有 httphttps 的来源以及 example.com 的任何子网域。

在 Kubernetes 配置文件中设置此选项时,您需要添加一个额外的反斜杠字符以转义字符串中出现的两个 \.,例如:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^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

后续步骤

了解以下内容: