Personnaliser le trafic GKE Gateway à l'aide des extensions de service

Cette page explique comment Google Kubernetes Engine (GKE) utilise les extensions de service pour ajouter une logique personnalisée à Cloud Load Balancing.

Cette page est destinée aux administrateurs de comptes et d'identité GKE, ainsi qu'aux développeurs qui doivent configurer une logique de gestion du trafic personnalisée à l'aide des extensions de service.

Avant de lire cette page, assurez-vous de connaître les éléments suivants :

Présentation

GKE utilise des extensions de service pour ajouter une logique personnalisée à Cloud Load Balancing. Vous pouvez utiliser les extensions de service pour des tâches telles que la répartition avancée du trafic, l'authentification personnalisée ou la journalisation des requêtes.

GKE Gateway Controller est compatible avec les extensions de service suivantes :

  • GCPRoutingExtension : cette extension ajoute une logique personnalisée à Cloud Load Balancing pour contrôler le routage du trafic.
  • GCPTrafficExtension : cette extension insère une logique personnalisée dans Cloud Load Balancing pour modifier le trafic. Cette logique est appliquée au trafic une fois le service sélectionné. L'équilibreur de charge peut ajouter ou modifier les en-têtes et les charges utiles des requêtes et des réponses HTTP. GCPTrafficExtension n'affecte pas la sélection de services ni les règles de sécurité des services.

Une extension est associée à une passerelle et fait référence à un Service, un GCPWasmPlugin ou un googleAPIServiceName.

  • Faire référence à un service : dans ce modèle, vous déployez votre logique personnalisée en tant qu'application de backend distincte, exposée en tant que service Kubernetes. L'équilibreur de charge effectue un appel à ce service pour traiter le trafic. Cette approche est polyvalente et vous permet d'implémenter une logique de routage personnalisée ou d'effectuer une manipulation du trafic, comme la modification d'en-tête ou l'inspection de la charge utile. Vous référencez un service avec GCPRoutingExtension ou GCPTrafficExtension.

  • Faire référence à une ressource GCPWasmPlugin : pour les cas d'utilisation hautes performances, vous pouvez injecter une logique personnalisée écrite par l'utilisateur directement dans le chemin d'accès aux données de l'équilibreur de chargeGoogle Cloud à l'aide d'un module WebAssembly (Wasm). Vous définissez une ressource GCPWasmPlugin qui pointe vers l'image de votre module Wasm dans Artifact Registry. Cette méthode n'est utilisée qu'avec un GCPTrafficExtension et un équilibreur de charge d'application externe global.

  • Faire référence à un service d'API Google : vous pouvez également faire référence directement à un service d'API Google en utilisant le champ googleAPIServiceName dans un GCPTrafficExtension.

Dans le diagramme suivant, la ressource GCPRoutingExtension est associée à une passerelle et fait référence à plusieurs services. L'extension contrôle le routage du trafic vers les Services.

La ressource `GCPRoutingExtension` est associée à une passerelle et fait référence à un service. L'extension contrôle le routage du trafic.
Figure : Fonctionnement de GCPRoutingExtension avec les passerelles

Dans le schéma suivant, la ressource GCPTrafficExtension est associée à une passerelle et fait référence à un service, à un GoogleAPIServiceName ou à un GCPWasmPlugin. L'extension modifie les en-têtes et les charges utiles des requêtes et des réponses.

La ressource `GCPTrafficExtension` est associée à une passerelle et fait référence à un service, à un `GoogleAPIServiceName` ou à un `GCPWasmPlugin`. L'extension modifie les en-têtes et les charges utiles des requêtes et des réponses.
Figure : Fonctionnement de GCPTrafficExtension avec les passerelles

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Google Kubernetes Engine.
    • Activer l'API Google Kubernetes Engine
  • Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la commande gcloud components update. Il est possible que les versions antérieures de gcloud CLI ne permettent pas d'exécuter les commandes de ce document.

Conditions requises pour le contrôleur GKE Gateway

  • Votre cluster doit utiliser GKE version 1.33 ou ultérieure.
  • Pour utiliser GCPWasmPlugin, votre cluster doit utiliser GKE version 1.33.3 ou ultérieure.
  • L'API Gateway doit être activée sur votre cluster.
  • Vous devez disposer d'une ressource Gateway configurée. Cette ressource peut être une passerelle d'équilibreur de charge d'application externe global, d'équilibreur de charge d'application externe régional ou d'équilibreur de charge d'application interne régional. Si vous utilisez une ressource GCPWasmPlugin, vous ne devez déployer qu'une passerelle d'équilibreur de charge d'application externe global.
  • Vous devez disposer d'une ressource HTTPRoute configurée.

Restrictions et limitations

Le tableau suivant répertorie les restrictions associées à la configuration des extensions de service de passerelle dans GKE :

Catégorie Restrictions et limitations
Équilibreur de charge La métrique GCPRoutingExtension est compatible avec les équilibreurs de charge suivants :
  • Équilibreur de charge d'application externe régional (classe Gateway gke-l7-regional-external-managed)
  • Équilibreur de charge d'application interne régional(classe Gatewaygke-l7-rilb)
GCPTrafficExtension est compatible avec les équilibreurs de charge suivants :
  • Équilibreur de charge d'application externe régional (classe Gateway gke-l7-regional-external-managed)
  • Équilibreur de charge d'application interne régional (classe Gateway gke-l7-rilb)
  • Équilibreur de charge d'application externe global (classe Gateway gke-l7-global-external-managed)
Chaîne et spécification des extensions
  • Pour un GCPTrafficExtension, chaque ExtensionChain peut comporter au maximum trois Extensions.
  • Pour un GCPRoutingExtension, chaque ExtensionChain est limité à 1 Extension.
  • Un GCPTrafficExtensionSpec et un GCPRoutingExtensionSpec peuvent chacun comporter jusqu'à cinq ExtensionChains.
Timing et correspondance
  • Le délai avant expiration de chaque message individuel du flux dans une extension doit être compris entre 10 et 10 000 millisecondes. Cette limite d'une seconde s'applique aux extensions Route et Trafic.
  • Chaque MatchCondition dans un ExtensionChain est limité à un maximum de 10 CELExpressions.
  • La chaîne MatchCondition résultante envoyée à GCE est limitée à 512 caractères.
  • La chaîne CELMatcher dans un CELExpression ne doit pas comporter plus de 512 caractères et doit respecter un format spécifique. Nous ne prenons pas en charge le champ BackendRefs de CELExpression.
En-tête et métadonnées
  • La liste ForwardHeaders d'un Extension peut contenir jusqu'à 50 noms d'en-tête HTTP.
  • Une carte Metadata dans un Extension peut contenir jusqu'à 16 propriétés.
  • Les clés du mappage Metadata doivent comporter entre 1 et 63 caractères.
  • Les valeurs de la carte Metadata doivent comporter entre 1 et 1 023 caractères.
