Configurer une extension de route

Service Extensions permet aux équilibreurs de charge d'application compatibles d'utiliser des plug-ins ou d'envoyer des appels aux services de backend pour insérer un traitement personnalisé dans le chemin de traitement. Les extensions de route s'exécutent dans le chemin de traitement des requêtes lorsque l'équilibreur de charge reçoit des en-têtes de requêtes et avant d'évaluer le mappage d'URL. Cette page explique comment configurer les extensions de route.

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

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

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

Une extension d'itinéraire regroupe les services d'extension associés dans une chaîne. Vous pouvez configurer à la fois des plug-ins et des encadrés dans la même chaîne d'extension. La chaîne d'extension sélectionne le trafic sur lequel agir à l'aide des conditions de correspondance du Common Expression Language (CEL). L'équilibreur de charge évalue une requête par rapport aux conditions de correspondance d'une 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.

L'extension fait référence à la règle de transfert de l'équilibreur de charge à laquelle s'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 de l'équilibreur de charge d'application, consultez la page Quotas et limites.

Configurer à l'aide de plug-ins

Cette section utilise un exemple pour vous montrer comment configurer une extension de route à l'aide d'un plug-in qui réécrit l'en-tête de requête :host en service-extensions.com lorsque le chemin d'accès correspond à /extensions. L'ancien hôte et celui nouvellement configuré sont mappés à des services de backend dans différentes régions, ce qui illustre le comportement de routage.

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 route.

    Suivez les instructions de la page Configurer un équilibreur de charge d'application interne interrégional avec des backends de groupes d'instances de VM pour toutes les étapes, à l'exception des suivantes :

    • Nommez le service de backend service-one.
    • Pointez service-one vers une instance de machine virtuelle (VM) dans la région A.
    • Le point gl7-gilb-url-map est défini sur service-one par défaut.

  3. Configurez un service de backend supplémentaire, service-two, et pointez-le vers une VM dans la région B.

  4. Ajoutez un outil de mise en correspondance des chemins d'accès au mappage d'URL, en pointant vers service-two. Utilisez la commande gcloud compute url-maps add-path-matcher avec les exemples de valeurs suivants :

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

  5. 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 route à l'aide d'un plug-in

  1. Vérifiez le comportement avant la configuration d'une extension.

    1. Vérifiez qu'une requête sans chemin d'accès explicite est envoyée à la région A :

      curl FORWARDING_RULE_IP

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

      Le résultat ressemble à ce qui suit et indique que la page est diffusée à partir d'une VM dans region A :

      Page served from region-A-vm

    2. Vérifiez qu'il n'y a aucune correspondance pour /extensions dans le mappage d'URL :

      curl FORWARDING_RULE_IP/extensions

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

      Le résultat indique qu'il n'y a aucune correspondance pour /extensions dans le mappage d'URL. Le résultat ressemble à ce qui suit :

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configurez l'extension de route.

    Console

    1. Dans la console Google Cloud , 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 à travers les premières étapes.

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

      Une 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 interne interrégional". Cliquez ensuite sur Continuer.

    5. Pour le type d'extension, sélectionnez Extensions d'itinéraire, 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 d'un maximum de 62 caractères (lettres minuscules, chiffres ou traits d'union) et ne doit pas se terminer par un trait d'union.

      2. Facultatif : Saisissez une brève description de l'extension (1 024 caractères maximum).

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

        • Dans le champ Clé, saisissez le nom d'une 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.

    8. Pour Règles de transfert, sélectionnez une ou plusieurs règles de transfert à associer à l'extension (par exemple, cr-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 désactivées.

    9. Pour les chaînes d'extensions, ajoutez une ou plusieurs chaînes d'extensions à exécuter pour une requête correspondante.

      Pour ajouter une chaîne d'extension, procédez comme suit, puis cliquez sur OK :

      • Pour Nouvelle chaîne d'extension, spécifiez un nom unique.

        Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit 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.

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

        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.

      • Ajoutez une extension à exécuter pour une requête correspondante. Pour les extensions de route, vous ne pouvez spécifier qu'une seule extension.

        Sous Extensions, procédez comme suit, puis cliquez sur OK :

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

        • Dans le champ Nom de l'extension, spécifiez un nom unique.

          Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit 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.

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

        • Pour Transférer les en-têtes, cliquez sur Ajouter un en-tête, puis ajoutez les en-têtes HTTP à transférer à l'extension (depuis le client ou le 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, sélectionnez Activé pour Échec ouvert.

          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 Échec ouvert est préférable lorsque la sécurité ou l'intégrité sont prioritaires. L'activation de l'option Échec ouvert, en particulier pour les opérations non critiques, est utile lorsque la disponibilité est une priorité.

    10. 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 globale, par exemple cr-ilb-forwarding-rule.

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
EOF

      Remplacez les éléments suivants :

      • PROJECT_ID : 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.

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

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

    Une fois l'extension d'itinéraire créée, il faut un certain temps pour que le nouveau plug-in soit distribué dans tous les lieux. L'heure peut varier selon les zones géographiques, car le plug-in n'est pas distribué simultanément dans toutes les zones.

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

    curl FORWARDING_RULE_IP/extensions

    Le résultat ressemble à ce qui suit et indique que la page est diffusée à partir d'une VM dans region B :

    Page served from region-B-vm

    Pour vérifier que le plug-in ne s'exécute que pour les requêtes avec le préfixe de chemin /extension, répétez la commande curl sans chemin.

    curl FORWARDING_RULE_IP

    Le résultat ressemble à ce qui suit :

    Page served from region-A-vm

