GKE Gateway-Traffic mit Service Extensions anpassen

Auf dieser Seite wird beschrieben, wie Google Kubernetes Engine (GKE) Service Extensions verwendet, um benutzerdefinierte Logik in Cloud Load Balancing einzufügen.

Diese Seite richtet sich an GKE-Identitäts- und Kontoadministratoren sowie Entwickler, die benutzerdefinierte Logik für die Traffic-Verwaltung mit Service Extensions konfigurieren müssen.

Machen Sie sich vor dem Lesen dieser Seite mit den folgenden Themen vertraut:

• Grundlegende GKE-Netzwerkkonzepte
• GKE Gateway API
• GKE Gateway-Controller
• GKE GatewayClasses
• Übersicht über Service Extensions

Übersicht

GKE verwendet Service Extensions, um benutzerdefinierte Logik in Cloud Load Balancing einzufügen. Sie können Service Extensions für Aufgaben wie erweitertes Traffic-Splitting, benutzerdefinierte Authentifizierung oder Anfragelogging verwenden.

Der GKE Gateway Controller unterstützt die folgenden Service Extensions:

• GCPRoutingExtension: Diese Erweiterung fügt Cloud Load Balancing benutzerdefinierte Logik hinzu, um das Traffic-Routing zu steuern.
• GCPTrafficExtension: Mit dieser Erweiterung wird benutzerdefinierte Logik in Cloud Load Balancing eingefügt, um Traffic zu ändern. Diese Logik wird auf den Traffic angewendet, nachdem der Dienst ausgewählt wurde. Der Load-Balancer kann die Header und Nutzlasten von HTTP-Anfragen und ‑Antworten hinzufügen oder ändern. GCPTrafficExtension hat keine Auswirkungen auf die Auswahl von Diensten oder auf Sicherheitsrichtlinien für Dienste.
• GCPEdgeExtension: Mit dieser Erweiterung können Sie die Auswahl des Backend-Dienstes und die Cloud CDN-Cache-Schlüssel beeinflussen, indem Sie Anfrageheader ändern. Sie wird ausschließlich für globale externe verwaltete Load Balancer unterstützt.
• GCPAuthzExtension: Mit dieser Erweiterung können Sie Autorisierungsentscheidungen an eine benutzerdefinierte oder Drittanbieter-Autorisierungs-Engine (z. B. eine externe Web Application Firewall) oder Identity-Aware Proxy delegieren. Diese Erweiterung wird mit einer GCPAuthzPolicy-Ressource verwendet, die die Zugriffssteuerung für Traffic erzwingt, der in das Gateway gelangt, und festlegt, wann der Callout an die Erweiterung erfolgen soll.

Eine Erweiterung wird an ein Gateway angehängt. Bei einem Single-Cluster-Gateway verweist die Erweiterung auf eine Service-Ressource, eine GCPWasmPlugin-Ressource oder eine GoogleAPIServiceName-Ressource. Bei einem Multi-Cluster-Gateway verweist die Erweiterung auf eine ServiceImport-Ressource oder eine GoogleAPIServiceName-Ressource.

• Auf eine Service-Ressource oder eine ServiceImport-Ressource verweisen: In diesem Modell stellen Sie Ihre benutzerdefinierte Logik als separate Back-End-Anwendung bereit, die als Kubernetes-Dienst verfügbar gemacht wird. Der Load-Balancer ruft diesen Dienst auf, um Traffic zu verarbeiten. Dieser Ansatz ist vielseitig und ermöglicht es Ihnen, benutzerdefinierte Routinglogik zu implementieren oder Traffic zu manipulieren, z. B. Header zu ändern oder die Nutzlast zu prüfen.

• Auf eine GCPWasmPlugin-Ressource verweisen: Bei Anwendungsfällen mit hoher Leistung können Sie benutzerdefinierte, vom Nutzer geschriebene Logik direkt in den Datenpfad desCloud de Confiance by S3NS -Load-Balancers einfügen, indem Sie ein WebAssembly-Modul (Wasm) verwenden. Sie definieren eine GCPWasmPlugin-Ressource, die auf das Image Ihres Wasm-Moduls in Artifact Registry verweist. Diese Methode wird nur mit GCPTrafficExtension- und GCPEdgeExtension-Ressourcen und einem globalen externen Application Load Balancer verwendet.

• Auf einen Google API-Dienst verweisen: Sie können auch direkt auf einen Google API-Dienst verweisen, indem Sie das Feld googleAPIServiceName in einer GCPTrafficExtension oder GCPAuthzExtension verwenden.

Im folgenden Diagramm ist die GCPRoutingExtension-Ressource an ein Gateway angehängt und verweist auf mehrere Dienste. Die Erweiterung steuert das Traffic-Routing zu den Diensten.

Im folgenden Diagramm ist die GCPTrafficExtension-Ressource an ein Gateway angehängt und verweist auf einen Dienst, einen GoogleAPIServiceName oder ein GCPWasmPlugin. Die Erweiterung ändert die Header und Nutzlasten von Anfragen und Antworten.

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

