Service Extensions を使用して GKE Gateway トラフィックをカスタマイズする

このページでは、Google Kubernetes Engine（GKE）が Service Extensions を使って Cloud Load Balancing にカスタム ロジックを追加する方法について説明します。

このページは、Service Extensions を使ってカスタム トラフィックの管理ロジックを構成する必要がある GKE の ID およびアカウントの管理者と開発者の方を対象としています。

このページを読む前に、次のことをよく理解しておいてください。

概要

GKE は Service Extensions を使用して、カスタム ロジックを Cloud Load Balancing に追加します。Service Extensions は、高度なトラフィック分割、カスタム認証、リクエスト ロギングなどのタスクに使用できます。

GKE Gateway Controller は、次のサービス拡張機能に対応しています。

  • GCPRoutingExtension: この拡張機能は、トラフィック ルーティングを制御するためにカスタム ロジックを Cloud Load Balancing に追加します。
  • GCPTrafficExtension: この拡張機能は、トラフィックを変更するためにカスタム ロジックを Cloud Load Balancing に挿入します。このロジックは、サービスが選択された後にトラフィックに適用されます。ロードバランサは、HTTP リクエストとレスポンスのヘッダーとペイロードを追加または変更できます。GCPTrafficExtension は、サービスの選択やサービス セキュリティ ポリシーには影響しません。

拡張機能は Gateway に接続し、Service、GCPWasmPlugin、または googleAPIServiceName を参照します。

  • Service を参照する: このモデルでは、カスタム ロジックを個別のバックエンド アプリケーションとしてデプロイし、Kubernetes Service として公開します。ロードバランサは、このサービスにコールアウトしてトラフィックを処理します。このアプローチは汎用性が高く、カスタム ルーティング ロジックを実装したり、ヘッダーの変更やペイロードの検査などのトラフィック操作を実行したりできます。GCPRoutingExtension または GCPTrafficExtension を使用して Service を参照します。

  • GCPWasmPlugin リソースを参照する: パフォーマンスの高いユースケースでは、WebAssembly（Wasm）モジュールを使用して、カスタムのユーザー作成ロジックをGoogle Cloud ロードバランサのデータパスに直接挿入できます。Artifact Registry 内の Wasm モジュールのイメージを指す GCPWasmPlugin リソースを定義します。このメソッドは、GCPTrafficExtension とグローバル外部アプリケーション ロードバランサでのみ使用されます。

  • Google API サービスを参照する: GCPTrafficExtension 内の googleAPIServiceName フィールドを使用して、Google API サービスを直接参照することもできます。

次の図では、GCPRoutingExtension リソースが Gateway に接続され、複数の Service を参照しています。拡張機能は、サービスへのトラフィック ルーティングを制御します。

`GCPRoutingExtension` リソースは Gateway に接続され、Service を参照します。拡張機能がトラフィック ルーティングを制御します。
図: `GCPRoutingExtension` が Gateway と連携する仕組み

次の図では、GCPTrafficExtension リソースが Gateway に接続され、Service、GoogleAPIServiceName、または GCPWasmPlugin を参照しています。拡張機能は、リクエストとレスポンスのヘッダーとペイロードを変更します。

`GCPTrafficExtension` リソースは Gateway に関連付けられ、Service、`GoogleAPIServiceName`、または `GCPWasmPlugin` を参照します。この拡張機能は、リクエストおよびレスポンスのヘッダーとペイロードを変更します。
図: `GCPTrafficExtension` が Gateway と連携する仕組み

始める前に

作業を始める前に、次のタスクが完了していることを確認してください。

  • Google Kubernetes Engine API を有効にする。
    • Google Kubernetes Engine API の有効化
  • このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。

  • 必要に応じて、Compute Engine API、Network Services API、Model Armor API を有効にします。

    API へのアクセスを有効にするに移動し、手順に沿って操作します。

  • Google Cloud Service Extensions の料金体系について詳しくは、料金をご覧ください。

  • Service Extensions のアクセス制御で、必要なロールと権限を確認します。

  • Service Extensions の割り当てで割り当てと上限を確認します。

  • Common Expression Language（CEL）マッチャーを使用する場合は、CEL マッチャーの言語リファレンスでサポートされている属性と演算子を確認してください。

  • Service Extensions の制限事項を確認してください。

