Présentation des accroches

Les extensions de service vous permettent d'effectuer un appel à partir de proxys réseau. Les extensions d'accroche sont compatibles avec la plupart des équilibreurs de charge d'application. Les extensions d'accroche sont également compatibles avec le proxy Web sécurisé (en version preview).

Flux de données des encadrés

Un proxy réseau communique avec un callout à l'aide de l'un des protocoles Envoy gRPC suivants :

  • Le protocole de traitement externe ou ext_proc.

    Ce protocole est compatible avec les extensions d'itinéraire, de trafic et d'autorisation, et il est utilisé par défaut.

    Le protocole ext_proc permet au service d'extension de répondre aux événements du cycle de vie d'une requête HTTP en examinant et en modifiant les en-têtes ou le corps de la requête.

  • Protocole d'autorisation externe ou ext_authz.

    Ce protocole n'est compatible qu'avec les extensions d'autorisation.

    Le protocole ext_authz délègue les décisions d'autorisation pour les requêtes entrantes à un service externe indépendant. Cette API permet au service d'extension de répondre aux événements du cycle de vie d'une requête HTTP pour une décision d'autorisation complexe en examinant les en-têtes ou les métadonnées de la requête.

    Vous pouvez spécifier ce protocole avec l'option wireFormat lorsque vous configurez une extension d'autorisation.

Vous pouvez déployer ces services d'extension sur des instances de machine virtuelle (VM) ou sur GKE, et configurer un groupe d'instances ou un groupe de points de terminaison du réseau (NEG) pour représenter les points de terminaison de ces services.

Exemple de scénario de déploiement

Le schéma suivant illustre un exemple de scénario de déploiement. Vous pouvez déployer le service de backend d'encart avec un serveur gRPC sur une ressource de calcul gérée par l'utilisateur, telle qu'une instance de VM ou un cluster Google Kubernetes Engine (GKE), et le représenter à l'équilibreur de charge en tant que service de backend régulier.

Les équilibreurs de charge d'application utilisent des appels pour inclure une logique personnalisée à partir des services de backend d'appel.
Les équilibreurs de charge d'application envoient des appels Service Extensions pour appeler les services de backend (cliquez pour agrandir).

Fonctionnement des accroches avec ext_proc

Voici une version abrégée de l'API gRPC ext_proc.

// 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;
  }
}

Après avoir reçu les en-têtes d'une requête HTTP, les proxys équilibreur de charge d'application et Secure Web Proxy envoient le message ProcessingRequest au service d'extension avec le champ request_headers défini sur les en-têtes HTTP du client.

Le service d'extension doit répondre au message ProcessingRequest par un message ProcessingResponse correspondant contenant les modifications configurées apportées aux en-têtes ou au corps du message ProcessingRequest. Le service peut également définir le champ immediate_response pour que le proxy réseau mette fin au traitement de la requête et renvoie la réponse spécifiée au client.

Pour les événements REQUEST_HEADER et RESPONSE_HEADER, le service d'extension peut manipuler les en-têtes HTTP dans la requête ou la réponse. Le service peut ajouter, modifier ou supprimer des en-têtes en définissant le champ request_headers ou response_headers dans le message ProcessingResponse de manière appropriée. Utilisez le champ raw_value pour les en-têtes.

Les extensions de trafic permettent de modifier les en-têtes et le corps des requêtes et des réponses. Le serveur d'extension peut remplacer le mode de traitement de manière dynamique et permettre d'activer ou de désactiver l'extension pour les phases ultérieures du traitement des requêtes. Les équilibreurs de charge ne réévaluent pas les règles de routage après avoir appelé une extension de trafic.

Les extensions Edge, d'autorisation et de route ne sont compatibles qu'avec les en-têtes HTTP. Ces extensions ne peuvent pas inspecter ni modifier les corps HTTP.

Pour les extensions d'itinéraire et de trafic, les encarts peuvent s'exécuter de manière asynchrone lorsque observabilityMode pour l'extension est défini sur true et que le mode de traitement du corps est STREAMED (par défaut). Les appels au backend de l'extension sont effectués de manière asynchrone, sans mettre en pause le traitement de la requête en cours. Les réponses, le cas échéant, sont ignorées.

Accéder aux attributs dans les encarts

