GKE でのネットワーク分離のトラブルシューティング


このページでは、Google Kubernetes Engine(GKE)のネットワーク分離に関する問題を解決する方法について説明します。

さらにサポートを必要とされる場合は、Cloud カスタマーケアにお問い合わせください。

GKE クラスタが実行されていない

クラスタ コントロール プレーンからポート 10250 上のノードへの上り(内向き)トラフィックを許可するファイアウォール ルールを削除するか、デフォルトのインターネット ゲートウェイへのデフォルト ルートを削除すると、クラスタは機能しなくなります。デフォルト ルートを削除する場合は、必要な Google Cloud サービスへのトラフィックが転送されるようにする必要があります。詳細については、カスタム ルーティングをご覧ください。

クラスタの作成時のタイムアウト

現象
バージョン 1.28 以前でプライベート ノードを使用して作成されたクラスタには、VPC 間のピアリング ルートが必須です。ただし、一度に実行できるピアリング オペレーションは 1 つだけです。上記の特性を持つ複数のクラスタを同時に作成しようとすると、クラスタの作成がタイムアウトする場合があります。
解決策

次のいずれかの方法を使用します。

  • バージョン 1.28 以前のクラスタを順次作成して、後続のクラスタごとに外部エンドポイントのない VPC ピアリング ルートが存在するようにします。VPC で実行中のオペレーションがある場合、単一のクラスタを作成しようとしてもタイムアウトになることがあります。

  • バージョン 1.29 以降でクラスタを作成します。

VPC ネットワーク ピアリング接続が誤って削除される

現象

誤って VPC ネットワーク ピアリング接続を削除すると、クラスタは修復状態になり、すべてのノードに UNKNOWN ステータスが表示されます。コントロール プレーンへの到達性が切断されているため、クラスタに対してオペレーションは実行できません。コントロール プレーンを検査すると、ログに次のようなエラーが表示されます。

error checking if node NODE_NAME is shutdown: unimplemented
考えられる原因

VPC ネットワーク ピアリング接続を誤って削除してしまった。

解決策

以下の操作を行います。

  1. 新しい一時的な VPC ネットワーク ピアリング クラスタを作成します。クラスタを作成すると、VPC ネットワーク ピアリングが再作成され、古いクラスタは通常の稼働状況に復元されます。

  2. 古いクラスタが通常の動作に戻ったら、一時的に作成された VPC ネットワーク ピアリング クラスタを削除します。

Private Service Connect エンドポイントと転送ルールが誤って削除された

現象

Private Service Connect エンドポイントまたは転送ルールを誤って削除すると、クラスタは修復状態になり、すべてのノードに UNKNOWN ステータスが表示されます。コントロール プレーンへのアクセスが切断されているため、クラスタに対してオペレーションは実行できません。コントロール プレーンを検査すると、ログに次のようなエラーが表示されます。

error checking if node NODE_NAME is shutdown: unimplemented
考えられる原因

Private Service Connect エンドポイントまたは転送ルールを誤って削除した。どちらのリソースも gke-[cluster-name]-[cluster-hash:8]-[uuid:8]-pe という名前を持っており、コントロール プレーンとノードがプライベート接続できます。

解決策

コントロール プレーンの IP アドレスをローテーションする

クラスタがアクティブピアと重複している

現象

外部エンドポイントのないクラスタを作成しようとすると、次のようなエラーが返されます。

Google Compute Engine: An IP range in the peer network overlaps with an IP
range in an active peer of the local network.
考えられる原因

重複コントロール プレーン CIDR を選択している。

解決策

次のいずれかの方法を使用します。

  • クラスタを削除して、別のコントロール プレーン CIDR を使用して再作成します。
  • バージョン 1.29 でクラスタを再作成し、--enable-private-nodes フラグを指定します。

外部エンドポイントのないクラスタのコントロール プレーンに到達できない

クラスタ エンドポイント アクセス構成を実装することで、クラスタ コントロール プレーンに到達できる可能性を高めます。詳細については、クラスタ エンドポイントへのアクセスをご覧ください。

現象

外部エンドポイントのないクラスタを作成した後、クラスタに対して kubectl コマンドを実行しようとすると、次のいずれかのエラーが返されます。

Unable to connect to the server: dial tcp [IP_ADDRESS]: connect: connection
timed out.
Unable to connect to the server: dial tcp [IP_ADDRESS]: i/o timeout.
考えられる原因

kubectl がクラスタ コントロール プレーンと通信できません。

解決策

