Extensible Service Proxy V2 启动选项

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 配置标志。

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

如需在 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 配置标志可分为以下几类:

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

非无服务器配置

在非无服务器平台(如 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 指定本地后端应用服务器地址。有效协议为 httphttpsgrpcgrpcs(如果包含)。默认协议为 >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 计费。

通过在启动时调用 Google Cloud 实例元数据服务器来确定项目 ID。如果 ESPv2 部署在 Google Cloud 外部(使用 --non_gcp 标志),则除非您明确设置此标志,否则系统会自动停用跟踪记录。

--tracing_sample_rate

将跟踪记录采样率设置为 0.0 到 1.0 之间的值。此值用于指定所采样请求的比例。

默认值为 0.001,相当于 1000 个请求中的 1 个。

--tracing_incoming_context

此标志指定要在哪些 HTTP 标头中检查跟踪上下文,标志值以英文逗号分隔,不带空格。 请注意,顺序很重要:跟踪记录上下文将从匹配的第一个标头派生。

可能的值包括 traceparentx-cloud-trace-contextgrpc-trace-bin

如果省略,则系统会按顺序检查 traceparentx-cloud-trace-context 标头。

如需了解详情,请参阅跟踪 API

--tracing_outgoing_context

在发送到后端服务的请求中设置 trace context 标头。

此标志指定要设置的 HTTP 标头,标志值由英文逗号分隔,不带空格。

可能的值包括 traceparentx-cloud-trace-contextgrpc-trace-bin

如果省略,则系统将发送 traceparentx-cloud-trace-context 标头。

如需了解详情,请参阅跟踪 API

健康检查

使用以下标志为 ESPv2 配置健康检查。第一个标志可用于设置健康处理程序,以响应健康检查调用。其他标志可用于为 gRPC 后端启用健康检查。

/tbody>
标志 说明
-z, --healthz 定义健康检查端点。例如,-z healthz 会使 ESPv2 为路径 /healthz 返回代码 200。
--health_check_grpc_backend 启用 ESPv2 以定期检查由 --backend 标志指定的后端的 gRPC 健康服务。后端必须使用 gRPC 协议并实现 gRPC 健康检查协议。由标志 --healthz 启用的健康检查端点将反映后端健康检查结果。
--health_check_grpc_backend_service 在调用后端 gRPC 健康检查协议时指定服务名称。只有在使用 --health_check_grpc_backend 标志时才会应用此标志的值。此标志是可选标志,如果未设置,则默认值为空。服务名称为空是查询 gRPC 服务器的整体健康状况。
--health_check_grpc_backend_interval 在调用后端 gRPC 健康服务时,指定检查间隔和请求超时。只有在使用 --health_check_grpc_backend 标志时才会应用此标志的值。默认值为 1 秒。接受的格式是一系列十进制数字,每个数字都包含一个可选的小数和单位后缀,例如“5s”、“100ms”或“2m”。有效的时间单位包括“m”(表示分钟)、“s”(表示秒)、“ms”(表示毫秒)。

调试

使用这些标志为 ESPv2 配置调试。这些标志可用于设置 Envoy 管理端口以提取配置和统计信息,或在调试模式下运行 Envoy 以将调试级别信息写入日志。

标志 说明
--status_port--admin_port 在此端口上启用 ESPv2 Envoy 管理。如需了解详情,请参阅 Envoy 管理接口参考。管理端口默认处于停用状态。
--enable_debug 启用调试级别日志并添加调试标头。

非 Google Cloud 部署

如果 ESPv2 部署在非 Google Cloud 环境中,则可能需要使用以下标志。

标志 说明
--service_account_key

指定用于访问 Google 服务的服务账号密钥 JSON 文件。如果省略此选项,代理会与 Google Cloud 元数据服务器联系, 获取访问令牌。

--dns_resolver_addresses DNS 解析器的地址。每个地址应采用 IP_ADDRIP_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 定义所有后端的 DNS 查找系列。选项包括 autov4onlyv6onlyv4preferredall。默认值为 v4preferred。请注意,auto 是旧版值。将该标志设置为 auto 会导致行为与 v6preferred 等效。
--non_gcp 默认情况下,代理会尝试连接到 Google Cloud 元数据服务器,以在前几个请求中获取虚拟机位置。如需跳过此步骤,请将此标志设置为 true

本地测试

可以在工作站上本地部署 ESPv2 以进行测试。如需了解详情,请参阅在本地或其他平台上运行 ESP

将这些标志与非 Google Cloud 部署标志搭配使用,以便在持续集成中更轻松地进行本地部署和测试。

标志 说明
--service_json_path

指定 ESPv2 的路径以加载端点服务配置。借助此标志,ESPv2 将使用“固定”发布策略,并且以下标志将被忽略:

  • --service
  • --version
  • --rollout_strategy

此标志会阻止 ESPv2 使用 Service Management API 配额

--enable_backend_address_override

可以使用 --backend 标志或服务配置中的 backend.rule.address 字段指定后端地址。对于 OpenAPI 用户,请注意 backend.rule.address 字段通过 x-google-backend 扩展中的 address 字段设置。

您通常会为无服务器路由指定服务配置每项操作 backend.rule.address。默认情况下,backend.rule.address 优先于每项操作的 --backend 标记。

如果您希望改为 --backend 标志优先,请启用此标志。如果您在本地工作站上进行开发,这会非常有用。然后,您可以使用同一生产服务配置,但通过 --backend 标志替换后端地址以用于本地测试。

注意:只有地址会被覆盖。backend.rule 的所有其他组成部分仍将适用(截止时间、后端身份验证、路径转换等)。

客户端 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-Max-Age: 1728000

如需替换 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$"

在 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
--cors_max_age Access-Control-Max-Age 设置为指定的时长。可接受的格式是一系列十进制数字,每个数字都有一个可选的小数值和单位后缀,例如“300m”、“1.5h”或“2h45m”。有效时间单位为“m”(分钟)、“h”(小时)。如果未设置,则默认值为“480h”。
示例
--cors_preset=basic
--cors_max_age=24h

TLS 支持

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

标志 说明
--ssl_server_cert_path 代理的服务器证书路径。配置后,ESPv2 仅接受 listener_port 上的 HTTP/1.x 和 HTTP/2 安全连接。此路径中需要证书和密钥文件“server.crt”和“server.key”。
--ssl_server_cipher_suites 要用于下游连接的加密套件,以用英文逗号分隔的列表的形式指定。请参阅加密套件配置
--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_backend_client_cipher_suites 要用于 HTTPS 后端的加密套件,以用逗号分隔的列表的形式指定。请参阅加密套件配置
--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
--backend_retry_ons

ESPv2 在后端重试的条件。可采用以英文逗号分隔的列表指定一个或多个 retryOn 条件。默认值为 reset,connect-failure,refused-stream。 将此标志留空,以停用重试功能。

有关接受的条件,请参阅以下链接:

--backend_retry_num 允许的重试次数。必须大于等于 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_stream_newline_delimited

如果为 true,则使用换行分隔符来分隔响应流式传输消息。如果为 false,所有响应流式传输消息都会转码为 JSON 数组。

--transcoding_case_insensitive_enum_parsing

通常,在 JSON 中使用原生枚举值时,应使用大写形式。 如果您的 JSON 请求使用非大写枚举值,请将此标志设置为 true。

--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

--transcoding_query_parameters_disable_unescape_plus

默认情况下,在 grpc-json 转码中,查询参数中的加号 "+" 不会转义为空格 " "。这是为了支持 HTML 2.0。如果不需要,请将此标志设置为 true 以停用此功能。

请求和响应修改

使用这些标志将 ESPv2 配置为部分修改请求和响应。

标志 说明
--add_request_header

在将请求发送到上游后端之前,为该请求添加 HTTP 标头。如果标头已在请求中,系统会将它的值替换为新的标头。

它支持 Envoy 自定义变量

此参数可以重复多次以指定多个标头。例如:
--add_request_header=key1=value1
--add_request_header=key2=value2

--append_request_header

在将请求发送到上游后端之前,为该请求附加 HTTP 标头。如果请求中已经包含标头,将附加新值。

它支持 Envoy 自定义变量

此参数可以重复多次以指定多个标头。例如:
--append_request_header=key1=value1
--append_request_header=key2=value2

--add_response_header

在将响应发送到下游客户端之前,为响应添加 HTTP 标头。如果标头已存在于响应中,系统会将它替换为新的标头。

它支持 Envoy 自定义变量

此参数可以重复多次以指定多个标头。例如:
--add_response_header=key1=value1
--add_response_header=key2=value2

--append_response_header

在将响应发送到下游客户端之前,为响应附加 HTTP 标头。如果标头已存在于响应中,系统将附加新的标头。

它支持 Envoy 自定义变量

此参数可以重复多次以指定多个标头。例如:
--append_response_header=key1=value1
--append_response_header=key2=value2

安全选项

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

标志 说明
--underscores_in_headers

允许标头名称包含要传递的下划线。默认值为 false

header-7230 允许在标头名称中使用下划线字符。不过,此行为是作为安全措施实施的,因为某些系统将 _- 视为可互换。

--envoy_connection_buffer_limit_bytes

配置为每个客户端缓冲的最大数据量 请求/响应正文,以字节为单位。如果未设置,则由 Envoy 确定默认值。请参阅 Envoy 的监听器配置

--disable_normalize_path

根据 RFC 3986 停用 path HTTP 标头的标准化。如果您的后端默认执行路径规范化,我们建议保留此选项。

下表提供了基于此标志的配置,后端将从 ESPv2 接收的请求 path 的示例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------
     

默认情况下,ESPv2 将对路径进行规范化。仅当您的流量受该行为影响时,您才能停用此功能。

注意:遵循 RFC 3986,此选项不会取消百分号编码的斜杠字符转义。如需启用此不合规行为,请参阅 --disallow_escaped_slashes_in_path 标志。

注意:即使启用了此选项,也不支持 RFC 3986 标准中的案例规范化

如需了解详情,请参阅了解路径模板化

--disable_merge_slashes_in_path

禁止在 path HTTP 标头中合并相邻的斜杠。如果您的后端默认执行合并,我们建议您启用此选项。

下表提供了基于此标志的配置,后端将从 ESPv2 接收的请求 path 的示例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------
     

默认情况下,ESPv2 将会合并斜杠。仅当您的流量受该行为影响时,您才能停用此功能。

如需了解详情,请参阅了解路径模板化

--disallow_escaped_slashes_in_path

不允许含有百分号编码的转义斜杠字符的请求:

  • %2F%2f 会被视为 /
  • %5C%5c 会被视为 \

启用后,行为取决于所使用的协议:

  • 对于 OpenAPI 后端,含有百分号编码的转义斜杠的请求路径将通过重定向自动取消转义。
  • 对于 gRPC 后端,系统会拒绝含有百分号编码的转义斜杠的请求路径(gRPC 不支持重定向)。

此选项不符合 RFC 3986 标准,因此默认情况下处于关闭状态。如果您的后端不符合 RFC 3986 标准并且对斜杠进行了转义,则必须在 ESPv2 中启用此选项。这样可以防止因强制实施安全要求而导致的路径混乱攻击。

如需了解详情,请参阅了解路径模板化

JWT 身份验证

使用以下标志将 ESPv2 配置为通过重试提取远程 Jwks。

标志 说明
--jwks_fetch_num_retries

在远程 JWKS 提取重试政策中指定重试次数。默认值为 0,不重试。

--jwks_fetch_retry_back_off_base_interval_ms

指定 JWKS 提取重试指数退避算法的基准间隔(以毫秒为单位)。如未设置,默认值为 200 毫秒。

--jwks_fetch_retry_back_off_max_interval_ms

指定 JWKS 提取重试指数退避算法的最长间隔(以毫秒为单位)。如未设置,则默认值为 32 秒。

--jwks_cache_duration_in_s

指定 JWT 公钥缓存时长(以秒为单位)。如果未设置,则默认值为 5 分钟。

--jwks_async_fetch_fast_listener

仅在未设置 --disable_jwks_async_fetch 标志时适用。 此标志用于确定 ESPv2 是否等待初始 jwks 提取 完成后才能绑定监听器端口。如果为 false,则会等待。 默认值为 false。

--jwt_cache_size

将唯一 JWT 令牌的数量指定为 JWT 缓存大小上限。 缓存仅存储经过验证的令牌。如果为 0,则停用 JWT 缓存。 此标志会限制 JWT 缓存的内存用量。缓存使用的内存大致为每个令牌的(令牌大小 + 64 字节)。 如果未指定,则默认值为 100000。

--disable_jwt_audience_service_name_check

通常,系统会针对 OpenAPI x-google-audiences 字段中指定的目标对象检查 JWT aud 字段。此标志会更改未指定 x-google-audiences 字段时的行为。 如果未指定 x-google-audiences 字段,也未使用此标志,系统会使用服务名称检查 JWT aud 字段。 如果使用此标志,系统将不会检查 JWT aud 字段。

后续步骤

了解: