gke-service-networking

GKE サービスネットワーキングスキル

このスキルでは、GKE 上で実行されるアプリケーションを、インターネットまたは内部ネットワークに安全に公開するためのワークフローを提供します。

デプロイ可能なマニフェストのテンプレートは assets/ にあります。適用する前に # Replace ... プレースホルダーを編集してください。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず利用時のクレジット表記をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでは実行しないでください）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-service-networking)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-service-networking) を追加してください。

ワークフロー

1. Gateway API を構成する（推奨）

Gateway API は、Kubernetes でルーティングを管理するための最新の方法です。

前提条件：クラスターで Gateway API が有効になっている必要があります（GKE 1.26 以降を実行する新しいクラスターではデフォルトで有効です。古いサポート対象バージョンでは、--gateway-api=standard を指定して有効にしてください）。

テンプレート：

• assets/gateway.yaml — HTTP リスナーを備えた gke-l7-global-external-managed GatewayClass を使用する外部 Gateway。
• assets/httproute.yaml — parentRefs を介して Gateway に接続し、パスプレフィックスを Service の backendRef にルーティングする HTTPRoute。
• assets/httproute-traffic-split.yaml — バックエンドサービス間で重み付きトラフィック分割（例：90/10）を行う、カナリアデプロイ用の HTTPRoute の例。

kubectl apply -f assets/gateway.yaml
kubectl apply -f assets/httproute.yaml

トラフィック分割（カナリアデプロイ）：

HTTPRoute は、カナリア展開において複数のバックエンド Service 間で重み付きトラフィック分割をサポートします。

spec:
  rules:
    - backendRefs:
        - name: app-v1
          port: 80
          weight: 90
        - name: app-v2
          port: 80
          weight: 10

2. 標準 GKE Ingress を構成する

よりシンプルなユースケースやレガシー環境では、標準の Ingress を使用します。

テンプレート： assets/ingress.yaml — Service にルーティングする GCE Ingress（kubernetes.io/ingress.class: "gce" アノテーション）。

3. Cloud Armor で保護する

Cloud Armor は、WAF と DDoS 保護を提供します。

1. Cloud Armor でセキュリティポリシーを作成します。

   gcloud compute security-policies create {security_policy_name} \
     --description "WAF policy for {app_name}"
   
   # ルールの例：悪意のある IP 範囲をブロックする
   gcloud compute security-policies rules create 1000 \
     --security-policy {security_policy_name} \
     --action deny-403 \
     --src-ip-ranges "203.0.113.0/24" \
     --description "Block abusive range"
   

2. BackendConfig で参照します：assets/backendconfig.yaml（spec.securityPolicy.name を設定します）。

3. アノテーションを介して BackendConfig を Service に関連付けます。

   # Kubernetes Service マニフェストの metadata.annotations 内：
   cloud.google.com/backend-config: '{"default": "{backend_config_name}"}'
   # または、特定のポートマッピングの場合：
   cloud.google.com/backend-config: '{"ports": {"80": "{backend_config_name}"}}'
   

4. Google 管理の SSL 証明書を構成する

SSL 証明書を自動的にプロビジョニングし、更新します。

レガシー Ingress の方法： assets/managed-certificate.yaml（ドメインを列挙する ManagedCertificate）を適用し、Ingress のアノテーションで参照します。

networking.gke.io/managed-certificates: {certificate_name}

Gateway API の方法： 標準の Certificate Manager 統合では、CertificateMap を作成し、正確なアノテーション networking.gke.io/certmap を使用して（certmap にハイフンを入れずに）Gateway のメタデータアノテーションで参照します。

metadata:
  annotations:
    networking.gke.io/certmap: {certificate_map_name}

重要

アノテーションキーは厳密に networking.gke.io/certmap です（cert-map や certificate-map は使用しないでください）。

または、HTTPS リスナーの tls.certificateRefs で Kubernetes Secret を参照します。どちらの方法も assets/gateway-https.yaml に記載されています。

5. コンテナネイティブの負荷分散を有効にする（推奨）

