ノードが Amazon EKS Anywhere クラスターに参加できない場合のトラブルシューティング方法を教えてください。

所要時間3分

Amazon Elastic Kubernetes Service (Amazon EKS) ノードが Amazon EKS Anywhere クラスターに参加できません。

簡単な説明

トラブルシューティングを開始する前に、構成が次の要件を満たしていることを確認してください。

クラスターのライフサイクル操作を実行する管理マシンを使用できること。
管理マシン、コントロールプレーン、およびワーカーノードは、同一のレイヤー 2 ネットワーク上に配置されていること。
使用するネットワークは DHCP をサポートしていること。
注: ネットワーク構成では、コントロールプレーンとワーカーノード用の特定の IP アドレスを除外することをおすすめします。
コントロールプレーンエンドポイントおよび他のクラスターノード用に静的 IP アドレスを予約済みであり、DHCP 範囲から静的 IP アドレスを除外済みであること。
サーバーの各ノードには、2 つ以上の vCPU、8 GB 以上の RAM、25 GB 以上のストレージが備わっていること。
Elastic ネットワークインターフェイスは、Preboot eXecution Environment (PXE) をサポートしていること。
VMware vSphere 7 または 8、および VMware vCenter Server を使用していること。
6 ～ 10 台の仮想マシン (VM) をデプロイできる容量があること。また、ワークロードクラスターのプライマリ VM ネットワークで DHCP サービスを実行していること。
vSphere ネットワークは vCenter Serverへのアクセスを許可しており、必要な IP アドレスは予約済みであり、DHCP から除外済みであること。

解決策

ノード登録に関するエラー

AWS IAM Authenticator for Kubernetes 構成マップ (aws-auth ConfigMap) がクラスターに適用されていない場合、次のエラーメッセージが表示されます。

"Unable to register node with API server err=Unauthorized."

注: この構成マップは、ノードをクラスターに登録するために、ロールベースアクセス制御 (RBAC) 権限 system:bootstrappers および system:nodes を付与します。

ノード登録のエラーを解決するには、AWS Identity and Access Management (IAM) ロールを aws-auth ConfigMap に追加します。

Unauthorized エラー

マネージドノードグループを削除し、その後ノードのロールエントリを aws-auth ConfigMap から削除した場合、"unauthorized" エラーメッセージが表示されます。kubelet ログで API サーバーへの kubelet API リクエストを確認すると、このエラーを特定できます。

unauthorized エラーを解決するには、IAM ロールを aws-auth ConfigMap に再度追加します。

Kubelet の依存関係に関するエラー

CA ファイルエラー

ノードがクラスターから認証局 (CA) ファイルを取得できない場合、または /etc/eks/bootstrap.sh スクリプトの実行時に次のエラーメッセージが表示されます。

"Failed to construct kubelet dependencies" err="unable to load client CA file /etc/kubernetes/pki/ca.crt: open /etc/kubernetes/pki/ca.crt: no such file or directory."

Kubelet の依存関係に関するエラーを解決するには、次の手順を実行します。

cloud-init ログの /var/log/cloud-init-output.log ストリームで次のエラーメッセージを探します。
"Connect timeout on endpoint URL: https://eks.us-east-1.amazonaws.com/clusters/vg-xx-uat Exited with error on line 291"

次の curl-vk コマンドを実行し、Amazon EKS API エンドポイントに到達できることを確認します。

curl -vk https://eks.us-east-1.amazonaws.com/

Amazon EKS エンドポイントを削除します。

エンドポイントに到達できない場合は、次の手順を実行します。

プライベートエンドポイントでは、ノードを同じ仮想プライベートクラウド (VPC) またはコネクテッドネットワーク内に配置します。プライベートエンドポイントには、パブリックアクセスできません。
パブリックエンドポイントのセキュリティグループ、ルートテーブル、およびネットワークアクセスコントロールリスト (ネットワーク ACL) を構成します。セキュリティグループ、ルートテーブル、およびネットワーク ACL はすべて、Amazon EKS エンドポイントへのアウトバウンド HTTPS (TCP 443) トラフィックを許可する必要があります。詳細については、「VPC とサブネットに関する考慮事項」を参照してください。
プライベートサブネット内のノードでは、インターネットへのアウトバウンドアクセス用の NAT ゲートウェイまたは VPC エンドポイントが設定されていることを確認します。
VPC の enableDnsHostnames および enableDnsSupport を true に設定します。
DHCP オプションセットに AmazonProvidedDNS が含まれていることを確認します。

検証エラー

Kubernetes がワークロードクラスター内でコントロールプレーンのリソース "kubeadmcontrolplanes.controlplane.cluster.x-k8s.io" を見つけられない場合、次の検証エラーメッセージが表示されます。

"Validation failed: kubeadmcontrolplanes.controlplane.cluster.x-k8s.io 'eksa-sit' not found; no CAPI cluster objects present on workload cluster 'eksa-sit'..."