• Aktivieren Sie die Google Kubernetes Engine API.
Google Kubernetes Engine API aktivieren
• Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem Befehl gcloud components update ab. In früheren gcloud CLI-Versionen werden die Befehle in diesem Dokument möglicherweise nicht unterstützt.

• Aktivieren Sie bei Bedarf die Compute Engine API, die Network Services API und die Model Armor API.

  Rufen Sie Zugriff auf APIs aktivieren auf und folgen Sie der Anleitung.

• Ausführliche Informationen zu den Preisen für Cloud de ConfianceService Extensions finden Sie unter Preise.

• Die erforderlichen Rollen und Berechtigungen finden Sie unter Zugriffssteuerung für Service Extensions.

• Machen Sie sich mit den Kontingenten und Limits unter Service Extensions-Kontingente vertraut.

• Wenn Sie Common Expression Language (CEL)-Matcher verwenden möchten, sehen Sie sich die unterstützten Attribute und Operatoren in der CEL-Matcher-Sprachreferenz an.

• Einschränkungen für Service Extensions

Anforderungen für GKE Gateway Controller

• Ihr Cluster muss die GKE-Version 1.33 oder höher verwenden.
• Damit Sie das GCPWasmPlugin verwenden können, muss Ihr Cluster die GKE-Version 1.33.3 oder höher verwenden.
• Zur Verwendung der ServiceImport-Ressource muss auf Ihrem Cluster die GKE-Version 1.34.3 oder höher ausgeführt werden.
• Sie benötigen eine konfigurierte Gateway-Ressource für ein internes Multi-Cluster-Gateway. Diese Ressource kann ein globaler externer Application Load Balancer, ein regionenübergreifender interner Application Load Balancer, ein regionaler externer Application Load Balancer oder ein regionaler interner Application Load Balancer-Gateway sein.
• In Ihrem Cluster muss die Gateway API aktiviert sein.
• Sie benötigen eine konfigurierte Gateway-Ressource. Diese Ressource kann ein globaler externer Application Load Balancer, ein regionaler externer Application Load Balancer oder ein regionales internes Application Load Balancer-Gateway sein. Wenn Sie eine GCPWasmPlugin-Ressource verwenden, müssen Sie nur ein globales externes Application Load Balancer-Gateway bereitstellen.
• Sie müssen eine HTTPRoute-Ressource konfiguriert haben.

Limits und Einschränkungen

In der folgenden Tabelle sind die Einschränkungen aufgeführt, die mit der Konfiguration von Gateway Service Extensions in GKE verbunden sind:

Auf einen Dienst verweisen

In Service Extensions können Sie auf einen Dienst verweisen, der die benutzerdefinierte Logik hostet, die der Load Balancer ausführen soll. Gateways haben standardmäßig keine Service Extensions.

So konfigurieren Sie GKE Service Extensions:

1. Backend-Callout-Dienst bereitstellen: Erstellen Sie einen Kubernetes-Dienst, der den Backend-Dienst für die Ausführung benutzerdefinierter Logik darstellt. Der Load-Balancer ruft diesen Dienst auf.

2. Diensterweiterungen konfigurieren: Verwenden Sie die entsprechende Erweiterung basierend auf Ihrem Load-Balancer-Typ.

   1. GCPRoutingExtension für regionale Gateways: Verwenden Sie diese Erweiterung für regionale externe Application Load Balancer und regionale interne Application Load Balancer, um benutzerdefinierte Routinglogik innerhalb der Region zu implementieren.

   2. GCPTrafficExtension für globale externe, regionale externe und interne Gateways: Verwenden Sie diese Erweiterung für globale externe Application Load Balancer, regionale externe Application Load Balancer und regionale interne Application Load Balancer, um Traffic-Manipulationen wie Header-Änderungen oder Nutzlastprüfungen für verschiedene Load-Balancer-Typen durchzuführen.

Backend-Callout-Dienst bereitstellen

Ein Callout-Dienst implementiert benutzerdefinierte Logik für Gateway Service Extensions in GKE. Das Gateway ruft diese Backend-Anwendungen basierend auf GCPTrafficExtension- oder GCPRoutingExtension-Konfigurationen auf, um Traffic zu ändern oder weiterzuleiten.

Sie stellen einen Callout-Dienst bereit, um Ihrem Gateway benutzerdefinierte Logik hinzuzufügen. Dieser separate Dienst übernimmt die benutzerdefinierte Verarbeitung, z. B. die Bearbeitung von Headern, die Transformation von Nutzlasten oder das Traffic-Routing.

So stellen Sie einen Dienst bereit, der als Callout für Ihr Gateway fungieren kann:

1. (Optional) Secret für TLS erstellen: Mit diesem Befehl wird ein Kubernetes-Secret vom Typ „TLS“ erstellt, das Ihr TLS-Zertifikat und Ihren privaten Schlüssel enthält.

   So erstellen Sie das TLS-Secret für Ihren Callout-Dienst:

   • SECRET_NAME: der Secret-Name für Ihren Callout-Dienst
   • path-to-cert: die Dateipfade zu Ihrem Zertifikat
   • path-to-key: die Dateipfade zu Ihrem Schlüssel

