GKE Gateway-Traffic mithilfe von Diensterweiterungen anpassen

Auf dieser Seite wird beschrieben, wie in der Google Kubernetes Engine (GKE) Diensterweiterungen verwendet werden, um benutzerdefinierte Logik in das Cloud Load Balancing einzubinden.

Diese Seite richtet sich an GKE Identity- und Kontoadministratoren sowie Entwickler, die benutzerdefinierte Logik zur Verkehrsverwaltung mithilfe von Diensterweiterungen konfigurieren müssen.

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

Übersicht

In GKE werden Diensterweiterungen verwendet, um Cloud Load Balancing benutzerdefinierte Logik hinzuzufügen. Eine Erweiterung wird an eine Gateway angehängt und verweist auf eine Service oder GoogleAPIServiceName. GoogleAPIServiceName wird nur für GCPTrafficExtensions unterstützt.

Sie können HTTP-Header und Nutzlasten für Anfragen und Antworten ändern oder das Traffic-Routing steuern, ohne die Auswahl des Backend-Dienstes oder die Sicherheitsrichtlinien zu beeinflussen. Sie können Diensterweiterungen für Aufgaben wie erweiterte Traffic-Aufteilung, benutzerdefinierte Authentifizierung oder Anfrageprotokollierung verwenden.

Der GKE Gateway Controller unterstützt die folgenden Diensterweiterungen:

  • GCPRoutingExtension: Mit dieser Erweiterung wird Cloud Load Balancing benutzerdefinierte Logik hinzugefügt, um das Traffic-Routing zu steuern. Sie wird für regionale externe und regionale interne Application Load Balancer unterstützt.

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

  • GCPTrafficExtension: Mit dieser Erweiterung wird benutzerdefinierte Logik in das Cloud Load Balancing eingefügt. Damit kann ein Erweiterungsdienst die Header und Nutzlasten von Anfragen und Antworten ändern. Die GCPTrafficExtension hat keine Auswirkungen auf die Auswahl des Back-End-Dienstes oder die Sicherheitsrichtlinien des Back-End-Dienstes.

    Die Ressource „GCPTrafficExtension“ ist mit einem Gateway verknüpft und verweist auf einen Dienst oder einen „GoogleAPIServiceName“. Die Erweiterung ändert die Header und Nutzlasten von Anfragen und Antworten.
    Abbildung: Funktionsweise von „GCPTrafficExtension“ mit Gateways

Google Cloud Kompatibilität von Diensterweiterungen mit GatewayClasses

In der folgenden Tabelle wird die Kompatibilität von Google Cloud -Diensterweiterungen mit verschiedenen GatewayClasses beschrieben:

GatewayClass GCPRoutingExtension GCPTrafficExtension
gke-l7-rilb Unterstützt Unterstützt
gke-l7-regional-external-managed Unterstützt Unterstützt
gke-l7-global-external-managed Nicht unterstützt Unterstützt

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 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 gcloud components update ab.

Anforderungen für GKE Gateway Controller

Limits und Einschränkungen

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

Kategorie Limits und Einschränkungen
Load Balancer Die GCPRoutingExtension wird nur für regionale externe und regionale interne Application Load Balancer (gke-l7-regional-external-managed- und gke-l7-rilb-Gateway-Klassen) unterstützt und nicht von der gke-l7-global-external-managed-Gateway-Klasse.
Erweiterungskette und ‑spezifikation
  • Bei einem GCPTrafficExtension kann jeder ExtensionChain maximal drei Extensions haben.
  • Bei einer GCPRoutingExtension ist jede ExtensionChain auf eine Extension beschränkt.
  • Ein GCPTrafficExtensionSpec und ein GCPRoutingExtensionSpec können jeweils maximal 5 ExtensionChains haben.
Timing und Abgleich
  • Das Zeitlimit für jede einzelne Nachricht im Stream innerhalb einer Erweiterung muss zwischen 10 und 1.000 Millisekunden liegen. Dieses Limit von einer Sekunde gilt für Routen- und Verkehrserweiterungen.
  • Jede MatchCondition in einer ExtensionChain ist auf maximal 10 CELExpressions begrenzt.
  • Der resultierende MatchCondition-String, der an die GCE gesendet wird, ist auf 512 Zeichen begrenzt.
  • Der CELMatcher-String in einem CELExpression darf maximal 512 Zeichen lang sein und muss einem bestimmten Muster entsprechen. Das Feld BackendRefs von CELExpression wird nicht unterstützt.