Événement
  • Pour un GCPRoutingExtension, si requestBodySendMode n'est pas défini, la liste supportedEvents ne peut contenir que des événements RequestHeaders.
  • Pour un GCPRoutingExtension, si requestBodySendMode est défini sur FullDuplexStreamed, la liste supportedEvents ne peut contenir que les événements RequestHeaders, RequestBody et RequestTrailers.
GCPTrafficExtension
  • Le champ responseBodySendMode n'est compatible qu'avec GCPTrafficExtension.
  • Le champ googleAPIServiceName n'est compatible qu'avec GCPTrafficExtension.
  • Le champ GCPWasmPlugin n'est compatible qu'avec GCPTrafficExtension.
GCPWasmPlugin
  • Les extensions avec GCPWasmPlugin ne sont pas compatibles avec les champs suivants :
    • authority
    • timeout
    • metadata
    • requestBodySendMode
    • responseBodySendMode
  • Les extensions avec GCPWasmPlugin ne prennent en charge que les événements RequestHeaders, RequestBody, ResponseHeaders et ResponseBody.
googleAPIServiceName et backendRef Lorsque vous faites référence à un Service qui utilise backendRef dans une Extension, vous devez respecter les conditions suivantes :
  • Doit utiliser HTTP2 comme appProtocol.
  • Doit se trouver dans le même espace de noms que l'extension et la passerelle référencée par l'extension.
  • Vous ne pouvez pas utiliser IAP.
  • Impossible d'utiliser les règles de sécurité Google Cloud Armor (champ securityPolicy de GCPBackendPolicyConfig).
  • Vous ne pouvez pas utiliser Cloud CDN.
  • Vous devez définir exactement l'un des éléments backendRef ou googleAPIServiceName pour un Extension.
  • Vous devez définir authority si backendRef est défini et que kind est Service.
  • Ne définissez pas authority si googleAPIServiceName est défini.
  • Configurez requestBodySendMode pour les extensions à l'aide de backendRef et Service uniquement.
  • Configurez responseBodySendMode pour les extensions à l'aide de backendRef et Service uniquement.

Faire référence à un service

Dans les extensions de service, vous pouvez faire référence à un service qui héberge la logique personnalisée que vous souhaitez que l'équilibreur de charge exécute. Les passerelles ne disposent pas d'extensions de service par défaut.

Pour configurer les extensions de service GKE, procédez comme suit :

  1. Déployez un service d'appel de backend : créez un service Kubernetes qui représente le service de backend pour l'exécution de la logique personnalisée. L'équilibreur de charge appelle ce service.

  2. Configurer les extensions de service : utilisez l'extension appropriée en fonction du type d'équilibreur de charge.

    1. GCPRoutingExtension pour les passerelles régionales : utilisez cette extension pour les équilibreurs de charge d'application externes régionaux et les équilibreurs de charge d'application internes régionaux afin d'implémenter une logique de routage personnalisée dans la région.

    2. GCPTrafficExtension pour les passerelles externes globales, externes régionales et internes : utilisez cette extension pour les équilibreurs de charge d'application externes globaux, les équilibreurs de charge d'application externes régionaux et les équilibreurs de charge d'application internes régionaux afin de manipuler le trafic (par exemple, en modifiant les en-têtes ou en inspectant la charge utile) sur différents types d'équilibreurs de charge.

Déployer un service d'appel de backend

Un service d'appel implémente une logique personnalisée pour les extensions de service de passerelle dans GKE. La passerelle appelle ces applications de backend, en fonction des configurations GCPTrafficExtension ou GCPRoutingExtension, pour modifier ou acheminer le trafic.

Vous déployez un service d'appel pour ajouter une logique personnalisée à votre passerelle. Ce service distinct gère le traitement personnalisé, comme la manipulation des en-têtes, les transformations de charge utile ou le routage du trafic.

Pour déployer un service pouvant servir d'appel pour votre passerelle, procédez comme suit :

  1. (Facultatif) Créez un secret pour TLS : cette commande crée un secret Kubernetes de type TLS contenant votre certificat TLS et votre clé privée.

    Pour créer le secret TLS pour votre service d'appel, remplacez les éléments suivants :

    • SECRET_NAME : nom secret de votre service d'appel
    • path-to-cert : chemins d'accès à votre certificat
    • path-to-key : chemins d'accès à votre clé

  2. Pour vérifier que le secret a été ajouté, exécutez la commande suivante :

    kubectl get secrets SECRET_NAME

    Remplacez SECRET_NAME par le nom secret de votre service d'appel.

    La sortie devrait ressembler à ce qui suit :

    NAME            TYPE                DATA   AGE
SECRET_NAME     kubernetes.io/tls   2      12s

  3. Définissez les ressources de déploiement et de service.

    Vous devez définir les éléments suivants :

    • Déploiement : pour gérer les pods d'application qui contiennent la logique personnalisée de vos extensions de service.
    • Service : pour exposer les pods d'application gérés par le déploiement en tant que service réseau.

    1. Créez un exemple de fichier manifeste extension-service-app.yaml contenant des définitions de déploiement et de service :

      apiVersion: apps/v1
kind: Deployment
metadata:
name: extension-service-app
spec:
selector:
    matchLabels:
      app: store
  replicas: 1
  template:
    metadata:
      labels:
        app: store
    spec:
      containers:
      - name: serviceextensions
        image: us-docker.pkg.dev/service-extensions-samples/callouts/python-example-basic:main
        ports:
        - containerPort: 8080
        - containerPort: 443
        volumeMounts:
        - name: certs
          mountPath: "/etc/certs/"
          readOnly: true
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: TLS_SERVER_CERT
          value: "/etc/certs/path-to-cert"
        - name: TLS_SERVER_PRIVKEY
          value: "/etc/certs/path-to-key"
          resources:
          requests:
            cpu: 10m
      volumes:
      - name: certs
        secret:
          secretName: SECRET_NAME
          optional: false
---
apiVersion: v1
kind: Service
metadata:
  name: extension-service
spec:
  ports:
  - port: 443
    targetPort: 443
    appProtocol: HTTP2
  selector:
    app: store

    2. Appliquez le fichier manifeste extension-service-app.yaml :

      kubectl apply -f extension-service-app.yaml

  4. Vérifiez votre configuration :

    1. Vérifiez que l'application a bien été déployée :

      kubectl get pod --selector app=store

      Une fois l'application en cours d'exécution, le résultat ressemble à ce qui suit :

      NAME                                     READY   STATUS    RESTARTS   AGE
extension-service-app-85f466bc9b-b5mf4   1/1     Running   0          7s

    2. Vérifiez que le service a été déployé :

      kubectl get service extension-service

      Le résultat ressemble à ce qui suit, qui montre un service pour chaque déploiement de magasin :

      NAME                TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
extension-service   ClusterIP   34.118.225.9   <none>        443/TCP   2m40s

