GKE の限定公開クラスタのトラブルシューティング

このページでは、Google Kubernetes Engine（GKE）限定公開クラスタの問題を解決する方法について説明します。

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

限定公開クラスタが実行されていない

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

限定公開クラスタの作成時のタイムアウト

すべての限定公開クラスタには、VPC との間にピアリング ルートが必要ですが、一度に実行できるピアリング オペレーションは 1 つだけです。複数の限定公開クラスタを作成しようとすると、クラスタの作成がタイムアウトする場合があります。これを回避するには、後続の限定公開クラスタごとに既存の VPC ピアリング ルートが存在するように、限定公開クラスタを順次作成します。VPC で実行中のオペレーションがある場合、単一の限定公開クラスタを作成しようとしてもタイムアウトになることがあります。

限定公開クラスタの VPC ネットワーク ピアリング接続が誤って削除される

現象

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

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

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

解決策

以下の操作を行います。

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

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

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

現象

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

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 を使用して再作成します。

限定公開クラスタのコントロール プレーンにアクセスできない

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

現象

限定公開クラスタを作成した後、クラスタに 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 がクラスタ コントロール プレーンと通信できません。

解決策

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

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

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

      gcloud container clusters describe CLUSTER_NAME \
      --format="value(masterAuthorizedNetworksConfig)"\
      --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 コマンドを実行する場合は、コントロール プレーンのプライベート エンドポイント グローバル アクセスが有効になっているかを確認してください。詳細については、グローバルにコントロール プレーンのプライベート エンドポイントにアクセスするをご覧ください。

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

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --flatten "privateClusterConfig.masterGlobalAccessConfig"

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

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

      enabled: true

  2. null が返された場合は、コントロール プレーンへのグローバル アクセスを有効にします。

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 のメタデータに保存されます。またクラスタを削除した際、セカンダリ範囲のメタデータも削除されます。しかし、クラスタが正常に削除された場合でも、セカンダリ範囲のメタデータが削除されないことがあります。
解決策

手順は次のとおりです。

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

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

現象

自動サブネットを使用して限定公開クラスタを作成するか、カスタム サブネットを作成すると、次のようなエラーが発生することがある。

An IP range in the peer network overlaps
with an IP range in one of the active peers of the local network.
考えられる原因

指定したコントロール プレーンの CIDR 範囲が、クラスタ内の別の IP 範囲と重複しています。これは、限定公開クラスタを最近削除して、同じコントロール プレーン 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 は失敗します。

解決策

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

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

現象

限定公開クラスタを作成すると、ヘルスチェックのステップが停止し、次のいずれかのエラーが返される。

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 に到達できない。

解決策

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

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

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

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

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

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

限定公開 GKE クラスタ内の 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 範囲を追加する方法をご覧ください。