2. Führen Sie den folgenden Befehl aus, um zu prüfen, ob das Secret hinzugefügt wurde:

   kubectl get secrets SECRET_NAME
   

   Ersetzen Sie SECRET_NAME durch den Secret-Namen für Ihren Callout-Dienst.

   Die Ausgabe sollte in etwa so aussehen:

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

3. Deployment- und Dienstressourcen definieren

   Sie müssen Folgendes definieren:

   • Deployment: zum Verwalten der Anwendungs-Pods, die die benutzerdefinierte Logik für Ihre Service Extensions enthalten.
   • Service: Damit werden die Anwendungs-Pods, die vom Deployment verwaltet werden, als Netzwerkdienst verfügbar gemacht.

   1. Erstellen Sie ein Beispielmanifest extension-service-app.yaml mit Deployment- und Dienstdefinitionen:

      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:public-image-e42d951
              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_PATH
                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
      

      Ersetzen Sie Folgendes:

      • POD_NAME: der Name Ihres Pods.
      • SECRET_NAME: der Secret-Name für Ihren Callout-Dienst.
      • TLS_SERVER_CERT_PATH: Der Pfad zum TLS-Serverzertifikat im Pod.
      • TLS_SERVER_PRIVKEY: Der Pfad zum privaten TLS-Serverschlüssel im Pod.

   2. Wenden Sie das extension-service-app.yaml-Manifest an:

      kubectl apply -f extension-service-app.yaml
      

4. Konfiguration überprüfen:

   1. Prüfen Sie, ob die Anwendung bereitgestellt wurde:

      kubectl get pod --selector app=store
      

      Nachdem die Anwendung ausgeführt wurde, sieht die Ausgabe in etwa so aus:

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

   2. Prüfen Sie, ob der Dienst bereitgestellt wurde:

      kubectl get service extension-service
      

      Die Ausgabe sieht in etwa so aus; sie zeigt einen Dienst für jede Store-Bereitstellung:

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

Diensterweiterungen konfigurieren

Sie können entweder eine GCPRoutingExtension oder eine GCPTrafficExtension konfigurieren, um den Trafficfluss anzupassen.

GCPRoutingExtension für regionale Gateways konfigurieren

Sie können den Traffic mithilfe einer GCPRoutingExtension umleiten. Wenn Sie eine GCPRoutingExtension konfigurieren möchten, aktualisieren Sie die HTTPRoute, um die Anfragen für den Host service-extensions.com anzugeben.

1. HTTPRoute aktualisieren Ändern Sie Ihre HTTPRoute so, dass sie Hostnamen oder Pfade enthält, die die Routing-Erweiterung auslösen.

   1. Speichern Sie das folgende Beispielmanifest als Datei 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
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

   2. Wenden Sie das store-route.yaml-Manifest an:

      kubectl apply -f store-route.yaml
      

2. Definieren Sie die GCPRoutingExtension.

   1. Speichern Sie die GCPRoutingExtension-Konfiguration in der Beispieldatei 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
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

   2. Wenden Sie das Beispielmanifest auf Ihren Cluster an:

      kubectl apply -f gcp-routing-extension.yaml
      

3. Prüfen Sie die Konfiguration der GCPRoutingExtension und ihre Bindung an das Gateway.

   1. GCPRoutingExtension-Bereitstellung prüfen:

      kubectl describe gcproutingextension my-gateway-extension
      

      Die Ausgabe sieht etwa so aus:

      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>
      

      Die Ausgabe enthält die Details der GCPRoutingExtension mit dem Namen my-gateway-extension im Standard-Namespace. Die Ausgabe enthält das Feld Spec, das die Definition des Verhaltens der Erweiterung enthält.

   2. Gateway-Bindung prüfen:

      1. Prüfen Sie, ob die GCPRoutingExtension an das Gateway gebunden ist. Dies kann einige Minuten dauern:

         kubectl describe gateway GATEWAY_NAME
         

         Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

         Die Ausgabe sieht etwa so aus:

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

         Die Ausgabe zeigt die Annotationen, die GKE verwendet, um die Verknüpfungen zwischen dem Gateway und den zugrunde liegendenCloud de Confiance -Ressourcen zu speichern. Die Anmerkung networking.gke.io/lb-route-extensions bestätigt die Bindung des Gateways an die GCPRoutingExtension.

      2. Prüfen Sie den Erweiterungsstatus, indem Sie bestätigen, dass die GCPRoutingExtension den Status Programmed mit dem Grund ProgrammingSucceeded hat. Die Ausführung dieses Befehls kann einige Minuten dauern.

         kubectl describe gcproutingextension my-gateway-extension
         

         Die Ausgabe sieht etwa so aus:

         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
         

         Im Feld Status.Conditions wird eine Programmed-Bedingung mit Status: True und Reason: ProgrammingSucceeded angezeigt. Diese Informationen bestätigen, dass die Verlängerung erfolgreich angewendet wurde.