コンテナネイティブの負荷分散では、ノードではなく Kubernetes Pod を直接負荷分散の対象にできます。これにより、レイテンシと分散が改善されます。

前提条件：クラスターが VPC ネイティブである必要があります。

仕組み：Service の cloud.google.com/neg アノテーションにより、Pod の IP を反映する NEG が作成されます。GKE が自動で追加することもありますが、常に追加されるわけではありません。どのケースに該当するかを把握することが重要です。

# In your Kubernetes Service manifest metadata.annotations:
cloud.google.com/neg: '{"ingress": true}'

アノテーションが自動で設定される場合（手動で追加しないでください）：

• 内部 Ingress — コンテナネイティブの負荷分散が常に使用され、オプションではありません。内部 Ingress は常に GCE_VM_IP_PORT NEG を使用し、VPC ネイティブクラスターが必要です。
• 外部 Ingress — 次の4つの条件をすべて満たす場合に限ります。クラスターが VPC ネイティブであり、Shared VPC 上ではなく、GKE Network Policy を使用せず、HttpLoadBalancing アドオンが有効になっていること（デフォルトで有効です。無効にしないでください）。この場合、GKE が Service にアノテーションを自動で設定します。

明示的に追加する必要がある場合：

• スタンドアロン NEG — Ingress に負荷分散の管理を任せず、自分で管理します。Ingress は同期時またはアップグレード時に管理対象の負荷分散設定を上書きするため、GKE の外部で LB を構成する必要がある場合は必須です。負荷分散のすべての部分を自分で管理することになります。
• 上記4つの条件のいずれかを満たさない外部 Ingress クラスター — Shared VPC、GKE Network Policy の使用、または VPC ネイティブではないクラスターが該当します。Service ごとに有効にしてください。
• レガシー構成 — VPC ネイティブクラスターで作成された一部の古い外部 Ingress オブジェクトは、引き続きインスタンスグループのバックエンドを使用します。

サポート対象外／NEG にフォールバックしないケース：

• Windows Server ノードプール。
• 外部 Ingress を使用するルートベース（非 VPC ネイティブ）クラスター — Ingress コントローラーは、すべてのノードにまたがる未管理のインスタンスグループにフォールバックします。

スケールへの影響：NEG がない場合、クラスターの上限は 1,000 ノードです。また、それを超えると Ingress の背後にある非 NEG Service は正常に機能しなくなります。NEG を使用する場合、GKE のノード数上限はありません。

6. Private Service Connect（PSC）を構成する

Private Service Connect を使用すると、VPC ピアリングを使わずに、ある VPC 内のサービスを別の VPC の利用者に安全に公開できます。

前提条件：バックエンドの Service は内部パススルー Network Load Balancer である必要があります。つまり、type: LoadBalancer を設定し、networking.gke.io/load-balancer-type: "Internal" アノテーションを付けます。ServiceAttachment にはこれが必要です。ClusterIP や外部 LoadBalancer Service は使用できません。

手順：

1. ワークロード用の内部 LoadBalancer Service を作成します。
2. その Service を参照する ServiceAttachment を作成します。 assets/service-attachment.yaml（connectionPreference、PSC NAT サブネット、Service の resourceRef を設定します）。
3. 利用者に ServiceAttachment の URI を共有し、利用者の VPC に PSC エンドポイントを作成してもらいます。

7. トポロジーを考慮したルーティング（コストとレイテンシの最適化）

ゾーン間のデータ転送コストとネットワークレイテンシを最小限に抑えるには、トポロジーを考慮したルーティングを使用するよう Kubernetes Service を構成します。これにより、送信元クライアントと同じゾーンにある Pod にトラフィックがルーティングされます。

# In your Kubernetes Service manifest metadata.annotations:
service.kubernetes.io/topology-mode: auto

トラブルシューティング

Ingress／ロードバランサーのデータプレーン障害を診断します。これらは Ingress（BackendConfig／FrontendConfig）と Gateway（GCPBackendPolicy／HealthCheckPolicy／GCPGatewayPolicy）の両方に対応します。読み取り専用からマニフェストの提案までの範囲にとどめ、稼働中環境への変更を直接適用しないでください。

