Amazon EKS マネージドノードグループ作成の失敗をトラブルシューティングするにはどうすればよいですか?

最終更新日: 2022 年 6 月 3 日

Amazon Elastic Kubernetes Service (Amazon EKS) マネージドノードグループの作成に失敗しました。ノードがクラスターに参加できず、次のようなエラーが表示されました。

「Instances failed to join the kubernetes cluster」(インスタンスが Kubernetes クラスターに参加できませんでした)。

簡単な説明

Amazon EKS マネージドノードグループの作成エラーを解決するには、次のステップに従います。

  • AWS Systems Manager Automation ランブックを使用して、一般的な問題を特定します。
  • ワーカーノードセキュリティグループのトラフィック要件を確認します。
  • ワーカーノードの Identity and Access Management (IAM) 許可を確認します。
  • クラスターの Amazon Virtual Private Cloud (Amazon VPC) が、DNS ホスト名と解決をサポートしていることを確認します。
  • ワーカーノードの NodeInstanceRole を使用して aws-auth ConfigMap を更新します。
  • ワーカーノード用にタグを設定します。
  • ワーカーノードの Amazon VPC サブネットに使用可能な IP アドレスがあることを確認します。
  • ワーカーノードがクラスターの API サーバーエンドポイントに到達できることを確認します。
  • Amazon Elastic Compute Cloud (Amazon EC2)、Amazon Elastic Container Registry (Amazon ECR)、Amazon Simple Storage Service (Amazon S3) API エンドポイントがご利用の AWS リージョンに到達できることを確認します。

解決方法

注: AWS Command Line Interface (AWS CLI) コマンドの実行中にエラーが発生した場合は、最新の AWS CLI バージョンを使用していることを確認してください

Systems Manager Automation ランブックを使用して一般的な問題を特定する

AWSSupport-TroubleshootEKSWorkerNode ランブックを使用して、ワーカーノードがクラスターに参加するのを妨げる一般的な問題を見つけます。

重要: オートメーションが機能するには、Systems Manager にアクセスし、Systems Manager を実行するための許可がワーカーノードに必要です。許可を付与するには、EC2 インスタンスプロファイルに対応する IAM ロールに AmazonSSMManagedInstanceCore AWS マネージドポリシーをアタッチします。これは、eksctl を使用して作成される EKS マネージドノードグループのデフォルト設定です。

  1. ランブックを開きます
  2. AWS マネジメントコンソールの AWS リージョンがクラスターと同じリージョンに設定されていることを確認します。
    注: ランブックの詳細については、ランブックの [Document details] (ドキュメントの詳細) セクションを確認してください。
  3. [Input parameters] (入力パラメータ) セクションで、[ClusterName] フィールドにクラスターの名前を指定し、[WorkerID] フィールドにインスタンス ID を指定します。
  4. (オプション) [AutomationAssumeRole] フィールドで、Systems Manager にアクションの実行を許可する IAM ロールを指定します。指定しない場合、ランブックのアクションを実行するために、現在の IAM エンティティの IAM 許可が使用されます。
  5. [Execute] (実行) を選択します。
  6. [Outputs] (出力) セクションで、ワーカーノードがクラスターに参加しない理由と、それを解決するために実行できるステップを確認します。

ワーカーノードセキュリティグループのトラフィック要件を確認する

コントロールプレーンのセキュリティグループとワーカーノードのセキュリティグループが、インバウンドトラフィックとアウトバウンドトラフィック向けの推奨設定で設定されていることを確認します。デフォルトでは、Amazon EKS はノードグループ内のインスタンスにクラスターセキュリティグループを適用して、ノードとコントロールプレーン間の通信を容易にします。マネージドノードグループの起動テンプレートでカスタムセキュリティグループを指定した場合、Amazon EKS はクラスターセキュリティグループを追加しません。

ワーカーノードの IAM 許可を確認する

ワーカーノードに関連付けられている IAM インスタンスロールに AmazonEKSWorkerNodePolicy および AmazonEC2ContainerRegistryReadOnly ポリシーがアタッチされていることを確認します。

注: Amazon マネージドポリシー AmazonEKS_CNI_Policy を IAM ロールにアタッチする必要があります。ノードインスタンスロールにアタッチできます。ただし、kube-system 名前空間の aws-node Kubernetes サービスアカウントに関連付けられているロールにポリシーをアタッチするのがベストプラクティスです。詳細については、「サービスアカウントの IAM ロールを使用する Amazon VPC CNI プラグインの設定」を参照してください。

