Présentation des plug-ins

Cette page présente l'intégration des plug-ins aux équilibreurs de charge d'application Cloud Load Balancing et à Media CDN.

Cette fonctionnalité est disponible en version preview pour Media CDN.

Les plug-ins sont créés au format WebAssembly (Wasm) et utilisent les API Proxy-Wasm.

  • Wasm est un format d'instruction binaire ouvert et standardisé qui permet à un hôte de charger et d'exécuter des modules Wasm avec du code fourni par le client. Wasm présente un certain nombre d'avantages pour l'exécution du code client, y compris le bac à sable pour la sécurité, la compatibilité avec plusieurs langages, la portabilité, une compatibilité étendue et croissante dans le secteur, et des performances améliorées par rapport à d'autres options basées sur des machines virtuelles (VM), telles que JavaScript.

  • Proxy-Wasm est un projet Open Source lancé par Google. Elle définit des API qui vous permettent de personnaliser le comportement des proxys réseau en implémentant des rappels à exécuter lors du traitement des requêtes et des réponses HTTP.

Fonctionnement des plug-ins

Vous pouvez utiliser les extensions de service avec les équilibreurs de charge d'application et Media CDN comme suit :

  1. Préparez le code du plug-in comme suit :

    1. Créez du code personnalisé à l'aide de l'un des SDK Proxy-Wasm :

    2. Compilez votre code dans un module Wasm.

    3. Importez le code de votre plug-in compilé dans un dépôt Artifact Registry.

  2. Créez un plug-in contenant le code du plug-in importé.

  3. Configurez le plug-in dans les extensions Cloud Load Balancing ou les extensions Media CDN.

Ressources de plug-in

Les extensions de service vous aident à créer les ressources clés suivantes, qui vous permettent d'ajouter du code personnalisé dans le chemin de traitement :

  • Plug-ins, qui contiennent le code personnalisé que vous souhaitez déployer.

  • Versions du plug-in, qui sont des versions de votre module Wasm. Vous pouvez indiquer la version de votre module Wasm qu'un plug-in doit utiliser comme version principale (active).

Accéder aux attributs dans les plug-ins

Les plug-ins Wasm peuvent accéder aux attributs transférés à l'aide de l'appel ABI proxy_get_property, qui fait partie de l'ABI Proxy-Wasm. Le nom de la propriété que vous pouvez récupérer correspond au nom de l'attribut.

Vous pouvez accéder aux propriétés en tant que représentation du chemin d'accès du nom de l'attribut. Par exemple, pour récupérer request.host, vous pouvez utiliser une représentation de chemin d'accès telle que {"request", "host"}.

L'exemple conceptuel Rust suivant montre comment accéder aux attributs transférés dans une implémentation 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
}

Limites

Cette section liste certaines limites liées aux plug-ins.

Limites des ressources

Les plug-ins sont strictement limités dans le nombre de ressources qu'ils peuvent utiliser :

  • Un plug-in peut utiliser jusqu'à 1 ms de processeur virtuel normalisé pour chaque appel. Une milliseconde de processeur dépend de la plate-forme, mais la plate-forme normalisée est approximativement égale à un processeur avec une vitesse d'horloge de 4 GHz. Une invocation est une phase d'exécution facturée indépendamment, qui peut être un en-tête de requête, un corps de requête, un en-tête de réponse ou un corps de réponse.

  • Un plug-in peut utiliser jusqu'à 16 Mio de mémoire pour chaque instance de VM (4 Mio pour les plug-ins Media CDN).

    • Une instance doit pouvoir diffuser jusqu'à 1 000 requêtes simultanées, ce qui signifie qu'un plug-in peut contenir jusqu'à 16 Kio de mémoire pour chaque flux (4 Kio pour les plug-ins Media CDN). L'utilisation totale de la mémoire inclut l'état global et les allocations de pile. Les plug-ins qui dépassent cette limite sont arrêtés.

    • C++ et Rust produisent des plug-ins avec l'espace mémoire utilisé le plus faible. Nous vous déconseillons d'utiliser le SDK Go pour Media CDN, car l'environnement d'exécution Go et le récupérateur de mémoire nécessitent un espace mémoire minimal de 2 à 3 Mio.

Utilisez l'outil de test de plug-in pour évaluer les caractéristiques de processeur et de mémoire d'un plug-in.

Limites concernant les API

  • Les plug-ins peuvent utiliser un sous-ensemble de l'ABI Proxy-Wasm. Les plug-ins ne sont pas compatibles avec les minuteurs, les métriques personnalisées, les données partagées, les files d'attente partagées ni les appels réseau sortants.

  • Les événements de fin HTTP ne sont pas acceptés.

Limites de la manipulation des en-têtes

  • La taille maximale d'une mutation (en-têtes ou fragments de corps) est de 128 Kio.

  • Les plug-ins ne peuvent pas remplacer le mode de traitement du flux ext_proc.

  • La manipulation des en-têtes via des plug-ins n'est pas possible pour certains en-têtes. Le processeur ignore les modifications apportées à ces en-têtes et continue de traiter la requête.

    Les plug-ins Media CDN ne sont pas compatibles avec les éléments suivants :

    • En-têtes : CDN-Loop, connection, keep-alive, proxy-authenticate, proxy-authorization, proxy-connection, te, trailers, transfer-encoding, upgrade ou X-user-IP.
    • En-têtes commençant par : x-forwarded, x-goog-, x-google, x-gfe ou x-amz-.

    Les plug-ins Cloud Load Balancing suivants ne sont pas compatibles :

    • En-têtes : 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.

      De plus, pour LbTrafficExtension, les en-têtes suivants ne sont pas non plus acceptés : method, authority, scheme ou les en-têtes d'hôte.

    • En-têtes commençant par : sec-gfe-, sec-google-, x-amz-, x-forwarded-, x-gfe-, x-goog-, x-google- ou x-gproxy-.

Limites avec les clients et backends HTTP/1.1

Lorsque vous configurez REQUEST_BODY ou RESPONSE_BODY pour une extension, si l'équilibreur de charge reçoit une demande avec correspondance, il supprime l'en-tête Content-Length de la réponse et passe à l'encodage du corps fragmenté.

Étapes suivantes