Visão geral dos plug-ins

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

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

Os plug-ins são criados usando o formato WebAssembly (Wasm) e as 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 o código do cliente, incluindo sandbox para segurança, suporte para várias linguagens, portabilidade, suporte amplo e crescente no setor e melhor desempenho em relação a outras opções baseadas em máquinas virtuais (VMs), como o 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 HTTP e respostas HTTP.

Como os plug-ins funcionam

É possível usar as Extensões de Serviço 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

As extensões de serviço ajudam 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. É possível indicar qual versão do módulo Wasm um plug-in deve usar como principal (ativa).

Acessar atributos em plug-ins

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

É possível acessar as 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 de 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 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 (4 MiB para plug-ins do Media CDN).

    • Uma instância precisa ser capaz de exibir até 1.000 solicitações simultâneas, o que significa que um plug-in pode conter até 16 KiB de memória para cada stream (4 KiB para plug-ins do Media CDN). O uso total de memória inclui o estado global e as alocações de pilha. Os plug-ins que excedem esse limite são encerrados.

    • Recomendamos o uso de C++ e Rust, porque eles produzem plug-ins com o menor consumo de memória. O SDK do Go não é recomendado para o Media CDN porque o ambiente de execução do Go e o coletor de lixo exigem um consumo de memória mínimo de 2 a 3 MiB.

Use o testador de plug-ins 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.

  • Os eventos de trailer HTTP não são compatíveis.

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

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

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

  • A manipulação de cabeçalhos por plug-ins não é compatível com alguns cabeçalhos. O processador ignora as modificações nesses cabeçalhos e continua processando a solicitação.

    Para plug-ins do Media CDN, os seguintes não são compatíveis:

    • 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, os seguintes itens não são compatíveis:

    • 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 compatíveis: 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 removerá o cabeçalho Content-Length da resposta e alternará para a codificação de corpo em partes.

A seguir