Configurer les extensions de service

Vous pouvez configurer un GCPRoutingExtension ou un GCPTrafficExtension pour personnaliser votre flux de trafic.

Configurer GCPRoutingExtension pour les passerelles régionales

Vous pouvez rediriger le trafic à l'aide d'un GCPRoutingExtension. Pour configurer un GCPRoutingExtension, mettez à jour l'HTTPRoute afin de spécifier les requêtes pour l'hôte service-extensions.com.

  1. Mettez à jour HTTPRoute. Modifiez votre HTTPRoute pour inclure les noms d'hôte ou les chemins d'accès qui déclencheront l'extension de routage.

    1. Enregistrez l'exemple de fichier manifeste suivant sous le nom store-route.yaml :

      kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: store
spec:
  parentRefs:
  - kind: Gateway
    name:GATEWAY_NAME
  hostnames:
  - "store.example.com"
  - "service-extensions.example.com"
  rules:
  - backendRefs:
    - name: store-v1
      port: 8080
  - matches:
    - headers:
      - name: env
        value: canary
    backendRefs:
    - name: store-v2
      port: 8080
  - matches:
    - path:
        value: /de
    backendRefs:
    - name: store-german
      port: 8080

      Remplacez GATEWAY_NAME par le nom de votre passerelle.

    2. Appliquez le fichier manifeste store-route.yaml :

      kubectl apply -f store-route.yaml

  2. Définissez le GCPRoutingExtension.

    1. Enregistrez la configuration GCPRoutingExtension dans l'exemple de fichier gcp-routing-extension.yaml :

      kind: GCPRoutingExtension
apiVersion: networking.gke.io/v1
metadata:
  name: my-gateway-extension
  namespace: default
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: GATEWAY_NAME
  extensionChains:
  - name: chain1
    matchCondition:
      celExpressions:
      - celMatcher: request.path.contains("serviceextensions")
    extensions:
    - name: ext1
      authority: "myext.com"
      timeout: 1s
        backendRef:
          group: ""
        kind: Service
        name: extension-service
        port: 443

      Remplacez GATEWAY_NAME par le nom de votre passerelle.

    2. Appliquez l'exemple de fichier manifeste à votre cluster :

      kubectl apply -f gcp-routing-extension.yaml

  3. Vérifiez la configuration de GCPRoutingExtension et sa liaison à la passerelle.

    1. Vérifiez le déploiement GCPRoutingExtension :

      kubectl describe gcproutingextension my-gateway-extension

      Le résultat ressemble à ce qui suit :

      Name:         my-gateway-extension
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPRoutingExtension
Metadata:
  Creation Timestamp:  2025-03-02T17:12:30Z
  Generation:        1
  Resource Version:  31283253
  UID:               ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
Spec:
  Extension Chains:
    Extensions:
      Authority:    myext.com
      Backend Ref:
        Group:
        Kind: Service
        Name: extension-service
        Port: 443
      Name:       ext1
      Timeout:    1s
    Match Condition:
      Cel Expressions:
        Cel Matcher: request.path.contains("serviceextensions")
    Name:  chain1
  Target Refs:
    Group: gateway.networking.k8s.io
    Kind: Gateway
    Name: GATEWAY_NAME
Events:  <none>

      Le résultat affiche les détails de GCPRoutingExtension, qui est nommé my-gateway-extension, dans l'espace de noms par défaut. La sortie affiche le champ Spec, qui contient la définition du comportement de l'extension.

    2. Vérifiez la liaison de la passerelle :

      1. Vérifiez que GCPRoutingExtension est lié à la passerelle. Cela peut prendre quelques minutes.

        kubectl describe gateway GATEWAY_NAME

        Le résultat ressemble à ce qui suit :

        Name:         GATEWAY_NAME
Namespace:    default
Labels:       none
Annotations:  networking.gke.io/addresses: /projects/1234567890/regions/us-central1/addresses/test-hgbk-default-internal-http-5ypwen3x2gcr
              networking.gke.io/backend-services:
                /projects/1234567890/regions/us-central1/backendServices/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/re...
              networking.gke.io/firewalls: /projects/1234567890/global/firewalls/test-hgbk-l7-default-us-central1
              networking.gke.io/forwarding-rules: /projects/1234567890/regions/us-central1/forwardingRules/test-hgbk-default-internal-http-qn7dk9i9zm73
              networking.gke.io/health-checks:
                /projects/1234567890/regions/us-central1/healthChecks/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/regio...
              networking.gke.io/last-reconcile-time: 2025-03-02T17:15:02Z
              networking.gke.io/lb-route-extensions:
                /projects/1234567890/locations/us-central1/lbRouteExtensions/test-hgbk-default-internal-http-lwh0op4qorb0
              networking.gke.io/lb-traffic-extensions:
              networking.gke.io/ssl-certificates:
              networking.gke.io/target-http-proxies:
                /projects/1234567890/regions/us-central1/targetHttpProxies/test-hgbk-default-internal-http-2jzr7e3xclhj
              networking.gke.io/target-https-proxies:
              networking.gke.io/url-maps: /projects/1234567890/regions/us-central1/urlMaps/test-hgbk-default-internal-http-2jzr7e3xclhj
API Version:  gateway.networking.k8s.io/v1
Kind:         Gateway
Metadata:
  Creation Timestamp:  2025-03-02T16:37:50Z
  Finalizers:
  gateway.finalizer.networking.gke.io
  Generation:        1
  Resource Version:  31284863
  UID:               fd512611-bad2-438e-abfd-5619474fbf31
...

        Le résultat affiche les annotations que GKE utilise pour stocker les liens entre la passerelle et les ressourcesGoogle Cloud sous-jacentes. L'annotation networking.gke.io/lb-route-extensions confirme l'association de la passerelle à GCPRoutingExtension.

      2. Vérifiez l'état de l'extension en vous assurant que GCPRoutingExtension est à l'état Programmed avec le motif ProgrammingSucceeded. L'exécution de cette commande peut prendre quelques minutes.

        kubectl describe gcproutingextension my-gateway-extension

        Le résultat ressemble à ce qui suit :

        Name:         my-gateway-extension
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPRoutingExtension
Metadata:
  Creation Timestamp:  2025-03-02T17:12:30Z
  Generation:          1
  Resource Version:    31284378
  UID:                 ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
Spec:
  Extension Chains:
    Extensions:
      Authority:  myext.com
      Backend Ref:
        Group:
        Kind:   Service
        Name:   extension-service
        Port:   443
      Name:     ext1
      Timeout:  1s
    Match Condition:
      Cel Expressions:
        Cel Matcher:  request.path.contains("serviceextensions")
    Name:             chain1
  Target Refs:
    Group:  gateway.networking.k8s.io
    Kind:   Gateway
    Name:   GATEWAY_NAME