次のいずれかの方法を使用します。

  • DNS アクセスを有効にして、クラスタに安全にアクセスする方法を簡素化します。詳細については、DNS ベースのエンドポイントをご覧ください。

  • クラスタの認証情報が kubeconfig に生成されているか、正しいコンテキストが有効になっていることを確認します。クラスタ認証情報の設定の詳細については、kubeconfig エントリを生成するをご覧ください。

  • 外部 IP アドレスを使用したコントロール プレーンへのアクセスが許可されていることを確認します。クラスタ コントロール プレーンへの外部アクセスを無効にすると、クラスタがインターネットから分離されます。この構成では、承認済みの内部ネットワークの CIDR 範囲または予約済みネットワークのみがコントロール プレーンにアクセスできます。

    1. 送信元 IP アドレスがコントロール プレーンへのアクセスが許可されていることを確認します。

        gcloud container clusters describe CLUSTER_NAME \
            --format="value(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetworksConfig)"\
            --location=COMPUTE_LOCATION
      

      次のように置き換えます。

      送信元 IP アドレスが承認されていない場合、出力では空の結果(中かっこのみ)または送信元 IP アドレスを含まない CIDR 範囲が返されることがあります。

      cidrBlocks:
        cidrBlock: 10.XXX.X.XX/32
        displayName: jumphost
        cidrBlock: 35.XXX.XXX.XX/32
        displayName: cloud shell
      enabled: true
      
    2. コントロール プレーンにアクセスするために、承認済みネットワークを追加します。

  • オンプレミス環境またはクラスタのロケーションとは異なるリージョンから kubectl コマンドを実行する場合は、コントロール プレーンのプライベート エンドポイント グローバル アクセスが有効になっているかを確認してください。詳細については、コントロール プレーンの内部 IP アドレスを使用して任意のリージョンからアクセスするをご覧ください。

    1. 制御アクセス構成のレスポンスを表示するようにクラスタを記述します。

      gcloud container clusters describe CLUSTER_NAME \
          --location=COMPUTE_LOCATION \
          --flatten "controlPlaneEndpointsConfig.ipEndpointsConfig.globalAccess"
      

      次のように置き換えます。

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

        enabled: true
      
    2. null が返された場合は、任意のリージョンからコントロール プレーンの内部 IP アドレスを使用してアクセスを有効にします

IPv4 CIDR ブロックが重複しているためクラスタを作成できない

現象

gcloud container clusters create が次のようなエラーを返す。

The given master_ipv4_cidr 10.128.0.0/28 overlaps with an existing network
10.128.0.0/20.
考えられる原因

指定したコントロール プレーン CIDR ブロックが、VPC 内の既存のサブネットと重複している。

解決策

既存のサブネットと重複しない --master-ipv4-cidr の CIDR ブロックを指定します。

別のクラスタですでに使用されているサービス範囲があるため、クラスタを作成できない

現象

クラスタを作成しようとすると、次のようなエラーが返されます。

Services range [ALIAS_IP_RANGE] in network [VPC_NETWORK], subnetwork
[SUBNET_NAME] is already used by another cluster.
考えられる原因

このエラーは、次の構成で発生する可能性があります。

  • 別のクラスタで使用されているサービス範囲を選択しているか、クラスタが削除されていません。
  • そのサービス範囲を使用するクラスタは削除されましたが、セカンダリ範囲メタデータが正しくクリーンアップされませんでした。GKE クラスタのセカンダリ範囲は Compute Engine のメタデータに保存されます。またクラスタを削除した際、セカンダリ範囲のメタデータも削除されます。しかし、クラスタが正常に削除された場合でも、セカンダリ範囲のメタデータが削除されないことがあります。
解決策

手順は次のとおりです。

  1. サービス範囲が既存のクラスタで使用されているかどうかを確認します。クラスタを検索するには、filter フラグを指定して gcloud container clusters list コマンドを実行します。サービス範囲を使用する既存のクラスタがある場合は、そのクラスタを削除するか、新しいサービス範囲を作成する必要があります。
  2. サービス範囲が既存のクラスタで使用されていない場合は、使用するサービス範囲と一致するメタデータ エントリを手動で削除します。

サブネットを作成できない

現象

自動サブネットを使用してクラスタを作成するか、カスタム サブネットを作成すると、次のいずれかのエラーが発生することがあります。

An IP range in the peer network overlaps
with an IP range in one of the active peers of the local network.
Error: Error waiting for creating GKE cluster: Invalid value for field
PrivateClusterConfig.MasterIpv4CidrBlock: x.x.x.x/28 conflicts with an
existing subnet in one of the peered VPCs.
考えられる原因

