Alibaba Cloud Service Mesh:Write a Wasm plug-in in Rust for an Envoy proxy in ASM

Fonctionnement

Un plug-in Wasm s'exécute au sein du proxy Envoy sous forme de module isolé. La spécification Proxy-Wasm définit une interface binaire d'application (ABI) standard pour la communication entre l'hôte du proxy et les modules Wasm. Étant donné que Proxy-Wasm est indépendant du proxy, les plug-ins construits sur cette ABI sont portables sur tout proxy implémentant la spécification.

Le SDK Rust Proxy-Wasm organise la logique du plug-in autour de trois types de traits :

Lorsqu'Envoy reçoit une requête HTTP, il crée une nouvelle instance de HttpContext via le RootContext. Les rappels de HttpContext se déclenchent à chaque étape du traitement de la requête, offrant au plug-in un contrôle total sur les en-têtes, le corps et les trailers.

Informations contextuelles

Wasm offre des performances d'exécution proches du natif et s'exécute dans un sandbox sécurisé au niveau de la mémoire, ce qui le rend idéal pour étendre Envoy sans recompilation du binaire du proxy. Toutefois, les langages dotés d'un ramasse-miettes intégré peuvent engendrer une surcharge de performance dans Wasm. Pour cette raison, les langages avec gestion manuelle de la mémoire — C++ et Rust — sont recommandés.

Par rapport au C++, Rust propose un flux de compilation et de construction plus simple, bien que sa courbe d'apprentissage soit plus raide. Faites votre choix en fonction de la maîtrise de chaque langage au sein de votre équipe.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Un cluster ajouté à une instance ASM version 1.18 ou ultérieure. Pour plus d'informations, consultez la rubrique Ajouter un cluster à une instance ASM

• L'injection sidecar activée. Pour plus d'informations, consultez la rubrique Configurer la politique d'injection sidecar

• Une passerelle ingress créée. Pour plus d'informations, consultez la rubrique Créer une passerelle ingress

• L'application HTTPBin déployée et accessible. Pour plus d'informations, consultez la rubrique Déployer l'application HTTPBin

• Une instance Container Registry Enterprise Edition créée. Pour plus d'informations, consultez la rubrique Créer une instance Container Registry Enterprise Edition

Vue d'ensemble du workflow

Le processus de bout en bout comprend cinq étapes :

1. Configurer l'environnement de développement — Installez la chaîne d'outils Rust et la cible de compilation Wasm.

2. Rédiger le plug-in — Créez un projet de bibliothèque Rust, définissez les dépendances et implémentez la logique d'inspection des en-têtes de requête.

3. Construire et empaqueter — Compilez le code Rust en binaire Wasm et empaquetez-le sous forme d'image OCI.

4. Déployer — Poussez l'image vers Container Registry et appliquez la ressource de plug-in Wasm dans ASM.

5. Vérifier — Envoyez des requêtes de test pour confirmer que le plug-in bloque et autorise le trafic comme prévu.

Étape 1 : Configurer l'environnement de développement

1. Installez la chaîne d'outils Rust via rustup. Pour obtenir des instructions, consultez la page Install Rust.

2. Ajoutez la cible de compilation wasm32-wasi : La cible wasm32-wasi compile le code Rust en WebAssembly avec accès à l'interface système WASI, attendue par le runtime Wasm d'Envoy. Si Rust est déjà installé, commencez par le mettre à jour :

      rustup target add wasm32-wasi

      rustup update

Étape 2 : Rédiger le plug-in

Cette étape couvre trois parties : création du projet, configuration des dépendances et implémentation de la logique du plug-in.

mkdir rust-example && cd rust-example
cargo init --lib

[package]
name = "rust-example"
version = "0.1.0"
edition = "2021"

[lib]
# Build as a C-compatible dynamic library so Envoy can load it
crate-type = ["cdylib"]

[dependencies]
log = "0.4.8"
proxy-wasm = "0.2.2"

use log::info;
use proxy_wasm::traits::*;
use proxy_wasm::types::*;

proxy_wasm::main! {{
    proxy_wasm::set_log_level(LogLevel::Trace);
    proxy_wasm::set_root_context(|_| -> Box<dyn RootContext> { Box::new(HttpHeadersRoot) });
}}

struct HttpHeadersRoot;

// Inherit shared utility functions (property access, timers, etc.)
impl Context for HttpHeadersRoot {}

