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 配置标志可分为以下几类:
非无服务器配置
在非无服务器平台(如 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
|
记录所指定请求标头的值(以英文逗号分隔,不带空格)。例如,将此标志设置为:
如果请求中有“foo”和“bar”标头的值,则 Endpoints 日志包含:
|
--log_response_headers
|
记录所指定响应标头的值(以英文逗号分隔,不带空格)。例如,将此标志设置为:
如果响应中有“baz”和“bing”标头的值,则 Endpoints 日志包含:
|
--log_jwt_payloads
|
记录所指定 JWT 载荷原初字段的值(以英文逗号分隔,不带空格)。例如,将此标志设置为:
如果 JWT 载荷中有这些值,则 Endpoints 日志包含:
JWT 载荷中的值必须是原初字段(字符串、整数)。系统不会记录 JSON 对象和数组。 |
--access_log
|
如果指定,则为访问日志条目将要写入的本地文件的路径。 |
--access_log_format
|
跟踪
使用这些标志配置发送到 Stackdriver 的 ESPv2 跟踪数据。只有在启用跟踪功能后,这些标志才适用。
标志 | 说明 |
---|---|
--disable_tracing
|
停用跟踪功能。默认情况下,系统会启用跟踪功能。 启用后,ESPv2 每秒会对发送至 API 的请求进行少量采样,以获取其发送至 Stackdriver Trace 的跟踪记录。默认情况下,对 1000 个请求中的 1 个进行采样。使用 |
--tracing_project_id
|
Stackdriver 跟踪的 Google 项目 ID。 跟踪是一项付费服务。系统将向所指定的项目收取跟踪费用。 默认情况下,系统会对已部署的 ESPv2 服务的项目 ID 计费。
通过在启动时调用 GCP 实例元数据服务器来确定项目 ID。如果 ESPv2 部署在 GCP 外部(使用 |
--tracing_sample_rate
|
将跟踪记录采样率设置为 0.0 到 1.0 之间的值。此值用于指定所采样请求的比例。 默认值为 0.001,相当于 1000 个请求中的 1 个。 |
--tracing_incoming_context
|
此标志指定要在哪些 HTTP 标头中检查跟踪上下文,标志值以英文逗号分隔,不带空格。 可能的值包括 如果省略,则将检查 如需了解详情,请参阅跟踪 API。 |
--tracing_outgoing_context
|
在发送到后端服务的请求中设置跟踪上下文标头。 此标志指定要设置的 HTTP 标头,标志值由英文逗号分隔,不带空格。 可能的值包括 如果省略,则将发送 如需了解详情,请参阅跟踪 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_regex |
与 --cors_preset=cors_with_regex 配合使用。可让您通过正则表达式来设置 Access-Control-Allow-Origin 。示例:
--cors_preset=cors_with_regex
上述示例中的正则表达式允许 http 或 https 的来源以及 在 Kubernetes 配置文件中设置此选项时,您需要添加额外的反斜杠字符以对字符串中出现的两个 \ 进行转义,例如:
"--cors_preset","cors_with_regex",
在 Cloud Run 的 gcloud_build_image 脚本中设置此选项时,请避免使用转义字符和反斜杠,因为在启动时,它们可能无法从 bash 脚本正确传递到代理。请使用字符类而非元序列。例如:
|
设置 --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
|
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 字段的查询参数。如果您无法控制查询参数,并且事先不知道这些参数,请使用此方法。否则,请使用 |
安全选项
使用这些标志进一步优化 ESPv2 允许的请求。
标志 | 说明 |
---|---|
--underscores_in_headers
|
允许标头名称包含要传递的下划线。默认值为 false。
header-7230 允许在标头名称中使用下划线字符。不过,此行为是作为安全措施实施的,因为某些系统将 |
如需查看 ESPv2 标志的更多一般示例和帮助文本,请访问 GitHub 代码库。
后续步骤
了解: