ノード登録のトラブルシューティング

Standard

このドキュメントでは、Google Kubernetes Engine（GKE）Standard クラスタにノードを追加する際に発生する問題を解決する方法について説明します。これらの問題が発生するシナリオには、クラスタの作成、ノードプールの作成、スケールアップイベント中のものがあります。

GKE Autopilot クラスタの問題を解決するには、Autopilot クラスタのトラブルシューティングをご覧ください。

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

ノード登録について

ノードは、GKE がユーザーに代わって作成する Compute Engine VM インスタンスです。新しいノードを GKE クラスタに追加する際は、それをクラスタのコントロールプレーンに登録する必要があります。ノード登録またはノードブートストラップと呼ばれるこのプロセスは、ノードを作成する際に発生します。

ノード登録が発生した場合

ノード登録は、次のようなシナリオを含めて、ノードが作成されるたびに発生します。

クラスタを作成します。
ノードプールを作成します。
GKE によって、ノードの自動プロビジョニングを使用してノードプールが作成されます。
クラスタオートスケーラーによって、クラスタがスケールアップされます。
クラスタのサイズを変更します。
ノードの自動修復で、新しいノードが作成されます。

ノード登録プロセスは、次の手順のとおりです。

ノードプールに設定されたノード数が、マネージドインスタンスグループ（MIG）に複製されます。
MIG が、必要な数の VM インスタンスを作成します。
作成された VM インスタンスごとに、次のようにします。
1. VM インスタンスを起動します。
2. VM インスタンスが、Kubernetes ノードとして実行するために必要なパッケージを構成してインストールします。
3. ここで、VM インスタンスで実行されている kubelet は、コントロールプレーンの API サーバーと通信して、ノードとして登録します。

ノード登録のエラーメッセージ

GKE がノードをクラスタに追加しようとする場合、ノード登録が失敗すると Google Cloud コンソールに次のエラーが表示されます。

  All cluster resources were brought up, but: only 0 nodes out of * have
  registered; this is likely due to the Nodes failing to start correctly; try
  re-creating the cluster or contact support if that doesn't work.

このエラーメッセージは、ノードがクラスタに正常に登録されなかったことを示しています。以降のセクションでは、このエラーの考えられる原因について説明します。

ノード登録が成功するための前提条件

GKE クラスタへのノード登録が成功するかどうかは、次のような要因によって決まります。

ネットワーク接続。
リソースの可用性。
サービスアカウントの権限。

インスタンス作成の前提条件

GKE がクラスタのノードを作成する場合、最初のステップは新しい Compute Engine VM インスタンスを作成することです。

次のいずれかの理由で、インスタンスの作成が失敗する場合があります。

インスタンスの作成に失敗すると、GKE ノードとして登録するインスタンスを GKE が作成しようとした時間帯には、インスタンスが決して作成されないため、インスタンス作成のログは欠落しています。欠落しているログを確認するには、ノード登録に失敗したインスタンスを見つけるの手順をご覧ください。

サービスアカウントの権限

GKE ノードには、それらに関連付けられている IAM サービスアカウントがあります。デフォルトでは、このサービスアカウントは Compute Engine のデフォルトのサービスアカウントです。クラスタを強化するには、必要最小限の権限を持つカスタム IAM サービスアカウントを使用することをおすすめします。

このサービスアカウントには、GKE ノードとして初期化される VM インスタンスに対する適切な権限を持つ必要があります。サービスアカウントを削除または無効化した場合、または適切な権限を付与していない場合、ノードの登録が失敗する可能性があります。

Google API とサービスへのネットワーク接続の前提条件

VM インスタンスは、GKE ノードとしての実行を準備するためのパッケージをダウンロードします。接続タイムアウトは、クラスタが Google API とサービスに接続するのに必要なネットワーキング要件（storage.googleapis.com など）を満たしていないことを意味する場合があります。インスタンスがこれらのサービスに接続できない場合は、Kubernetes ディストリビューションをダウンロードして、ノード登録プロセスを完了することはできません。

ネットワーク接続によっては、この接続を許可するには、限定公開の Google アクセスを構成するか、接続を許可するクラスタの Virtual Private Cloud（VPC）ネットワークにファイアウォールルールとルートを持つ必要があります。

コントロールプレーンとのネットワーク接続の前提条件