4. Senden Sie Traffic an Ihre Anwendung.

   Nachdem das Gateway, die Route und die Anwendung in Ihrem Cluster bereitgestellt wurden, können Sie den Traffic an Ihre Anwendung weiterleiten.

   1. Um auf Ihre Anwendung zuzugreifen, müssen Sie die IP-Adresse Ihres Gateways ermitteln.

      Verwenden Sie im Terminal den folgenden Befehl:

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

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Dieser Befehl gibt die IP-Adresse des Gateways aus. Ersetzen Sie in den nachfolgenden Befehlen GATEWAY_IP_ADDRESS durch die IP-Adresse aus der Ausgabe.

   2. Testen Sie die Pfadaktualisierung. Rufen Sie dazu die serviceextensions-Version des Speicherdienstes unter store.example.com/serviceextensions auf:

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

      Die Ausgabe sieht etwa so aus:

      {
      "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"
      }
      

GCPTrafficExtension konfigurieren

Mit einer GCPTrafficExtension können Sie erweiterte Funktionen zur Traffic-Verwaltung in Ihrer Cloud de Confiance -Umgebung verwenden. Sie können diese Erweiterung für globale externe Application Load Balancer, regionale externe Application Load Balancer und regionale interne Application Load Balancer konfigurieren. Mit GCPTrafficExtension können Sie benutzerdefinierte HTTP-Anfrage- und ‑Antwortlogik, komplexes Routing, Transformationen und Sicherheitsrichtlinien implementieren.

1. HTTPRoute aktualisieren Ändern Sie Ihre HTTPRoute so, dass sie Hostnamen oder Pfade enthält, die die Traffic-Erweiterung auslösen.

   1. Speichern Sie das folgende Beispielmanifest als Datei 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
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways, z. B. internal-http, external-http oder global-external-http.

   2. Wenden Sie das store-route.yaml-Manifest auf Ihren Cluster an:

      kubectl apply -f store-route.yaml
      

2. Definieren Sie die GCPTrafficExtension.

   1. Speichern Sie die GCPTrafficExtension-Konfiguration in der Beispieldatei 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
          supportedEvents:
            - RequestHeaders
            - RequestBody
            - ResponseHeaders
            - ResponseBody
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways, z. B. internal-http, external-http oder global-external-http.

   2. Wenden Sie das Beispielmanifest auf Ihren Cluster an:

      kubectl apply -f gcp-traffic-extension.yaml
      

3. Prüfen Sie die Konfiguration der GCPTrafficExtension und ihre Bindung an das Gateway.

   1. Bereitstellung von GCPTrafficExtension prüfen:

      kubectl describe gcptrafficextension my-traffic-extension
      

      Die Ausgabe sieht etwa so aus:

      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>
      

      Die Ausgabe enthält die Details der GCPTrafficExtension mit dem Namen my-traffic-extension im Standard-Namespace. Es enthält das Feld Spec, in dem definiert wird, wie sich die Erweiterung verhalten soll.

   2. Gateway-Bindung prüfen:

      Prüfen Sie, ob die GCPTrafficExtension an das Gateway gebunden ist. Die Ausführung dieses Befehls kann einige Minuten dauern:

      kubectl describe gateway GATEWAY_NAME
      

      Die Ausgabe sieht etwa so aus:

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

      Die Ausgabe enthält die Annotationen, die GKE zum Speichern der Links zwischen dem Gateway und den zugrunde liegenden Cloud de Confiance -Ressourcen verwendet. Die Annotation networking.gke.io/lb-traffic-extensions bestätigt die Bindung.

   3. Prüfen Sie den Status der Erweiterung:

      Führen Sie den folgenden Befehl aus, um den Erweiterungsstatus von GCPTrafficExtension zu prüfen:

      kubectl describe gcptrafficextension my-traffic-extension
      

      Prüfen Sie, ob die GCPTrafficExtension den Status Programmed mit dem Grund ProgrammingSucceeded hat. Die Verarbeitung des Befehls kann einige Minuten dauern.

      Die Ausgabe der GCPTrafficExtension-Ressource sieht in etwa so aus:

      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
      

      Im Feld Status.Conditions wird eine Programmed-Bedingung mit Status: True und Reason: ProgrammingSucceeded angezeigt. Diese Informationen bestätigen, dass die Verlängerung erfolgreich angewendet wurde.

4. Senden Sie Traffic an Ihre Anwendung.

   Nachdem das Gateway, die Route und die Anwendung in Ihrem Cluster bereitgestellt wurden, können Sie den Traffic an Ihre Anwendung weiterleiten.

   1. Um auf Ihre Anwendung zuzugreifen, müssen Sie die IP-Adresse Ihres Gateways ermitteln.

      Verwenden Sie im Terminal den folgenden Befehl:

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

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Dieser Befehl gibt die IP-Adresse des Gateways aus. Ersetzen Sie in den nachfolgenden Befehlen GATEWAY_IP_ADDRESS durch die IP-Adresse aus der Ausgabe.

   2. Testen Sie die Pfadaktualisierung. Rufen Sie dazu die serviceextensions-Version des Speicherdienstes unter store.example.com/serviceextensions auf:

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

      Die Ausgabe sieht etwa so aus:

      {
      *   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
      }
      