クラスターの Amazon VPC において、DNS ホスト名と解決がサポートされていることを確認します。

EKS クラスターエンドポイントのプライベートアクセスを設定したら、Amazon VPC 用に DNS ホスト名と DNS 解決を有効にする必要があります。エンドポイントプライベートアクセスをアクティブ化すると、Amazon EKS は Amazon Route 53 プライベートホストゾーンを作成します。その後、Amazon EKS はそれをクラスターの Amazon VPC に関連付けます。詳細については、「Amazon EKS クラスターエンドポイントでのアクセスコントロール」を参照してください。

ワーカーノードの NodeInstanceRole で aws-auth ConfigMap を更新する

aws-auth ConfigMap が、インスタンスプロファイルではなく、ワーカーノードの IAM ロールで正しく設定されていることを確認します。

ワーカーノードのタグを設定する

ワーカーノードの [Tag] (タグ) プロパティについて、[key] (キー) を kubernetes.io/cluster/clusterName に設定し、[value] (値) を owned に設定します。

ワーカーノードの Amazon VPC サブネットに使用可能な IP アドレスがあることを確認する

Amazon VPC の IP アドレスが不足している場合は、セカンダリ CIDR を既存の Amazon VPC に関連付けることができます。詳細については、「Amazon VPC で利用可能な IP アドレスを増やす」を参照してください。

Amazon EKS ワーカーノードがクラスターの API サーバーエンドポイントに到達できることを確認する

次のゲートウェイを経由するインターネットルートがある場合は、クラスター VPC またはピアリングされたサブネット内の任意のサブネットでワーカーノードを起動できます。

  • NAT
  • インターネット
  • トランジット

ワーカーノードが制限されたプライベートネットワークで起動されている場合は、ワーカーノードが Amazon EKS API サーバーエンドポイントに到達できることを確認してください。詳細については、アウトバウンドインターネットアクセスなしでプライベートクラスターで Amazon EKS を実行するための要件を参照してください。

: NAT ゲートウェイを基盤とするプライベートサブネットにあるノードについては、パブリックサブネットに NAT ゲートウェイを作成するのがベストプラクティスです。

AWS PrivateLink エンドポイントを使用していない場合は、次の AWS のサービスのプロキシサーバー経由で API エンドポイントへのアクセスを確認します。

  • Amazon EC2
  • Amazon ECR
  • Amazon S3

ワーカーノードが API サーバーにアクセスできることを確認するには、SSH を使用してワーカーノードに接続し、次の netcat コマンドを実行します。

nc -vz 9FCF4EA77D81408ED82517B9B7E60D52.yl4.eu-north-1.eks.amazonaws.com 443

注: 9FCF4EA77D81408ED82517B9B7E60D52.yl4.eu-north-1.eks.amazonaws.com を API サーバーのエンドポイントに置き換えてください。

インスタンスに接続した状態で kubelet ログを確認します。

journalctl -f -u kubelet

kubelet ログに問題の原因に関する情報がない場合は、ワーカーノードの kubelet のステータスを確認してください。

sudo systemctl status kubelet

Amazon EKS ログとオペレーティングシステムのログを収集して、さらにトラブルシューティングを進めます。

Amazon EC2、Amazon ECR、および Amazon S3 API エンドポイントがご利用の AWS リージョンに到達できることを確認する

SSH を使用してワーカーノードの 1 つに接続し、各サービスについて次のコマンドを実行します。

$ nc -vz ec2.region.amazonaws.com 443
$ nc -vz ecr.region.amazonaws.com 443
$ nc -vz s3.region.amazonaws.com 443

注: region をワーカーノードの AWS リージョンに置き換えます。

ワーカーノードのユーザーデータを設定する

指定した AMI を持つマネージドノードグループ起動テンプレートでは、ワーカーノードがクラスターに参加するためにブートストラップコマンドを指定する必要があります。Amazon EKS は、デフォルトのブートストラップコマンドをユーザーデータにマージしません。詳細については、「Introducing launch template and custom AMI support in Amazon EKS Managed Node Groups」(Amazon EKS マネージドノードグループでの起動テンプレートとカスタム AMI サポートの紹介) および「AMI を指定する」を参照してください。

ブートストラップコマンドを含む起動テンプレートの例:

#!/bin/bash
set -o xtrace
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments}

注: ${ClusterName} を Amazon EKS クラスターの名前に置き換えます。必要な場合は、${BootstrapArguments} を追加のブートストラップ値に置き換えます。