Pour les extensions d'accroche qui utilisent le protocole ext_proc, les attributs configurés sont envoyés dans le message ProcessingRequest. Les attributs sont stockés dans un champ de carte, généralement sous une clé telle que envoy.filters.http.ext_proc.

Les clés du mappage correspondent aux noms d'attributs que vous avez spécifiés dans le champ forwardAttributes de la configuration de votre extension.

L'exemple suivant montre la structure de ProcessingRequest.attributes :

attributes {
  key: "envoy.filters.http.ext_proc"
  value {
    fields {
      key: "request.host"
      value { string_value: "example.com" }
    }
    fields {
      key: "source.client_region"
      value { string_value: "US" }
    }
    // ... other forwarded attributes
  }
}

L'implémentation de votre service gRPC peut accéder à ces valeurs à partir du mappage dans les messages ProcessingRequest que vous avez reçus.

Fonctionnement des accroches avec ext_authz

L'API ext_authz n'est compatible qu'avec les extensions d'accroche d'autorisation.

Voici une version abrégée de l'API.

// 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;
}

Après avoir reçu les en-têtes d'une requête HTTP, l'équilibreur de charge envoie le message CheckRequest au service d'extension.

Le service d'extension doit répondre au message CheckRequest par un message CheckResponse correspondant contenant les informations suivantes :

  • status : indique l'état. OK indique que la requête est autorisée. Tout autre état indique que la demande est refusée.

  • denied_response ou ok_response : indique si la réponse est autorisée ou refusée. Ce champ est accompagné des attributs de réponse HTTP associés pour une vérification de l'autorisation.

    • Le champ ok_response est utilisé lorsque le service d'autorisation autorise la requête. Le service peut modifier, ajouter ou supprimer des en-têtes de requête d'origine, et mettre à jour les en-têtes de réponse HTTP envoyés au client. Utilisez le champ raw_value pour les en-têtes.

    • Le champ denied_response est utilisé lorsque le service d'autorisation refuse la requête. Le service peut mettre à jour les en-têtes de réponse HTTP envoyés au client.

    Si le service d'extension renvoie un nom ou une valeur d'en-tête non autorisés via le message CheckResponse, la requête est rejetée avec le code d'état 500 Internal Error. Pour en savoir plus sur les en-têtes non autorisés, consultez Limites applicables à la manipulation des en-têtes.

  • dynamic_metadata : inclut des métadonnées facultatives à utiliser par toutes les extensions appelées après l'extension d'autorisation, telles que les extensions de trafic.

Modes de traitement du corps

Pour les extensions qui acceptent le traitement du corps, vous pouvez configurer l'un des deux modes d'envoi suivants pour le traitement du corps de la requête et de la réponse en définissant la valeur des champs request_body_send_mode ou response_body_send_mode, respectivement.

Le mode par défaut est STREAMED, qui est recommandé pour la plupart des cas d'utilisation.

Mode Description Événements compatibles requis Extensions acceptées
STREAMED

Les appels sont exécutés en mode streaming. Ce paramètre par défaut est également utilisé si le mode n'est pas défini.

Le proxy envoie des blocs de corps au service d'extension et attend une seule réponse pour chaque bloc. L'extension peut renvoyer des blocs modifiés, confirmer des blocs sans aucune modification ou supprimer des blocs.

Le proxy n'envoie qu'une quantité limitée de données à la fois. Le service d'extension doit donc accuser réception des blocs dès que possible.

Bien que le mode de corps ne puisse pas être modifié de manière dynamique, un serveur d'extension avancé peut sélectionner de manière dynamique les futurs événements HTTP à recevoir. En renvoyant l'option ext_proc mode_override lors d'une requête d'en-têtes, un serveur d'appel peut activer ou désactiver les futurs événements d'en-têtes, de corps ou de bandes-annonces.

 Doit inclure REQUEST_BODY pour les requêtes ou RESPONSE_BODY pour les réponses. Extensions de trafic (pour les requêtes et les réponses).
FULL_DUPLEX_STREAMED

Les appels sont exécutés en mode duplex intégral.

Le proxy envoie les blocs à mesure qu'ils arrivent, sans les mettre en mémoire tampon. Comme il n'y a pas de mise en mémoire tampon, le proxy est moins sensible à la latence de l'extension.