コントロールプレーンとノードの間の接続は、ノード登録と通常の機能にとって重要です。この通信はデフォルトで許可されます。VPC ファイアウォールルールの設定時であっても、ノードとコントロールプレーンの間の通信は許可してください。

詳細については、コントロールプレーンの接続を許可するをご覧ください。

ノード登録チェッカーを使用してノード登録をトラブルシューティングする

GKE バージョン 1.24.0-gke.100 以降で作成されたノードプールの場合、ノード登録チェッカーというユーティリティが新しく作成されたインスタンスで実行され、インスタンスが正常にノード登録の手順を完了したかどうかを確認します。

ノード登録に失敗した場合、ユーティリティはサマリーレポートを生成します。これで、インスタンスが失敗したプロセスの場所に基づいて、どの前提条件が満たされていなかったのかを確認できます。

次のセクションの手順を使用してノード登録に失敗したインスタンスを見つけて、ノード登録チェッカーの概要を使用して失敗した理由を確認します。

ノードプールでノード登録チェッカーを使用できない場合は、ノード登録チェッカーなしでノード登録をトラブルシューティングするをご覧ください。

ノード登録に失敗したインスタンスを見つける

1 つ以上のインスタンスが GKE クラスタのコントロールプレーンでノードとしての登録に失敗した場合、Google Cloud コンソールのクラスタの詳細ページに示されたエラーメッセージから失敗したインスタンスの数を確認できます。複数のインスタンスが同時に登録に失敗した場合は、同じ原因が存在する場合があります。このため、失敗したインスタンスのいずれかを使用して、すべてのインスタンスが失敗した理由を調査できます。

ただし、インスタンスは GKE ノードとして登録されていないため、以下の手順を使用して、登録に失敗した基盤となる Compute Engine VM の名前を知る必要があります。

Google Cloud コンソールで、[ログエクスプローラ] ページに移動します。

[ログエクスプローラ] に移動

次のログフィルタを使用して、VM インスタンスの作成に関するログを見つけます。

resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.requestMetadata.callerSuppliedUserAgent="GCE Managed Instance Group for GKE"
protoPayload.response.status="RUNNING"

PROJECT_ID は、クラスタのプロジェクト ID に置き換えます。

ログフィルタの下にあるヒストグラムを使用して、ノード作成が行われたはずの時間帯を絞り込みます。
[クエリ結果] の下に表示されるログのいずれかをクリックしてから、[ネストされたフィールドを展開] をクリックして詳細を表示します。
protoPayload.resourceName フィールドを見つけます。ここで一覧表示されたパスの最後の部分がインスタンス名です。インスタンス名は、クラスタの名前とノードプールの名前で始まる形式に従います。たとえば、次のとおりです。

gke-cluster-1-default-pool-b0ac62d3-9g1v は、gke-cluster-1 内の default-pool ノードプール用のインスタンスです。
Google Cloud コンソールで、Compute Engine の [VM インスタンス] ページに移動します。

[VM インスタンス] に移動

フィルタを使用して VM インスタンスの名前を見つけます。クリックして詳細を確認します。

ノード登録チェッカーを使用してインスタンスをトラブルシューティングする

登録に失敗したインスタンスの名前を見つけた後で、ノード登録チェッカーを使用して失敗した理由を調査できます。

VM インスタンスの [詳細] タブの [ログ] セクションで、[シリアルポート 1（コンソール）] をクリックします。

GKE バージョン 1.24.0-gke.100 以降で作成されたノードプールの場合、新しく作成されたインスタンスへの出力には次のものが含まれ、ノード登録チェッカーが開始されたことを示します。

** Starting Node Registration Checker **
** Loading variables from kube-env **
** Sleeping for 7m to allow registration to complete  **

ノードの登録が成功すると、出力には次のメッセージが含まれます。

** Node ready and registered. **
** Completed running Node Registration Checker **

これらのメッセージが表示されない場合は、ノードの登録が失敗し、ノード登録チェッカーが登録に失敗した理由の概要を示すレポートを生成しています。この要約レポートを確認するには、次の追加メッセージを探してください。

** Here is a summary of the checks performed: **

このメッセージの下で、次のようなテーブルを探してください。

------------------------------
Service    DNS      Reachable
------------------------------
LOGGING    true     true
GCR        true     true
GCS        true     true
Master     N/A      false
------------------------------