GKE Gateway コントローラの要件

  • クラスタが使用する GKE バージョンは 1.33 以降である必要があります。
  • GCPWasmPlugin を使用するには、クラスタで GKE バージョン 1.33.3 以降を使用する必要があります。
  • クラスタで Gateway API が有効になっている必要があります。
  • 構成済みの Gateway リソースが必要です。このリソースは、グローバル外部アプリケーション ロードバランサ、リージョン外部アプリケーション ロードバランサ、リージョン内部アプリケーション ロードバランサ Gateway のいずれかです。GCPWasmPlugin リソースを使用する場合は、グローバル外部アプリケーション ロードバランサ Gateway のみをデプロイする必要があります。
  • 構成済みの HTTPRoute リソースが必要です。

制限事項

次の表に、GKE での Gateway Service Extensions の構成に関連する制限事項を示します。

カテゴリ 制限事項
ロードバランサ GCPRoutingExtension は、次のロードバランサでサポートされています。
  • リージョン外部アプリケーション ロードバランサ（gke-l7-regional-external-managed Gateway クラス）
  • リージョン内部アプリケーション ロードバランサ（gke-l7-rilb Gateway クラス）
GCPTrafficExtension は、次のロードバランサでサポートされています。
  • リージョン外部アプリケーション ロードバランサ（gke-l7-regional-external-managed Gateway クラス）
  • リージョン内部アプリケーション ロードバランサ（gke-l7-rilb Gateway クラス）
  • グローバル外部アプリケーション ロードバランサ（gke-l7-global-external-managed Gateway クラス）
拡張チェーンと仕様
  • GCPTrafficExtension の場合、各 ExtensionChain に最大 3 つの Extensions を指定できます。
  • GCPRoutingExtension の場合、各 ExtensionChain は 1 つの Extension に制限されます。
  • GCPTrafficExtensionSpec と GCPRoutingExtensionSpec には、それぞれ最大 5 個の ExtensionChains を設定できます。
タイミングとマッチング
  • Extension 内のストリーム上でのメッセージごとのタイムアウトは、10 ～ 10,000 ミリ秒にする必要があります。この 1 秒の上限は、Route 拡張機能と Traffic 拡張機能に適用されます。
  • ExtensionChain 内の各 MatchCondition は、最大 10 個の CELExpressions に制限されます。
  • GCE に送信される結果の MatchCondition 文字列の文字数制限は 512 です。
  • CELExpression 内の CELMatcher 文字列の最大長は 512 文字で、特定のパターンに準拠する必要があります。CELExpression の BackendRefs フィールドはサポートされていません。
ヘッダーとメタデータ
  • Extension の ForwardHeaders リストには、最大 50 個の HTTP ヘッダー名を含めることができます。
  • Extension の Metadata マップには、最大 16 個のプロパティを設定できます。
  • Metadata マップ内のキーは 1～63 文字にする必要があります。
  • Metadata マップ内の値は 1～1,023 文字にする必要があります。
イベント
  • GCPRoutingExtension の場合、requestBodySendMode が設定されていないと、supportedEvents リストに含められるのは RequestHeaders イベントのみとなります。
  • GCPRoutingExtension の場合、requestBodySendMode が FullDuplexStreamed に設定されていると、supportedEvents リストに含められるのは RequestHeaders、RequestBody、RequestTrailers のイベントのみとなります。
GCPTrafficExtension
  • responseBodySendMode フィールドは GCPTrafficExtension でのみサポートされています。
  • googleAPIServiceName フィールドは GCPTrafficExtension でのみサポートされています。
  • GCPWasmPlugin フィールドは GCPTrafficExtension でのみサポートされています。
GCPWasmPlugin
  • GCPWasmPlugin を含む拡張機能は、次のフィールドをサポートしていません。
    • authority
    • timeout
    • metadata
    • requestBodySendMode
    • responseBodySendMode
  • GCPWasmPlugin を使用する拡張機能は、RequestHeaders、RequestBody、ResponseHeaders、ResponseBody のイベントのみをサポートします。