GCPAuthzExtension-Ressource konfigurieren

Sie können eine GCPAuthzExtension mit einer GCPAuthzPolicy verwenden, um komplexe Autorisierungsentscheidungen zu erzwingen, indem Sie sie an einen externen Dienst oder Identity-Aware Proxy (IAP) delegieren.

1. Definieren Sie die GCPAuthzExtension:

   Sie können die GCPAuthzExtension so konfigurieren, dass sie entweder auf einen benutzerdefinierten Erweiterungsdienst oder auf IAP als Callout-Dienst verweist.

   • Option 1: Auf einen benutzerdefinierten Erweiterungsdienst verweisen

     1. Speichern Sie die GCPAuthzExtension-Konfiguration in der Beispieldatei gcp-authz-extension.yaml:

     apiVersion: networking.gke.io/v1
     kind: GCPAuthzExtension
     metadata:
       name: my-authz-ext
       namespace: default
     spec:
       backendRef:
         kind: Service
         name: "${authz-service}"
       forwardHeaders:
       - Authorization
       failOpen: false
       timeout: "0.1s"
       wireFormat: EXT_PROC_GRPC
     

     Im obigen Beispiel ist "${authz-service}" ein Erweiterungsdienst, der sich im selben Namespace wie GCPAuthzPolicy befinden muss.

     1. Wenden Sie das Manifest an:

     kubectl apply -f gcp-authz-extension.yaml
     

   • Option 2: IAP als benutzerdefinierten Callout-Dienst referenzieren

     Sie können IAP auch als benutzerdefinierten Callout-Dienst konfigurieren, indem Sie iap.googleapis.com im Feld googleAPIServiceName angeben:

     1. Speichern Sie die GCPAuthzExtension-Konfiguration in der Beispieldatei authz-extension-iap.yaml:

     apiVersion: networking.gke.io/v1
     kind: GCPAuthzExtension
     metadata:
       name: my-authz-ext-iap
       namespace: default
     spec:
       googleAPIServiceName: iap.googleapis.com
       timeout: 50ms
       failOpen: false
     

     1. Wenden Sie das Manifest an:

     kubectl apply -f authz-extension-iap.yaml
     

2. Definieren Sie die GCPAuthzPolicy:

   Die GCPAuthzPolicy ist auf das Gateway ausgerichtet und gibt die Aktion an, die für übereinstimmenden Traffic ausgeführt werden soll:

   • CUSTOM-Autorisierungsrichtlinie einrichten:

     Mit der Aktion CUSTOM wird die Autorisierungsentscheidung an die Erweiterung delegiert, die Sie im vorherigen Schritt erstellt haben.

     1. Speichern Sie das folgende Manifest unter gcp-authz-policy.yaml:

        apiVersion: networking.gke.io/v1
        kind: GCPAuthzPolicy
        metadata:
          name: my-gateway-authz
          namespace: default
        spec:
          enforcementLevel: L7
          targetRefs:
          - group: gateway.networking.k8s.io
            kind: Gateway
            name: "GATEWAY_NAME"
          rules:
          - from:
              sources:
              - principals:
                - principal_selector: CLIENT_CERT_URI_SANS
                  principal:
                    exact: "spiffee://cluster.local/ns1/pod1"
          - to:
              operations:
              - paths:
                - exact: "/api/secure-endpoint"
          action: CUSTOM
          customProvider:
            authzExtension:
              extensionRefs:
              - group: networking.gke.io
                kind: GCPAuthzExtension
                name: my-authz-ext
        

        Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

     2. Wenden Sie das Manifest an:

        kubectl apply -f gcp-authz-policy.yaml
        

Auf eine GCPWasmPlugin-Ressource verweisen

Sie können benutzerdefinierte Logik direkt in den Datenpfad des Load Balancers einschleusen, indem Sie ein GCPWasmPlugin mit einer GCPTrafficExtension oder GCPEdgeExtension verwenden. Mit dieser Methode können Sie benutzerdefinierte Funktionen zur Trafficverwaltung bereitstellen, die als Wasm-Modul verpackt sind.

So konfigurieren Sie GKE Service Extensions:

1. GCPWasmPlugin bereitstellen: Erstellen und stellen Sie eine GCPWasmPlugin CustomResourceDefinition (CRD) bereit, die den benutzerdefinierten Code für Ihr Wasm-Modul enthält. Sie können GCPWasmPlugin mit GCPTrafficExtension oder GCPEdgeExtension für die gke-l7-global-external-managed-GatewayClass verwenden.