LOGGING、GCR、または GCS が到達不可として一覧表示されている場合は、ノード登録に対するサービスアカウントの権限およびノード登録のための Google API とサービスへのネットワーク接続を確認してください。

Master が到達不可として一覧表示されている場合は、ノード登録用のコントロールプレーンとのネットワーク接続の前提条件を確認してください。

ノード登録の成功を妨げているすべての問題を解決したら、根本原因の修正後にノード登録を完了するをご覧ください。

前述の手順でノード登録が失敗した理由がわからない場合は、さらなる調査のために情報を収集するをご覧ください。

ノード登録チェッカーを使用せずにノード登録をトラブルシューティングする

1.24.0-gke.100 より前の GKE バージョンで作成されたノードプールでノード登録が失敗した場合は、ノード登録を手動でのみトラブルシューティングできます。ノードプールが GKE バージョン 1.24.0-gke.100 以降で作成された場合は、手順に沿ってノード登録チェッカーを使用してノード登録をトラブルシューティングします。

ノード登録を妨げているすべての問題を解決したら、次の手順を使用して根本原因の修正後のノード登録を完了します。

このページの調査手順のどれでもノード登録が失敗した理由がわからない場合は、さらなる調査のために情報を収集するをご覧ください。

ノード登録のサービスアカウントの権限を確認する

ノードが使用するサービスアカウントには、ノード登録のための前提条件が必要です。これらの前提条件を満たしていることを確認する手順は次のとおりです。

ノードの登録に失敗したインスタンスを見つけます。
VM インスタンスの [詳細] タブの [API と ID の管理] セクションで、[サービスアカウント] フィールド内のサービスアカウントの名前を確認します。ノードが Compute Engine のデフォルトのサービスアカウントを使用している場合、名前は PROJECT_NUMBER-compute@developer.gserviceaccount.com の形式に従います。このサービスアカウントには、最低限必要な権限が必要です。
シリアルコンソール出力で成功した登録のインジケーターを確認します。VM インスタンスの [詳細] タブの [ログ] セクションで、[シリアルポート 1（コンソール）] をクリックします。

