Zusatzinformationen – Übersicht

Mit Service Extensions können Sie Erweiterungen mit Zusatzinformationen von Netzwerkproxys aus aufrufen. Erweiterungen mit Zusatzinformationen werden von den meisten Application Load Balancern unterstützt. Erweiterungen mit Zusatzinformationen werden auch von Secure Web Proxy (in der Vorschau) unterstützt.

Datenfluss von Erweiterungen mit Zusatzinformationen

Ein Netzwerkproxy kommuniziert mit einer Erweiterung mit Zusatzinformationen über eines der folgenden Envoy-gRPC-Protokolle:

  • Das Protokoll für die externe Verarbeitung oder ext_proc.

    Dieses Protokoll wird für Routen-, Traffic- und Autorisierungserweiterungen unterstützt und standardmäßig verwendet.

    Mit dem Protokoll ext_proc kann der Erweiterungsdienst auf Ereignisse im Lebenszyklus einer HTTP-Anfrage reagieren, indem er die Header oder den Text der Anfrage prüft und ändert.

  • Das Protokoll für die externe Autorisierung oder ext_authz.

    Dieses Protokoll wird nur für Autorisierungserweiterungen unterstützt. Die Unterstützung für ext_authz befindet sich in der Vorschau.

    Das Protokoll ext_authz delegiert Autorisierungsentscheidungen für eingehende Anfragen an einen externen, unabhängigen Dienst. Mit dieser API kann der Erweiterungsdienst auf Ereignisse im Lebenszyklus einer HTTP-Anfrage für komplexe Autorisierungsentscheidungen reagieren, indem er die Header oder Metadaten der Anfrage prüft.

    Sie können dieses Protokoll mit der wireFormat Option angeben, wenn Sie eine Autorisierungserweiterung konfigurieren.

Sie können diese Erweiterungsdienste auf VM-Instanzen (virtuelle Maschinen) oder in GKE bereitstellen und eine Instanzgruppe oder Netzwerk-Endpunktgruppe (NEG) konfigurieren, um die Endpunkte für diese Dienste darzustellen.

Beispiel für ein Bereitstellungsszenario

Das folgende Diagramm zeigt ein Beispiel für ein Bereitstellungsszenario. Sie können den Backend-Dienst für Erweiterungen mit Zusatzinformationen mit einem gRPC-Server auf einer vom Nutzer verwalteten Compute-Ressource wie einer VM-Instanz oder einem Google Kubernetes Engine-Cluster (GKE) bereitstellen und ihn dem Load-Balancer als regulären Backend-Dienst präsentieren.

Application Load Balancer verwenden Callouts, um benutzerdefinierte Logik aus Callout-Backend-Diensten einzufügen.
Application Load Balancer senden Service Extensions-Callouts an Backend-Dienste für Callouts (zum Vergrößern anklicken).

Funktionsweise von Erweiterungen mit Zusatzinformationen mit ext_proc

Eine gekürzte Version der ext_proc-gRPC-API sieht so aus:

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

Nachdem die Proxys von Application Load Balancer und Secure Web Proxy die Header für eine HTTP-Anfrage empfangen haben, senden sie die Nachricht ProcessingRequest an den Erweiterungsdienst. Das Feld request_headers ist dabei auf die HTTP-Header vom Client festgelegt.

Der Erweiterungsdienst muss auf die Nachricht ProcessingRequest mit einer entsprechenden Nachricht ProcessingResponse antworten, die alle konfigurierten Änderungen an den Headern oder dem Text der Nachricht ProcessingRequest enthält. Alternativ kann der Dienst das Feld immediate_response festlegen, damit der Netzwerkproxy die Verarbeitung der Anfrage beendet und die angegebene Antwort an den Client zurücksendet.

Bei REQUEST_HEADER- und RESPONSE_HEADER-Ereignissen kann der Erweiterungsdienst die HTTP-Header in der Anfrage oder Antwort bearbeiten. Der Dienst kann Header hinzufügen, ändern oder löschen, indem er das Feld request_headers oder response_headers in der Nachricht ProcessingResponse entsprechend festlegt. Verwenden Sie das Feld raw_value für Header.

Mit Traffic-Erweiterungen können die Header und der Text von Anfragen und Antworten geändert werden. Der Erweiterungsserver kann den Verarbeitungsmodus dynamisch überschreiben und die Erweiterung für nachfolgende Phasen der Anfragenverarbeitung aktivieren oder deaktivieren. Load Balancer werten Routenregeln nach dem Aufrufen einer Traffic-Erweiterung nicht neu aus.

Edge-, Autorisierungs- und Routenerweiterungen unterstützen nur HTTP-Header. Diese Erweiterungen können HTTP-Texte nicht prüfen oder ändern.

Bei Routen- und Traffic-Erweiterungen können Erweiterungen mit Zusatzinformationen asynchron ausgeführt werden, wenn observabilityMode für die Erweiterung auf true gesetzt ist und der Modus für die Textverarbeitung ist STREAMED (Standard). Aufrufe an das Erweiterungs-Backend werden asynchron ausgeführt, ohne die Verarbeitung der laufenden Anfrage zu unterbrechen. Antworten werden gegebenenfalls ignoriert.