2. Service Extensions konfigurieren: Konfigurieren Sie eine der folgenden Erweiterungen mit GCPWasmPlugin:

   • GCPTrafficExtension
   • GCPEdgeExtension

GCPWasmPlugin bereitstellen

Mit dem GCPWasmPlugin können Sie benutzerdefinierte, von Nutzern geschriebene Logik direkt in den Datenpfad des Cloud de Confiance Load Balancers einfügen. Die GCPWasmPlugin-Ressource verweist auf das Image des Wasm-Moduls in Artifact Registry, das dann vom Load Balancer ausgeführt wird.

Bevor Sie mit den folgenden Schritten fortfahren, müssen Sie Ihr Wasm-Modul in ein Artifact Registry-Repository hochgeladen haben. Weitere Informationen finden Sie unter Plugin-Code vorbereiten.

So stellen Sie eine GCPWasmPlugin-Ressource bereit:

1. Speichern Sie das folgende Manifest als 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
   

   Wichtige Hinweise:

   • spec.versions.name: Der Versionsname muss innerhalb der GCPWasmPlugin-Ressource eindeutig sein. Sie können bis zu 10 Versionen auflisten. Nur eine Version muss ein Gewicht ungleich null haben.
   • spec.versions.image: Verweist auf das Image mit dem Plug-in-Code, das in Artifact Registry gespeichert ist.
   • spec.versions.weight: Gibt das Gewicht der Plugin-Version an. Die Gewichtung muss eine Zahl zwischen 0 und 1.000.000 (jeweils einschließlich) sein.
   • spec.logConfig: Gibt an, ob Cloud Logging für dieses Plug-in aktiviert werden soll. Wenn der Wert nicht angegeben ist, ist Cloud Logging standardmäßig deaktiviert.
   • spec.logConfig.sampleRate: Konfiguriert die Abtastrate von Aktivitätsprotokollen. Die Rate muss eine Zahl zwischen 0 und 1.000.000 (einschließlich) sein. Wenn Cloud Logging aktiviert ist und nichts angegeben wird, ist der Standardwert 1,000,000 (100% der Anfragen werden protokolliert).
   • spec.logConfig.minLogLevel: Gibt die niedrigste Ebene von Logs an, die in Cloud Logging exportiert werden. Wenn der Wert nicht angegeben ist, wenn Cloud Logging aktiviert ist, wird das Feld standardmäßig auf INFO gesetzt.

2. Wenden Sie das wasm-plugin.yaml-Manifest an:

   kubectl apply -f wasm-plugin.yaml
   

3. Prüfen Sie, ob das Plug-in bereitgestellt wurde:

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

   Die Ausgabe sieht etwa so aus:

   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>
   

GCPTrafficExtension konfigurieren

Wenn Sie Ihrem globalen externen Application Load Balancer benutzerdefinierte Logik hinzufügen möchten, können Sie eine GCPTrafficExtension so konfigurieren, dass ein GCPWasmPlugin verwendet wird. Mit einer GCPTrafficExtension können Sie erweiterte Funktionen zur Traffic-Verwaltung in Ihrer Cloud de Confiance -Umgebung nutzen. Sie können diese Erweiterung für globale externe Application Load Balancer konfigurieren.

Führen Sie die folgenden Schritte aus, um eine GCPTrafficExtension für die Verwendung eines GCPWasmPlugin zu konfigurieren:

1. Definieren Sie die GCPTrafficExtension.

   1. Speichern Sie die GCPTrafficExtension-Konfiguration als 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
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways, z. B. global-external-http.

   2. Wenden Sie das Beispielmanifest auf Ihren Cluster an:

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

2. Prüfen Sie die Konfiguration der GCPTrafficExtension und ihre Bindung an das Gateway.

   1. Bereitstellung von GCPTrafficExtension prüfen:

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

      Die Ausgabe sieht etwa so aus:

      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>
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Die Ausgabe enthält die Details der GCPTrafficExtension mit dem Namen gcp-traffic-extension-with-plugin im Standard-Namespace. Es wird das Feld Spec angezeigt, das die Definition des Verhaltens der Erweiterung enthält.

   2. Gateway-Bindung prüfen:

      Prüfen Sie, ob die GCPTrafficExtension an das Gateway gebunden ist. Die Ausführung dieses Befehls kann einige Minuten dauern:

      kubectl describe gateway GATEWAY_NAME
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Die Ausgabe sieht etwa so aus:

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

      Die Ausgabe zeigt die Annotationen, die GKE zum Speichern der Links zwischen dem Gateway und den zugrunde liegenden Cloud de Confiance-Ressourcen verwendet. Die Annotationen networking.gke.io/lb-traffic-extensions, networking.gke.io/wasm-plugin-versions und networking.gke.io/wasm-plugins bestätigen die Bindung.

   3. Prüfen Sie den Status der Erweiterung:

      Prüfen Sie, ob die GCPTrafficExtension den Status Programmed mit dem Grund ProgrammingSucceeded hat. Die Verarbeitung des Befehls kann einige Minuten dauern.

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

      Die Ausgabe sieht etwa so aus:

      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. Prüfen Sie den Status des Plug-ins.

      Prüfen Sie, ob die GCPWasmPlugin-Ressource den Status Programmed mit dem Grund ProgrammingSucceeded hat. Die Verarbeitung des Befehls kann einige Minuten dauern.

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

      Die Ausgabe sieht etwa so aus:

      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. Senden Sie Traffic an Ihre Anwendung.

   Nachdem das Gateway, die Route und die Anwendung in Ihrem Cluster bereitgestellt wurden, können Sie den Traffic an Ihre Anwendung weiterleiten.

   1. Um auf Ihre Anwendung zuzugreifen, müssen Sie die IP-Adresse Ihres Gateways ermitteln.

      Verwenden Sie im Terminal den folgenden Befehl:

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

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Dieser Befehl gibt die IP-Adresse des Gateways aus. Ersetzen Sie in den nachfolgenden Befehlen GATEWAY_IP_ADDRESS durch die IP-Adresse aus der Ausgabe.

   2. Testen Sie die Pfadaktualisierung. Rufen Sie dazu die serviceextensions-Version des Speicherdienstes unter store.example.com/serviceextensions auf:

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

      Die Ausgabe gibt Hello World zurück.

