宣传信息概览

借助 Service Extensions，您可以从网络代理发出宣传信息。 大多数 应用负载平衡器都支持宣传信息扩展程序。 Secure Web Proxy （预览版）也支持宣传信息扩展程序。

宣传信息数据传输

网络代理使用以下 Envoy gRPC 协议之一与宣传信息进行通信：

  • 外部处理或 ext_proc 协议。

    此协议支持路由、流量和授权扩展程序，并且默认使用。

    借助 ext_proc 协议，扩展程序服务可以通过检查和修改请求的标头或正文来响应 HTTP 请求生命周期中的事件。

  • 外部授权或 ext_authz 协议。

    此协议仅支持 授权扩展程序。

    借助 ext_authz 协议，您可以将传入请求的授权决策委托给外部独立服务。借助此 API，扩展程序服务可以通过检查请求的标头或元数据来响应 HTTP 请求生命周期中的事件，以做出复杂的授权决策。

    配置授权扩展程序时，您可以使用 wireFormat 选项指定此协议。

您可以将这些扩展程序服务部署在虚拟机 (VM) 实例或 GKE 上，并配置实例组或网络端点组 (NEG) 来表示这些服务的端点。

示例部署场景

下图展示了一个示例部署场景。您可以在用户管理的计算资源（例如 VM 实例或 Google Kubernetes Engine (GKE) 集群）上使用 gRPC 服务器部署宣传信息后端服务，并将其表示为负载均衡器的常规后端服务。

应用负载平衡器使用标注来包含来自标注后端服务的自定义逻辑。
应用负载平衡器将 Service Extensions 宣传信息发送到宣传信息后端服务（点击可放大）。

宣传信息如何与 ext_proc 搭配使用

以下是 ext_proc gRPC API 的缩写版本。

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

收到 HTTP 请求的标头后，应用负载平衡器和 Secure Web Proxy 代理会将 ProcessingRequest 消息发送到扩展程序服务，并将 request_headers 字段设置为来自客户端的 HTTP 标头。

扩展程序服务必须使用相应的 ProcessingResponse 消息响应 ProcessingRequest 消息，该消息包含对 ProcessingRequest 消息的标头或正文的任何配置更改。或者，该服务可以设置 immediate_response 字段，使网络代理结束请求处理并将指定的响应发回给客户端。

对于 REQUEST_HEADER 和 RESPONSE_HEADER 事件，扩展程序服务可以操纵请求或响应中的 HTTP 标头。该服务可以通过在 ProcessingResponse 消息中适当地设置 request_headers 或 response_headers 字段来添加、修改或删除标头。对标头使用 raw_value 字段。

借助流量扩展程序，您可以更改请求和响应的标头和正文。扩展程序服务器可以动态替换处理模式，并允许它为后续请求处理阶段启用或停用扩展程序。负载平衡器在调用流量扩展程序后不会重新评估路由规则。

边缘、授权和路由扩展程序仅支持 HTTP 标头。这些扩展程序无法检查或更改 HTTP 正文。

对于路由和流量扩展程序，当 observabilityMode为扩展程序设置为true且正文处理模式 为STREAMED（默认）时，宣传信息可以异步执行。对扩展程序后端的调用是异步执行的，不会暂停正在进行的请求的处理。 系统会忽略响应（如果有）。

访问宣传信息中的属性

对于使用 ext_proc 协议的宣传信息扩展程序，配置的属性会在 ProcessingRequest 消息中发送。这些属性存储在映射字段中，通常位于 envoy.filters.http.ext_proc 等键下。

映射中的键对应于您在扩展程序配置的 forwardAttributes 字段中指定的属性名称。

以下示例展示了 ProcessingRequest.attributes 的结构：

attributes {
  key: "envoy.filters.http.ext_proc"
  value {
    fields {
      key: "request.host"
      value { string_value: "example.com" }
    }
    fields {
      key: "source.client_region"
      value { string_value: "US" }
    }
    // ... other forwarded attributes
  }
}

您的 gRPC 服务实现可以从收到的 ProcessingRequest 消息中的映射访问这些值。

宣传信息如何与 ext_authz 搭配使用

ext_authz API 仅支持授权宣传信息扩展程序。

以下是该 API 的缩写版本。

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

收到 HTTP 请求的标头后，负载均衡器会将 CheckRequest 消息发送到扩展程序服务。

扩展程序服务必须使用相应的 CheckResponse 消息响应 CheckRequest 消息，该消息包含以下信息：

  • status：表示状态。OK 表示允许该请求。任何其他状态都表示拒绝该请求。

  • denied_response 或 ok_response：表示是允许还是拒绝响应。此字段附带用于授权检查的相关 HTTP 响应属性。

    • 当授权服务允许该请求时，系统会使用 ok_response 字段。该服务可以修改、添加或移除任何原始请求标头，并更新发送给客户端的 HTTP 响应标头。 对标头使用 raw_value 字段。

    • 当授权服务拒绝该请求时，系统会使用 denied_response 字段。该服务可以更新发送给客户端的 HTTP 响应标头。

    如果扩展程序服务通过 CheckResponse 消息返回不允许的标头名称或值，则该请求会被拒绝，并返回 500 Internal Error 状态代码。如需了解不允许的标头， 请参阅 标头操纵的限制。

  • dynamic_metadata：包含可选元数据，供授权扩展程序之后调用的任何扩展程序（例如流量扩展程序）使用。