検証エラーを解決するには、次の手順を実行します。

kubeadm プロセスが実行されているコントロールプレーンノードにアクセスします。
次の journalctl コマンドを実行し、kubelet サービスログからトラブルシューティング情報を取得します。
```
journalctl -u kubelet -f
```
ログ出力から、検証エラーを引き起こすクラスターコンポーネントを特定します。

ブートストラップトークンのエラー

Amazon EKS Anywhere クラスターのバージョン 1.0.2 にはバグがあり、ブートストラップトークンに関するエラーが発生します。詳細については、GitHub のウェブサイトで「ブートストラップクラスターの時間がワークロードクラスターよりも有意に遅れている場合、ブートストラップトークンは使用可能になる前に失効する可能性がある」を参照してください。

このエラーの解決方法については、「シークレット自体の欠落時、ブートストラップシークレットのローテーションを有効化する修正」を参照してください。

ブートストラップトークンのシークレット欠落エラー

eksctl anywhere upgrade cluster -f cluster.yaml コマンドの実行時、エラーメッセージが表示される可能性があります。ワークフローにバグがあり、ブートストラップトークンのシークレットが欠如していることが原因で、このエラーが発生します。このバグは、クラスターへの接続を試行する新規ノードをブロックします。

このエラーを解決するには、次の手順を実行します。

ブートストラップトークンをリフレッシュするために、新しくプロビジョニングされたマシンを手動で削除します。
クラスターが正常化した際、Kubernetes Cluster API (CAPI) をバックアップし、CAPI コンポーネントを管理クラスターに移動します。手順については、「ブートストラップクラスターの管理コンポーネントでクラスターのアップグレードに失敗する」を参照してください。

内部エラー

ウェブフック検証サービスの接続に問題がある場合、次の内部エラーメッセージが表示されます。

"Error from server (InternalError): Internal error occurred: failed calling webhook..."

内部エラーを解決するには、次の手順を実行します。

eks-controller-manager ポッドを見つけるには、次の kubectl get pods コマンドを実行します。

kubectl get pods -n kube-system | grep eks-controller-manager

次の kubectl logs コマンドを実行すると、ポッドに関するログが表示されます。
```
kubectl logs eksa-controller-manager-pod-name -n kube-system
```
注: eksa-controller-manager-pod-name を実際の eksa-controller-manager ポッド名に置き換えてください。
ログ出力の情報を参考に問題をトラブルシューティングします。

Kubernetes コントロールプレーンのリーダー選出プロセスがタイムアウトした場合、次の内部エラーメッセージが表示されます。

"Failed to update lock: etcdserver: request timed out failed to renew lease eksa-system/f64ae69e.eks.amazonaws.com: timed out waiting for the condition Error setup problem running manager {'error': 'leader election lost'}..."

リーダー選出プロセスが、etcd のリソースロックに対するリースの更新に失敗した場合も、このエラーメッセージが表示される可能性があります。

このエラーの根本原因には、ネットワーク遅延、etcd を利用できない状態、リソース競合の問題が含まれます。

この内部エラーを解決するには、eksa-controller-manager ポッドを削除します。交換ポッドが起動し、Running 状態に移行します。

注: 内部エラーは、バージョン 1.21 以前の Amazon EKS Anywhere クラスターで発生する可能性があります。このエラーを回避するために、クラスターを最新の Kubernetes バージョンに更新することをおすすめします。

PLEG エラー

Pod Lifecycle Event Generator (PLEG) に問題がある場合、次のエラーメッセージが表示されます。

"PLEG is not healthy: pleg was last seen active."

この PLEG エラーを解決するには、次の手順を実行します。

コンテナ実行時の遅延やタイムアウト (例: リモートリクエスト中のパフォーマンスの低下、デッドロック、バグ) が発生していないか確認し、解決します。
ホストリソースに対して過剰なポッド数を実行することも、高仕様ホストであっても過剰なポッド数を実行することも避けてください。
ノードのリソースに関する問題をトラブルシューティングします。

PLEG の詳細については、Red Hat Developer のウェブサイトで「Pod Lifecycle Event Generator: Kubernetes での "PLEG is not healthy" 問題について」を参照してください。

NotReady,SchedulingDisabled エラー

Amazon EKS Anywhere クラスター内のいずれかのノードが NotReady,SchedulingDisabled ステータスの場合、エラーが発生します。この原因は、vSphere VM を実行していた物理マシンが現在は存在しないことです。クラスターはスケーリングステージで停滞し、新しいノードは起動できません。

NotReady,SchedulingDisabled ステータスエラーを解決するには、次の手順を実行します。

マシンのファイナライザーを削除します。
次の kubectl delete node コマンドを実行し、保留中の Amazon EKS ノードを削除して新しいノードが起動できるようにします。
```
kubectl delete node your_node_name
```
注: your_node_name を削除するノード名に置き換えてください。