Présentation des plug-ins

Cette page fournit des informations générales sur l'intégration de plug-ins avec les é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 plusieurs avantages pour l'exécution du code client, y compris le bac à sable pour la sécurité, la prise en charge de plusieurs langages, la portabilité, une prise en charge large et croissante dans le secteur, et des performances améliorées par rapport à d'autres options basées sur des VM telles que JavaScript.

  • Proxy-Wasm est un projet Open Source lancé par Google. Il 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 Service Extensions 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 de 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 de 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 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 de chemin du nom de l'attribut. Par exemple, pour récupérer request.host, vous pouvez utiliser une représentation de chemin 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 répertorie certaines limites liées aux plug-ins.

Limites concernant les ressources

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

  • Un plug-in peut utiliser jusqu'à 1 ms de processeur virtuel normalisé pour chaque invocation. 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 des en-têtes de requête, un corps de requête, des en-têtes 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. Une instance doit pouvoir traiter 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. N'oubliez pas que l'utilisation totale de la mémoire inclut l'état global et les allocations de pile.

Utilisez le testeur de plug-in pour évaluer les caractéristiques du processeur et de la 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 de requête HTTP ne sont pas compatibles.

Limites concernant la manipulation des en-têtes

  • La taille maximale de toute mutation (en-têtes ou blocs 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 compatible avec certains en-têtes. Le processeur ignore toutes les modifications apportées à ces en-têtes et continue de traiter la requête.

    Pour les plug-ins Media CDN, les éléments suivants ne sont pas compatibles :

    • 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-.

    Pour les plug-ins Cloud Load Balancing, les éléments 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, ces en-têtes ne sont pas non plus compatibles : 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 concernant les clients et les backends HTTP/1.1

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

Étape suivante