Status:
  Ancestors:
    Ancestor Ref:
      Group:      gateway.networking.k8s.io
      Kind:       Gateway
      Name:       GATEWAY_NAME
      Namespace:  default
    Conditions:
      Last Transition Time:  2025-03-02T17:14:15Z
      Message:
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-03-02T17:14:15Z
      Message:
      Reason:                ProgrammingSucceeded
      Status:                True
      Type:                  Programmed
    Controller Name:         networking.gke.io/gateway
Events:
  Type    Reason  Age                From                   Message
  ----    ------  ----               ----                   -------
  Normal  ADD     2m31s              sc-gateway-controller  default/my-gateway-extension
Normal  SYNC    51s (x2 over 98s)  sc-gateway-controller  Attachment of GCPRoutingExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "GATEWAY_NAME",
SectionName: nil,
Port:        nil} was a success
  Normal  SYNC    23s           sc-gateway-controller  Reconciliation of GCPRoutingExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "GATEWAY_NAME",
SectionName: nil,
Port:        nil} was a success

        Le champ Status.Conditions affiche une condition Programmed avec Status: True et Reason: ProgrammingSucceeded. Ces informations confirment que l'extension a bien été appliquée.

  4. Envoyez du trafic vers votre application.

    Une fois votre passerelle, votre route et votre application déployées dans votre cluster, vous pouvez transmettre du trafic à votre application.

    1. Pour accéder à votre application, vous devez trouver l'adresse IP de votre passerelle.

      Dans votre terminal, utilisez la commande suivante :

      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"

      Remplacez GATEWAY_NAME par le nom de votre passerelle.

      Cette commande génère l'adresse IP de la passerelle. Dans les commandes suivantes, remplacez GATEWAY_IP_ADDRESS par l'adresse IP de la sortie.

    2. Testez la mise à jour du chemin en accédant à la version serviceextensions du service de magasin à l'adresse store.example.com/serviceextensions :

      curl http://store.example.com/serviceextensions --resolve store.example.com:80:GATEWAY_IP_ADDRESS -v

      Le résultat ressemble à ce qui suit :

      {
"cluster_name": "gke1",
"host_header": "service-extensions.com",
"metadata": "store-v1",
"pod_name": "store-v1-5d9554f847-cvxpd",
"pod_name_emoji": "💇🏼‍♀️",
"project_id": "gateway-demo",
"timestamp": "2025-03-15T12:00:00",
"zone": "us-central1-c"
}

Configurer le GCPTrafficExtension

Vous pouvez utiliser un GCPTrafficExtension pour utiliser des fonctionnalités avancées de gestion du trafic dans votre environnement Google Cloud . Vous pouvez configurer cette extension pour les équilibreurs de charge d'application externes globaux, les équilibreurs de charge d'application externes régionaux et les équilibreurs de charge d'application internes régionaux. Vous pouvez utiliser GCPTrafficExtension pour implémenter une logique personnalisée de requête et de réponse HTTP, un routage sophistiqué, des transformations et des règles de sécurité.

  1. Mettez à jour HTTPRoute. Modifiez votre HTTPRoute pour inclure les noms d'hôte ou les chemins d'accès qui déclencheront l'extension de trafic.

    1. Enregistrez l'exemple de fichier manifeste suivant sous le nom store-route.yaml :

      kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: store
spec:
  parentRefs:
  - kind: Gateway
    name: GATEWAY_NAME
  hostnames:
  - "store.example.com"
  - "service-extensions.example.com"
  rules:
  - backendRefs:
    - name: store-v1
      port: 8080
  - matches:
    - headers:
      - name: env
        value: canary
    backendRefs:
    - name: store-v2
      port: 8080
  - matches:
    - path:
        value: /de
    backendRefs:
    - name: store-german
      port: 8080

      Remplacez GATEWAY_NAME par le nom de votre passerelle, par exemple internal-http, external-http ou global-external-http.

    2. Appliquez le fichier manifeste store-route.yaml à votre cluster :

      kubectl apply -f store-route.yaml

  2. Définissez le GCPTrafficExtension.

    1. Enregistrez la configuration GCPTrafficExtension dans l'exemple de fichier gcp-traffic-extension.yaml :

      kind: GCPTrafficExtension
apiVersion: networking.gke.io/v1
metadata:
  name: my-traffic-extension
  namespace: default
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: GATEWAY_NAME
  extensionChains:
  - name: chain1
    matchCondition:
      celExpressions:
      - celMatcher: request.path.contains("serviceextensions")
    extensions:
    - name: ext1
      authority: "myext.com"
      timeout: 1s
      backendRef:
        group: ""
        kind: Service
        name: extension-service
        port: 443

      Remplacez GATEWAY_NAME par le nom de votre passerelle, à savoir internal-http, external-http ou global-external-http.

    2. Appliquez l'exemple de fichier manifeste à votre cluster :

      kubectl apply -f gcp-traffic-extension.yaml

  3. Vérifiez la configuration de GCPTrafficExtension et sa liaison à la passerelle.

    1. Vérifiez le déploiement GCPTrafficExtension :

      kubectl describe gcptrafficextension my-traffic-extension

      Le résultat ressemble à ce qui suit :

      Name:         my-traffic-extension
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPTrafficExtension
Metadata:
  Creation Timestamp:  2025-03-02T17:12:30Z
  Generation:        1
  Resource Version:  31283253
  UID:               ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
Spec:
  Extension Chains:
    Extensions:
      Authority:    myext.com
      Backend Ref:
        Group:
        Kind: Service
        Name: extension-service
        Port: 443
      Name:       ext1
      Timeout:    1s
    Match Condition:
      Cel Expressions:
        Cel Matcher: request.path.contains("serviceextensions")
    Name:  chain1
  Target Refs:
    Group: gateway.networking.k8s.io
    Kind: Gateway
    Name: GATEWAY_NAME
Events:  <none>

      Le résultat affiche les détails de l'GCPTrafficExtension nommé my-traffic-extension dans l'espace de noms par défaut. Il affiche le champ Spec, qui contient la définition du comportement de l'extension.

    2. Vérifiez la liaison de la passerelle :

      Vérifiez que GCPTrafficExtension est lié à la passerelle. L'exécution de cette commande peut prendre quelques minutes :

      kubectl describe gateway GATEWAY_NAME

      Le résultat ressemble à ce qui suit :

      Name:         GATEWAY_NAME
