Descripción general de los textos destacados

Service Extensions te permite realizar una llamada desde proxies de redes. La mayoría de los balanceadores de cargas de aplicaciones admiten las extensiones de texto destacado. Secure Web Proxy también admite las extensiones de texto destacado (en versión preliminar).

Flujo de datos de textos destacados

Un proxy de redes se comunica con una devolución de llamada a través de uno de los siguientes protocolos de gRPC de Envoy:

  • El protocolo de procesamiento externo o ext_proc

    Este protocolo es compatible con las extensiones de rutas, tráfico y autorización, y se usa de forma predeterminada.

    El protocolo ext_proc permite que el servicio de extensión responda a eventos en el ciclo de vida de una solicitud HTTP examinando y modificando los encabezados o el cuerpo de la solicitud.

  • El protocolo de autorización externa o ext_authz

    Este protocolo solo se admite para las extensiones de autorización.

    El protocolo ext_authz delega las decisiones de autorización para las solicitudes entrantes a un servicio externo independiente. Esta API permite que el servicio de extensión responda a eventos en el ciclo de vida de una solicitud HTTP para una decisión de autorización compleja examinando los encabezados o los metadatos de la solicitud.

    Puedes especificar este protocolo con la opción wireFormat cuando configures una extensión de autorización.

Puedes implementar estos servicios de extensión en instancias de máquina virtual (VM) o en GKE, y configurar un grupo de instancias o un grupo de extremos de red (NEG) para representar los extremos de estos servicios.

Situación de implementación de muestra

En el siguiente diagrama, se muestra una situación de implementación de ejemplo. Puedes implementar el servicio de backend de la llamada con un servidor de gRPC en un recurso de procesamiento administrado por el usuario, como una instancia de VM o un clúster de Google Kubernetes Engine (GKE), y representarlo en el balanceador de cargas como un servicio de backend normal.

Los balanceadores de cargas de aplicaciones usan llamadas para incluir lógica personalizada de los servicios de backend de llamadas.
Los balanceadores de cargas de aplicaciones envían llamadas de Service Extensions a los servicios de backend (haz clic para ampliar).

Cómo funcionan los textos destacados con ext_proc

A continuación, se muestra una versión abreviada de la API de gRPC de ext_proc.

// 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;
  }
}

Después de recibir los encabezados de una solicitud HTTP, el balanceador de cargas de aplicaciones y el proxy web seguro envían el mensaje ProcessingRequest al servicio de extensión con el campo request_headers establecido en los encabezados HTTP del cliente.

El servicio de extensión debe responder al mensaje ProcessingRequest con un mensaje ProcessingResponse correspondiente que contenga los cambios configurados en los encabezados o el cuerpo del mensaje ProcessingRequest. Como alternativa, el servicio puede establecer el campo immediate_response para que el proxy de redes finalice el procesamiento de la solicitud y envíe la respuesta especificada al cliente.

En el caso de los eventos REQUEST_HEADER y RESPONSE_HEADER, el servicio de extensión puede manipular los encabezados HTTP en la solicitud o la respuesta. El servicio puede agregar, modificar o borrar encabezados configurando el campo request_headers o response_headers en el mensaje ProcessingResponse de forma adecuada. Usa el campo raw_value para los encabezados.

Las extensiones de tráfico permiten cambiar los encabezados y el cuerpo de las solicitudes y respuestas. El servidor de extensión puede anular el modo de procesamiento de forma dinámica y permitir que se habilite o inhabilite la extensión para las fases posteriores del procesamiento de solicitudes. Los balanceadores de cargas no vuelven a evaluar las reglas de ruta después de llamar a una extensión de tráfico.

Las extensiones de borde, autorización y ruta solo admiten encabezados HTTP. Estas extensiones no pueden inspeccionar ni modificar los cuerpos HTTP.

En el caso de las extensiones de ruta y tráfico, los textos destacados se pueden ejecutar de forma asíncrona cuando observabilityMode para la extensión se establece en true y el modo de procesamiento del cuerpo es STREAMED (predeterminado). Las llamadas al backend de la extensión se realizan de forma asíncrona, sin pausar el procesamiento de la solicitud en curso. Se ignoran las respuestas, si las hay.

Atributos de acceso en textos destacados