googleAPIServiceName と backendRef Extension で backendRef を使用する Service を参照する場合は、次の条件を満たす必要があります。
  • appProtocol として HTTP2 を使用する必要があります。
  • Extension と、Extension で参照される Gateway と同じ Namespace に存在する必要があります。
  • IAP を使用できません。
  • Google Cloud Armor のセキュリティ ポリシー（ GCPBackendPolicyConfig の securityPolicy フィールド）を使用できません。
  • Cloud CDN を使用できません。
  • Extension に backendRef または googleAPIServiceName のどちらか一方のみを設定する必要があります。
  • backendRef が設定されていて、kind が Service の場合は、authority を設定する必要があります。
  • googleAPIServiceName が設定されている場合は、authority を設定しないでください。
  • backendRef と Service のみを使用して、拡張機能の requestBodySendMode を構成します。
  • backendRef と Service のみを使用して、拡張機能の responseBodySendMode を構成します。

サービスを参照する

Service Extensions では、ロードバランサに実行させるカスタム ロジックをホストする Service を参照できます。デフォルトでは、Gateway に Service Extensions はありません。

GKE Service Extensions を構成する手順は次のとおりです。

  1. バックエンド コールアウト サービスをデプロイする: カスタム ロジック実行用のバックエンド サービスを表す Kubernetes Service を作成します。ロードバランサがこのサービスを呼び出します。

  2. Service Extensions を構成する: ロードバランサのタイプに基づいて適切な拡張機能を使用します。

    1. リージョン ゲートウェイの GCPRoutingExtension: リージョン外部アプリケーション ロードバランサとリージョン内部アプリケーション ロードバランサでこの拡張機能を使用して、リージョン内でカスタム ルーティング ロジックを実装します。

    2. グローバル外部、リージョン外部、内部ゲートウェイの GCPTrafficExtension: グローバル外部アプリケーション ロードバランサ、リージョン外部アプリケーション ロードバランサ、リージョン内部アプリケーション ロードバランサでこの拡張機能を使用して、さまざまなロードバランサ タイプでヘッダーの変更やペイロードの検査などのトラフィック操作を実行します。

バックエンド コールアウト サービスをデプロイする

コールアウト サービスは、GKE の Gateway Service Extensions に対してカスタム ロジックを実装するサービスです。Gateway は、GCPTrafficExtension や GCPRoutingExtension の構成に基づいてこれらのバックエンド アプリケーションを呼び出し、トラフィックを変更またはルーティングします。

Gateway にカスタム ロジックを追加するために、コールアウト サービスをデプロイします。この独立したサービスは、ヘッダー操作、ペイロード変換、トラフィック ルーティングなどのカスタム処理を担当します。

Gateway のコールアウトとして機能するサービスをデプロイする手順は次のとおりです。

  1. （省略可）TLS の Secret を作成する: このコマンドは、TLS 証明書と秘密鍵を含む TLS タイプの Kubernetes Secret を作成します。

    コールアウト サービスの TLS シークレットを作成するには、次の値を置き換えます。

    • SECRET_NAME: コールアウト サービスのシークレット名
    • path-to-cert: 証明書のファイルパス
    • path-to-key: 鍵のファイルパス

  2. シークレットが追加されたことを確認するには、次のコマンドを実行します。

    kubectl get secrets SECRET_NAME

    SECRET_NAME は、コールアウト サービスのシークレット名に置き換えます。

    出力例を以下に示します。

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

  3. Deployment と Service のリソースを定義します。

    次の項目を定義する必要があります。

    • Deployment: Service Extensions のカスタム ロジックを含むアプリケーション Pod を管理します。
    • Service: Deployment によって管理されるアプリケーション Pod をネットワーク サービスとして公開します。

    1. Deployment と Service の定義を含むサンプル マニフェスト extension-service-app.yaml を作成します。

      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. extension-service-app.yaml マニフェストを適用します。

      kubectl apply -f extension-service-app.yaml

  4. 構成を確認します

    1. アプリケーションがデプロイされたことを確認します。

      kubectl get pod --selector app=store

      アプリケーションの実行が開始されると、出力は次のようになります。

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

    2. Service がデプロイされたことを確認します。

      kubectl get service extension-service

      出力は次のようになります。各ストアの Deployment の Service を示しています。

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

Service Extensions を構成する

