Descripción general de los complementos

En esta página, se proporciona información general sobre la integración de complementos con los balanceadores de cargas de aplicaciones de Cloud Load Balancing y Media CDN.

Esta función está en versión preliminar para Media CDN.

Los complementos se compilan con el formato WebAssembly (Wasm) y usan las APIs de Proxy-Wasm.

  • Wasm es un formato de instrucción binario abierto y estandarizado que permite que un host cargue y ejecute módulos de Wasm con código proporcionado por el cliente. Wasm tiene una serie de beneficios para ejecutar el código del cliente, como la zona de pruebas para la seguridad, la compatibilidad con varios lenguajes, la portabilidad, la compatibilidad amplia y creciente dentro de la industria y el rendimiento mejorado en relación con otras opciones basadas en máquinas virtuales (VMs), como JavaScript.

  • Proxy-Wasm es un proyecto de código abierto que inició Google. Define las APIs que te permiten personalizar el comportamiento de los proxies de red implementando devoluciones de llamada que se ejecutarán durante el procesamiento de solicitudes HTTP y respuestas HTTP.

Cómo funcionan los complementos

Puedes usar las extensiones de servicio con balanceadores de cargas de aplicaciones y Media CDN de la siguiente manera:

  1. Prepara el código del complemento de la siguiente manera:

    1. Crea código personalizado con uno de los SDK de Proxy-Wasm:

    2. Compila tu código en un módulo de Wasm.

    3. Sube el código del complemento compilado a un repositorio de Artifact Registry.

  2. Crea un complemento que contenga el código del complemento subido.

  3. Configura el complemento en las extensiones de Cloud Load Balancing o en las extensiones de Media CDN.

Recursos de complementos

Las extensiones de servicio te ayudan a crear los siguientes recursos clave que te permiten agregar código personalizado en la ruta de procesamiento:

  • Complementos, que contienen el código personalizado que deseas implementar.

  • Versiones del complemento, que son versiones de tu módulo de Wasm. Puedes indicar qué versión de tu módulo de Wasm debe usar un complemento como su versión principal (activa).

Accede a los atributos en los complementos

Los complementos de Wasm pueden acceder a los atributos reenviados con la llamada a la ABI de proxy_get_property, que forma parte de la ABI de Proxy-Wasm. El nombre de la propiedad que puedes recuperar corresponde al nombre del atributo.

Puedes acceder a las propiedades como una representación de ruta de acceso del nombre del atributo. Por ejemplo, para recuperar request.host, puedes usar una representación de ruta de acceso, como {"request", "host"}.

En el siguiente ejemplo conceptual de Rust, se muestra cómo acceder a los atributos reenviados dentro de una implementación de HttpContext:

use proxy_wasm::traits::{HttpContext, RootContext};
use proxy_wasm::types::Action;

// ... inside your HttpContext implementation ...

fn on_request_headers(&mut self, _num_headers: usize, _end_of_stream: bool) -> Action {
    if let Some(host) = self.get_property(vec!["request", "host"]) {
        // host is a Vec, convert to string
        let host_str = String::from_utf8(host).unwrap_or_default();
        log::info!("Request host: {}", host_str);
    }

    if let Some(region) = self.get_property(vec!["source", "client_region"]) {
        let region_str = String::from_utf8(region).unwrap_or_default();
        log::info!("Client region: {}", region_str);
    }

    Action::Continue
}

Limitaciones

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

Limitaciones de recursos

Los complementos están estrictamente limitados en cuanto a la cantidad de recursos que pueden usar:

  • Un complemento puede usar hasta 1 mseg de CPU virtual normalizada para cada invocación. Un milisegundo de CPU depende de la plataforma, pero la plataforma normalizada es aproximadamente igual a un procesador con una velocidad de reloj de 4 GHz. Una invocación es una fase de ejecución que se factura de forma independiente, que puede ser encabezados de la solicitud, cuerpo de solicitud, encabezados de respuesta o cuerpo de respuesta.

  • Un complemento puede usar hasta 16 MiB de memoria para cada instancia de VM (4 MiB para los complementos de Media CDN).

    • Una instancia debe poder entregar hasta 1,000 solicitudes simultáneas, lo que significa que un complemento puede contener hasta 16 KiB de memoria para cada transmisión (4 KiB para los complementos de Media CDN). El uso total de memoria incluye el estado global y las asignaciones de pila. Los complementos que superen este límite se finalizarán.

    • Te recomendamos que uses C++ y Rust, ya que producen complementos con el menor espacio en memoria. No se recomienda el SDK de Go para Media CDN porque el entorno de ejecución de Go y el recolector de elementos no utilizados requieren un espacio en memoria de referencia mínimo de 2 a 3 MiB.

Usa el verificador de complementos para comparar las características de CPU y memoria de un complemento.

Limitaciones de las APIs

  • Los complementos pueden usar un subconjunto de la ABI de Proxy-Wasm. Los complementos no admiten temporizadores, métricas personalizadas, datos compartidos, colas compartidas ni llamadas de red salientes.

  • No se admiten los eventos de finalización de HTTP.

Limitaciones con la manipulación de encabezados

  • El tamaño máximo de cualquier mutación (encabezados o fragmentos del cuerpo) es de 128 KiB.

  • Los complementos no pueden anular el modo de procesamiento de la transmisión de ext_proc.

  • No se admite la manipulación de encabezados a través de complementos para algunos encabezados. El procesador ignora cualquier modificación en estos encabezados y continúa procesando la solicitud.

    En el caso de los complementos de Media CDN, no se admite lo siguiente:

    • Encabezados: CDN-Loop, connection, keep-alive, proxy-authenticate, proxy-authorization, proxy-connection, te, trailers, transfer-encoding, upgrade o X-user-IP.
    • Encabezados que comienzan con: x-forwarded, x-goog-,x-google, x-gfe o x-amz-.

    En el caso de los complementos de Cloud Load Balancing, no se admite lo siguiente:

    • Encabezados: connection, keep-alive, proxy-authenticate, proxy-authorization, proxy-connection, sec-user-ip, te, trailer, transfer-encoding, upgrade, x-dont-count-ads, x-dont-show-ads, x-gr, x-proxyuser-ip o x-user-ip.

      Además, para LbTrafficExtension, tampoco se admiten estos encabezados: method, authority, scheme ni encabezados de host.

    • Encabezados que comienzan con: sec-gfe-, sec-google-, x-amz-, x-forwarded-, x-gfe-, x-goog-, x-google- o x-gproxy-.

Limitaciones con clientes y backends HTTP/1.1

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

¿Qué sigue?