指定したコントロール プレーンの CIDR 範囲が、クラスタ内の別の IP 範囲と重複しています。このサブネット作成エラーは、最近削除されたクラスタで使用された master-ipv4-cidr CIDR を再利用しようとした場合にも発生することがあります。

解決策

別の CIDR 範囲を使用してみてください。

公開 Docker Hub からイメージを pull できない

現象

kubectl describe を実行すると、クラスタで実行中の Pod で警告が表示されることがある。

Failed to pull image: rpc error: code = Unknown desc = Error response
from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled
while waiting for connection (Client.Timeout exceeded while awaiting
headers)
考えられる原因

プライベート IP アドレスを持つノードでは、インターネット アクセスの要件を満たすための追加構成のみが必要です。ただし、限定公開の Google アクセスが有効になっていて、ネットワーク要件を満たしている場合、ノードは Artifact Registry を含む Google Cloud APIs とサービスにアクセスできます。

解決策

次のいずれかの方法を使用します。

  • クラスタ内の Docker Hub から Artifact Registry にイメージをコピーします。詳細については、サードパーティ レジストリからのコンテナの移行をご覧ください。

  • そのまま GKE で、mirror.gcr.io に、よくアクセスされる Docker Hub イメージのキャッシュに保存されたコピーがあるかどうかを調べます。

  • Docker Hub または別の公開リポジトリからイメージを pull する必要がある場合は、Cloud NAT または静的 0.0.0.0/0 ルートのターゲットであるインスタンス ベースのプロキシを使用します。

アドミッション Webhook のタイムアウトをトリガーする API リクエスト

現象

targetPort が 443 以外のサービスを使用するように構成されたアドミッション Webhook をトリガーする API リクエストがタイムアウトし、リクエストが失敗する。

Error from server (Timeout): request did not complete within requested timeout 30s
考えられる原因

デフォルトのファイアウォールでは、ポート 443(HTTPS)と 10250(kubelet)以外のノードへの TCP 接続は許可されません。トラフィックを許可するカスタム ファイアウォール ルールがない場合、443 以外のポートで Pod との通信を試みるアドミッション Webhook は失敗します。

解決策

特定のユースケースにファイアウォール ルールを追加します。

ヘルスチェックに失敗したためクラスタを作成できない

現象

限定公開ノードプールを使用して Standard クラスタを作成すると、ヘルスチェックのステップで停止し、次のようなエラーが返されます。

All cluster resources were brought up, but only 0 of 2 have registered.
All cluster resources were brought up, but: 3 nodes out of 4 are unhealthy
考えられる原因

このエラーは、次の構成で発生する可能性があります。

  • クラスタノードが、Cloud Storage API(storage.googleapis.com)から必要なバイナリをダウンロードできない。
  • 下り(外向き)トラフィックを制限するファイアウォール ルール。
  • 共有 VPC の IAM 権限が正しくない。
  • 限定公開の Google アクセスでは *.gcr.io に DNS を構成する必要があります。
解決策

次のいずれかの方法を使用します。

kubelet に Pod サンドボックスを作成できませんでした。

現象

プライベート ノードを含むクラスタを作成すると、次のようなエラーが返されます。

Warning  FailedCreatePodSandBox  12s (x9 over 4m)      kubelet  Failed to create pod sandbox: rpc error: code = Unknown desc = Error response from daemon: Get https://registry.k8s.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized
考えられる原因

calico-node Pod または netd Pod が *.gcr.io に到達できない。

解決策

必要な Container Registry または Artifact Registry の設定が完了していることを確認します。

作成された限定公開ノードがクラスタに参加しない

プライベート IP アドレスのみを持つノードを使用しているクラスタの場合、VPC でカスタム ルーティングとサードパーティ ネットワーク アプライアンスを使用すると、デフォルトのインターネット ゲートウェイではなく、アプライアンスにデフォルト ルート(0.0.0.0/0)がリダイレクトされることがあります。コントロール プレーンの接続だけでなく、次の宛先に到達できるようにする必要があります。

  • *.googleapis.com
  • *.gcr.io
  • gcr.io

3 つのドメインすべてに対して限定公開の Google アクセスを構成します。このベスト プラクティスでは、インターネットにバインドされたトラフィックを制限しながら、新しいノードが起動してクラスタに参加できるようになります。

GKE クラスタのワークロードがインターネットにアクセスできない

プライベート IP アドレスを持つノードで実行されている Pod は、インターネットにアクセスできません。たとえば、Pod exec shell から apt update コマンドを実行すると、次のようなエラーが報告されます。