Configurer à l'aide d'accroches

Cette section vous explique comment configurer une extension d'itinéraire à l'aide d'un encart.

Avant de commencer

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

Configurer une extension d'itinéraire à l'aide d'un encart

L'exemple suivant montre comment configurer une extension de route à appeler lorsque le chemin correspond à /extensions. Le serveur d'appel de route dans callout-vm remplace l'en-tête Host par service-extensions.com, définit le chemin sur /, puis envoie une instruction à l'équilibreur de charge pour recalculer la route. Le trafic est ensuite redirigé vers l7-ilb-backend-service2 au lieu de l7-ilb-backend-service.

  1. Vérifiez si /extensions correspond à une entrée dans le mappage d'URL.

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

      curl FORWARDING_RULE_IP/extensions

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

      Le résultat indique qu'il n'y a aucune correspondance pour /extensions dans le mappage d'URL. Le résultat ressemble à ce qui suit :

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configurez l'extension de route.

    Console

    1. Dans la console Google Cloud , 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 à travers les premières étapes.

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

      Une 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 d'itinéraire, 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 d'un maximum de 62 caractères (lettres minuscules, chiffres ou traits d'union) et ne doit pas se terminer par un trait d'union.

      2. Facultatif : Saisissez une brève description de l'extension (1 024 caractères maximum).

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

        • Dans le champ Clé, saisissez le nom d'une 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.

    8. 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 désactivées.

    9. Pour les chaînes d'extensions, ajoutez une ou plusieurs chaînes d'extensions à exécuter pour une requête correspondante.

      Pour ajouter une chaîne d'extension, procédez comme suit, puis cliquez sur OK.

      • Pour Nouvelle chaîne d'extension, spécifiez un nom unique.

        Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit 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.

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

        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.

      • Ajoutez une extension à exécuter pour une requête correspondante. Pour les extensions de route, vous ne pouvez spécifier qu'une seule extension.

        Sous Extensions, procédez comme suit, puis cliquez sur OK :

        • Dans le champ Type de programmabilité, sélectionnez Appels.

        • Dans le champ Nom de l'extension, spécifiez un nom unique.

          Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit 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.

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

        • Pour Service de backend, sélectionnez un service de backend créé en suivant les instructions de 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 alors que l'équilibreur de charge attend toujours une réponse du service ext_proc.

        • Pour Transférer les en-têtes, cliquez sur Ajouter un en-tête, puis ajoutez les en-têtes HTTP à transférer à l'extension (depuis le client ou le 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, sélectionnez Activé pour Échec ouvert. 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 Échec ouvert est préférable lorsque la sécurité ou l'intégrité sont prioritaires. L'activation de l'option É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 les exemples de valeurs suggérés. 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 correspondant à 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 demande 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 à 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.

    10. 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 >route.yaml <<EOF
    name: route-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.path.startsWith("/extensions")'
      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"
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 correspondant à 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.

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

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

  3. Vérifiez que l'extension d'itinéraire fonctionne comme prévu. Exécutez la même commande curl :

    curl FORWARDING_RULE_IP/extensions

    Le résultat indique que le trafic correspond à l'hôte virtuel service-extensions.com et a atteint le service l7-ilb-backend-service2, même si la requête d'origine ne l'a pas fait. Le résultat ressemble à ce qui suit :

    Page served from second backend service

    Pour vérifier que l'appel de service ne cible que les requêtes avec le préfixe /extension, répétez la commande curl sans le préfixe path.

    curl FORWARDING_RULE_IP

    Le résultat ressemble à ce qui suit :

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

Limites concernant les extensions d'itinéraire

  • Les extensions de route ne sont pas compatibles avec le traitement du corps HTTP.
  • Une réponse directe de l'extension au client n'est pas acceptée pour les extensions de route. Si le serveur d'extension de route répond à une demande de traitement avec une réponse de traitement contenant une réponse directe, l'équilibreur de charge ignore la réponse de traitement.

Pour connaître les limites applicables à toutes les extensions, consultez Limites pour les extensions.

Étapes suivantes