Extensible Service Proxy V2 启动选项

OpenAPI   |  gRPC

Extensible Service Proxy V2 (ESPv2) 是一个基于 Envoy 的代理，通过该代理，Cloud Endpoints 可以提供 API 管理功能。如需配置 ESPv2，您可以在部署 ESPv2 服务时指定配置标志。

设置配置标志

设置 ESPv2 配置标志的方法因部署平台而异，如以下部分所述。

Compute Engine 虚拟机

Compute Engine 的 ESPv2 配置标志在 docker run 命令中指定。例如：

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

在此示例中，--service、--rollout_strategy 和 --backend 是 ESPv2 配置标志。

GKE 和 Kubernetes

您可以在部署清单文件的 args 字段中为 GKE 和 Kubernetes 指定配置标志。例如：

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

在此示例中，--listener_port、--backend、--service 和 --rollout_strategy 是 ESPv2 配置标志。

适用于无服务器平台的 Cloud Run

要为适用于无服务器平台的 Cloud Run 指定启动选项，请使用 ESPv2_ARGS 环境变量。可以在 gcloud run deploy 命令中使用 --set-env-vars 选项设置此变量。

例如：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

在此示例中，--enable_debug 是 ESPv2 配置标志。

如需详细了解 gcloud run deploy 命令，请参阅适用于 OpenAPI 的 Cloud Functions、适用于 OpenAPI 的 Cloud Run 或适用于 gRPC 的 Cloud Run。

如需在 ESPv2_ARGS 环境变量中设置多个参数，请指定自定义分隔符，并使用该分隔符分隔多个参数。请勿使用英文逗号作为分隔符。将自定义分隔符放置在 ESPv2_ARGS 环境变量的开头，并使用插入符号括起来。

以下示例使用 ++ 作为分隔符：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

如果要设置的标记包含英文逗号，您必须在 gcloud_build_image 脚本中设置 ESPv2_ARGS 环境变量。

例如，如需添加 --cors_allow_methods=PUT,POST,GET 标志，请执行以下操作：

• 下载 gcloud_build_image 脚本。
• 修改 gcloud_build_image，如下所示：

  cat <<EOF > Dockerfile
    FROM BASE_IMAGE
  
    ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
    COPY service.json \ENDPOINTS_SERVICE_PATH
  
    ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
  
    ENTRYPOINT ["/env_start_proxy.py"]
    EOF

  注意：自定义分隔符用于分隔多个参数。
• 运行 gcloud_build_image 脚本以构建映像。

ESPv2 配置标志

ESPv2 配置标志可分为以下几类：

• 非无服务器配置
• Logging
• 跟踪
• 调试
• 非 GCP 配置
• 客户端 IP 提取
• CORS 支持
• TLS 支持
• 超时和重试
• gRPC 转码
• 安全选项

非无服务器配置

在非无服务器平台（如 GKE、Compute Engine 和 Kubernetes）中运行 ESPv2 时需要使用这些标志。当针对无服务器平台部署到 Cloud Run 中时，您无法设置这些标志。

标志	说明
--service	设置 Endpoints 服务的名称。
--version	设置 Endpoints 服务的服务配置 ID。
--rollout_strategy	指定服务配置部署策略，[fixed|managed]。默认为 fixed。
--listener_port	标识接受下游连接的端口。它支持 HTTP/1.x、HTTP/2 和 gRPC 连接。默认为 8080。
--backend	指定本地后端应用服务器地址。有效协议为 http、https、grpc 和 grpcs（如果包含）。默认协议为 >http。

日志记录

使用这些标志配置 ESPv2 以将其他信息写入 Stackdriver 日志。

标志	说明
--log_request_headers	记录所指定请求标头的值（以英文逗号分隔，不带空格）。例如，将此标志设置为： --log_request_headers=foo,bar 如果请求中有“foo”和“bar”标头的值，则 Endpoints 日志包含： request_headers: foo=foo_value;bar=bar_value
--log_response_headers	记录所指定响应标头的值（以英文逗号分隔，不带空格）。例如，将此标志设置为： --log_response_headers=baz,bing 如果响应中有“baz”和“bing”标头的值，则 Endpoints 日志包含： response_headers: baz=baz_value;bing=bing_value
--log_jwt_payloads	记录所指定 JWT 载荷原初字段的值（以英文逗号分隔，不带空格）。例如，将此标志设置为： --log_jwt_payload=sub,project_id,foo.foo_name 如果 JWT 载荷中有这些值，则 Endpoints 日志包含： jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value JWT 载荷中的值必须是原初字段（字符串、整数）。系统不会记录 JSON 对象和数组。
--access_log	如果指定，则为访问日志条目将要写入的本地文件的路径。
--access_log_format	用于指定访问日志格式的字符串格式。如果未设置，则会使用 >默认格式字符串。如需详细了解格式语法，请参阅格式字符串参考。