正文处理模式

对于支持正文处理的扩展程序，您可以通过分别设置 request_body_send_mode 或 response_body_send_mode 字段的值，为请求和响应正文处理配置以下两种发送模式之一。

默认模式为 STREAMED，建议用于大多数使用场景。

模式 说明 必须包含的支持的事件 支持的扩展程序
STREAMED

调用以流式模式执行。如果未设置模式，系统也会使用此默认设置。

代理会将正文块发送到扩展程序服务，并为每个块返回一个 响应。扩展程序可以发回修改后的块 、 确认块而不进行任何更改，或删除块。

代理一次仅发送有限的数据量。因此， 扩展程序服务必须尽快确认块。

虽然正文模式无法动态更改，但高级 扩展程序服务器可以动态选择要接收的未来 HTTP 事件。 通过在标头请求期间返回 ext_proc mode_override 选项 ，宣传信息服务器可以启用或停用 未来的标头、正文或预告片事件。

 对于请求，必须包含 REQUEST_BODY；对于响应，必须包含 RESPONSE_BODY。 流量扩展程序（适用于请求和响应）。
FULL_DUPLEX_STREAMED

调用以全双工模式执行。

代理会按块到达的顺序发送块，而不会缓冲这些块。由于没有缓冲，代理对扩展程序延迟的敏感度较低。

代理可以根据需要接收任意数量的回复块。回复块与代理发送的块断开连接。后续块会在到达代理后立即发送以进行处理，而无需等待之前的块和事件完全处理完毕。

扩展程序可以自由缓冲、修改和重新分块正文 内容。如果扩展程序未发回正文内容，则 链中的下一个扩展程序会收到一个空正文。

ext_proc mode_override 选项不适用，并且模式无法动态更改。

 对于请求，必须包含 REQUEST_BODY 和 REQUEST_TRAILERS ；对于响应，必须包含 RESPONSE_BODY 和 RESPONSE_TRAILERS 。 流量扩展程序（适用于请求和响应）。

路由扩展程序（适用于请求）。

用户管理的宣传信息后端服务支持的后端

您可以在后端服务上托管用户管理的宣传信息扩展程序，该后端服务使用运行 Envoy gRPC 服务的以下类型的后端之一：

宣传信息的建议优化措施

将扩展程序集成到处理路径中会增加请求和响应的延迟时间。扩展程序服务处理的每种类型的数据（包括请求标头、请求正文、响应标头和响应正文，如适用）都会增加延迟时间。

请考虑以下优化措施，以最大限度地缩短延迟时间：

  • 将宣传信息部署在与代理的常规目标后端服务相同的可用区中。

    使用跨区域内部应用负载均衡器时，请将扩展程序服务后端放置在与负载均衡器的仅代理子网相同的区域中。

  • 使用全球外部应用负载均衡器时，请将宣传信息服务后端放置在常规负载均衡器的目标虚拟机、GKE 工作负载和 Cloud Run 函数所在的地理区域中。

  • 如果可能，请将扩展程序配置为仅处理所需的数据。例如，如需仅修改路由和流量扩展程序的请求标头，请将扩展程序中的 supported_events 字段设置为 REQUEST_HEADERS。

宣传信息的限制

本部分列出了一些宣传信息的限制。

标头操纵的限制

您无法更改某些标头。以下是标头操纵的限制：

  • 以下标头不支持标头操纵：

    • X-user-IP
    • CDN-Loop
    • 以 X-Forwarded、X-Google、X-GFE 或 X-Amz- 开头的标头
    • connection
    • keep-alive
    • transfer-encoding、te
    • upgrade
    • proxy-connection、proxy-authenticate、proxy-authorization
    • trailers

    对于流量和授权扩展程序，以下标头也不支持标头操纵：:method、:authority、:scheme 或主机标头。

  • 当 gRPC 服务器在 HeaderMutation中指定标头值时，系统会忽略 value 字段。

正文处理的限制

以下是 HTTP/1.1 客户端和后端在消息正文方面的限制，适用于 ext_proc，但不适用于 ext_authz。

  • 当您为扩展程序配置 REQUEST_BODY 或 RESPONSE_BODY 时，如果代理收到匹配的请求，它会从响应中移除 Content-Length 标头，并切换为分块正文编码。

  • 在将消息正文流式传输到 ext_proc 服务器时，代理可能会在末尾发送尾随 ProcessingRequest 消息，其中包含一个空正文，并将 end_stream 设置为 true，以表明流已结束。

其他限制

以下是 gRPC 响应消息的限制：

  • 响应消息的大小上限为 128 KB。如果收到的消息超出此限制，系统会关闭流并返回 RESOURCE_EXHAUSTED 错误。

  • 宣传信息后端服务无法使用 Cloud Armor、IAP 或 Cloud CDN 政策。

  • 宣传信息后端服务必须使用 HTTP/2 作为协议。

  • 对于授权扩展程序，负载均衡器不会将任何请求正文转发到宣传信息后端服务。

  • 对于路由扩展程序，宣传信息后端服务无法替换 ext_proc 流的处理模式。

后续步骤