Funktionsweise von Erweiterungen mit Zusatzinformationen mit ext_authz

Die ext_authz-API unterstützt nur Autorisierungserweiterungen mit Zusatzinformationen.

Eine gekürzte Version der API sieht so aus:

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

Nachdem der Load-Balancer die Header für eine HTTP-Anfrage empfangen hat, sendet er die Nachricht CheckRequest an den Erweiterungsdienst.

Der Erweiterungsdienst muss auf die Nachricht CheckRequest mit einer entsprechenden Nachricht CheckResponse antworten, die die folgenden Informationen enthält:

  • status: gibt den Status an. OK gibt an, dass die Anfrage zulässig ist. Jeder andere Status gibt an, dass die Anfrage abgelehnt wurde.

  • denied_response oder ok_response: gibt an, ob die Antwort zulässig oder abgelehnt ist. Dieses Feld wird von den zugehörigen HTTP-Antwortattributen für eine Autorisierungsprüfung begleitet.

    • Das Feld ok_response wird verwendet, wenn der Autorisierungsdienst die Anfrage zulässt. Der Dienst kann alle ursprünglichen Anfrageheader ändern, hinzufügen oder entfernen und HTTP-Antwortheader aktualisieren, die an den Client gesendet werden. Verwenden Sie das Feld raw_value für Header.

    • Das Feld denied_response wird verwendet, wenn der Autorisierungsdienst die Anfrage ablehnt. Der Dienst kann HTTP-Antwortheader aktualisieren, die an den Client gesendet werden.

    Wenn der Erweiterungsdienst über die Nachricht CheckResponse einen nicht zulässigen Headernamen oder -wert zurückgibt, wird die Anfrage mit dem Statuscode 500 Internal Error abgelehnt. Informationen zu nicht zulässigen Headern finden Sie unter Einschränkungen bei der Headerbearbeitung.

  • dynamic_metadata: enthält optionale Metadaten zur Verwendung durch alle Erweiterungen, die nach der Autorisierungserweiterung aufgerufen werden, z. B. Traffic-Erweiterungen.

Modi für die Textverarbeitung

Bei Erweiterungen, die die Textverarbeitung unterstützen, können Sie einen der folgenden beiden Sendemodi für die Verarbeitung von Anfrage- und Antworttexten konfigurieren, indem Sie den Wert der Felder request_body_send_mode bzw. response_body_send_mode festlegen.

Der Standardmodus ist STREAMED. Dieser wird für die meisten Anwendungsfälle empfohlen.

Modus Beschreibung Erforderliche unterstützte Ereignisse Unterstützte Erweiterungen
STREAMED

Aufrufe werden im Streamingmodus ausgeführt. Diese Standardeinstellung wird auch verwendet, wenn der Modus nicht festgelegt ist.

Der Proxy sendet Textblöcke an den Erweiterungsdienst und erwartet eine einzelne Antwort pro Block. Die Erweiterung kann geänderte Blöcke zurücksenden, Blöcke ohne Änderungen bestätigen oder Blöcke löschen.

Der Proxy sendet jeweils nur eine begrenzte Datenmenge. Daher muss der Erweiterungsdienst Blöcke so schnell wie möglich bestätigen.

Der Textmodus kann zwar nicht dynamisch geändert werden, aber ein erweiterter Erweiterungsserver kann die zukünftigen HTTP-Ereignisse, die empfangen werden sollen, dynamisch auswählen. Wenn die Option ext_proc mode_override während einer Headeranfrage zurückgegeben wird, kann ein Erweiterungsserver zukünftige Header-, Text- oder Trailer-Ereignisse aktivieren oder deaktivieren.

 Muss REQUEST_BODY für Anfragen oder RESPONSE_BODY für Antworten enthalten. Traffic-Erweiterungen (für Anfragen und Antworten).
FULL_DUPLEX_STREAMED

Aufrufe werden im Vollduplexmodus ausgeführt.

Der Proxy sendet Blöcke, sobald sie eingehen, und puffert sie nicht. Da keine Pufferung erfolgt, reagiert der Proxy weniger empfindlich auf die Latenz der Erweiterung.

Der Proxy kann beliebig viele Antwortblöcke empfangen. Antwortblöcke sind von den Blöcken getrennt, die der Proxy sendet. Nachfolgende Blöcke werden zur Verarbeitung gesendet, sobald sie beim Proxy eingehen, ohne darauf zu warten, dass die vorherigen Blöcke und Ereignisse vollständig verarbeitet wurden.

Die Erweiterung kann die Textinhalte frei puffern, ändern und neu aufteilen. Wenn die Erweiterung die Textinhalte nicht zurücksendet, empfängt die nächste Erweiterung in der Kette einen leeren Text.

Die Option ext_proc mode_override ist nicht anwendbar und der Modus kann nicht dynamisch geändert werden.

 Muss REQUEST_BODY und REQUEST_TRAILERS für Anfragen oder RESPONSE_BODY und RESPONSE_TRAILERS für Antworten enthalten. Traffic-Erweiterungen (für Anfragen und Antworten).