インスタンスが、適切な権限を持つサービスアカウントを使用した場合、出力は次のものを含みます。
- Started Download and install k8s binaries and configurations
- Started Docker Application Container Engine.
- Started Configure kubernetes node.
- Reached target Kubernetes.
これらのメッセージは、この出力のさまざまな場所で見つかります。それらはまた、Starting [0;1;39mConfigure kubernetes node のように、タイムスタンプやその他のアーティファクトによって中断される場合もあります。これらメッセージのすべてが表示された場合は、サービスアカウントの前提条件が満たされています。

こうしたメッセージが表示されない場合は、VM インスタンスに割り当てられたサービスアカウントが削除または無効化されたか、適切な権限がない可能性があります。

ノード登録のための Google API とサービスへのネットワーク接続を確認する

SSH アクセス権ありの接続を確認する

プロジェクトに VM インスタンスへの SSH アクセス権がある場合、VM インスタンスが Google API とサービスにネットワーク接続していることも確認できます。

ノードの登録に失敗したインスタンスを見つけます。
VM インスタンスの [詳細] タブで、[SSH] をクリックします。
VM インスタンス用のコマンドラインに接続したら、次のコマンドを実行して Google API とサービスへの接続を確認します。
```
curl -m 5 -v https://storage.googleapis.com/generate_204
```
接続に成功した場合、出力は次のようになります。
```
*   Trying 142.250.148.128:443...
* Connected to storage.googleapis.com (142.250.148.128) port 443 (#0)

...

< HTTP/1.1 204 No Content
< Content-Length: 0
< Cross-Origin-Resource-Policy: cross-origin
< Date: Wed, 04 Jan 2023 00:58:41 GMT
<
* Connection #0 to host storage.googleapis.com left intact
```
接続に成功しなかった場合、出力は次のようになります。
```
*   Trying 142.250.148.128:443...
* Connection timed out after 5000 milliseconds
* Closing connection 0
curl: (28) Connection timed out after 5000 milliseconds```
```
接続がタイムアウトして、返された IP アドレスが 199.36.153.0/24 の IP アドレス範囲内の場合は、クラスタが Google API とサービスへの接続に関するネットワーキング要件を満たしていることを確認します。接続がタイムアウトして、返された IP アドレスが上記の IP アドレス範囲内でない場合は、ファイアウォールルールが送信トラフィックをブロックしているか、またはクラスタの VPC ネットワークのルートの構成に誤りがあるかを確認します。

VM インスタンスへの SSH 接続は開いたままにして、次のセクションに進みます。

接続テストを使用して SSH アクセス権なしの接続を確認する

VM インスタンスへの SSH アクセス権がない場合は、接続テストを使用して、VM インスタンスが Google API とサービスに接続していることを確認します。

ノードの登録に失敗したインスタンスを見つけます。
VM インスタンスを接続元、storage.googleapis.com TCP/443 を接続先として、接続テストを作成して実施します。

テスト結果を使用して、クラスタのネットワーキング構成を確認します。

ノード登録用のコントロールプレーンとのネットワーク接続を確認する

プロジェクトに VM インスタンスへの SSH アクセス権がある場合、VM インスタンスがクラスタのコントロールプレーンにネットワーク接続しているかどうかを確認できます。

ノードの登録に失敗したインスタンスを見つけます。
VM インスタンスの [詳細] タブで、[SSH] をクリックします。
VM インスタンスのコマンドラインに接続したら、クラスタのコントロールプレーンエンドポイントを環境変数として保存します。
```
source <(sudo grep KUBERNETES_MASTER_NAME /home/kubernetes/kube-env)
```

コントロールプレーンエンドポイントに GET リクエストを送信します。

curl -k -m 5  https://${KUBERNETES_MASTER_NAME}/version

出力が次のようになったら、VM インスタンスはコントロールプレーンとの接続を確立できます。

{
"major": "1",
"minor": "24",
"gitVersion": "v1.24.7-gke.900",
"gitCommit": "e35c4457f66187eff006dda6d2c0fe12144ef2ec",
"gitTreeState": "clean",
"buildDate": "2022-10-26T09:25:34Z",
"goVersion": "go1.18.7b7",
"compiler": "gc",
"platform": "linux/amd64"
}

出力が次のようになったら、VM インスタンスはコントロールプレーンとの接続を確立できません。

curl: (28) Connection timed out after 5000 milliseconds

VM インスタンスがコントロールプレーンとの接続を確立できない場合は、GKE ネットワーキングのベストプラクティスのコントロールプレーンとの接続の許可についてのセクションをご覧ください。

根本原因の修正後にノード登録を完了する

ノード登録をブロックしている問題を解決した後に、先に進む方法は障害のコンテキストによって異なります。

クラスタの作成時にノード登録が失敗した場合は、クラスタを削除してもう一度試してください。
クラスタオートスケーラーでのスケールアップ中にノード登録が失敗した場合は、VM インスタンスが再び登録を試みるのを待ちます。
ノードプールの作成時にノード登録が失敗した場合:
- VM インスタンスが作成された場合は、VM インスタンスが再び登録を試みるのを待ちます。
- VM インスタンスが作成されなかった場合は、ノードプールを削除して、もう一度試してください。
クラスタのサイズ変更時にノード登録が失敗した場合は、コマンドを再実行してクラスタのサイズを増加します。
修復オペレーション中など、ノード登録がオペレーションの範囲外で失敗した場合は、VM インスタンスが再び登録を試みるのを待ちます。

さらなる調査のために情報を収集する

ノード登録の問題を解決できない場合は、次の手順で追加情報を収集し、Cloud カスタマーケアによる調査に役立てることができます。この手順では、プロジェクトの VM インスタンスへの SSH アクセス権を必要とし、COS イメージに含まれている sosreport ユーティリティを使用します。

ノードの登録に失敗したインスタンスを見つけます。

sosreport を使用してデバッグ情報を収集します。

ノードに sosreport ユーティリティがダウンロードされておらず、インストールできない場合は、次のコマンドを実行してデバッグ情報を手動で収集します。

sudo journalctl -u cloud-init-local
sudo journalctl -u cloud-init
sudo journalctl -u cloud-final
sudo journalctl -u cloud-config
systemctl status kubelet
journalctl -u kubelet
systemctl status kube-node-installation.service
systemctl status kube-node-configuration.service
journalctl -u kube-node-installation.service --no-pager
journalctl -u kube-node-configuration.service --no-pager
journalctl -u kubelet.service --no-pager

この情報を ZIP ファイルにパッケージ化し、Cloud カスタマーケアへのサポートケースの提出時にそれを含めます。

次のステップ