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 und Entwickler, die benutzerdefinierte Logik für die Traffic-Verwaltung mit Diensterweiterungen konfigurieren müssen.

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

Übersicht

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

Der GKE Gateway Controller unterstützt die folgenden Dienst-Extensions:

  • GCPRoutingExtension: Diese Erweiterung fügt Cloud Load Balancing benutzerdefinierte Logik hinzu, um das Traffic-Routing zu steuern.
  • GCPTrafficExtension: Diese Erweiterung fügt Cloud Load Balancing benutzerdefinierte Logik hinzu, um den Traffic zu ändern. Diese Logik wird auf 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 Dienstauswahl oder die Sicherheitsrichtlinien für Dienste.

Eine Erweiterung wird an ein Gateway angehängt und verweist auf eine Service, eine GCPWasmPlugin oder eine googleAPIServiceName.

  • Auf einen Dienst verweisen: In diesem Modell stellen Sie Ihre benutzerdefinierte Logik als separate Backend-Anwendung bereit, die als Kubernetes-Dienst verfügbar gemacht wird. Der Load-Balancer ruft diesen Dienst auf, um den 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. Sie verweisen auf einen Dienst mit GCPRoutingExtension oder GCPTrafficExtension.

  • Auf eine GCPWasmPlugin-Ressource verweisen: Bei leistungsstarken Anwendungsfällen können Sie benutzerdefinierte, vom Nutzer geschriebene Logik mithilfe eines WebAssembly-Moduls (Wasm) direkt in den Datenpfad desGoogle Cloud -Load-Balancers einfügen. Sie definieren eine GCPWasmPlugin-Ressource, die auf das Image Ihres Wasm-Moduls in Artifact Registry verweist. Diese Methode wird nur mit einem GCPTrafficExtension 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 einem GCPTrafficExtension 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.

Die `GCPRoutingExtension`-Ressource ist an ein Gateway angehängt und verweist auf einen Dienst. Die Erweiterung steuert das Traffic-Routing.
Abbildung: Funktionsweise von GCPRoutingExtension mit Gateways

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

Die Ressource `GCPTrafficExtension` ist 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.
Abbildung: Funktionsweise von GCPTrafficExtension mit Gateways

Hinweise

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 diesen Task 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 Google Cloud Service Extensions finden Sie unter Preise.

  • Die erforderlichen Rollen und Berechtigungen finden Sie unter Zugriffssteuerung für Dienst-Erweiterungen.

  • Machen Sie sich mit den Kontingenten und Limits unter Kontingente für Dienstextensions vertraut.

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

  • Einschränkungen für Service Extensions

Anforderungen für GKE Gateway Controller

  • Ihr Cluster muss GKE-Version 1.33 oder höher verwenden.
  • Damit Sie GCPWasmPlugin verwenden können, muss Ihr Cluster die GKE-Version 1.33.3 oder höher verwenden.
  • Für den 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 regionaler interner Application Load Balancer-Gateway sein. Wenn Sie eine GCPWasmPlugin-Ressource verwenden, müssen Sie nur ein globales externes Application Load Balancer-Gateway bereitstellen.
  • Sie benötigen eine konfigurierte HTTPRoute-Ressource.

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:

Kategorie Limits und Einschränkungen
Load Balancer Der Messwert GCPRoutingExtension wird für die folgenden Load-Balancer unterstützt:
  • Regionaler externer Application Load Balancer (gke-l7-regional-external-managed-Gateway-Klasse)
  • Regionaler interner Application Load Balancer(gke-l7-rilb Gateway-Klasse)
Die GCPTrafficExtension wird für die folgenden Load-Balancer unterstützt:
  • Regionaler externer Application Load Balancer (gke-l7-regional-external-managed-Gateway-Klasse)
  • Regionaler interner Application Load Balancer (gke-l7-rilb-Gateway-Klasse)
  • Globaler externer Application Load Balancer (gke-l7-global-external-managed Gateway-Klasse)
Erweiterungskette und Spezifikation
  • Für ein GCPTrafficExtension kann jede ExtensionChain maximal drei Extensions haben.
  • Bei einem GCPRoutingExtension ist jede ExtensionChain auf 1 Extension beschränkt.
  • Ein GCPTrafficExtensionSpec und ein GCPRoutingExtensionSpec können jeweils maximal 5 ExtensionChains haben.
