宣传信息概览

借助 Service Extensions，您可以从网络代理进行调用。大多数应用负载平衡器都支持宣传信息附加信息。 Secure Web Proxy（处于预览版阶段）也支持宣传信息扩展服务。

标注数据传输

网络代理通过以下任一 Envoy gRPC 协议与出站流量通信：

  • 外部处理或 ext_proc 协议。

    此协议受路由、流量和授权扩展服务支持，并且是默认使用的协议。

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

  • 外部授权或 ext_authz 协议。

    此协议仅适用于授权扩展程序。对 ext_authz 的支持目前处于预览版阶段。

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

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

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

示例部署方案

下图显示了一个示例部署方案。您可以在用户管理的计算资源（例如虚拟机实例或 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_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 functions 所在的地理区域。

  • 尽可能将扩展程序配置为仅处理您需要的数据。例如，如需仅修改路由和流量扩展的请求标头，请将扩展中的 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 流的处理模式。

后续步骤