Configurer une extension de trafic

Service Extensions permet aux équilibreurs de charge d'application compatibles d'utiliser des plug-ins ou d'envoyer des appels à des services de backend pour insérer un traitement personnalisé dans le chemin de traitement. Les extensions de trafic s'exécutent en dernier dans le chemin de traitement des requêtes et en premier dans le chemin de traitement des réponses pour modifier les en-têtes et les charges utiles sans affecter le choix du service de backend. Cette page explique comment configurer les extensions de trafic.

Pour obtenir une présentation des extensions d'équilibreur de charge d'application, consultez la Présentation des extensions Cloud Load Balancing.

Une extension de trafic pour un équilibreur de charge d'application pointe vers les ressources suivantes :

  • Une règle de transfert à associer
  • Un plug-in ou un service de backend d'appel dont les backends exécutent l'API gRPC ext_proc

Une extension de trafic regroupe les services d'extension associés en une ou plusieurs chaînes. Vous pouvez configurer des plug-ins et des appels dans la même chaîne d'extension. Chaque chaîne d'extension sélectionne le trafic sur lequel agir à l'aide des conditions de correspondance du CEL (Common Expression Language). L'équilibreur de charge évalue une requête par rapport à la condition de correspondance de chaque chaîne de manière séquentielle. Lorsqu'une requête correspond aux conditions définies par une chaîne, toutes les extensions de la chaîne agissent sur la requête. Une seule chaîne correspond à une requête donnée.

Chaque extension d'une chaîne peut avoir son propre ensemble d'événements compatibles. Les modifications apportées par une extension au contenu des requêtes et des réponses sont visibles par les extensions restantes de la chaîne. Pour les extensions configurées pour prendre en charge les événements de réponse, la séquence des extensions est inversée sur le chemin de réponse.

L'extension de trafic fait référence à la règle de transfert de l'équilibreur de charge à associer. Une fois la ressource configurée, l'équilibreur de charge commence à envoyer les requêtes correspondantes aux services d'extension.

Pour en savoir plus sur les limites liées aux extensions, consultez la page Quotas et limites.

Configurer à l'aide de plug-ins

Cette section explique comment configurer une extension de trafic à l'aide d'un plug-in.

Toutes les ressources d'extension qui font référence à un plug-in donné doivent être du même type. Les extensions doivent également avoir le même schéma d'équilibrage de charge. Vous ne pouvez pas configurer les extensions Cloud Load Balancing avec des plug-ins déjà utilisés dans les extensions Media CDN.

Avant de commencer

  1. Créez un plug-in contenant votre code personnalisé.

  2. Créez et configurez un équilibreur de charge d'application compatible avec les plug-ins d'extension de trafic.

    Par exemple, configurez un équilibreur de charge d'application externe global avec des backends de groupe d'instances de VM.

  3. Configurez un moyen d'envoyer des requêtes de test à votre service, par exemple en exécutant curl. Si vous utilisez un équilibreur de charge interne, créez une VM cliente pour les tests.

Configurer une extension de trafic à l'aide d'un plug-in