GCPEdgeExtension mit GCPWasmPlugin konfigurieren

Wenn Sie Ihrem globalen externen Application Load Balancer mithilfe eines WebAssembly-Moduls (Wasm) benutzerdefinierte Logik hinzufügen möchten, konfigurieren Sie eine GCPEdgeExtension, die auf das GCPWasmPlugin verweist.

1. Speichern Sie das folgende GCPEdgeExtension-Manifest als gcp-edge-extension-with-plugin.yaml:

   kind: GCPEdgeExtension
   apiVersion: networking.gke.io/v1
   metadata:
     name: gcp-edge-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.startsWith("/serviceextensions")
       extensions:
       - name: ext1
         supportedEvents:
         - RequestHeaders
         backendRef:
           group: "networking.gke.io"
           kind: GCPWasmPlugin
           name: gcp-wasm-plugin
   

   Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

2. Wenden Sie das Manifest auf Ihren Cluster an:

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

3. Prüfen Sie die Konfiguration der GCPEdgeExtension und ihre Bindung an das Gateway:

   1. Prüfen Sie den Status der Erweiterung:

      Führen Sie den folgenden Befehl aus, um den Erweiterungsstatus von GCPEdgeExtension zu prüfen:

      kubectl describe gcpedgeextensions.networking.gke.io gcp-edge-extension-with-plugin
      

      Prüfen Sie, ob die GCPEdgeExtension den Status Programmed mit dem Grund ProgrammingSucceeded hat. Die Verarbeitung dieses Befehls kann einige Minuten dauern.

   2. Gateway-Bindung prüfen:

      Führen Sie dazu diesen Befehl aus:

      kubectl describe gateway GATEWAY_NAME
      

      Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

      Prüfen Sie, ob die GCPEdgeExtension an das Gateway gebunden ist. Die Ausführung dieses Befehls kann einige Minuten dauern. Die Ausgabe enthält die Annotation networking.gke.io/lb-edge-extensions, die die Verbindung zwischen dem Gateway und der Edge-Erweiterung bestätigt.

Traffic an die Erweiterung senden

Nachdem Sie Ihr Gateway und Ihre GCPEdgeExtension bereitgestellt haben, testen Sie die Routinglogik, indem Sie Traffic an Ihre Anwendung senden.

1. Rufen Sie die IP-Adresse Ihres Gateways ab, um auf Ihre Anwendung zuzugreifen:

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

   Die Ausgabe ist die IP-Adresse des Gateways. Ersetzen Sie in den folgenden Befehlen GATEWAY_IP_ADDRESS durch die IP-Adresse aus der Ausgabe.

2. Senden Sie eine Anfrage an die Basis-URL:

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

   Das Gateway leitet die Anfrage an den Standarddienst weiter, z. B. store-v1.

3. Senden Sie eine Anfrage an den in Ihrem „celMatcher“ angegebenen Pfad, z. B. /serviceextensions:

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

   Die Erweiterung löst das Wasm-Plug-in aus, das die Anfrage an den sekundären Dienst weiterleitet, z. B. store-v2.

GCPWasmPlugin-Ressource verwalten

Sie können die GCPWasmPlugin-CRD aktualisieren und das Plug-in überwachen.

GCPWasmPlugin aktualisieren

So aktualisieren Sie eine GCPWasmPlugin-Ressource:

1. Nehmen Sie die Änderung in Ihrem GCPWasmPlugin-Manifest vor und folgen Sie der Anleitung unter GCPWasmPlugin bereitstellen.

   Wenn Sie beispielsweise zwei Versionen des Plug-ins haben möchten, wobei eine Version Traffic verarbeitet und die andere nicht, aktualisieren Sie die Datei wasm-plugin.yaml so:

   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
   

   In diesem Beispiel gilt Folgendes:

   • wasm-plugin-version-v1 hat eine weight von 1000000, d. h., es wird der gesamte Traffic bedient.
   • wasm-plugin-version-v2 hat einen weight von 0, d. h., es wird kein Traffic bereitgestellt.