UNHEALTHY なバックエンドによる 502／5xx（ヘルスチェック）

Google Cloud ロードバランサーのヘルスチェックは、Kubernetes の liveness／readiness プローブとは別のものです。クラスターの外部から実行されるため、 Pod が Ready でも、バックエンドサービスが UNHEALTHY と表示されることがあります。

1. Google のヘルスチェック送信元範囲からノード／Pod のサービスポートへの通信を許可します。 GKE では通常、このルールが自動的に作成されますが、Shared VPC や ファイアウォールを手動で管理している環境では設定されていないことがあります。

   gcloud compute firewall-rules create allow-lb-health-checks \
     --allow tcp:SERVING_PORT \
     --source-ranges 130.211.0.0/22,35.191.0.0/16 \
     --target-tags NODE_TAG
   

2. ヘルスチェックの送信先を正常なエンドポイントに設定します。 デフォルトの / が 200 以外を返す場合は、BackendConfig（Ingress）または HealthCheckPolicy（Gateway）でカスタムヘルスチェックを設定します。

   # BackendConfig (Ingress)
   spec:
     healthCheck:
       requestPath: /healthz
       port: 8080
       checkIntervalSec: 15
       timeoutSec: 5
   

3. Service がコンテナネイティブ（NEG）であり、ヘルスチェックの対象がノードではなく Pod の IP になっていることを確認します（ワークフロー 5 を参照）。

ロールアウト中または長時間リクエストによる 502／リクエストの切断

• **コネクションドレインを有効にして、**ローリングアップデートまたはスケールダウン中に バックエンド Pod が削除される前に、処理中のリクエストを完了させます。

  # BackendConfig (Ingress)
  spec:
    connectionDraining:
      drainingTimeoutSec: 60
  

• バックエンドのタイムアウトを延長します。 処理に時間のかかるレスポンスやストリーミング レスポンスでは、バックエンドのレスポンスタイムアウトを超えて実行されるリクエストでの 502／408 が典型的な症状です。BackendConfig（Ingress）または GCPBackendPolicy （Gateway）で timeoutSec を設定します。

TLS／SSL ハンドシェイクの失敗または弱い暗号スイートの適用

• Ingress： FrontendConfig の sslPolicy を使って SSL ポリシー（最小 TLS バージョン／ 暗号スイートプロファイル）を適用し、必要に応じて redirectToHttps で HTTP から HTTPS へのリダイレクトを強制します。

  # FrontendConfig (external Ingress only)
  spec:
    sslPolicy: gke-ingress-ssl-policy
    redirectToHttps:
      enabled: true
  

• Gateway： GCPGatewayPolicy で SSL ポリシー名を指定します。リージョン Gateway の場合は、 リージョン SSL ポリシーを作成して参照してください。

注意点

1. networking.gke.io/certmap アノテーションを機能させるには、 Certificate Manager API を有効にする必要があります （gcloud services enable certificatemanager.googleapis.com）。有効になっていない場合、Gateway は証明書マップの プロビジョニングに失敗します。
2. リージョン Gateway クラスにはプロキシ専用サブネットが必要です。
   gke-l7-regional-external-managed や gke-l7-rilb などのクラスでは、リージョン内に --purpose=REGIONAL_MANAGED_PROXY を指定したサブネットが必要です。これがない場合、 Gateway はプログラムされないままになります。
3. ManagedCertificate のプロビジョニングは DNS に依存します。 ドメインの A／AAAA レコードが ロードバランサーの IP を指すまで、証明書は Provisioning のままです。DNS の設定が正しく なってから完了まで、15～60 分かかることがあります。

参考資料

• Ingress の機能（BackendConfig／FrontendConfig）
• コンテナネイティブのロードバランシング（NEG）
• Gateway リソースの設定（GCPGatewayPolicy／HealthCheckPolicy／GCPBackendPolicy）
• ヘルスチェックの概念