L'exemple suivant vous aide à configurer une extension de trafic à l'aide d'un plug-in qui ajoute un en-tête de réponse, hello: service-extensions, lorsque l'hôte correspond à example.com.

  1. Vérifiez si example.com correspond dans le mappage d'URL.

    1. Exécutez la commande curl suivante sur la règle de transfert dans la VM cliente :

      curl -D - -H "host: example.com" FORWARDING_RULE_IP

      Remplacez FORWARDING_RULE_IP par l'adresse IP de la règle de transfert. Pour trouver l'adresse IP, utilisez la gcloud compute forwarding-rules describe commande.

      Le résultat ressemble à ce qui suit :

      HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

  2. Configurez l'extension de trafic.

    Console

    1. Dans la Google Cloud console, accédez à la page Extensions de service.

      Accéder aux extensions de service

    2. Cliquez sur Créer une extension.

      Un assistant s'ouvre pour vous guider dans les premières étapes.

    3. Pour le produit, sélectionnez Équilibrage de charge. Cliquez ensuite sur Continuer.

      La liste des équilibreurs de charge d'application compatibles s'affiche.

    4. Pour le type d'équilibreur de charge, sélectionnez Équilibreur de charge d'application externe global ou Équilibreur de charge d'application interne interrégional. Cliquez ensuite sur Continuer.

    5. Pour le type d'extension, sélectionnez Extensions de trafic, puis cliquez sur Continuer.

    6. Pour ouvrir le formulaire Créer une extension, cliquez sur Continuer.

      Dans le formulaire Créer une extension, notez que les sélections précédentes, qui apparaissent en haut de la page, ne sont pas modifiables.

    7. Dans la section Informations de base, procédez comme suit :

      1. Spécifiez un nom unique pour l'extension.

        Le nom doit commencer par une lettre minuscule suivie de 1 à 62 caractères (lettres minuscules, chiffres ou traits d'union). Il ne peut pas se terminer par un trait d'union.

      2. (Facultatif) Saisissez une brève description de l'extension en utilisant jusqu'à 1 024 caractères.

    8. (Facultatif) Dans la section Libellés, cliquez sur Ajouter un libellé. Ensuite, dans la ligne qui s'affiche, procédez comme suit :

      • Pour Clé, saisissez un nom de clé.
      • Pour Valeur, saisissez une valeur pour la clé.

      Pour ajouter d'autres paires clé-valeur, cliquez sur Ajouter un libellé. Vous pouvez ajouter jusqu'à 64 paires clé-valeur.

      Pour en savoir plus sur les libellés, consultez Créer et mettre à jour des libellés pour les projets.

    9. Pour Règles de transfert, sélectionnez une ou plusieurs règles de transfert à associer à l'extension, par exemple http-content-rule.

      Les règles de transfert déjà associées à une autre extension ne peuvent pas être sélectionnées et apparaissent comme indisponibles.

    10. Pour Extension, afin d'ajouter une extension à exécuter pour une requête correspondante, procédez comme suit :

      • Pour faire correspondre les requêtes pour lesquelles la chaîne d'extension est exécutée, dans le champ Condition de correspondance, spécifiez une expression CEL (Common Expression Language) , par exemple request.host == "example.com".

        Pour en savoir plus sur les expressions CEL, cliquez sur Obtenir de l'aide sur la syntaxe ou consultez la documentation de référence sur le langage de correspondance CEL.

      • Pour Type de programmabilité, sélectionnez Plug-ins.

      • Pour Plug-in, sélectionnez un plug-in créé à l'aide des Service Extensions pour le même type de produit et d'extension.

      • Pour Événements, sélectionnez un ou plusieurs types d'événements HTTP qui appellent l'extension.

      • Pour Attributs de transfert, sélectionnez les attributs de requête, de connexion et d'emplacement que vous souhaitez que l'équilibreur de charge transfère à votre plug-in Wasm. Vous pouvez configurer jusqu'à 16 attributs pour chaque extension. Pour en savoir plus, consultez Attributs compatibles.

      • Pour En-têtes de transfert, cliquez sur Ajouter un en-tête, puis ajoutez des en-têtes HTTP à transférer à l'extension (à partir du client ou du backend). Si aucun en-tête n'est spécifié, tous les en-têtes sont envoyés.

      • (Facultatif) Si l'extension expire ou échoue et que vous souhaitez que le traitement des requêtes ou des réponses se poursuive, pour Échec ouvert, sélectionnez Activé. Les extensions suivantes de la chaîne sont également exécutées.

        Par défaut, l'option Échec ouvert n'est pas sélectionnée. Dans ce cas, lorsqu'une erreur se produit, le traitement des requêtes ou des réponses s'arrête. Si les en-têtes de réponse n'ont pas été transmis au client en aval, un code d'état HTTP 500 générique lui est renvoyé. Si des en-têtes de réponse ont été fournis, le flux HTTP vers le client est réinitialisé.

        L'option par défaut consistant à ne pas sélectionner Échec ouvert est préférable lorsque la sécurité ou l'intégrité est une priorité. L'activation Échec ouvert, en particulier pour les opérations non critiques, est utile lorsque la disponibilité est une priorité.

      Si vous souhaitez spécifier plusieurs extensions ou chaînes d'extension plutôt qu'une seule extension, cliquez sur le bouton Passer au mode avancé à la fin du formulaire, puis spécifiez les extensions et les chaînes requises. Les extensions s'exécutent dans l'ordre dans lequel elles sont listées.

      Spécifiez des noms uniques pour chaque extension et chaque chaîne d'extension. Les noms doivent être conformes à la norme RFC-1034, ne comporter que des lettres minuscules, des chiffres et des traits d'union, et ne pas dépasser 63 caractères. De plus, le premier caractère doit être une lettre et le dernier doit être une lettre ou un chiffre.

    11. Cliquez sur Créer une extension.

    gcloud

    1. Définissez le plug-in dans un fichier YAML et associez-le à une règle de transfert, par exemple http-content-rule.

      cat >traffic-plugin.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/http-content-rule
    loadBalancingScheme: EXTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.host == "example.com"'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - RESPONSE_HEADERS
        forwardAttributes:
        - request.host
        - request.path
EOF

      Remplacez les éléments suivants :

      • PROJECT_ID : the ID du projet.
      • REGION: région de la règle de transfert. La valeur doit correspondre à celle spécifiée pour l'emplacement du plug-in.
      • LOCATION: emplacement du plug-in, global ou une région.
      • WASM_PLUGIN: ID ou nom complet du plug-in.

      Pour en savoir plus sur les champs du fichier YAML, consultez ExtensionChain dans la documentation de l'API.

      Le champ forwardAttributes vous permet de spécifier les attributs de requête, de connexion et d'emplacement que vous pouvez transférer à votre plug-in Wasm. Vous pouvez configurer jusqu'à 16 attributs pour chaque extension. Pour en savoir plus sur les attributs compatibles, consultez Attributs compatibles.

    2. Importez l'extension de trafic. Utilisez la gcloud service-extensions lb-traffic-extensions import commande avec les exemples de valeurs suivants.

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic-plugin.yaml \
    --location=global

    Une fois l'extension de trafic créée, la distribution du nouveau plug-in dans tous les emplacements prend un certain temps. Ce délai peut varier selon les emplacements, car le plug-in n'est pas distribué simultanément dans tous les emplacements.

  3. Pour vérifier que l'extension de trafic fonctionne comme prévu, utilisez la même commande curl :

    curl -D - -H "host: example.com" FORWARDING_RULE_IP

    Le résultat inclut l'en-tête de réponse hello: service-extensions.

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/
hello: service-extensions
via: 1.1 google

    Pour vérifier que l'extension ne cible que le trafic example.com, répétez la commande curl sans l'en-tête host.

    curl -D - FORWARDING_RULE_IP

    Le résultat ressemble à ce qui suit :

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

Configurer les extensions de trafic pour les services gérés par l'utilisateur à l'aide d'appels

Cette section explique comment configurer une extension de trafic pour un service de backend d'appel géré par l'utilisateur à l'aide d'un appel.

Avant de commencer

Créez les ressources requises, comme décrit dans Configurer un service de backend d'appel.

Configurer une extension de trafic à l'aide d'un appel

L'exemple suivant vous aide à configurer une extension de trafic à l'aide d'un appel à appeler lorsque l'hôte correspond à example.com. Le serveur d'extension de trafic dans callout-vm ajoute un en-tête de réponse, hello: service-extensions, aux requêtes correspondantes.

  1. Vérifiez si example.com correspond dans le mappage d'URL.

    1. Exécutez la commande curl suivante sur la règle de transfert dans la VM cliente :

      curl -D - -H "host: example.com" FORWARDING_RULE_IP

      Remplacez FORWARDING_RULE_IP par l'adresse IP de la règle de transfert. Pour trouver l'adresse IP, utilisez la gcloud compute forwarding-rules describe commande.

      Le résultat ressemble à ce qui suit :

      HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

  2. Configurez l'extension de trafic.

    Console

    1. Dans la Google Cloud console, accédez à la page Extensions de service.

      Accéder aux extensions de service

    2. Cliquez sur Créer une extension.

      Un assistant s'ouvre pour vous guider dans les premières étapes.

    3. Pour le produit, sélectionnez Équilibrage de charge. Cliquez ensuite sur Continuer.

      La liste des équilibreurs de charge d'application compatibles s'affiche.

    4. Sélectionnez un type d'équilibreur de charge. Pour les équilibreurs de charge régionaux, spécifiez également la région. Cliquez sur Continuer.

    5. Pour le type d'extension, sélectionnez Extensions de trafic, puis cliquez sur Continuer.

    6. Pour ouvrir le formulaire Créer une extension, cliquez sur Continuer.

      Dans le formulaire Créer une extension, notez que les sélections précédentes, qui apparaissent en haut de la page, ne sont pas modifiables.

    7. Dans la section Informations de base, procédez comme suit :

      1. Spécifiez un nom unique pour l'extension.

        Le nom doit commencer par une lettre minuscule suivie de 1 à 62 caractères (lettres minuscules, chiffres ou traits d'union). Il ne peut pas se terminer par un trait d'union.

      2. (Facultatif) Saisissez une brève description de l'extension en utilisant jusqu'à 1 024 caractères.

    8. (Facultatif) Dans la section Libellés, cliquez sur Ajouter un libellé. Ensuite, dans la ligne qui s'affiche, procédez comme suit :

      • Pour Clé, saisissez un nom de clé.
      • Pour Valeur, saisissez une valeur pour la clé.

      Pour ajouter d'autres paires clé-valeur, cliquez sur Ajouter un libellé. Vous pouvez ajouter jusqu'à 64 paires clé-valeur.

      Pour en savoir plus sur les libellés, consultez Créer et mettre à jour des libellés pour les projets.

    9. Pour Règles de transfert, sélectionnez une ou plusieurs règles de transfert à associer à l'extension, par exemple l7-ilb-forwarding-rule.

      Les règles de transfert déjà associées à une autre extension ne peuvent pas être sélectionnées et apparaissent comme indisponibles.

    10. Pour Extension, afin d'ajouter une extension à exécuter pour une requête correspondante, procédez comme suit :

      • Pour Type de programmabilité, sélectionnez Appels.

      • Pour faire correspondre les requêtes pour lesquelles la chaîne d'extension est exécutée, dans le champ Condition de correspondance, spécifiez une expression CEL (Common Expression Language) , par exemple request.host == "example.com".

        Pour en savoir plus sur les expressions CEL, cliquez sur Obtenir de l'aide sur la syntaxe ou consultez la documentation de référence sur le langage de correspondance CEL.

      • Pour Autorité, saisissez l'en-tête authority de la requête gRPC envoyée depuis l'équilibreur de charge au service d'extension.

      • Pour Service de backend, sélectionnez un service de backend créé en suivant les instructions de la section Configurer un service de backend d'appel.

      • Pour Délai avant expiration, spécifiez une valeur comprise entre 10 et 1 000 millisecondes après laquelle un message sur le flux expire.

      • Pour Événements, sélectionnez un ou plusieurs types d'événements HTTP qui appellent l'extension.

      • Pour Attributs de transfert, sélectionnez les attributs de requête, de connexion et d'emplacement que vous souhaitez que l'équilibreur de charge transfère à votre service d'appel. Vous pouvez configurer jusqu'à 16 attributs pour chaque extension. Pour en savoir plus, consultez Attributs compatibles.

      • Pour En-têtes de transfert, cliquez sur Ajouter un en-tête, puis ajoutez des en-têtes HTTP à transférer à l'extension (à partir du client ou du backend). Si aucun en-tête n'est spécifié, tous les en-têtes sont envoyés.

      • (Facultatif) Si l'extension expire ou échoue et que vous souhaitez que le traitement des requêtes ou des réponses se poursuive, pour Échec ouvert, sélectionnez Activé. Les extensions suivantes de la chaîne sont également exécutées.

        Par défaut, l'option Échec ouvert n'est pas sélectionnée. Dans ce cas, lorsqu'une erreur se produit, le traitement des requêtes ou des réponses s'arrête. Si les en-têtes de réponse n'ont pas été transmis au client en aval, un code d'état HTTP 500 générique lui est renvoyé. Si des en-têtes de réponse ont été fournis, le flux HTTP vers le client est réinitialisé.

        L'option par défaut consistant à ne pas sélectionner Échec ouvert est préférable lorsque la sécurité ou l'intégrité est une priorité. L'activation Échec ouvert, en particulier pour les opérations non critiques, est utile lorsque la disponibilité est une priorité.

      • Pour Métadonnées, cliquez sur Ajouter des métadonnées et spécifiez des exemples de valeurs comme suggéré. Pour Clé, spécifiez key, et pour Valeur, spécifiez value.

        Cliquez sur Ajouter des métadonnées pour ajouter une autre paire clé-valeur. Pour Clé, spécifiez fr, et pour Valeur, spécifiez forwarding_rule_id.

        Le champ Métadonnées vous permet de transmettre des informations supplémentaires de l'équilibreur de charge au serveur d'extension. Les métadonnées sont envoyées dans un message ProcessingRequest et encodées au format protobuf.Struct. Tout texte des métadonnées qui correspond à l'ID de règle de transfert spécifié est remplacé par l'URL de ressource complète de la règle de transfert associée à la requête du client.

        La taille totale des métadonnées doit être inférieure à 1 Kio. Le nombre total de clés dans les métadonnées doit être inférieur à 20. La longueur de chaque clé doit être inférieure à 64 caractères. La longueur de chaque valeur doit être inférieure à 1 024 caractères. Toutes les valeurs doivent être des chaînes.

      Si vous souhaitez spécifier plusieurs extensions ou chaînes d'extension plutôt qu'une seule extension, cliquez sur le bouton Passer au mode avancé à la fin du formulaire, puis spécifiez les extensions et les chaînes requises. Les extensions s'exécutent dans l'ordre dans lequel elles sont listées.

      Spécifiez des noms uniques pour chaque extension et chaque chaîne d'extension. Les noms doivent être conformes à la norme RFC-1034, ne comporter que des lettres minuscules, des chiffres et des traits d'union, et ne pas dépasser 63 caractères. De plus, le premier caractère doit être une lettre et le dernier doit être une lettre ou un chiffre.

    11. Cliquez sur Créer une extension.

    gcloud

    1. Définissez l'appel dans un fichier YAML et associez-le à la règle de transfert. Utilisez les exemples de valeurs fournis.

      cat >traffic.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.host == "example.com"'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
        supportedEvents:
        - RESPONSE_HEADERS
        forwardAttributes:
        - request.host
        - request.path
EOF

      Remplacez PROJECT_ID par l' ID du projet.

      Le champ metadata de la configuration de l'extension vous permet de transmettre des informations supplémentaires de l'équilibreur de charge au serveur d'extension. Les métadonnées sont envoyées dans un message ProcessingRequest et encodées au format protobuf.Struct. Tout texte des métadonnées qui correspond à l'ID de règle de transfert spécifié est remplacé par l'URL de ressource complète de la règle de transfert associée à la requête du client.

      La taille totale de metadata doit être inférieure à 1 Kio. Le nombre total de clés dans les métadonnées doit être inférieur à 16. La longueur de chaque clé doit être inférieure à 64 caractères. La longueur de chaque valeur doit être inférieure à 1 024 caractères. Toutes les valeurs doivent être des chaînes.

      Pour en savoir plus sur les champs du fichier YAML, consultez ExtensionChain dans la documentation de l'API.

      Le champ forwardAttributes vous permet de spécifier les attributs de requête, de connexion et d'emplacement à transférer à votre service d'appel. Vous pouvez configurer jusqu'à 16 attributs pour chaque extension. Pour en savoir plus sur les attributs compatibles, consultez Attributs compatibles.

    2. Importez l'extension de trafic. Utilisez la gcloud service-extensions lb-traffic-extensions import commande avec les exemples de valeurs suivants.

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic.yaml \
    --location=us-west1

  3. Vérifiez que l'extension de trafic fonctionne comme prévu. Utilisez la même commande curl :

    curl -D - -H "host: example.com" FORWARDING_RULE_IP

    Le résultat inclut l'en-tête de réponse hello: service-extensions.

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/
hello: service-extensions
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

    Pour vérifier que l'extension ne cible que le trafic example.com, répétez la commande curl sans l'en-tête host.

    curl -D - FORWARDING_RULE_IP

    Le résultat ressemble à ce qui suit :

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

Étape suivante