GCPRoutingExtension または GCPTrafficExtension を構成して、トラフィック フローをカスタマイズできます。

リージョン Gateway の GCPRoutingExtension を構成する

GCPRoutingExtension を使用してトラフィックを再ルーティングできます。GCPRoutingExtension を構成するには、service-extensions.com ホストのリクエストを指定するように HTTPRoute を更新します。

  1. HTTPRoute を更新します。ルーティング拡張機能をトリガーするホスト名またはパスを含めるように HTTPRoute を変更します。

    1. 次のサンプル マニフェストを 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

      GATEWAY_NAME は実際のプロジェクト名に置き換えます。

    2. store-route.yaml マニフェストを適用します。

      kubectl apply -f store-route.yaml

  2. GCPRoutingExtension を定義します。

    1. サンプルの gcp-routing-extension.yaml ファイルに GCPRoutingExtension の構成を保存します。

      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

      GATEWAY_NAME は実際のプロジェクト名に置き換えます。

    2. マニフェストをクラスタに適用します。

      kubectl apply -f gcp-routing-extension.yaml

  3. GCPRoutingExtension の構成と、Gateway へのバインディングを確認します。

    1. GCPRoutingExtension のデプロイを確認します。

      kubectl describe gcproutingextension my-gateway-extension

      出力は次のようになります。

      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>

      出力には、デフォルト Namespace 内の my-gateway-extension という名前の GCPRoutingExtension の詳細が表示されます。出力には、拡張機能の動作を定義する Spec フィールドが表示されます。

    2. Gateway のバインディングを確認します。

      1. GCPRoutingExtension が Gateway にバインドされていることを確認します。これには数分かかることがあります。

        kubectl describe gateway GATEWAY_NAME

        出力は次のようになります。

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

        出力には、GKE が Gateway と基盤となるGoogle Cloud リソース間のリンクを保存するために使用するアノテーションが表示されます。networking.gke.io/lb-route-extensions アノテーションは、ゲートウェイと GCPRoutingExtension のバインディングを確認します。

      2. GCPRoutingExtension に Programmed というステータスと、ProgrammingSucceeded という理由が表示されていることを確認することで、拡張機能のステータスをチェックします。このコマンドは数分かかることがあります。

        kubectl describe gcproutingextension my-gateway-extension

        出力は次のようになります。

        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

        Status.Conditions フィールドに、Programmed 条件が Status: True および Reason: ProgrammingSucceeded として表示されています。この情報は、拡張機能が正常に適用されたことを示しています。

  4. アプリケーションにトラフィックを送信する

    Gateway、Route、アプリケーションをクラスタ内にデプロイした後は、そのアプリケーションにトラフィックを流せるようになります。

    1. アプリケーションにアクセスするには、Gateway の IP アドレスを見つける必要があります。

      ターミナルで次のコマンドを使用します。

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

      GATEWAY_NAME は実際のプロジェクト名に置き換えます。

      このコマンドによって、Gateway の IP アドレスが出力されます。後続のコマンドでは、GATEWAY_IP_ADDRESS を出力の IP アドレスに置き換えます。

    2. store.example.com/serviceextensions にある serviceextensions バージョンのストアサービスにアクセスして、パスの更新をテストします。

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

      出力は次のようになります。

      {
"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 を構成する

GCPTrafficExtension を使用すると、 Google Cloud 環境内で高度なトラフィック管理機能を利用できます。この拡張機能は、グローバル外部アプリケーション ロードバランサ、リージョン外部アプリケーション ロードバランサ、リージョン内部アプリケーション ロードバランサのいずれでも構成できます。GCPTrafficExtension を使用すると、カスタムの HTTP リクエストとレスポンスのロジック、高度なルーティング、変換、セキュリティ ポリシーを実装できます。

  1. HTTPRoute を更新します。トラフィック拡張をトリガーするホスト名またはパスを含めるように HTTPRoute を変更します。

    1. 次のサンプル マニフェストを 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

      GATEWAY_NAME は、ゲートウェイの名前に置き換えます（internal-http、external-http、global-external-http など）。

    2. store-route.yaml マニフェストをクラスタに適用します。

      kubectl apply -f store-route.yaml

  2. GCPTrafficExtension を定義します。

    1. GCPTrafficExtension 構成をサンプル gcp-traffic-extension.yaml ファイルに保存します。

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

      GATEWAY_NAME は Gateway の名前に置き換えます（internal-http、external-http、global-external-http など）。

    2. マニフェストをクラスタに適用します。

      kubectl apply -f gcp-traffic-extension.yaml

  3. GCPTrafficExtension の構成と、Gateway へのバインディングを確認します。

    1. GCPTrafficExtension のデプロイを確認します。

      kubectl describe gcptrafficextension my-traffic-extension

      出力は次のようになります。

      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>

      出力には、デフォルト Namespace 内の my-traffic-extension という名前の GCPTrafficExtension の詳細が表示されます。拡張機能の動作を定義する Spec フィールドが表示されます。

    2. Gateway のバインディングを確認します。

      GCPTrafficExtension が Gateway にバインドされていることを確認します。このコマンドが完了するまで数分かかる場合があります。

      kubectl describe gateway GATEWAY_NAME

      出力は次のようになります。

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

      出力には、GKE が Gateway と基盤となる Google Cloud リソース間のリンクを保存するために使用するアノテーションが表示されます。networking.gke.io/lb-traffic-extensions アノテーションはバインディングを確認します。

    3. 拡張機能のステータスを確認します。

      GCPTrafficExtension のステータスが Programmed で、理由が ProgrammingSucceeded であることを確認します。このコマンドが完了するまで数分かかる場合があります。

      GCPTrafficExtension の拡張機能のステータスを確認するには、次のコマンドを実行します。

      kubectl describe gcptrafficextension my-traffic-extension

      GCPTrafficExtension リソースの出力は次のようになります。

      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

      Status.Conditions フィールドに、Programmed 条件が Status: True および Reason: ProgrammingSucceeded として表示されています。この情報は、拡張機能が正常に適用されたことを示しています。

  4. アプリケーションにトラフィックを送信する

    Gateway、Route、アプリケーションをクラスタ内にデプロイした後は、そのアプリケーションにトラフィックを流せるようになります。

    1. アプリケーションにアクセスするには、Gateway の IP アドレスを見つける必要があります。

      ターミナルで次のコマンドを使用します。

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

      GATEWAY_NAME は、Gateway の名前に置き換えます。

      このコマンドによって、Gateway の IP アドレスが出力されます。後続のコマンドでは、GATEWAY_IP_ADDRESS を出力の IP アドレスに置き換えます。

    2. store.example.com/serviceextensions にある serviceextensions バージョンのストアサービスにアクセスして、パスの更新をテストします。

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

      出力は次のようになります。

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

GCPWasmPlugin リソースを参照する

GCPTrafficExtension を含む GCPWasmPlugin を使用して、ロードバランサのデータパスにカスタム ロジックを直接挿入できます。この方法では、Wasm モジュールとしてパッケージ化されたカスタム トラフィック管理機能をデプロイできます。

GKE Service Extensions を構成する手順は次のとおりです。

  1. GCPWasmPlugin をデプロイする: Wasm モジュールのカスタムコードを含む GCPWasmPlugin カスタム リソース定義（CRD）を作成してデプロイします。gke-l7-global-external-managed GatewayClass では、GCPWasmPlugin は GCPTrafficExtension とのみ使用できます。

  2. Service Extensions を構成する: グローバル外部アプリケーション ロードバランサに GCPTrafficExtension を使用します。

GCPWasmPlugin をデプロイする

GCPWasmPlugin を使用すると、カスタムのユーザー作成ロジックを Google Cloud ロードバランサのデータパスに直接挿入できます。GCPWasmPlugin リソースは、Artifact Registry 内の Wasm モジュールのイメージを指します。このイメージは、ロードバランサによって実行されます。

次の手順に進む前に、Wasm モジュールを Artifact Registry リポジトリにアップロードしていることを確認してください。詳細については、プラグイン コードを準備するをご覧ください。

GCPWasmPlugin リソースをデプロイする手順は次のとおりです。

  1. 次のマニフェストを 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

    次の点にご注意ください。

    • spec.versions.name: バージョン名は GCPWasmPlugin リソース内で一意である必要があります。最大 10 個のバージョンをリストできます。0 以外の重みを持つバージョンは 1 つだけです。
    • spec.versions.image: Artifact Registry に保存されているプラグイン コードを含むイメージを参照します。
    • spec.versions.weight: プラグイン バージョンの重みを指定します。重みは 0 ～ 1,000,000 の数値（指定した値を含む）で指定してください。
    • spec.logConfig: このプラグインで Cloud Logging を有効にするかどうかを指定します。値が指定されていない場合、Cloud Logging はデフォルトで無効になります。
    • spec.logConfig.sampleRate: アクティビティ ログのサンプリング レートを構成します。レートは 0 ～ 1,000,000 の数値（指定した値を含む）で指定してください。Cloud Logging が有効になっているときに指定しない場合、デフォルト値は 1,000,000（リクエストの 100% がログに記録されます）です。
    • spec.logConfig.minLogLevel: Cloud Logging にエクスポートされるログの最小レベルを指定します。Cloud Logging が有効になっているときに値が指定されていない場合、フィールドはデフォルトで INFO に設定されます。

  2. wasm-plugin.yaml マニフェストを適用します。

    kubectl apply -f wasm-plugin.yaml

  3. プラグインがデプロイされたことを確認します。

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

    出力は次のようになります。

    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>

Service Extensions を構成する

グローバル外部アプリケーション ロードバランサにカスタム ロジックを追加するには、GCPTrafficExtension を構成して GCPWasmPlugin を使用します。GCPTrafficExtension を使用すると、 Google Cloud 環境内で高度なトラフィック管理機能を利用できます。この拡張機能は、グローバル外部アプリケーション ロードバランサで構成できます。

GCPWasmPlugin を使用するように GCPTrafficExtension を構成するには、次の操作を行います。

  1. GCPTrafficExtension を定義します。

    1. GCPTrafficExtension 構成を 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

      GATEWAY_NAME は、Gateway の名前に置き換えます（global-external-http など）。

    2. マニフェストをクラスタに適用します。

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

  2. GCPTrafficExtension の構成と、Gateway へのバインディングを確認します。

    1. GCPTrafficExtension のデプロイを確認します。

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

      出力は次のようになります。

      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>

      出力には、デフォルト Namespace 内の gcp-traffic-extension-with-plugin という名前の GCPTrafficExtension の詳細が表示されます。拡張機能の動作を定義する Spec フィールドが表示されます。

    2. Gateway のバインディングを確認します。

      GCPTrafficExtension が Gateway にバインドされていることを確認します。このコマンドが完了するまで数分かかる場合があります。

      kubectl describe gateway GATEWAY_NAME

      出力は次のようになります。

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

      出力には、GKE が Gateway と基盤となる Google Cloudリソース間のリンクを保存するために使用するアノテーションが表示されます。networking.gke.io/lb-traffic-extensions、networking.gke.io/wasm-plugin-versions、networking.gke.io/wasm-plugins アノテーションはバインディングを確認します。

    3. 拡張機能のステータスを確認します。

      GCPTrafficExtension のステータスが Programmed で、理由が ProgrammingSucceeded であることを確認します。このコマンドが完了するまで数分かかる場合があります。

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

      出力は次のようになります。

      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. プラグインのステータスを確認します。

      GCPWasmPlugin リソースのステータスが Programmed で、理由が ProgrammingSucceeded であることを確認します。このコマンドが完了するまで数分かかる場合があります。

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

      出力は次のようになります。

      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. アプリケーションにトラフィックを送信する

    Gateway、Route、アプリケーションをクラスタ内にデプロイした後は、そのアプリケーションにトラフィックを流せるようになります。

    1. アプリケーションにアクセスするには、Gateway の IP アドレスを見つける必要があります。

      ターミナルで次のコマンドを使用します。

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

      GATEWAY_NAME は、Gateway の名前に置き換えます。

      このコマンドによって、Gateway の IP アドレスが出力されます。後続のコマンドでは、GATEWAY_IP_ADDRESS を出力の IP アドレスに置き換えます。

    2. store.example.com/serviceextensions にある serviceextensions バージョンのストアサービスにアクセスして、パスの更新をテストします。

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

      出力は Hello World を返します。

GCPWasmPlugin リソースを管理する

GCPWasmPlugin CRD を更新して、プラグインをモニタリングできます。

GCPWasmPlugin を更新する

GCPWasmPlugin リソースを更新する手順は次のとおりです。

  1. GCPWasmPlugin マニフェストで変更を行い、GCPWasmPlugin をデプロイするの手順に沿って操作します。

    たとえば、プラグインの 2 つのバージョンを用意し、一方のバージョンはトラフィックを処理し、もう一方のバージョンは処理しないようにするには、wasm-plugin.yaml ファイルを次のように更新します。

    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

    この例では、次のようになります。

    • wasm-plugin-version-v1 の weight は 1000000 です。これは、すべてのトラフィックを処理することを意味します。
    • wasm-plugin-version-v2 の weight は 0 です。つまり、トラフィックは提供されません。

  2. Gateway が更新されていることを確認するには、次のコマンドを実行します。このコマンドが完了するまで数分かかることがあります。

    kubectl describe gateway GATEWAY_NAME

    GATEWAY_NAME は実際のプロジェクト名に置き換えます。

GCPWasmPlugin をモニタリングする

Google Cloud コンソールで GCPWasmPlugin の指標を表示するには、プラグインの観点からモニタリングするをご覧ください。

ガイドの手順で [プラグイン バージョン フィルタ] リストから値を選択する必要がある場合は、prefix−WASM_PLUGIN_VERSION_NAME_FROM_FILE−suffix という形式を探します。ここで、WASM_PLUGIN_VERSION_NAME_FROM_FILE は GCPWasmPlugin 構成ファイルで定義した特定のバージョン名です。

ゲートウェイでのトラフィック拡張機能のトラブルシューティング

このセクションでは、Gateway でトラフィック拡張機能を構成する際のトラブルシューティングのヒントを紹介します。

ゲートウェイが見つかりませんでした

次のエラーは、GCPTrafficExtension リソースまたは GCPRoutingExtension リソースの targetRefs フィールドで指定された Gateway リソースが存在しないことを示しています。

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

この問題を解決するには、GCPTrafficExtension または GCPRoutingExtension リソースの targetRefs フィールドで指定された Gateway リソースが、指定された Namespace に存在することを確認します。

サービスまたはサービスポートが見つからない

次のエラーは、GCPTrafficExtension または GCPRoutingExtension リソースの backendRef フィールドで指定された Service または Service ポートが存在しないことを示しています。

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

この問題を解決するには、GCPTrafficExtension または GCPRoutingExtension リソースの backendRef フィールドで指定された Service と Service ポートが、指定された Namespace に存在することを確認します。

NEG にネットワーク エンドポイントがない

次のエラーは、NEG にネットワーク エンドポイントがなく、GCPTrafficExtension または GCPRoutingExtension リソースの backendRef フィールドで指定された Service に関連付けられていないことを示しています。

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

この問題を解決するには、GCPTrafficExtension または GCPRoutingExtension リソースの backendRef フィールドで指定された Service にネットワーク エンドポイントがあることを確認します。

リクエストを送信しても応答がないかエラーが返される

リクエストを送信しても応答がない場合やエラーが返される場合は、コールアウト サービスが正しく機能していない可能性があります。

この問題を解決するには、コールアウト サービスのログでエラーを確認します。

JSON ペイロードのエラーコード 404

次のエラーは、コールアウト サービスが見つからないか、リクエストに応答していないことを示しています。

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

この問題を解決するには、コールアウト サービスが実行されていること、正しいポートでリッスンしていること、GCPTrafficExtension リソースまたは GCPRoutingExtension リソースでサービスが正しく構成されていることを確認します。

JSON ペイロードのエラーコード 500

次のエラーは、コールアウト サービスで内部サーバーエラーが発生していることを示しています。

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

この問題を解決するには、コールアウト サービスのログを調べて、内部サーバーエラーの原因を特定します。

GCPWasmPlugin は存在しません

次のエラーは、GCPWasmPlugin リソースがプロジェクトに存在しないことを示しています。

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

この問題を解決するには、 Google Cloud プロジェクトで対応する GCPWasmPlugin を作成するか、既存の GCPWasmPlugin に拡張機能を関連付けます。

次のステップ