Routenerweiterungen (für Anfragen).

Unterstützte Backends für vom Nutzer verwaltete Backend-Dienste für Erweiterungen mit Zusatzinformationen

Sie können vom Nutzer verwaltete Erweiterungen mit Zusatzinformationen auf einem Backend-Dienst hosten, der eine der folgenden Arten von Backends verwendet, auf denen Envoy-gRPC-Dienste ausgeführt werden:

Empfohlene Optimierungen für Erweiterungen mit Zusatzinformationen

Durch die Einbindung einer Erweiterung in den Verarbeitungspfad entsteht zusätzliche Latenz für Anfragen und Antworten. Jede Art von Daten, die der Erweiterungsdienst verarbeitet, einschließlich Anfrageheader, Anfragetext, Antwortheader und Antworttext, erhöht die Latenz.

Berücksichtigen Sie die folgenden Optimierungen, um die Latenz zu minimieren:

  • Stellen Sie Erweiterungen mit Zusatzinformationen in denselben Zonen wie der reguläre Ziel-Backend-Dienst für den Proxy bereit.

    Wenn Sie einen regionsübergreifenden internen Application Load Balancer verwenden, platzieren Sie die Backends des Erweiterungsdiensts in derselben Region wie die reinen Proxy-Subnetze des Load-Balancers.

  • Wenn Sie einen globalen externen Application Load Balancer verwenden, platzieren Sie die Backends des Erweiterungsdiensts mit Zusatzinformationen in den geografischen Regionen, in denen sich die regulären Ziel-VMs, GKE-Arbeitslasten und Cloud Run-Funktionen des Load-Balancers befinden.

  • Konfigurieren Sie die Erweiterung nach Möglichkeit so, dass nur die benötigten Daten verarbeitet werden. Wenn Sie beispielsweise nur Anfrageheader für Routen- und Traffic-Erweiterungen ändern möchten, legen Sie das Feld supported_events in der Erweiterung auf REQUEST_HEADERS fest.

Einschränkungen von Erweiterungen mit Zusatzinformationen

In diesem Abschnitt werden einige Einschränkungen von Erweiterungen mit Zusatzinformationen aufgeführt.

Einschränkungen bei der Headerbearbeitung

Einige Header können nicht geändert werden. Die folgenden Einschränkungen gelten für die Headerbearbeitung:

  • Die Headerbearbeitung wird für die folgenden Header nicht unterstützt:

    • X-user-IP
    • CDN-Loop
    • Header, die mit X-Forwarded, X-Google, X-GFE oder X-Amz- beginnen
    • connection
    • keep-alive
    • transfer-encoding, te
    • upgrade
    • proxy-connection, proxy-authenticate, proxy-authorization
    • trailers

    Bei Traffic- und Autorisierungserweiterungen wird die Headerbearbeitung auch für die folgenden Header nicht unterstützt: :method, :authority, :scheme oder Host-Header.

  • Wenn ein gRPC-Server Headerwerte in HeaderMutation angibt, wird das Feld value ignoriert.

Einschränkungen bei der Textverarbeitung

Die folgenden Einschränkungen gelten für HTTP/1.1-Clients und -Backends in Bezug auf den Inhalt der Nachricht. Sie gelten für ext_proc, aber nicht für ext_authz.

  • Wenn Sie entweder REQUEST_BODY oder RESPONSE_BODY für eine Erweiterung konfigurieren und der Proxy eine entsprechende Anfrage empfängt, entfernt er den Header Content-Length aus der Antwort und wechselt zur segmentierten Textcodierung.

  • Während des Streamings eines Nachrichtentexts an den ext_proc-Server sendet der Proxy am Ende möglicherweise eine nachfolgende ProcessingRequest-Nachricht mit einem leeren Text, wobei end_stream auf true gesetzt ist, um anzugeben, dass der Stream beendet wurde.

Sonstige Einschränkungen

Die folgenden Einschränkungen gelten für gRPC-Antwortnachrichten:

  • Die maximale Größe einer Antwortnachricht beträgt 128 KB. Wenn eine empfangene Nachricht dieses Limit überschreitet, wird der Stream mit einem RESOURCE_EXHAUSTED-Fehler geschlossen.

  • Der Backend-Dienst für Erweiterungen mit Zusatzinformationen kann keine Cloud Armor-, IAP- oder Cloud CDN-Richtlinien verwenden.

  • Der Backend-Dienst für Erweiterungen mit Zusatzinformationen muss HTTP/2 als Protokoll verwenden.

  • Bei Autorisierungserweiterungen leitet der Load-Balancer keinen Anfragetext an den Backend-Dienst für Erweiterungen mit Zusatzinformationen weiter.

  • Bei Routenerweiterungen kann der Backend-Dienst für Erweiterungen mit Zusatzinformationen den Verarbeitungsmodus des ext_proc-Streams nicht überschreiben.

Nächste Schritte