Header und Metadaten
  • Die ForwardHeaders-Liste in einer Extension kann maximal 50 HTTP-Headernamen enthalten.
  • Die Metadata-Zuordnung in einer Extension kann maximal 16 Properties haben.
  • 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 für GCPRoutingExtension kein requestBodySendMode festgelegt ist, kann die supportedEvents-Liste nur RequestHeaders-Ereignisse enthalten.
  • Wenn für eine GCPRoutingExtension requestBodySendMode auf FullDuplexStreamed festgelegt ist, kann die supportedEvents-Liste 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.
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 verwenden.
  • Muss sich im selben Namespace wie die Erweiterung und das Gateway befinden, auf das die Erweiterung verweist.
  • IAP kann nicht verwendet werden.
  • Google Cloud Armor-Sicherheitsrichtlinien können nicht verwendet werden (securityPolicy-Feld aus GCPBackendPolicyConfig).
  • Cloud CDN kann nicht verwendet werden.
  • Für eine Extension muss genau eine der beiden Optionen backendRef oder googleAPIServiceName festgelegt werden.
  • authority muss festgelegt werden, wenn backendRef festgelegt ist.
  • authority muss festgelegt werden, wenn googleAPIServiceName festgelegt ist.
  • Konfigurieren Sie requestBodySendMode für Erweiterungen und verwenden Sie nur backendRef.
  • Konfigurieren Sie responseBodySendMode für Erweiterungen und verwenden Sie nur backendRef.

GKE-Diensterweiterungen konfigurieren

Sie können das Traffic-Routing anpassen, Anfrage- oder Antwortnutzlasten ändern und externe Dienste integrieren, indem Sie GKE-Diensterweiterungen konfigurieren. Gateways haben standardmäßig keine Diensterweiterungen.

So konfigurieren Sie GKE-Diensterweiterungen:

  1. Gateway bereitstellen: Wenn Sie eine GKE-Diensterweiterung konfigurieren möchten, müssen Sie zuerst ein Gateway bereitstellen, das den externen Traffic an Ihren Cluster weiterleitet. Dies kann ein globaler externer, ein regionaler externer oder ein regionales internes Application Load Balancer-Gateway sein.

    Weitere Informationen zum Bereitstellen von Gateways finden Sie unter Gateways bereitstellen.

  2. Backend-Aufrufdienst 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.

  3. Diensterweiterungen konfigurieren: Konfigurieren Sie die entsprechenden Diensterweiterungen basierend auf dem Load Balancer-Typ und den Anforderungen.

    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, regionale externe und regionale interne Application Load Balancer, um Traffic zu manipulieren, z. B. Header zu ändern oder Nutzlast zu prüfen, und zwar für verschiedene Load Balancer-Typen.

Backend-Aufrufdienst bereitstellen

Ein Zusatzdienst 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. Headermanipulation, Nutzlasttransformationen oder Traffic-Routing.