跟踪

使用这些标志配置发送到 Stackdriver 的 ESPv2 跟踪数据。只有在启用跟踪功能后，这些标志才适用。

标志	说明
--disable_tracing	停用跟踪功能。默认情况下，系统会启用跟踪功能。 启用后，ESPv2 每秒会对发送至 API 的请求进行少量采样，以获取其发送至 Stackdriver Trace 的跟踪记录。默认情况下，对 1000 个请求中的 1 个进行采样。使用 --tracing_sample_rate 标志更改采样率。
--tracing_project_id	Stackdriver 跟踪的 Google 项目 ID。 跟踪是一项付费服务。系统将向所指定的项目收取跟踪费用。 默认情况下，系统会对已部署的 ESPv2 服务的项目 ID 计费。 通过在启动时调用 GCP 实例元数据服务器来确定项目 ID。如果 ESPv2 部署在 GCP 外部（使用 --non_gcp 标志），则除非您明确设置此标志，否则系统会自动停用跟踪记录。
--tracing_sample_rate	将跟踪记录采样率设置为 0.0 到 1.0 之间的值。此值用于指定所采样请求的比例。 默认值为 0.001，相当于 1000 个请求中的 1 个。
--tracing_incoming_context	此标志指定要在哪些 HTTP 标头中检查跟踪上下文，标志值以英文逗号分隔，不带空格。 可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。 如果省略，则将检查 traceparent 标头。 如需了解详情，请参阅跟踪 API。
--tracing_outgoing_context	在发送到后端服务的请求中设置跟踪上下文标头。 此标志指定要设置的 HTTP 标头，标志值由英文逗号分隔，不带空格。 可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。 如果省略，则将发送 traceparent 标头。 如需了解详情，请参阅跟踪 API。

调试

使用这些标志为 ESPv2 配置运行状况检查和调试。这些标志可用于设置响应运行状况检查调用的运行状况处理程序和提取配置和统计信息的 Envoy 管理端口，或者用于在调试模式下运行 Envoy 以将调试级别信息写入日志。

标志	说明
-z, --healthz	定义运行状况检查端点。例如，-z healthz 会使 ESPv2 为路径 /healthz 返回代码 200。
--status_port、--admin_port	在此端口上启用 ESPv2 Envoy 管理。如需了解详情，请参阅 Envoy 管理接口参考。管理端口默认处于停用状态。
--enable_debug	启用调试级别日志并添加调试标头。

非 GCP Platform 部署

如果在非 Google Cloud Platform (GCP) 环境中部署 ESPv2，则可能需要以下标志。

标志	说明
--service_account_key	指定用于访问 Google 服务的服务帐号密钥 JSON 文件。如果省略此选项，代理会与 GCP 元数据服务器联系以获取访问令牌。
--dns_resolver_addresses	DNS 解析器的地址。每个地址应采用 IP_ADDR 或 IP_ADDR:PORT 格式，并使用英文分号 (;) 分隔。IP_ADDR 将使用默认 DNS 端口 52。例如：--dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000)。如果未设置，ESPv2 将使用 /etc/resolv.conf 中配置的默认解析器
--backend_dns_lookup_family	定义所有后端的 DSN 查找系列。选项包括 auto、v4only 和 v6only。默认为 autocode>。
--non_gcp	默认情况下，代理会尝试连接到 GCP 元数据服务器，以在前几个请求中获取虚拟机位置。如需跳过此步骤，请将此标志设置为 true。

客户端 IP 提取

使用这些标志为 ESPv2 配置客户端 IP 提取。

标志	说明
--envoy_use_remote_address	Envoy HttpConnectionManager 配置，请参阅 Envoy 参考了解详情。默认为 off。
--envoy_xff_num_trusted_hops	Envoy HttpConnectionManager 配置，请参阅 Envoy 参考了解详情。默认值为 2。

CORS 支持

如需了解可用的 CORS 支持选项的说明，请参阅支持 CORS。本部分介绍如何使用 ESPv2 启动标志来支持 CORS。

如需在 ESPv2 中启用 CORS 支持，请添加 --cors_preset 选项，并设置以下标志之一：

• >--cors_preset=basic
• >--cors_preset=cors_with_regex

如果您添加 --cors_preset=basic 或 --cors_preset=cors_with_regex，ESPv2 将：

• 假定所有位置路径都具有相同的 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 的任何子网域。 在 Kubernetes 配置文件中设置此选项时，您需要添加额外的反斜杠字符以对字符串中出现的两个 \ 进行转义，例如： "--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$" 在 Cloud Run 的 gcloud_build_image 脚本中设置此选项时，请避免使用转义字符和反斜杠，因为在启动时，它们可能无法从 bash 脚本正确传递到代理。请使用字符类而非元序列。例如： Original: \d Recommended: [0-9]