Le proxy peut recevoir autant de blocs de réponse que nécessaire. Les blocs de réponse sont dissociés des blocs envoyés par le proxy. Les blocs suivants sont envoyés pour traitement dès qu'ils arrivent au niveau du proxy, sans attendre que les blocs et événements précédents soient entièrement traités.

L'extension peut mettre en mémoire tampon, modifier et regrouper librement le contenu du corps. Si l'extension ne renvoie pas le contenu du corps, l'extension suivante de la chaîne reçoit un corps vide.

L'option ext_proc mode_override n'est pas applicable, et le mode ne peut pas être modifié de manière dynamique.

 Doit inclure REQUEST_BODY et REQUEST_TRAILERS pour les requêtes, ou RESPONSE_BODY et RESPONSE_TRAILERS pour les réponses. Extensions de trafic (pour les requêtes et les réponses).

Extensions de route (pour les demandes).

Backends compatibles pour les services de backend d'accroche gérés par l'utilisateur

Vous pouvez héberger des extensions d'accroche gérées par l'utilisateur sur un service de backend qui utilise l'un des types de backends suivants exécutant des services Envoy gRPC :

Optimisations recommandées pour les accroches

L'intégration d'une extension dans le chemin de traitement entraîne une latence supplémentaire pour les requêtes et les réponses. Chaque type de données traité par le service d'extension (y compris les en-têtes et le corps de la requête et de la réponse, le cas échéant) ajoute de la latence.

Envisagez les optimisations suivantes pour minimiser la latence :

  • Déployez les callouts dans les mêmes zones que le service de backend de destination habituel pour le proxy.

    Lorsque vous utilisez un équilibreur de charge d'application interne interrégional, placez les backends du service d'extension dans la même région que les sous-réseaux proxy réservés de l'équilibreur de charge.

  • Lorsque vous utilisez un équilibreur de charge d'application externe global, placez les backends du service d'appel dans les régions géographiques où se trouvent les VM de destination, les charges de travail GKE et les fonctions Cloud Run de l'équilibreur de charge habituel.

  • Si possible, configurez l'extension pour qu'elle ne traite que les données dont vous avez besoin. Par exemple, pour modifier uniquement les en-têtes de requête pour les extensions de route et de trafic, définissez le champ supported_events de l'extension sur REQUEST_HEADERS.

Limites des encadrés

Cette section présente certaines limites avec des encadrés.

Limites concernant la manipulation des en-têtes

Vous ne pouvez pas modifier certains en-têtes. Voici les limites de la manipulation des en-têtes :

  • La manipulation des en-têtes n'est pas acceptée pour les en-têtes suivants :

    • X-user-IP
    • CDN-Loop
    • En-têtes commençant par X-Forwarded, X-Google, X-GFE ou X-Amz-
    • connection
    • keep-alive
    • transfer-encoding, te
    • upgrade
    • proxy-connection, proxy-authenticate, proxy-authorization
    • trailers

    Pour les extensions de trafic et d'autorisation, la manipulation des en-têtes n'est pas non plus compatible avec les en-têtes :method, :authority, :scheme ni les en-têtes hôtes.

  • Lorsqu'un serveur gRPC spécifie des valeurs d'en-tête dans HeaderMutation, le champ value est ignoré.

Limites du traitement du corps

Voici les limites des clients et des backends HTTP/1.1 concernant le corps du message, qui s'appliquent à ext_proc, mais pas à ext_authz.

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

  • Lors de la diffusion en flux continu d'un corps de message vers le serveur ext_proc, le proxy peut envoyer à la fin un message ProcessingRequest de fin avec un corps vide et end_stream défini sur true pour indiquer que le flux est terminé.

Autres limites

Voici les limites des messages de réponse gRPC :

  • La taille maximale d'un message de réponse est de 128 Ko. Si un message reçu dépasse cette limite, le flux est fermé avec une erreur RESOURCE_EXHAUSTED.

  • Le service de backend d'appel ne peut pas utiliser les règles Cloud Armor, IAP ni Cloud CDN.

  • Le service de backend d'encart doit utiliser HTTP/2 comme protocole.

  • Pour les extensions d'autorisation, l'équilibreur de charge ne transmet aucun corps de requête au service de backend d'appel.

  • Pour les extensions d'itinéraire, le service de backend d'accroche ne peut pas remplacer le mode de traitement du flux ext_proc.

Étapes suivantes