Namespace:    default
Labels:       <none>
Annotations:  networking.gke.io/addresses: /projects/1234567890/regions/us-central1/addresses/test-hgbk-default-internal-http-5ypwen3x2gcr
              networking.gke.io/backend-services:
                /projects/1234567890/regions/us-central1/backendServices/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/re...
              networking.gke.io/firewalls: /projects/1234567890/global/firewalls/test-hgbk-l7-default-us-central1
              networking.gke.io/forwarding-rules: /projects/1234567890/regions/us-central1/forwardingRules/test-hgbk-default-internal-http-qn7dk9i9zm73
              networking.gke.io/health-checks:
                /projects/1234567890/regions/us-central1/healthChecks/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/regio...
              networking.gke.io/last-reconcile-time: 2025-03-02T17:15:02Z
              networking.gke.io/lb-traffic-extensions:
                /projects/1234567890/locations/us-central1/lbTrafficExtensions/test-hgbk-default-internal-http-lwh0op4qorb0
              networking.gke.io/ssl-certificates:
              networking.gke.io/target-http-proxies:
                /projects/1234567890/regions/us-central1/targetHttpProxies/test-hgbk-default-internal-http-2jzr7e3xclhj
              networking.gke.io/target-https-proxies:
              networking.gke.io/url-maps: /projects/1234567890/regions/us-central1/urlMaps/test-hgbk-default-internal-http-2jzr7e3xclhj
API Version:  gateway.networking.k8s.io/v1
Kind:         Gateway
Metadata:
  Creation Timestamp:  2025-03-02T16:37:50Z
  Finalizers:
    gateway.finalizer.networking.gke.io
  Generation:        1
  Resource Version:  31284863
  UID:               fd512611-bad2-438e-abfd-5619474fbf31
...

      La sortie affiche les annotations que GKE utilise pour stocker les liens entre la passerelle et les ressources Google Cloud sous-jacentes. L'annotation networking.gke.io/lb-traffic-extensions confirme l'association.

    3. Vérifiez l'état de l'extension :

      Vérifiez que l'état de GCPTrafficExtension est Programmed et que la raison est ProgrammingSucceeded. L'exécution de cette commande peut prendre quelques minutes.

      Pour vérifier l'état de l'extension de GCPTrafficExtension, exécutez la commande suivante :

      kubectl describe gcptrafficextension my-traffic-extension

      Le résultat de la ressource GCPTrafficExtension est semblable à ce qui suit :

      Name:         my-traffic-extension
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPTrafficExtension
Metadata:
  Creation Timestamp:  2025-03-02T17:12:30Z
  Generation:          1
  Resource Version:    31284378
  UID:                 ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
Spec:
  Extension Chains:
    Extensions:
      Authority:  myext.com
      Backend Ref:
        Group:
        Kind:   Service
        Name:   extension-service
        Port:   443
      Name:     ext1
      Timeout:  1s
    Match Condition:
      Cel Expressions:
        Cel Matcher:  request.path.contains("serviceextensions")
    Name:             chain1
  Target Refs:
    Group:  gateway.networking.k8s.io
    Kind:   Gateway
    Name:   GATEWAY_NAME
Status:
  Ancestors:
    Ancestor Ref:
      Group:      gateway.networking.k8s.io
      Kind:       Gateway
      Name:       GATEWAY_NAME
      Namespace:  default
    Conditions:
      Last Transition Time:  2025-03-02T17:14:15Z
      Message:
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-03-02T17:14:15Z
      Message:
      Reason:                ProgrammingSucceeded
      Status:                True
      Type:                  Programmed
    Controller Name:         networking.gke.io/gateway
Events:
  Type    Reason  Age                From                   Message
  ----    ------  ----               ----                   -------
  Normal  ADD     2m31s              sc-gateway-controller  default/my-traffic-extension
  Normal  SYNC    51s (x2 over 98s)  sc-gateway-controller  Attachment of GCPTrafficExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
  Kind:        "Gateway",
  Namespace:   "default",
  Name:        "GATEWAY_NAME",
  SectionName: nil,
  Port:        nil} was a success
  Normal  SYNC    23s           sc-gateway-controller  Reconciliation of GCPTrafficExtension "default/my-traffic-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
  Kind:        "Gateway",
  Namespace:   "default",
  Name:        "GATEWAY_NAME",
  SectionName: nil,
  Port:        nil} was a success

      Le champ Status.Conditions affiche une condition Programmed avec Status: True et Reason: ProgrammingSucceeded. Ces informations confirment que l'extension a bien été appliquée.

  4. Envoyez du trafic vers votre application.

    Une fois votre passerelle, votre route et votre application déployées dans votre cluster, vous pouvez transmettre du trafic à votre application.

    1. Pour accéder à votre application, vous devez trouver l'adresse IP de votre passerelle.

      Dans votre terminal, utilisez la commande suivante :

      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"

      Remplacez GATEWAY_NAME par le nom de votre passerelle.

      Cette commande génère l'adresse IP de la passerelle. Dans les commandes suivantes, remplacez GATEWAY_IP_ADDRESS par l'adresse IP de la sortie.

    2. Testez la mise à jour du chemin en accédant à la version serviceextensions du service de magasin à l'adresse store.example.com/serviceextensions :

      curl http://store.example.com/serviceextensions --resolve store.example.com:80:GATEWAY_IP_ADDRESS -v

      Le résultat ressemble à ce qui suit :

      {
*   Request completely sent off
< HTTP/1.1 200 OK
< server: Werkzeug/2.3.7 Python/3.11.3
< date: Sun, 02 Mar 2025 16:58:10 GMT
< content-type: application/json
< access-control-allow-origin: *
< hello: service-extensions
< via: 1.1 google
< transfer-encoding: chunked
}

Faire référence à une ressource GCPWasmPlugin

Vous pouvez injecter une logique personnalisée directement dans le chemin d'accès aux données de l'équilibreur de charge en utilisant un GCPWasmPlugin avec un GCPTrafficExtension. Cette méthode vous permet de déployer des fonctionnalités de gestion du trafic personnalisées, empaquetées sous forme de module Wasm.

Pour configurer les extensions de service GKE, procédez comme suit :

  1. Déployez un GCPWasmPlugin : créez et déployez une définition de ressource personnalisée (CRD) GCPWasmPlugin qui contient le code personnalisé de votre module Wasm. Vous ne pouvez utiliser GCPWasmPlugin qu'avec GCPTrafficExtension pour la classe GatewayClass gke-l7-global-external-managed.

  2. Configurer les extensions de service : utilisez GCPTrafficExtension pour l'équilibreur de charge d'application externe global.

Déployer un GCPWasmPlugin

GCPWasmPlugin vous permet d'injecter une logique personnalisée écrite par l'utilisateur directement dans le chemin d'accès aux données de l'équilibreur de charge Google Cloud . La ressource GCPWasmPlugin pointe vers l'image du module Wasm dans Artifact Registry, qui est ensuite exécutée par l'équilibreur de charge.

Avant de continuer, assurez-vous d'avoir importé votre module Wasm dans un dépôt Artifact Registry. Pour en savoir plus, consultez Préparer le code du plug-in.

Pour déployer une ressource GCPWasmPlugin, procédez comme suit :

  1. Enregistrez le manifeste suivant sous le nom wasm-plugin.yaml :

    kind: GCPWasmPlugin
apiVersion: networking.gke.io/v1
metadata:
  name: gcp-wasm-plugin