Zeitliche Abstimmung und Abgleich
  • Das Zeitlimit für jede einzelne Nachricht im Stream innerhalb einer Erweiterung muss zwischen 10 und 10.000 Millisekunden liegen. Dieses Einsekundenlimit gilt für Routen- und Verkehrs-Erweiterungen.
  • Jedes MatchCondition in einem ExtensionChain ist auf maximal 10 CELExpressions begrenzt.
  • Der resultierende MatchCondition-String, der an GCE gesendet wird, darf maximal 512 Zeichen lang sein.
  • Der String CELMatcher in einem CELExpression darf maximal 512 Zeichen lang sein und muss einem bestimmten Muster entsprechen. Das Feld BackendRefs aus CELExpression wird nicht unterstützt.
Header und Metadaten
  • Die Liste ForwardHeaders in einem Extension kann maximal 50 HTTP-Headernamen enthalten.
  • Die Metadata-Karte in einer Extension kann maximal 16 Properties enthalten.
  • Schlüssel in der Metadata-Zuordnung müssen zwischen 1 und 63 Zeichen lang sein.
  • Werte in der Metadata-Zuordnung müssen zwischen 1 und 1.023 Zeichen lang sein.
Ereignis
  • Wenn requestBodySendMode für ein GCPRoutingExtension nicht festgelegt ist, kann die Liste supportedEvents nur RequestHeaders-Ereignisse enthalten.
  • Wenn requestBodySendMode für ein GCPRoutingExtension auf FullDuplexStreamed festgelegt ist, kann die Liste supportedEvents nur RequestHeaders-, RequestBody- und RequestTrailers-Ereignisse enthalten.
GCPTrafficExtension
  • Das Feld responseBodySendMode wird nur für GCPTrafficExtension unterstützt.
  • Das Feld googleAPIServiceName wird nur für GCPTrafficExtension unterstützt.
  • Das Feld GCPWasmPlugin wird nur für GCPTrafficExtension unterstützt.
GCPWasmPlugin
  • Die folgenden Felder werden in Erweiterungen mit GCPWasmPlugin nicht unterstützt:
    • authority
    • timeout
    • metadata
    • requestBodySendMode
    • responseBodySendMode
  • Erweiterungen mit GCPWasmPlugin unterstützen nur RequestHeaders-, RequestBody-, ResponseHeaders- und ResponseBody-Ereignisse.
googleAPIServiceName und backendRef Wenn Sie in einer Erweiterung auf einen Dienst verweisen, der backendRef verwendet, müssen Sie die folgenden Bedingungen erfüllen:
  • Es muss HTTP2 als appProtocol verwendet werden.
  • Muss sich im selben Namespace wie die Erweiterung und das Gateway befinden, auf das von der Erweiterung verwiesen wird.
  • IAP kann nicht verwendet werden.
  • Google Cloud Armor-Sicherheitsrichtlinien können nicht verwendet werden (Feld securityPolicy aus GCPBackendPolicyConfig.
  • Cloud CDN kann nicht verwendet werden.
  • Für ein Extension muss genau eines der beiden Elemente backendRef oder googleAPIServiceName festgelegt werden.
  • authority muss festgelegt werden, wenn backendRef festgelegt ist und kind Service ist.
  • authority darf nicht festgelegt werden, wenn googleAPIServiceName festgelegt ist.
  • Konfigurieren Sie requestBodySendMode für Erweiterungen nur mit backendRef und Service.
  • Konfigurieren Sie responseBodySendMode für Erweiterungen nur mit backendRef und Service.

Auf einen Dienst verweisen

In Diensterweiterungen können Sie auf einen Dienst verweisen, der die benutzerdefinierte Logik enthält, die der Load Balancer ausführen soll. Gateways haben standardmäßig keine Dienst-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-Diensterweiterungen in GKE. Das Gateway ruft diese Backend-Anwendungen basierend auf GCPTrafficExtension- oder GCPRoutingExtension-Konfigurationen auf, um den 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 Routing von Traffic.

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.

    Ersetzen Sie die folgenden Werte, um das TLS-Secret für Ihren Callout-Dienst zu erstellen:

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

    • Bereitstellung: 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: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. 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 eines 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 von GCPRoutingExtension und die 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 des GCPRoutingExtension mit dem Namen my-gateway-extension im Standardnamespace. 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

        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 liegendenGoogle Cloud -Ressourcen zu speichern. Die Anmerkung networking.gke.io/lb-route-extensions bestätigt die Bindung des Gateways an GCPRoutingExtension.

      2. Prüfen Sie den Erweiterungsstatus, indem Sie bestätigen, dass GCPRoutingExtension den Status Programmed mit dem Grund ProgrammingSucceeded hat. Dieser Befehl 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

Sie können ein GCPTrafficExtension verwenden, um erweiterte Funktionen zur Trafficverwaltung in Ihrer Google Cloud Umgebung zu nutzen. 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 gcp-traffic-extension.yaml-Beispieldatei:

      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

      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 von GCPTrafficExtension und die Bindung an das Gateway.

    1. GCPTrafficExtension-Bereitstellung 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 des GCPTrafficExtension mit dem Namen my-traffic-extension im Standardnamespace. Es enthält das Feld Spec, 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

      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 Verknüpfungen zwischen dem Gateway und den zugrunde liegenden Google Cloud -Ressourcen verwendet. Die Annotation networking.gke.io/lb-traffic-extensions bestätigt die Bindung.

    3. Prüfen Sie den Status der Erweiterung:

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

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

      kubectl describe gcptrafficextension my-traffic-extension

      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
}

