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 及更高版本。指定 |
-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。 如需了解详情,请参阅为 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 。
|
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 支持选项的说明,请参阅支持 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_regex |
与 --cors_preset=cors_with_regex 配合使用。可让您通过正则表达式来设置 Access-Control-Allow-Origin 。示例:
--cors_preset=cors_with_regex
上述示例中的正则表达式允许带有 |
设置 --cors_preset=basic
或 --cors_preset=cors_with_regex
以启用 CORS 后,您可以通过指定以下一个或多个选项来替换其他响应标头的默认值:
选项 | 说明 |
---|---|
--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
文件。如需了解详情,请参阅创建自定义 nginx.conf
以支持 CORS。
后续步骤
了解:
- 将 ESP 和 API 后端部署到 Google Cloud
- 在本地或其他平台上运行 ESP
- GitHub 上的
start_esp
脚本