En el caso de las extensiones de texto destacado que usan el protocolo ext_proc, los atributos configurados se envían en el mensaje ProcessingRequest. Los atributos se almacenan en un campo de mapa, por lo general, con una clave como envoy.filters.http.ext_proc.

Las claves del mapa corresponden a los nombres de los atributos que especificaste en el campo forwardAttributes de la configuración de tu extensión.

En el siguiente ejemplo, se muestra la estructura de 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
  }
}

La implementación de tu servicio de gRPC puede acceder a estos valores desde el mapa en los mensajes ProcessingRequest que recibiste.

Cómo funcionan los textos destacados con ext_authz

La API de ext_authz solo admite extensiones de devolución de llamada de autorización.

A continuación, se muestra una versión abreviada de la 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;
}

Después de recibir los encabezados de una solicitud HTTP, el balanceador de cargas envía el mensaje CheckRequest al servicio de extensión.

El servicio de extensión debe responder al mensaje CheckRequest con un mensaje CheckResponse correspondiente que contenga la siguiente información:

  • status: Indica el estado. OK indica que se permite la solicitud. Cualquier otro estado indica que se rechazó la solicitud.

  • denied_response o ok_response: Indica si se permite o rechaza la respuesta. Este campo se acompaña de los atributos de respuesta HTTP relacionados para una verificación de autorización.

    • El campo ok_response se usa cuando el servicio de autorización permite la solicitud. El servicio puede modificar, agregar o quitar cualquier encabezado de solicitud original y actualizar los encabezados de respuesta HTTP que se envían al cliente. Usa el campo raw_value para los encabezados.

    • El campo denied_response se usa cuando el servicio de autorización rechaza la solicitud. El servicio puede actualizar los encabezados de respuesta HTTP que se envían al cliente.

    Si el servicio de extensión devuelve un nombre o valor de encabezado no permitido a través del mensaje CheckResponse, se rechaza la solicitud con el código de estado 500 Internal Error. Para obtener información sobre los encabezados no permitidos, consulta Limitaciones con la manipulación de encabezados.

  • dynamic_metadata: Incluye metadatos opcionales para que los usen las extensiones que se llamen después de la extensión de autorización, como las extensiones de tráfico.

Modos de procesamiento del cuerpo

En el caso de las extensiones que admiten el procesamiento del cuerpo, puedes configurar uno de los siguientes dos modos de envío para el procesamiento del cuerpo de la solicitud y la respuesta. Para ello, establece el valor de los campos request_body_send_mode o response_body_send_mode, respectivamente.

El modo predeterminado es STREAMED, que se recomienda para la mayoría de los casos de uso.

Modo Descripción Se requieren eventos admitidos Extensiones compatibles
STREAMED

Las llamadas se ejecutan en el modo de transmisión. Este parámetro de configuración predeterminado también se usa si no se establece el modo.

El proxy envía fragmentos del cuerpo al servicio de extensión y espera una sola respuesta para cada fragmento. La extensión puede enviar fragmentos modificados, confirmar la recepción de fragmentos sin cambios o borrar fragmentos.

El proxy envía solo una cantidad limitada de datos a la vez. Por lo tanto, el servicio de extensión debe confirmar la recepción de los fragmentos lo antes posible.

Si bien el modo del cuerpo no se puede cambiar de forma dinámica, un servidor de extensión avanzado puede seleccionar de forma dinámica los futuros eventos HTTP que recibirá. Si se devuelve la opción ext_proc mode_override durante una solicitud de encabezados, un servidor de llamada puede habilitar o inhabilitar futuros eventos de encabezados, cuerpo o tráileres.

 Debe incluir REQUEST_BODY para las solicitudes o RESPONSE_BODY para las respuestas. Extensiones de tráfico (para solicitudes y respuestas)
FULL_DUPLEX_STREAMED

Las llamadas se ejecutan en modo dúplex completo.

El proxy envía fragmentos a medida que llegan y no los almacena en búfer. Como no hay almacenamiento en búfer, el proxy es menos sensible a la latencia de la extensión.

El proxy puede recibir tantos fragmentos de respuesta como sean necesarios. Los fragmentos de respuesta se desconectan de los fragmentos que envía el proxy. Los fragmentos posteriores se envían para su procesamiento a medida que llegan al proxy, sin esperar a que se procesen por completo los fragmentos y eventos anteriores.

La extensión puede almacenar en búfer, modificar y volver a fragmentar libremente el contenido del cuerpo. Si la extensión no envía el contenido del cuerpo, la siguiente extensión de la cadena recibe un cuerpo vacío.