spec:
  versions:
  - name: wasm-plugin-version
    description: "Test wasm plugin version"
    image: "us-docker.pkg.dev/service-extensions-samples/plugins/local-reply:main"
    weight: 1000000
  logConfig:
    enabled: true
    # Configures the sampling rate of activity logs.
    # The value of the field must be in range [0, 1e6].
    sampleRate: 1000000
    # Specifies the lowest level of logs that are exported to Cloud Logging.
    minLogLevel: INFO

    Veuillez noter les points suivants :

    • spec.versions.name : le nom de la version doit être unique dans la ressource GCPWasmPlugin. Vous pouvez lister jusqu'à 10 versions, mais une seule d'entre elles doit avoir une pondération non nulle.
    • spec.versions.image : fait référence à l'image contenant le code du plug-in stocké dans Artifact Registry.
    • spec.versions.weight : spécifie la pondération de la version du plug-in. La pondération doit être un nombre compris entre 0 et 1 000 000 (inclus).
    • spec.logConfig : indique s'il faut activer Cloud Logging pour ce plug-in. Si la valeur n'est pas spécifiée, Cloud Logging est désactivé par défaut.
    • spec.logConfig.sampleRate : configure le taux d'échantillonnage des journaux d'activité. Le taux doit être un nombre compris entre 0 et 1 000 000 (inclus). Si elle n'est pas spécifiée lorsque Cloud Logging est activé, la valeur par défaut est 1,000,000 (100 % des requêtes sont enregistrées).
    • spec.logConfig.minLogLevel : spécifie le niveau de journaux le plus bas qui est exporté vers Cloud Logging. Si la valeur n'est pas spécifiée lorsque Cloud Logging est activé, le champ est défini sur INFO par défaut.

  2. Appliquez le fichier manifeste wasm-plugin.yaml :

    kubectl apply -f wasm-plugin.yaml

  3. Vérifiez que le plug-in a été déployé :

    kubectl describe gcpwasmplugins.networking.gke.io gcp-wasm-plugin

    Le résultat ressemble à ce qui suit :

    Name:         gcp-wasm-plugin
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPWasmPlugin
Metadata:
  Creation Timestamp:  2025-08-08T19:54:18Z
  Generation:          1
  Resource Version:    44578
  UID:                 549a12c7-91d1-43ad-a406-d6157a799b79
Spec:
  Log Config:
    Enabled: true
    Min Log Level: INFO
    Sample Rate: 1000000
  Versions:
    Description:  Test wasm plugin version
    Image:        us-docker.pkg.dev/service-extensions-samples/plugins/local-reply:main
    Name:         wasm-plugin-version
    Weight:       1000000
  Events:     <none>

Configurer les extensions de service

Pour ajouter une logique personnalisée à votre équilibreur de charge d'application externe global, vous pouvez configurer un GCPTrafficExtension pour utiliser un GCPWasmPlugin. Vous pouvez utiliser un GCPTrafficExtension pour profiter des fonctionnalités avancées de gestion du trafic dans votre environnement Google Cloud . Vous pouvez configurer cette extension sur les équilibreurs de charge d'application externes globaux.

Pour configurer un GCPTrafficExtension afin qu'il utilise un GCPWasmPlugin, procédez comme suit :

  1. Définissez le GCPTrafficExtension.

    1. Enregistrez la configuration GCPTrafficExtension sous le nom gcp-traffic-extension-with-plugin.yaml :

      kind: GCPTrafficExtension
apiVersion: networking.gke.io/v1
metadata:
  name: gcp-traffic-extension-with-plugin
  namespace: default
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: GATEWAY_NAME
  extensionChains:
  - name: chain1
    matchCondition:
      celExpressions:
      - celMatcher: request.path.contains("serviceextensions")
    extensions:
    - name: ext1
      supportedEvents:
      - RequestHeaders
      - ResponseHeaders
      backendRef:
        group: "networking.gke.io"
        kind: GCPWasmPlugin
        name: gcp-wasm-plugin

      Remplacez GATEWAY_NAME par le nom de votre passerelle, par exemple global-external-http.

    2. Appliquez l'exemple de fichier manifeste à votre cluster :

      kubectl apply -f gcp-traffic-extension-with-plugin.yaml

  2. Vérifiez la configuration de GCPTrafficExtension et sa liaison à la passerelle.

    1. Vérifiez le déploiement GCPTrafficExtension :

      kubectl describe gcptrafficextensions.networking.gke.io gcp-traffic-extension-with-plugin

      Le résultat ressemble à ce qui suit :

      Name:         gcp-traffic-extension-with-plugin
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPTrafficExtension
Metadata:
  Creation Timestamp:  2025-03-02T17:12:30Z
  Generation:        1
  Resource Version:  31283253
  UID:               ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
Spec:
  Extension Chains:
    Extensions:
      Backend Ref:
        Group: networking.gke.io
        Kind: GCPWasmPlugin
        Name: gcp-wasm-plugin
      Name:       ext1
      Supported Events:
        RequestHeaders
        ResponseHeaders
    Match Condition:
      Cel Expressions:
        Cel Matcher: request.path.contains("serviceextensions")
    Name:  chain1
  Target Refs:
    Group: gateway.networking.k8s.io
    Kind: Gateway
    Name: GATEWAY_NAME
Events:  <none>

      Le résultat affiche les détails de l'GCPTrafficExtension nommé gcp-traffic-extension-with-plugin dans l'espace de noms par défaut. Il affiche le champ Spec, qui contient la définition du comportement de l'extension.

    2. Vérifiez la liaison de la passerelle :

      Vérifiez que GCPTrafficExtension est lié à la passerelle. L'exécution de cette commande peut prendre quelques minutes :

      kubectl describe gateway GATEWAY_NAME

      Le résultat ressemble à ce qui suit :

      Name:         GATEWAY_NAME
Namespace:    default
Labels:       <none>
Annotations:  networking.gke.io/addresses: /projects/922988411345/global/addresses/test-k18j-default-external-http-2jfqxrkgd0fm
              networking.gke.io/backend-services:
                /projects/922988411345/global/backendServices/test-k18j-default-gw-serve404-80-8zjp3d8cqfsu, /projects/922988411345/global/backendServices...
                networking.gke.io/certmap: store-example-com-map
                networking.gke.io/firewalls: /projects/922988411345/global/firewalls/test-k18j-l7-default-global
                networking.gke.io/forwarding-rules: /projects/922988411345/global/forwardingRules/test-k18j-default-external-http-wt1tl0cwi6zr
                networking.gke.io/health-checks:
                  /projects/922988411345/global/healthChecks/test-k18j-default-gw-serve404-80-8zjp3d8cqfsu, /projects/922988411345/global/healthChecks/test-...
                networking.gke.io/last-reconcile-time: 2025-08-08T20:27:35Z
                networking.gke.io/lb-route-extensions:
                networking.gke.io/lb-traffic-extensions:
                  projects/922988411345/locations/global/lbTrafficExtensions/test-k18j-default-external-http-0tdum40yts35
                networking.gke.io/ssl-certificates:
                networking.gke.io/target-http-proxies:
                networking.gke.io/target-https-proxies: /projects/922988411345/global/targetHttpsProxies/test-k18j-default-external-http-jy9mc97xb5yh
                networking.gke.io/url-maps: /projects/922988411345/global/urlMaps/test-k18j-default-external-http-jy9mc97xb5yh
                networking.gke.io/wasm-plugin-versions:
                  projects/922988411345/locations/global/wasmPlugins/test-k18j-default-gcp-wasm-plugin-itle20jj9nyk/versions/test-k18j-wasm-plugin-version-i...
                networking.gke.io/wasm-plugins: projects/922988411345/locations/global/wasmPlugins/test-k18j-default-gcp-wasm-plugin-itle20jj9nyk