So stellen Sie einen Back-End-Dienst bereit, der als Callout für Ihr Gateway verwendet werden 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 zum Erstellen des TLS-Secrets für Ihren Callback-Dienst Folgendes:

    • SECRET_NAME: der geheime Name für Ihren Zusatzdienst
    • 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 geheimen Namen Ihres Dienstes für die Aufforderung.

    Die Ausgabe sollte in etwa so aussehen:

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

  3. Definieren Sie Deployment- und Dienstressourcen.

    Sie müssen Folgendes definieren:

    • Bereitstellung: Hiermit verwalten Sie die Anwendungs-Pods, die die benutzerdefinierte Logik für Ihre Diensterweiterungen enthalten.
    • Dienst: Hiermit können Sie die Anwendungs-Pods, die vom Deployment verwaltet werden, als Netzwerkdienst freigeben.

    1. Erstellen Sie ein Beispielmanifest extension-service-app.yaml mit Bereitstellungs- 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

      Nach dem Starten der Anwendung 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 service-extensions.com-Host anzugeben.

  1. Aktualisieren Sie HTTPRoute. Ändern Sie Ihre HTTPRoute so, dass sie Hostnamen oder Pfade enthält, die die Routingerweiterung auslösen.

    1. Speichern Sie das folgende Beispielmanifest als store-route.yaml-Datei:

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

        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 enthält die Anmerkungen, mit denen GKE die Verknüpfungen zwischen dem Gateway und den zugrunde liegendenGoogle Cloud -Ressourcen speichert. Die Anmerkung networking.gke.io/lb-route-extensions bestätigt die Bindung des Gateways an die GCPRoutingExtension.

      2. Prüfen Sie den Verlängerungsstatus. Dazu muss die GCPRoutingExtension den Status Reconciled mit dem Grund ReconciliationSucceeded haben. 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:                ReconciliationSucceeded
      Status:                True
      Type:                  Reconciled
    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 ist eine Reconciled-Bedingung mit Status: True und Reason: ReconciliationSucceeded zu sehen.

        „Ja“ und „Grund“: ReconciliationSucceeded. 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 in Ihrem 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 einem GCPTrafficExtension können Sie erweiterte Funktionen zur Trafficverwaltung in Ihrer Google Cloud Umgebung verwenden. Sie können diese Erweiterung für globale externe, regionale externe und regionale interne Application Load Balancer konfigurieren. Mit GCPTrafficExtension können Sie benutzerdefinierte Logik für Anfragen und Antworten, ausgefeilte Routing-, Transformations- und Sicherheitsrichtlinien implementieren.

  1. Aktualisieren Sie HTTPRoute. Ä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 store-route.yaml-Datei:

      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 Beispielgcp-traffic-extension.yaml-Datei:

      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 der GCPTrafficExtension und ihre 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 Standard-Namespace. Es zeigt das Feld Spec, das die Definition dafür enthält, 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 Anmerkungen, mit denen GKE die Verbindungen zwischen dem Gateway und den zugrunde liegenden Google Cloud Ressourcen speichert. Die networking.gke.io/lb-traffic-extensions-Anmerkung bestätigt die Bindung.

    3. Prüfen Sie den Status der Erweiterung:

      Prüfen Sie, ob der GCPTrafficExtension den Status Reconciled mit dem Grund ReconciliationSucceeded hat. Die Verarbeitung dieses Befehls kann einige Minuten dauern.

      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:    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:                ReconciliationSucceeded
      Status:                True
      Type:                  Reconciled
    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 ist eine Reconciled-Bedingung mit Status: True und Reason: ReconciliationSucceeded zu sehen. 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 in Ihrem 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
}

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 gibt an, dass die Gateway-Ressource, die im Feld targetRefs der Ressource GCPTrafficExtension oder GCPRoutingExtension angegeben ist, nicht existiert:

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

Um dieses Problem zu beheben, prüfen Sie, ob die Gateway-Ressource, die im Feld targetRefs der Ressource GCPTrafficExtension oder GCPRoutingExtension angegeben ist, im angegebenen Namespace vorhanden ist.

Dienst oder Dienstport nicht gefunden

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

Keine Netzwerkendpunkte in der NEG

Der folgende Fehler gibt an, dass der Dienst, der im Feld backendRef der Ressource GCPTrafficExtension oder GCPRoutingExtension angegeben ist, in der NEG mit keinem Netzwerkendpunkt verknüpft 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 Fehler beim Senden der Anfrage

Wenn Sie keine Antwort oder eine Antwort mit einem Fehler erhalten, wenn Sie eine Anfrage senden, funktioniert der Zusatzdienst möglicherweise nicht richtig.

Prüfen Sie zur Behebung dieses Problems die Protokolle des Zusatzdiensts auf Fehler.

Fehlercode 404 in der JSON-Nutzlast

Der folgende Fehler weist darauf hin, dass der Zusatzdienst 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 Callback-Dienst ausgeführt wird, auf dem richtigen Port wartet und in der GCPTrafficExtension- oder GCPRoutingExtension-Ressource richtig konfiguriert ist.

Fehlercode 500 in der JSON-Nutzlast

Der folgende Fehler gibt an, dass beim Zusatzdienst ein interner Serverfehler aufgetreten ist:

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

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

Nächste Schritte