2. Führen Sie den folgenden Befehl aus, um sicherzustellen, dass das Gateway aktualisiert wird. Die Ausführung dieses Befehls kann einige Minuten dauern:

   kubectl describe gateway GATEWAY_NAME
   

   Ersetzen Sie GATEWAY_NAME durch den Namen Ihres Gateways.

GCPWasmPlugin überwachen

Informationen zum Aufrufen von Messwerten für GCPWasmPlugin in der Cloud de Confiance Console finden Sie unter Monitoring aus der Perspektive von Plug-ins.

Wenn Sie den Schritt in der Anleitung erreichen, in dem Sie einen Wert aus der Liste Plugin-Versionsfilter auswählen müssen, suchen Sie nach dem Format prefix−WASM_PLUGIN_VERSION_NAME_FROM_FILE−suffix, wobei WASM_PLUGIN_VERSION_NAME_FROM_FILE der spezifische Versionsname ist, den Sie in Ihrer GCPWasmPlugin-Konfigurationsdatei definiert haben.

Fehlerbehebung bei Traffic-Erweiterungen auf Gateways

In diesem Abschnitt finden Sie Tipps zur Fehlerbehebung bei der Konfiguration von Traffic-Erweiterungen auf Gateways.

Gateway nicht gefunden

Der folgende Fehler weist darauf hin, dass die im Feld targetRefs der Ressource „GCPTrafficExtension“, „GCPRoutingExtension“ oder „GCPEdgeExtension“ angegebene Gateway-Ressource nicht vorhanden ist:

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

Achten Sie zur Behebung dieses Problems darauf, dass die im Feld targetRefs der GCPTrafficExtension- oder GCPRoutingExtension-Ressource angegebene Gateway-Ressource im angegebenen Namespace vorhanden ist.

Dienst oder Dienstport nicht gefunden

Der folgende Fehler weist darauf hin, dass der im Feld backendRef der GCPTrafficExtension- oder GCPRoutingExtension-Ressource angegebene Dienst oder Dienstport nicht vorhanden ist:

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

Achten Sie zur Behebung dieses Problems darauf, dass der im Feld backendRef der GCPTrafficExtension- oder GCPRoutingExtension-Ressource angegebene Dienst und Dienstport im angegebenen Namespace vorhanden sind.

Keine Netzwerkendpunkte in der NEG

Der folgende Fehler weist darauf hin, dass keine Netzwerkendpunkte in der NEG dem Dienst zugeordnet sind, der im Feld backendRef der Ressource „GCPTrafficExtension“ oder „GCPRoutingExtension“ angegeben ist:

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

Prüfen Sie, ob der Dienst, der im Feld backendRef der GCPTrafficExtension- oder GCPRoutingExtension-Ressource angegeben ist, Netzwerkendpunkte hat, um dieses Problem zu beheben.

Keine Antwort oder Antwort mit einem Fehler beim Senden der Anfrage

Wenn Sie keine Antwort oder eine Antwort mit einem Fehler erhalten, wenn Sie eine Anfrage senden, kann dies darauf hindeuten, dass der Callout-Dienst nicht richtig funktioniert.

Prüfen Sie die Logs des Callout-Dienstes auf Fehler, um dieses Problem zu beheben.

Fehlercode 404 in der JSON-Nutzlast

Der folgende Fehler weist darauf hin, dass der Callout-Dienst nicht gefunden wurde oder nicht auf die Anfrage reagiert:

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

Prüfen Sie, ob der Callout-Dienst ausgeführt wird, ob er den richtigen Port überwacht und ob der Dienst in der GCPTrafficExtension- oder GCPRoutingExtension-Ressource richtig konfiguriert ist.

Fehlercode 500 in der JSON-Nutzlast

Der folgende Fehler weist darauf hin, dass beim Callout-Dienst ein interner Serverfehler aufgetreten ist:

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

Prüfen Sie zur Behebung dieses Problems die Logs des Callout-Dienstes, um die Ursache des internen Serverfehlers zu ermitteln.

GCPWasmPlugin ist nicht vorhanden

Der folgende Fehler weist darauf hin, dass die GCPWasmPlugin-Ressource für Ihre GCPTrafficExtension oder GCPEdgeExtension nicht in Ihrem Projekt vorhanden ist:

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

Um dieses Problem zu beheben, erstellen Sie ein entsprechendes GCPWasmPlugin im Cloud de Confiance Projekt oder verweisen Sie eine Erweiterung auf ein vorhandenes GCPWasmPlugin.

Nächste Schritte

• Weitere Informationen zum GKE Inference Gateway
• LLM mit GKE Inference Gateway bereitstellen
• Beobachtbarkeitsmesswerte aufrufen