API Version:  gateway.networking.k8s.io/v1
Kind:         Gateway
Metadata:
  Creation Timestamp:  2025-03-02T16:37:50Z
  Finalizers:
    gateway.finalizer.networking.gke.io
  Generation:        1
  Resource Version:  31284863
  UID:               fd512611-bad2-438e-abfd-5619474fbf31
Spec:
  Gateway Class Name:  gke-l7-global-external-managed
  Listeners:
    Allowed Routes:
      Namespaces:
        From:  Same
    Name:      https
    Port:      443
    Protocol:  HTTPS
...

      Le résultat affiche les annotations que GKE utilise pour stocker les liens entre la passerelle et les ressources Google Cloudsous-jacentes. Les annotations networking.gke.io/lb-traffic-extensions, networking.gke.io/wasm-plugin-versions et networking.gke.io/wasm-plugins confirment la liaison.

    3. Vérifiez l'état de l'extension :

      Vérifiez que l'état de GCPTrafficExtension est Programmed et que la raison est ProgrammingSucceeded. L'exécution de cette commande peut prendre quelques minutes.

      kubectl describe gcptrafficextensions.networking.gke.io gcp-traffic-extension-with-plugin

      Le résultat ressemble à ce qui suit :

      Name:         gcp-traffic-extension-with-plugin
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPTrafficExtension
Metadata:
  Creation Timestamp:  2025-08-08T20:08:09Z
  Generation:          1
  Resource Version:    56528
  UID:                 1389f790-9663-45ca-ac4e-a2c082f43359
Spec:
  Extension Chains:
    Extensions:
      Backend Ref:
        Group:  networking.gke.io
        Kind:   GCPWasmPlugin
        Name:   gcp-wasm-plugin
      Name:     ext1
      Supported Events:
        RequestHeaders
        ResponseHeaders
    Match Condition:
      Cel Expressions:
        Cel Matcher:  request.path.contains("serviceextensions")
    Name:             chain1
  Target Refs:
    Group:  gateway.networking.k8s.io
    Kind:   Gateway
    Name:   external-http
Status:
  Ancestors:
    Ancestor Ref:
      Group:      gateway.networking.k8s.io
      Kind:       Gateway
      Name:       external-http
      Namespace:  default
    Conditions:
      Last Transition Time:  2025-08-08T20:16:13Z
      Message:
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-08-08T20:16:13Z
      Message:
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
      Last Transition Time:  2025-08-08T20:16:13Z
      Message:
      Observed Generation:   1
      Reason:                ProgrammingSucceeded
      Status:                True
      Type:                  Programmed
    Controller Name:         networking.gke.io/gateway
Events:
  Type    Reason  Age                  From                   Message
  ----    ------  ----                 ----                   -------
  Normal  ADD     19m                  sc-gateway-controller  default/gcp-traffic-extension-with-plugin
  Normal  SYNC    3m25s (x4 over 11m)  sc-gateway-controller  Attachment of GCPTrafficExtension "default/gcp-traffic-extension-with-plugin" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil} was a success
  Normal  SYNC  3m25s (x4 over 11m)  sc-gateway-controller  All the object references were able to be resolved for GCPTrafficExtension "default/gcp-traffic-extension-with-plugin" bound to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil}
  Normal  SYNC  3m25s (x4 over 11m)  sc-gateway-controller  Programming of GCPTrafficExtension "default/gcp-traffic-extension-with-plugin" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil} was a success

    4. Vérifiez l'état du plug-in.

      Vérifiez que la ressource GCPWasmPlugin a l'état Programmed avec la raison ProgrammingSucceeded. L'exécution de cette commande peut prendre quelques minutes.

      kubectl describe gcpwasmplugins.networking.gke.io gcp-wasm-plugin

      Le résultat ressemble à ce qui suit :

      Name:         gcp-wasm-plugin
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPWasmPlugin
Metadata:
  Creation Timestamp:  2025-08-08T19:54:18Z
  Generation:          1
  Resource Version:    44578
  UID:                 549a12c7-91d1-43ad-a406-d6157a799b79
Spec:
  Log Config:
    Enabled: true
    Min Log Level: INFO
    Sample Rate: 1000000
  Versions:
    Description:  Test wasm plugin version
    Image:        us-docker.pkg.dev/service-extensions-samples/plugins/local-reply:main
    Name:         wasm-plugin-version
    Weight:       1000000
Status:
  Ancestors:
    Ancestor Ref:
      Group:      gateway.networking.k8s.io
      Kind:       Gateway
      Name:       external-http
      Namespace:  default
    Conditions:
      Last Transition Time:  2025-08-08T19:59:06Z
      Message:
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-08-08T19:59:06Z
      Message:
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
      Last Transition Time:  2025-08-08T19:59:06Z
      Message:
      Observed Generation:   1
      Reason:                ProgrammingSucceeded
      Status:                True
      Type:                  Programmed
    Controller Name:         networking.gke.io/gateway
Events:
  Type    Reason  Age                 From                   Message
  ----    ------  ----                ----                   -------
  Normal  ADD     31m                 sc-gateway-controller  default/gcp-wasm-plugin
  Normal  SYNC    2m1s (x7 over 26m)  sc-gateway-controller  Attachment of WasmPlugin "default/gcp-wasm-plugin" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil} was a success
  Normal  SYNC  2m1s (x7 over 26m)  sc-gateway-controller  All the object references were able to be resolved for WasmPlugin "default/gcp-wasm-plugin" bound to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil}
  Normal  SYNC  2m1s (x7 over 26m)  sc-gateway-controller  Programming of WasmPlugin "default/gcp-wasm-plugin" to AncestorRef {Group:       "gateway.networking.k8s.io",
Kind:        "Gateway",
Namespace:   "default",
Name:        "external-http",
SectionName: nil,
Port:        nil} was a success

  3. Envoyez du trafic vers votre application.

    Une fois votre passerelle, votre route et votre application déployées dans votre cluster, vous pouvez transmettre du trafic à votre application.

    1. Pour accéder à votre application, vous devez trouver l'adresse IP de votre passerelle.

      Dans votre terminal, utilisez la commande suivante :

      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"

      Remplacez GATEWAY_NAME par le nom de votre passerelle.

      Cette commande génère l'adresse IP de la passerelle. Dans les commandes suivantes, remplacez GATEWAY_IP_ADDRESS par l'adresse IP de la sortie.

    2. Testez la mise à jour du chemin en accédant à la version serviceextensions du service de magasin à l'adresse store.example.com/serviceextensions :

      curl https://store.example.com/serviceextensions --resolve store.example.com:443:GATEWAY_IP_ADDRESS --cacert cacert.pem -v

      Le résultat renvoie Hello World.