Auf eine GCPWasmPlugin-Ressource verweisen

Sie können benutzerdefinierte Logik direkt in den Datenpfad des Load Balancers einfügen, indem Sie ein GCPWasmPlugin mit einem GCPTrafficExtension verwenden. Mit dieser Methode können Sie benutzerdefinierte Funktionen zur Traffic-Verwaltung bereitstellen, die als Wasm-Modul verpackt sind.

So konfigurieren Sie GKE Service Extensions:

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

  2. Service Extensions konfigurieren: Verwenden Sie GCPTrafficExtension für den globalen externen Application Load Balancer.

GCPWasmPlugin bereitstellen

Mit GCPWasmPlugin können Sie benutzerdefinierte, vom Nutzer geschriebene Logik direkt in den Datenpfad des Google Cloud 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 Plug-in-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 darf ein Gewicht ungleich null haben.
    • spec.versions.image: Verweist auf das Image mit dem Plugin-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 der Wert nicht angegeben wird, wenn Cloud Logging aktiviert ist, 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 wird, 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>

Diensterweiterungen konfigurieren

Wenn Sie Ihrem globalen externen Application Load Balancer benutzerdefinierte Logik hinzufügen möchten, können Sie eine GCPTrafficExtension für die Verwendung einer GCPWasmPlugin konfigurieren. Sie können ein GCPTrafficExtension verwenden, um erweiterte Funktionen zur Traffic-Verwaltung in Ihrer Google Cloud -Umgebung zu nutzen. Sie können diese Erweiterung für globale externe Application Load Balancer konfigurieren.

Führen Sie die folgenden Schritte aus, um ein 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 von GCPTrafficExtension und die Bindung an das Gateway.

    1. GCPTrafficExtension-Bereitstellung 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>

      Die Ausgabe enthält die Details des GCPTrafficExtension mit dem Namen gcp-traffic-extension-with-plugin im Standardnamespace. Es enthält das Feld Spec, 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

      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 Google Cloud-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 der 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 Plugin-Status.

      Prüfen Sie, ob die Ressource GCPWasmPlugin 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.

Ressource GCPWasmPlugin 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 werden keine Zugriffe verarbeitet.

  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 Google Cloud 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 Filter für Plugin-Version 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 der Konfigurationsdatei GCPWasmPlugin 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 oder GCPRoutingExtension 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 Ressource GCPTrafficExtension oder GCPRoutingExtension angegebene Gateway-Ressource im angegebenen Namespace vorhanden ist.

Dienst oder Dienstport nicht gefunden

Der folgende Fehler gibt an, dass der im Feld backendRef der Ressource GCPTrafficExtension oder GCPRoutingExtension 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 Ressource GCPTrafficExtension oder GCPRoutingExtension angegebene Dienst und Dienstport im angegebenen Namespace vorhanden sind.

Keine Netzwerkendpunkte in der NEG

Der folgende Fehler gibt an, dass keine Netzwerkendpunkte in der NEG mit dem Dienst verknüpft 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"

Achten Sie zur Behebung dieses Problems darauf, dass der im Feld backendRef der Ressource GCPTrafficExtension oder GCPRoutingExtension angegebene Dienst Netzwerkendpunkte hat.

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 zur Behebung dieses Problems, 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 existiert nicht

Der folgende Fehler weist darauf hin, dass die Ressource GCPWasmPlugin in Ihrem Projekt nicht 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 eine entsprechendeGCPWasmPlugin im Google Cloud Projekt oder verweisen Sie eine Erweiterung auf eine vorhandeneGCPWasmPlugin.

Nächste Schritte