0% [Connecting to deb.debian.org (199.232.98.132)] [Connecting to security.debian.org (151.101.130.132)]

クラスタ内の Pod に使用されるサブネット セカンダリ IP アドレス範囲が Cloud NAT ゲートウェイに構成されていない場合、Cloud NAT ゲートウェイに外部 IP アドレスが構成されていないため、Pod はインターネットに接続できません。

クラスタが使用するサブネットに、少なくとも次のサブネット IP アドレス範囲が適用されるように Cloud NAT ゲートウェイを構成してください。

  • サブネットのプライマリ IP アドレス範囲(ノードで使用)
  • サブネット クラスタ内の Pod に使用されるセカンダリ IP アドレス範囲
  • クラスタ内のサービスに使用されるサブネット セカンダリ IP アドレス範囲

詳細については、Pod に使用されるセカンダリ サブネット IP 範囲を追加する方法をご覧ください。

パブリック クラスタで直接 IP アクセスを無効にできない

現象

IP アドレス エンドポイントを無効にすると、次のようなエラー メッセージが表示されます。

Direct IP access can't be disabled for public clusters
考えられる原因

クラスタが従来のネットワークを使用している。

解決策

クラスタを Private Service Connect に移行します。移行のステータスについて詳しくは、 サポートにお問い合わせ ください。

PSC 移行中のクラスタで直接 IP アクセスを無効にできない

現象

IP アドレス エンドポイントを無効にすると、次のようなエラー メッセージが表示されます。

Direct IP access can't be disabled for public clusters
考えられる原因

クラスタが従来のネットワークを使用している。

解決策

次のいずれかの方法を使用します。

  • すべてのノードプールを別のバージョンで手動で再作成します。
  • メンテナンス イベント中に GKE がノードプールを自動的にアップグレードするまで待ちます。

コントロール プレーンの内部エンドポイントを有効にできない

現象

クラスタのコントロール プレーンの内部エンドポイントを有効にしようとすると、次のようなエラー メッセージが表示されます。

private_endpoint_enforcement_enabled can't be enabled when envoy is disabled
private_endpoint_enforcement_enabled is unsupported. Please upgrade to the minimum support version
考えられる原因

クラスタで IP アドレスのローテーションまたはバージョンの更新を行う必要があります。

解決策

次のいずれかの方法を使用します。

組織のポリシーが定義されている場合、クラスタの作成が失敗する

現象

クラスタを作成しようとすると、次のようなエラー メッセージが表示されます。

compute.disablePrivateServiceConnectCreationForConsumers violated for projects
考えられる原因

クラスタのエンドポイントまたはバックエンドがコンシューマーの組織のポリシーによってブロックされている。

解決策

コンシューマ側の組織のポリシーの手順に沿って、インスタンスが compute.restrictPrivateServiceConnectProducer 制約を使用してエンドポイントを作成できるようにします。

クラスタの削除中に Private Service Connect エンドポイントが漏洩する可能性がある

現象

クラスタの作成後に、次のいずれかの症状が発生することがあります。

  • Private Service Connect ベースのクラスタの Private Service Connect に接続されたエンドポイントが表示されない。

  • Private Service Connect を使用するクラスタ内の内部エンドポイントに割り当てられたサブネットまたは VPC ネットワークは削除できません。次のようなエラー メッセージが表示されます。

    projects/<PROJECT_ID>/regions/<REGION>/subnetworks/<SUBNET_NAME> is already being used by projects/<PROJECT_ID>/regions/<REGION>/addresses/gk3-<ID>
    
考えられる原因

Private Service Connect を使用する GKE クラスタでは、コントロール プレーンのネットワークでクラスタのコントロール プレーンにアクセスするために内部 IP アドレスを割り振る転送ルールを使用して、Private Service Connect エンドポイントをデプロイします。Private Service Connect を使用してコントロール プレーンとノードの間の通信を保護するため、GKE はエンドポイントを非表示にします。Google Cloud コンソールまたは gcloud CLI でエンドポイントは表示されません。

解決策

クラスタの削除前に Private Service Connect エンドポイントが漏洩しないようにするには、次の操作を行います。

  1. Kubernetes Engine Service Agent role を GKE サービス アカウントに割り当てます。
  2. compute.forwardingRules.* 権限と compute.addresses.* 権限が GKE サービス アカウントから明示的に拒否されていないことを確認します。

Private Service Connect エンドポイントが漏洩している場合は、 サポートにお問い合わせ ください。

クラスタの承認済みネットワークを解析できない

現象

バージョン 1.29 以降ではクラスタを作成できません。次のようなエラー メッセージが表示されます。