Gérer la ressource GCPWasmPlugin

Vous pouvez mettre à jour le CRD GCPWasmPlugin et surveiller le plug-in.

Mettre à jour le GCPWasmPlugin

Pour mettre à jour une ressource GCPWasmPlugin, procédez comme suit :

  1. Modifiez le fichier manifeste GCPWasmPlugin et suivez la procédure décrite dans Déployer un GCPWasmPlugin.

    Par exemple, pour avoir deux versions du plug-in, dont l'une diffuse du trafic et l'autre non, mettez à jour votre fichier wasm-plugin.yaml comme suit :

    kind: GCPWasmPlugin
apiVersion: networking.gke.io/v1
metadata:
  name: gcp-wasm-plugin
spec:
  versions:
  - name: wasm-plugin-version-v1
    description: "Serving Wasm Plugin version"
    image: "us-docker.pkg.dev/service-extensions-samples/plugins/local-reply:main"
    weight: 1000000
  - name: wasm-plugin-version-v2
    description: "Non serving Wasm Plugin version"
    image: "us-docker.pkg.dev/service-extensions-samples/plugins/local-reply:main"
    weight: 0
  logConfig:
    enabled: true
    sampleRate: 1000000
    minLogLevel: INFO

    Dans cet exemple, les éléments suivants s'appliquent :

    • wasm-plugin-version-v1 a une weight de 1000000, ce qui signifie qu'il diffuse tout le trafic.
    • wasm-plugin-version-v2 a une weight de 0, ce qui signifie qu'il ne diffuse aucun trafic.

  2. Pour vous assurer que la passerelle est à jour, exécutez la commande suivante. L'exécution de cette commande peut prendre quelques minutes :

    kubectl describe gateway GATEWAY_NAME

    Remplacez GATEWAY_NAME par le nom de votre passerelle.

Surveiller GCPWasmPlugin

Pour afficher les métriques de GCPWasmPlugin dans la console Google Cloud , consultez Surveillance du point de vue des plug-ins.

Lorsque vous atteignez l'étape du guide où vous devez sélectionner une valeur dans la liste Filtre de version du plug-in, recherchez le format prefix−WASM_PLUGIN_VERSION_NAME_FROM_FILE−suffix, où WASM_PLUGIN_VERSION_NAME_FROM_FILE est le nom de version spécifique que vous avez défini dans votre fichier de configuration GCPWasmPlugin.

Résoudre les problèmes liés aux extensions de trafic sur les passerelles

Cette section fournit des conseils de dépannage pour configurer les extensions de trafic sur les passerelles.

Passerelle introuvable

L'erreur suivante indique que la ressource Gateway spécifiée dans le champ targetRefs de la ressource GCPTrafficExtension ou GCPRoutingExtension n'existe pas :

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.gatewayRef: gateway "my-gateway" not found in namespace "default"

Pour résoudre ce problème, assurez-vous que la ressource Gateway spécifiée dans le champ targetRefs de la ressource GCPTrafficExtension ou GCPRoutingExtension existe dans l'espace de noms spécifié.

Service ou port de service introuvable

L'erreur suivante indique que le service ou le port de service spécifiés dans le champ backendRef de la ressource GCPTrafficExtension ou GCPRoutingExtension n'existent pas :

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.service: service "callout-service" not found in namespace "default"

Pour résoudre ce problème, assurez-vous que le service et le port de service spécifiés dans le champ backendRef de la ressource GCPTrafficExtension ou GCPRoutingExtension existent dans l'espace de noms spécifié.

Aucun point de terminaison réseau dans le NEG

L'erreur suivante indique qu'aucun point de terminaison réseau du NEG n'est associé au service spécifié dans le champ backendRef de la ressource GCPTrafficExtension ou GCPRoutingExtension :

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.service: no network endpoints found for service "callout-service"

Pour résoudre ce problème, assurez-vous que le service spécifié dans le champ backendRef de la ressource GCPTrafficExtension ou GCPRoutingExtension dispose de points de terminaison réseau.

Aucune réponse ou réponse avec une erreur lors de l'envoi de la demande

Si vous ne recevez pas de réponse ou si vous recevez une réponse contenant une erreur lorsque vous envoyez une requête, cela peut indiquer que le service d'appel ne fonctionne pas correctement.

Pour résoudre ce problème, vérifiez si les journaux du service d'appel contiennent des erreurs.

Code d'erreur 404 dans la charge utile JSON

L'erreur suivante indique que le service d'appel est introuvable ou ne répond pas à la requête :

{
  "error": {
    "code": 404,
    "message": "Requested entity was not found.",
    "status": "NOT_FOUND"
  }
}

Pour résoudre ce problème, assurez-vous que le service d'appel est en cours d'exécution, qu'il écoute sur le bon port et qu'il est correctement configuré dans la ressource GCPTrafficExtension ou GCPRoutingExtension.

Code d'erreur 500 dans la charge utile JSON

L'erreur suivante indique que le service d'appel rencontre une erreur interne du serveur :

{
  "error": {
    "code": 500,
    "message": "Internal server error.",
    "status": "INTERNAL"
  }
}

Pour résoudre ce problème, consultez les journaux du service d'appel afin d'identifier la cause de l'erreur de serveur interne.

GCPWasmPlugin n'existe pas

L'erreur suivante indique que la ressource GCPWasmPlugin n'existe pas dans votre projet :

Status:
  Ancestors:
    Ancestor Ref:
      Group:      gateway.networking.k8s.io
      Kind:       Gateway
      Name:       external-http
      Namespace:  default
    Conditions:
      Last Transition Time:  2025-03-06T16:27:57Z
      Message:
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-03-06T16:27:57Z
      Message:               error cause: invalid-wasm-plugin: GCPWasmPlugin default/my-wasm-plugin in GCPTrafficExtension default/my-gateway-plugin-extension does not exist
      Reason:                GCPWasmPluginNotFound
      Status:                False
      Type:                  ResolvedRefs
    Controller Name:         networking.gke.io/gateway

Pour résoudre ce problème, créez un GCPWasmPlugin correspondant dans le projet Google Cloud ou associez une extension à un GCPWasmPlugin existant.

Étapes suivantes