设置 --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"

TLS 支持

使用这些标志配置 ESPv2 以使用 TLS 连接。

标志	说明
--ssl_server_cert_path	代理的服务器证书路径。配置后，ESPv2 仅接受 listener_port 上的 HTTP/1.x 和 HTTP/2 安全连接。此路径中需要证书和密钥文件“server.crt”和“server.key”。
--ssl_backend_client_cert_path	代理的客户端证书路径。配置后，ESPv2 会为 HTTPS 后端启用 TLS 双向身份验证。此路径中需要证书和密钥文件“client.crt”和“client.key”。
--ssl_backend_client_root_certs_file	ESPv2 用来验证后端服务器证书的根证书的文件路径。如果未指定，ESPv2 默认使用“/etc/ssl/certs/ca-certificates.crt”。
--ssl_minimum_protocol	客户端连接的最低 TLS 协议版本。请参阅此处
--ssl_maximum_protocol	客户端连接的最高 TLS 协议版本。请参阅此处
--enable_strict_transport_security	启用 HSTS（HTTP 严格传输安全协议）。来自本地后端的所有响应都会添加值为“max-age=31536000; includeSubdomains;”的“Strict-Transport-Security”响应标头。不适用于远程后端。
--generate_self_signed_cert	在启动时生成自签名证书和密钥，然后将其存储在“/tmp/ssl/endpoints/server.crt”和“/tmp/ssl/endpoints/server.key”中。如果只需要一个随机的自签名证书来处理 HTTPS 请求，这将非常有用。生成的证书的通用名称为“localhost”，有效期为 10 年。

超时和重试

使用这些标志为 ESPv2 配置远程 HTTP 调用超时和重试。

标志	说明
--http_request_timeout_s	设置向外部服务（后端和 Google Service Control 除外）发出的请求的超时，以秒为单位。它包括 Google ServiceManagement、元数据服务器和 Google IAM 服务器。必须大于 0，如果未设置，则默认为 30 秒。
--service_control_network_fail_open	在连接 Google Service Control 时发生网络故障的情况下，如果此标志处于启用状态，则允许请求。默认为 on。
--service_control_check_timeout_ms	设置 Service Control Check 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_report_timeout_ms	设置 Service Control Report 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_quota_timeout_ms	设置 Service Control Quota 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_check_retries	设置 Service Control Check 请求的重试次数。必须大于等于 0，如果未设置，则默认为 3。
--service_control_report_retries	设置 Service Control Report 请求的重试次数。必须大于等于 0，如果未设置，则默认为 5。
--service_control_quota_retries	设置 Service Control Quota 请求的重试次数。必须大于等于 0，如果未设置，则默认为 1。

gRPC 转码

使用这些标志配置 ESPv2，以将 HTTP/JSON 转码为 gRPC。

标志	说明
--transcoding_always_print_primitive_fields	指定是否输出 grpc-json 转码的原初字段。默认情况下，JSON 输出中将省略具有默认值的原初字段。例如，设置为 0 的 int32 字段将被省略。如果将此标志设置为 true，系统将覆盖默认行为并输出原初字段（无论其值为何）。默认值为 false。
--transcoding_always_print_enums_as_ints	指定是否将 grpc-json 转码的枚举输出为整数。默认情况下，它们呈现为字符串。默认值为 false。
--transcoding_preserve_proto_field_names	指定是否保留 grpc-json 转码的原型字段名称。默认情况下，protobuf 将按顺序使用 json_name 选项或小驼峰式命名法生成 JSON 字段名称。设置此标志将保留原始字段名称。默认值为 false。
--transcoding_ignore_query_parameters	grpc-json 转码中转码方法映射要忽略的查询参数列表（以英文逗号分隔）。默认情况下，转码器过滤器不会对具有未知/无效查询参数的请求进行转码。
--transcoding_ignore_unknown_query_parameters	指定是否忽略在 grpc-json 转码中无法映射到相应 protobuf 字段的查询参数。如果您无法控制查询参数，并且事先不知道这些参数，请使用此方法。否则，请使用 --transcoding_ignore_query_parameters。默认值为 false。

安全选项

使用这些标志进一步优化 ESPv2 允许的请求。

标志	说明
--underscores_in_headers	允许标头名称包含要传递的下划线。默认值为 false。 header-7230 允许在标头名称中使用下划线字符。不过，此行为是作为安全措施实施的，因为某些系统将 _ 和 - 视为可互换。

如需查看 ESPv2 标志的更多一般示例和帮助文本，请访问 GitHub 代码库。

后续步骤

了解：

• 迁移到 Extensible Service Proxy V2
• OpenAPI 扩展程序