La opción ext_proc mode_override no se aplica y el modo no se puede cambiar de forma dinámica.

 Debe incluir REQUEST_BODY y REQUEST_TRAILERS para las solicitudes, o bien RESPONSE_BODY y RESPONSE_TRAILERS para las respuestas. Extensiones de tráfico (para solicitudes y respuestas)

Son las extensiones de ruta (para solicitudes).

Backends compatibles con los servicios de backend de texto destacado administrados por el usuario

Puedes alojar extensiones de texto destacado administradas por el usuario en un servicio de backend que use uno de los siguientes tipos de backends que ejecutan servicios de gRPC de Envoy:

Optimizaciones recomendadas para los textos destacados

La integración de una extensión en la ruta de procesamiento genera latencia adicional para las solicitudes y las respuestas. Cada tipo de datos que procesa el servicio de extensión (incluidos los encabezados de solicitud, el cuerpo de la solicitud, los encabezados de respuesta y el cuerpo de respuesta, según corresponda) agrega latencia.

Considera las siguientes optimizaciones para minimizar la latencia:

  • Implementa textos destacados en las mismas zonas que el servicio de backend de destino normal para el proxy.

    Cuando uses un balanceador de cargas de aplicaciones interno entre regiones, coloca los backends del servicio de extensión en la misma región que las subredes de solo proxy del balanceador de cargas.

  • Cuando uses un balanceador de cargas de aplicaciones externo global, coloca los backends del servicio de llamada en las regiones geográficas en las que se encuentran las VMs de destino, las cargas de trabajo de GKE y las funciones de Cloud Run del balanceador de cargas normal.

  • Cuando sea posible, configura la extensión para que procese solo los datos que necesitas. Por ejemplo, para modificar solo los encabezados de solicitud de las extensiones de ruta y tráfico, configura el campo supported_events de la extensión como REQUEST_HEADERS.

Limitaciones de los textos destacados

En esta sección, se enumeran algunas limitaciones de los textos destacados.

Limitaciones con la manipulación de encabezados

No puedes cambiar algunos encabezados. Estas son las limitaciones de la manipulación de encabezados:

  • No se admite la manipulación de encabezados para los siguientes encabezados:

    • X-user-IP
    • CDN-Loop
    • Encabezados que comienzan con X-Forwarded, X-Google, X-GFE o X-Amz-
    • connection
    • keep-alive
    • transfer-encoding, te
    • upgrade
    • proxy-connection, proxy-authenticate, proxy-authorization
    • trailers

    En el caso de las extensiones de autorización y tráfico, la manipulación de encabezados tampoco se admite para los siguientes: :method, :authority, :scheme o encabezados de host.

  • Cuando un servidor de gRPC especifica valores de encabezado en HeaderMutation, se ignora el campo value.

Limitaciones con el procesamiento del cuerpo

A continuación, se indican las limitaciones de los clientes y los backends de HTTP/1.1 con respecto al cuerpo del mensaje, que se aplica a ext_proc, pero no a ext_authz.

  • Cuando configuras REQUEST_BODY o RESPONSE_BODY para una extensión, si el proxy recibe una solicitud coincidente, quita el encabezado Content-Length de la respuesta y cambia a la codificación de cuerpo fragmentado.

  • Mientras se transmite un cuerpo de mensaje al servidor de ext_proc, al final, el proxy podría enviar un mensaje ProcessingRequest final con un cuerpo vacío y end_stream establecido en true para indicar que finalizó la transmisión.

Otras limitaciones

A continuación, se indican las limitaciones de los mensajes de respuesta de gRPC:

  • El tamaño máximo de un mensaje de respuesta es de 128 kB. Si un mensaje recibido supera este límite, el flujo se cierra con un error RESOURCE_EXHAUSTED.

  • El servicio de backend de la llamada no puede usar políticas de Cloud Armor, IAP ni Cloud CDN.

  • El servicio de backend de la llamada debe usar HTTP/2 como protocolo.

  • En el caso de las extensiones de autorización, el balanceador de cargas no reenvía ningún cuerpo de solicitud al servicio de backend de la devolución de llamada.

  • En el caso de las extensiones de ruta, el servicio de backend de la llamada no puede anular el modo de procesamiento de la transmisión de ext_proc.

¿Qué sigue?