impl RootContext for HttpHeadersRoot {
    fn get_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }

    fn create_http_context(&self, context_id: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(HttpHeaders { context_id }))
    }
}

struct HttpHeaders {
    context_id: u32,
}

impl Context for HttpHeaders {}

impl HttpContext for HttpHeaders {
    fn on_http_request_headers(&mut self, _: usize, _: bool) -> Action {
        info!("#{} wasm-rust: on_http_request_headers", self.context_id);

        match self.get_http_request_header("allow") {
            Some(allow) if allow == "true" => {
                Action::Continue
            }
            _ => {
                info!("#{} wasm-rust: allow header not found or is not true, deny by default", self.context_id);
                self.send_http_response(
                    403,
                    vec![("Content-Type", "text/plain")],
                    Some(b"Forbidden by ASM Wasm Plugin, rust version\n"),
                );
                Action::Pause
            }
        }
    }
}

cargo build --target wasm32-wasi --release

target/wasm32-wasi/release/rust_example.wasm

Étape 3 : Construire une image OCI et la pousser vers Container Registry

Empaquetez le binaire Wasm sous forme d'image OCI afin qu'ASM puisse l'extraire et la charger.

1. Créez un Dockerfile à la racine du projet :

      FROM scratch
      # Copy the compiled Wasm binary into the image as plugin.wasm
      ADD target/wasm32-wasi/release/rust_example.wasm ./plugin.wasm

2. Construisez et poussez l'image. Pour connaître la procédure détaillée, consultez la rubrique Créer une image OCI du plug-in Wasm et la pousser vers l'instance Container Registry Enterprise Edition. Remplacez <your-registry> et <tag> par l'adresse réelle de votre registre et le tag de votre image :

      docker build -t <your-registry>/wasm-rust-example:<tag> .
      docker push <your-registry>/wasm-rust-example:<tag>

Étape 4 : Appliquer le plug-in Wasm à la passerelle ingress

Configurez la ressource WasmPlugin dans ASM pour charger le plug-in dans le proxy Envoy de la passerelle ingress.

Pour la procédure complète, consultez la rubrique Appliquer le plug-in Wasm à la passerelle ingress. Assurez-vous que le champ url pointe vers l'image que vous avez poussée à l'étape 3.

Étape 5 : Vérifier le plug-in

Après le déploiement du plug-in, testez-le en envoyant des requêtes avec et sans l'en-tête allow: true.

kubectl -n istio-system exec <gateway-pod-name> -c istio-proxy -- \
  curl -XPOST "localhost:15000/logging?wasm=debug"

curl <ASM-gateway-IP>/status/418

Forbidden by ASM Wasm Plugin, rust version

2024-09-05T08:33:31.079869Z  info  envoy wasm  wasm log istio-system.header-authorization: #2 wasm-rust: on_http_request_headers
2024-09-05T08:33:31.079943Z  info  envoy wasm  wasm log istio-system.header-authorization: #2 wasm-rust: allow header not found or is not true, deny by default
{"authority_for":"xx.xx.xx.xx","bytes_received":"0","bytes_sent":"43","downstream_local_address":"xx.xx.xx.xx:80","downstream_remote_address":"xx.xx.xx.xx:xxxxx","duration":"0","istio_policy_status":"-","method":"GET","path":"/status/418","protocol":"HTTP/1.1","request_id":"d5250d1a-54b3-406d-8bea-5a51b617b579","requested_server_name":"-","response_code":"403","response_flags":"-","route_name":"httpbin","start_time":"2024-09-05T08:33:31.079Z","trace_id":"-","upstream_cluster":"outbound|8000||httpbin.default.svc.cluster.local","upstream_host":"-","upstream_local_address":"-","upstream_response_time":"-","upstream_service_time":"-","upstream_transport_failure_reason":"-","user_agent":"curl/8.9.0-DEV","x_forwarded_for":"xx.xx.xx.xx"}

curl <ASM-gateway-IP>/status/418 -H "allow: true"

    -=[ teapot ]=-

       _...._
     .'  _ _ `.
    | ."` ^ `". _,
    \_;`"---"`|//
      |       ;/
      \_     _/
        `"""`

Étapes suivantes

• Pour rédiger un plug-in Wasm en Go plutôt qu'en Rust, consultez la version Go de ce tutoriel.

• Explorez davantage d'exemples de plug-ins dans le dépôt du SDK Rust proxy-wasm, y compris la modification du corps de la réponse HTTP, le chargement de la configuration et l'authentification gRPC.