Unable to parse cluster.master_ipv4_cidr "" into a valid IP address and mask
考えられる原因

Google Cloud プロジェクトでプライベート IP ベースの Webhook を使用している。そのため、Private Service Connect を使用してクラスタを作成することはできません。代わりに、クラスタは VPC ネットワーク ピアリングを使用して master-ipv4-cidr フラグを解析します。

解決策

次のいずれかの方法を使用します。

  • VPC ネットワーク ピアリング クラスタの作成を続行し、master-ipv4-cidr を含めて有効な CIDR を定義します。このソリューションには次の制限事項があります。

    • master-ipv4-cidr フラグは、Google Cloud コンソールで非推奨になりました。このフラグを更新するには、Google Cloud CLI または Terraform のみを使用できます。
    • VPC ネットワーク ピアリングは、GKE バージョン 1.29 以降で非推奨になりました。
  • Private Service Connect の制限事項の手順に沿って、プライベート IP ベースの Webhook を移行します。次に、 サポートにお問い合わせ Private Service Connect でクラスタを使用するようにオプトインします。

パブリック ノードを含むクラスタで内部 IP アドレス範囲を定義できない

現象

--master-ipv4-cidr フラグを使用して内部 IP アドレス範囲を定義することはできません。次のようなエラー メッセージが表示されます。

ERROR: (gcloud.container.clusters.create) Cannot specify --master-ipv4-cidr
  without --enable-private-nodes
考えられる原因

enable-private-nodes フラグを有効にせずに、クラスタで master-ipv4-cidr フラグを使用してコントロール プレーンの内部 IP アドレス範囲を定義しています。master-ipv4-cidr が定義されたクラスタを作成するには、enable-private-nodes フラグを使用して内部 IP アドレスを持つノード(プライベート ノード)をプロビジョニングするようにクラスタを構成する必要があります。

解決策

次のいずれかの方法を使用します。

  • 次のコマンドを使用してクラスタを作成します。

    gcloud container clusters create-auto CLUSTER_NAME \
        --enable-private-nodes \
        --master-ipv4-cidr CP_IP_RANGE
    

    次のように置き換えます。

    • CLUSTER_NAME: クラスタの名前。
    • CLUSTER_NAME: コントロール プレーンの内部 IP アドレス範囲。
  • IP アドレスのみを使用してノードをプロビジョニングするようにクラスタを更新します。詳細については、クラスタを構成するをご覧ください。

Autopilot クラスタで公開ワークロードをスケジュールできない

現象
Autopilot クラスタで、クラスタがプライベート ノードのみを使用する場合、cloud.google.com/private-node=false nodeSelector を使用してパブリック Pod でワークロードをスケジュールすることはできません。
考えられる原因
Pod の nodeSelector で false として設定された private-node フラグの構成は、バージョン 1.30.3 以降のクラスタでのみ使用できます。
解決策
クラスタを 1.30 バージョン以降にアップグレードします。

DNS ベースのエンドポイントへのアクセスが無効になっている

現象

クラスタに対して kubectl コマンドを実行しようとすると、次のようなエラーが返されます。

couldn't get current server API group list:
control_plane_endpoints_config.dns_endpoint_config.allow_external_traffic is
disabled
考えられる原因

クラスタで DNS ベースのアクセスが無効になっている。

解決策

コントロール プレーンの DNS ベースのエンドポイントを使用して、コントロール プレーンへのアクセスを有効にします。詳細については、コントロール プレーン アクセスを変更するをご覧ください。

スケーリング中にノードで IP アドレスを割り振れない

現象

サブネットのプライマリ IP アドレス範囲を承認済みネットワークのリストに拡張しようとすると、次のようなエラーが返されます。

 authorized networks fields cannot be mutated if direct IP access is disabled
考えられる原因

クラスタの IP ベースのエンドポイントを無効にしています。

解決策

enable-ip-access フラグを使用して、クラスタの IP ベースのエンドポイントを無効または有効にします。

CIDR ブロックが多すぎる

50 個を超える CIDR ブロックがあるクラスタを作成または更新しようとすると、gcloud は次のエラーを返します。

ERROR: (gcloud.container.clusters.update) argument --master-authorized-networks: too many args

この問題を解決するには、次のことを試してください。

サーバーに接続できません

CIDR ブロックの指定に誤りがあると、kubectl コマンドはタイムアウトになります。

Unable to connect to the server: dial tcp MASTER_IP: getsockopt: connection timed out

クラスタを作成または更新するときは、CIDR ブロックを正しく指定するよう注意してください