Visão geral dos plug-ins

Nesta página, você encontra informações gerais sobre a integração de plug-ins com balanceadores de carga de aplicativo do Cloud Load Balancing e Media CDN.

Esse recurso está em pré-lançamento para a Media CDN.

Os plug-ins são criados usando o formato WebAssembly (Wasm) e APIs Proxy-Wasm.

  • O Wasm é um formato de instrução binária aberto e padronizado que permite que um host carregue e execute módulos Wasm com código fornecido pelo cliente. O Wasm tem vários benefícios para executar código do cliente, incluindo isolamento para segurança, suporte a várias linguagens, portabilidade, suporte amplo e crescente no setor e melhor desempenho em relação a outras opções baseadas em VM, como JavaScript.

  • O Proxy-Wasm é um projeto de código aberto iniciado pelo Google. Ele define APIs que permitem personalizar o comportamento de proxies de rede implementando callbacks a serem executados durante o processamento de solicitações e respostas HTTP.

Como os plug-ins funcionam

É possível usar as Service Extensions com balanceadores de carga de aplicativo e o Media CDN da seguinte maneira:

  1. Prepare o código do plug-in da seguinte maneira:

    1. Crie um código personalizado usando um dos SDKs do Proxy-Wasm:

    2. Compile seu código em um módulo Wasm.

    3. Faça upload do código do plug-in compilado para um repositório do Artifact Registry.

  2. Crie um plug-in que contenha o código do plug-in enviado.

  3. Configure o plug-in nas extensões do Cloud Load Balancing ou nas extensões do Media CDN.

Recursos do plug-in

O Service Extensions ajuda a criar os seguintes recursos principais que ajudam a adicionar código personalizado no caminho de processamento:

  • Plug-ins, que contêm o código personalizado que você quer implantar.

  • Versões do plug-in, que são versões do seu módulo Wasm. Você pode indicar qual versão do módulo Wasm um plug-in vai usar como principal (ativa).

Acessar atributos em plug-ins

Os plug-ins Wasm podem acessar atributos encaminhados usando a chamada de ABI proxy_get_property, que faz parte da ABI Proxy-Wasm. O nome da propriedade que você pode recuperar corresponde ao nome do atributo.

Você pode acessar propriedades como uma representação de caminho do nome do atributo. Por exemplo, para recuperar request.host, use uma representação de caminho como {"request", "host"}.

O exemplo conceitual de Rust a seguir demonstra como acessar atributos encaminhados em uma implementação 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
}

Limitações

Esta seção lista algumas limitações dos plug-ins.

Limitações nos recursos

Os plug-ins são estritamente limitados em relação à quantidade de recursos que podem usar:

  • Um plug-in pode usar até 1 msec de vCPU normalizada para cada invocação. Um milissegundo de CPU depende da plataforma, mas a plataforma normalizada é aproximadamente igual a um processador com uma velocidade de clock de 4 GHz. Uma invocação é uma fase de execução faturada de forma independente, que pode ser cabeçalhos de solicitação, corpo da solicitação, cabeçalhos de resposta ou corpo da resposta.

  • Um plug-in pode usar até 16 MiB de memória para cada instância de VM. Uma instância precisa ser capaz de atender até 1.000 solicitações simultâneas, o que significa que um plug-in pode armazenar até 16 KiB de memória para cada stream. O uso total de memória inclui estado global e alocações de pilha.

Use o testador de plug-in para comparar as características de CPU e memória de um plug-in.

Limitações das APIs

  • Os plug-ins podem usar um subconjunto da ABI Proxy-Wasm. Os plug-ins não são compatíveis com timers, métricas personalizadas, dados compartilhados, filas compartilhadas ou chamadas de rede de saída.

  • Não há suporte para eventos de trailer HTTP.

Limitações com a manipulação de cabeçalhos

  • O tamanho máximo de qualquer mutação (cabeçalhos ou partes do corpo) é de 128 KiB.

  • Os plug-ins não podem substituir o modo de processamento do stream ext_proc.

  • A manipulação de cabeçalhos por plug-ins está indisponível para alguns cabeçalhos. O processador ignora qualquer modificação nesses cabeçalhos e continua processando a solicitação.

    Para plug-ins da CDN de mídia, o seguinte está indisponível:

    • Cabeçalhos: CDN-Loop, connection, keep-alive, proxy-authenticate, proxy-authorization, proxy-connection, te, trailers, transfer-encoding, upgrade ou X-user-IP.
    • Cabeçalhos que começam com: x-forwarded, x-goog-,x-google, x-gfe ou x-amz-.

    Para plug-ins do Cloud Load Balancing, o seguinte não é compatível:

    • Cabeçalhos: 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 ou x-user-ip.

      Além disso, para LbTrafficExtension, estes cabeçalhos também não são aceitos: method, authority, scheme ou cabeçalhos de host.

    • Cabeçalhos que começam com: sec-gfe-, sec-google-, x-amz-, x-forwarded-, x-gfe-, x-goog-, x-google- ou x-gproxy-.

Limitações com clientes e back-ends HTTP/1.1

Ao configurar REQUEST_BODY ou RESPONSE_BODY para uma extensão, se o balanceador de carga receber uma solicitação correspondente, ele vai remover o cabeçalho Content-Length da resposta e mudar para codificação de corpo em partes.

A seguir