Plug-ins – Übersicht

Auf dieser Seite finden Sie eine Übersicht über die Einbindung von Plug-ins in Cloud Load Balancing-Application Load Balancer und Media CDN.

Dieses Feature befindet sich für Media CDN im Vorschaumodus.

Plug-ins werden im WebAssembly-Format (Wasm) erstellt und verwenden Proxy-Wasm-APIs.

  • Wasm ist ein offenes und standardisiertes binäres Befehlsformat, mit dem ein Host Wasm-Module mit vom Kunden bereitgestelltem Code laden und ausführen kann. Wasm bietet eine Reihe von Vorteilen für die Ausführung von Kundencode, darunter Sandboxing für die Sicherheit, Unterstützung für mehrere Sprachen, Portabilität, breite und wachsende Unterstützung in der Branche und verbesserte Leistung im Vergleich zu anderen Optionen, die auf virtuellen Maschinen (VMs) basieren, wie JavaScript.

  • Proxy-Wasm ist ein von Google gestartetes Open-Source-Projekt. Sie definiert APIs, mit denen Sie das Verhalten von Netzwerkproxys anpassen können, indem Sie Callbacks implementieren, die während der Verarbeitung von HTTP-Anfragen und -Antworten ausgeführt werden.

Funktionsweise von Plug-ins

Sie können Service Extensions mit Application Load Balancern und Media CDN so verwenden:

  1. Bereiten Sie den Plug‑in-Code so vor:

    1. Erstellen Sie benutzerdefinierten Code mit einem der Proxy-Wasm-SDKs:

    2. Kompilieren Sie Ihren Code in ein Wasm-Modul.

    3. Laden Sie den kompilierten Plug-in-Code in ein Artifact Registry-Repository hoch.

  2. Erstellen Sie ein Plug‑in, das den hochgeladenen Plug‑in-Code enthält.

  3. Konfigurieren Sie das Plug-in in Cloud Load Balancing-Erweiterungen oder Media CDN-Erweiterungen.

Plug-in-Ressourcen

Mit Service Extensions können Sie die folgenden wichtigen Ressourcen erstellen, mit denen Sie benutzerdefinierten Code im Verarbeitungspfad hinzufügen können:

  • Plug-ins, die den benutzerdefinierten Code enthalten, den Sie bereitstellen möchten.

  • Plug-in-Versionen, also Versionen Ihres Wasm-Moduls. Sie können angeben, welche Version Ihres Wasm-Moduls ein Plug-in als Hauptversion (aktive Version) verwenden soll.

Auf Attribute in Plug-ins zugreifen

Wasm-Plug-ins können über den ABI-Aufruf proxy_get_property, der Teil der Proxy-Wasm-ABI ist, auf weitergeleitete Attribute zugreifen. Der abrufbare Attributname entspricht dem Attributnamen.

Sie können auf Attribute als Pfaddarstellung des Attributnamens zugreifen. Wenn Sie beispielsweise request.host abrufen möchten, können Sie eine Pfaddarstellung wie {"request", "host"} verwenden.

Das folgende konzeptionelle Rust-Beispiel zeigt, wie Sie in einer HttpContext-Implementierung auf weitergeleitete Attribute zugreifen:

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
}

Beschränkungen

In diesem Abschnitt werden einige Einschränkungen für Plug-ins aufgeführt.

Ressourcenbeschränkungen

Die Anzahl der Ressourcen, die Plug-ins verwenden können, ist streng begrenzt:

  • Ein Plug-in kann bis zu 1 ms normalisierte vCPU pro Aufruf verwenden. Eine CPU-Millisekunde ist plattformabhängig, aber die normalisierte Plattform entspricht ungefähr einem Prozessor mit einer Taktgeschwindigkeit von 4 GHz. Ein Aufruf ist eine unabhängig abgerechnete Ausführungsphase, die Anfrageheader, Anfragetext, Antwortheader oder Antworttext sein kann.

  • Ein Plug-in kann bis zu 16 MiB Arbeitsspeicher pro VM-Instanz verwenden (4 MiB für Media CDN-Plug-ins).

    • Eine Instanz muss bis zu 1.000 gleichzeitige Anfragen verarbeiten können. Das bedeutet, dass ein Plug-in bis zu 16 KiB Arbeitsspeicher pro Stream (4 KiB für Media CDN-Plug-ins) belegen kann. Die gesamte Arbeitsspeichernutzung umfasst den globalen Status und Stack-Zuweisungen. Plug-ins, die dieses Limit überschreiten, werden beendet.

    • Wir empfehlen die Verwendung von C++ und Rust, da sie Plug-ins mit dem geringsten Speicherbedarf erzeugen. Das Go SDK wird für Media CDN nicht empfohlen, da die Go-Laufzeit und der Garbage Collector einen Mindestspeicherbedarf von 2–3 MiB haben.

Verwenden Sie den Plug-in-Tester, um die CPU- und Arbeitsspeichereigenschaften eines Plug-ins zu testen.

Einschränkungen für APIs

  • Plug-ins können eine Teilmenge der Proxy-Wasm-ABI verwenden. Plug-ins unterstützen keine Timer, benutzerdefinierten Messwerte, freigegebenen Daten, freigegebenen Warteschlangen oder ausgehenden Netzwerkaufrufe.

  • HTTP-Trailer-Ereignisse werden nicht unterstützt.

Einschränkungen bei der Header-Manipulation

  • Die maximale Größe einer Mutation (Header oder Textblöcke) beträgt 128 KiB.

  • Plug-ins können den Verarbeitungsmodus des ext_proc-Streams nicht überschreiben.

  • Die Header-Manipulation über Plug-ins wird für einige Header nicht unterstützt. Der Prozessor ignoriert alle Änderungen in diesen Headern und verarbeitet die Anfrage weiter.

    Für Media CDN-Plug-ins wird Folgendes nicht unterstützt:

    • Header: CDN-Loop, connection, keep-alive, proxy-authenticate, proxy-authorization, proxy-connection, te, trailers, transfer-encoding, upgrade oder X-user-IP.
    • Header, die mit x-forwarded,x-goog-, x-google, x-gfe oder x-amz- beginnen.

    Für Cloud Load Balancing-Plug-ins wird Folgendes nicht unterstützt:

    • Überschriften: 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 oder x-user-ip.

      Außerdem werden für LbTrafficExtension die folgenden Header nicht unterstützt: method, authority, scheme oder Host-Header.

    • Header, die mit sec-gfe-, sec-google-, x-amz-, x-forwarded-, x-gfe-, x-goog-, x-google- oder x-gproxy- beginnen.

Einschränkungen bei HTTP/1.1-Clients und -Backends

Wenn Sie entweder REQUEST_BODY oder RESPONSE_BODY für eine Erweiterung konfigurieren und der Load Balancer eine entsprechende Anfrage empfängt, entfernt er den Content-Length-Header aus der Antwort und wechselt zur Codierung des fragmentierten Textes.

Nächste Schritte