ワーカーノードが Amazon EKS クラスターに参加できない原因を教えてください。

簡単な説明

Amazon EKS クラスターにワーカーノードを参加させようとした際、次のいずれかの問題が発生する可能性があります。

• EKS クラスターでマネージドノードグループを作成する際、マネージドノードグループのステータスが Create failed に変化する。ワーカーノードが EKS クラスターに参加せず、次のエラーメッセージが表示される: "Instances failed to join the kubernetes cluster"
• EKS クラスターのマネージドノードグループをアップグレードすると、新しいワーカーノードが EKS クラスターに参加できなくなる。

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

Systems Manager オートメーションランブックを使用する

AWSSupport-TroubleshootEKSWorkerNode ランブックを使用してワーカーノードがクラスターに参加できない原因を判断します。

重要: オートメーションを動作させるには、ワーカーノードには AWS Systems Manager にアクセスして実行するための権限が必要です。権限を付与するには、AWS マネージドポリシー AmazonSSMManagedInstanceCore を Amazon Elastic Compute Cloud (Amazon EC2) インスタンスプロファイルの AWS Identity and Access Management (IAM) ロールにアタッチします。eksctl を使用して作成した Amazon EKS マネージドノードグループでは、AmazonSSMManagedInstanceCore ポリシーをデフォルト構成として使用します。クラスター名には、次の形式を使用します: [-a-zA-Z0-9]{1,100}$

オートメーションを実行するには、次の手順を実行します。

1. Systems Manager コンソールで AWSSupport-TroubleshootEKSWorkerNode ランブックを開きます。
2. 注: ランブックの詳細については、ランブックの「ドキュメントの詳細」セクションを参照してください。
3. AWS リージョンの設定がクラスターと同じリージョンであることを確認します。
4. [入力パラメータ] セクションの [ClusterName] フィールドにクラスター名を、[WorkerID] フィールドに Amazon EC2 インスタンス ID を入力します。
5. (オプション) [AutomationAssumeRole] フィールドに、オートメーションがユーザーに代わってアクションを実行することを許可する IAM ロールの Amazon リソースネーム (ARN) を入力します。IAM ロールを指定しない場合、オートメーションはランブックを起動したユーザーの権限を使用します。
6. [実行] を選択します。
7. [出力] セクションで問題の原因および実行可能な解決手順を判断します。

Amazon VPC の DNS サポートを確認する

EKS クラスターの Amazon Virtual Private Cloud (Amazon VPC) で DNS ホスト名と DNS 解決が有効化されていることを確認します。

インスタンスプロファイルのワーカーノードに正しい権限が付与されていることを確認します。

インスタンスプロファイルのワーカーノードに関連付けられたロールに、次の AWS マネージドポリシーをアタッチします。

• AmazonEKSWorkerNodePolicy
• AmazonEKS_CNI_Policy
• AmazonEC2ContainerRegistryReadOnly

組織またはアカウントレベルの権限境界やサービスコントロールポリシー (SCP) が、ワーカーノードの API コールを制限しないことを確認します。

ワーカーノードのユーザーデータを構成する

注: AWS CloudFormation を使用してワーカーノードを起動する場合は、ワーカーノード用のユーザーデータを構成する必要はありません。代わりに、CloudFormation コンソールを使用してセルフマネージド Amazon Linux ノードを起動します。

マネージドノードグループを使用してワーカーノードを起動する場合は、Amazon EKS 最適化 Amazon Linux Amazon マシンイメージ (AMI) でユーザーデータを構成する必要はありません。カスタム AMI を使用してマネージドノードグループ経由でワーカーノードを起動する場合のみ、ユーザーデータを構成します。

カスタム起動テンプレートで Amazon マネージドノードグループを使用する場合は、起動テンプレートに適切なユーザーデータを指定します。Amazon EKS クラスターが完全プライベートクラスターであり、接続に VPC エンドポイントを使用する場合は、ユーザーデータを更新する必要があります。ユーザーデータで認証局 (CA)、API サーバーエンドポイント、および DNS クラスターの IP アドレスを指定します。

ユーザーデータの構成例:

#!/bin/bash
set -ex
B64_CLUSTER_CA=CA-CERT
API_SERVER_URL=ENDPOINT
K8S_CLUSTER_DNS_IP=IP-ADDRESS
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments} —b64-cluster-ca $B64_CLUSTER_CA —apiserver-endpoint $API_SERVER_URL —dns-cluster-ip $K8S_CLUSTER_DNS_I

注: CA-CERT、ENDPOINT、IP-ADDRESS を実際のインスタンスの値に置き換えてください。また、必要に応じて ${ClusterName} を EKS クラスター名に、${BootstrapArguments} を追加のブートストラップ値に置き換えてください。

Amazon EKS 最適化 Linux/Bottlerocket AMI の bootstrap.sh ファイルに引数を渡すために、ユーザーデータを指定する必要がある場合は、起動テンプレートの ImageField で AMI ID を指定します。

ワーカーノードのユーザーデータを構成するには、EC2 インスタンスの起動時にそのユーザーデータを指定します。

たとえば、Terraform などのサードパーティツールを使用するいる場合は、EKS ワーカーノードを起動するためにユーザーデータフィールドを更新します。

ユーザーデータの構成例:

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

注: 必要に応じて ${ClusterName} を EKS クラスター名に、${BootstrapArguments} を追加のブートストラップ値に置き換えてください。

Amazon Linux 2023 AMI を使用する場合は、ユーザーデータに最低限必要なパラメータを次の形式で追加します。

MIME-Version: 1.0Content-Type: multipart/mixed; boundary="//"

--//
Content-Type: application/node.eks.aws

---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    apiServerEndpoint: https://example.com
    certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
    cidr: 10.100.0.0/16
    name: my-cluster

--//--

Amazon VPC サブネットのネットワークが正しく構成されており、ワーカーノードが EKS クラスターと同じ Amazon VPC に配置されていることを確認します。

インターネットゲートウェイを使用する場合は、ルートテーブルに正しくアタッチされていることを確認します。

NAT ゲートウェイを使用する場合は、パブリックサブネットで正しく構成されていることを確認します。さらに、ルートテーブルが正しく構成されていることを確認します。

完全プライベートクラスターで VPC プライベートエンドポイントを使用する場合は、次のインターフェイスエンドポイントが利用可能であることを確認します。

• com.amazonaws.region.ec2
• com.amazonaws.region.ecr.api
• com.amazonaws.region.ecr.dkr
• com.amazonaws.region.sts

さらに、ゲートウェイエンドポイント (com.amazonaws.region.s3) が利用可能であることを確認します。

Amazon ECR に対する、Amazon Simple Storage Service (Amazon S3) ゲートウェイ VPC エンドポイントポリシーを制限できます。詳細については、「Amazon ECR 用の、最小限の Amazon S3 バケット権限」を参照してください。

サービスアカウントの IAM ロールを使用して構成したポッドは、AWS Security Token Service (AWS STS) API コールから認証情報を取得します。アウトバウンドのインターネットアクセスがない場合は、VPC に AWS STS VPC エンドポイントを作成して使用する必要があります。

VPC エンドポイントのセキュリティグループには、ポート 443 からのトラフィックを許可するインバウンドルールが必要です。詳細については、「セキュリティグループを使用してリソースへのトラフィックを制御する」を参照してください。

VPC エンドポイントにアタッチされたポリシーには、特定のサービスに API コールを行うのに必須の権限が付与されていることを確認します。

EKS クラスターの [ネットワーク] セクションにおいて、クラスターに関連付けられたサブネットを特定し、同じ VPC に属していることを確認します。

使用する AWS サービスごとに、別途エンドポイントを作成する必要があります。一般的な AWS サービス用のエンドポイントのリストについては、「ポッド要件」の表を参照してください。または、ユースケースに応じてエンドポイントサービスを作成することもできます。

ワーカーノードを起動する場所となるサブネットを別々に設定することもできます。サブネットは同じ Amazon VPC に配置されており、適切なタグ付けが行われている必要があります。Amazon EKS は、クラスターの作成時に設定したサブネットのタグのみを自動的に管理します。詳細については、「サブネットの要件と考慮事項」を参照してください。

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

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

次のコマンドを実行します。

kubectl describe configmap -n kube-system aws-auth

aws-auth ConfigMap が正しく構成されていない場合、次のエラーメッセージが表示されます。

"571 reflector.go:153] k8s.io/kubernetes/pkg/kubelet/kubelet.go:458 : Failed to list *v1.Node: Unauthorized"

認証方法に EKS API を使用する場合は、NodeInstanceRole にアクセスエントリを作成します。[タイプ] で EC2_linux を選択します。

ワーカーノードのセキュリティグループ要件に準拠する

コントロールプレーンのセキュリティグループおよびワーカーノードのセキュリティグループの構成には、インバウンドおよびアウトバウンドトラフィックの必須設定が含まれていることを確認します。さらに、ネットワークアクセスコントロールリスト (ネットワーク ACL) のルール構成は、0.0.0.0/0 との送受信トラフィックをポート 80、443、および 1025 ～ 65535 で許可していることを確認します。

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

ワーカーノードの**[タグ]プロパティで、[Key]** を Kubernetes.io/cluster/clusterName ** に設定し、[Value]** を owned に設定します。

詳細については、「VPC の要件と考慮事項」を参照してください。

ワーカーノードが EKS クラスターの API サーバーエンドポイントに到達できるかどうかを確認します。

NAT またはインターネットゲートウェイ経由で API エンドポイントにルーティングされるルートテーブルに関連付けられたサブネット内で、ワーカーノードを起動します。制限付きのプライベートネットワークでワーカーノードを起動する場合は、ワーカーノードが EKS API サーバーエンドポイントに到達できることを確認します。AmazonProvidedDNS ではなく、カスタム DNS を使用する Amazon VPC でワーカーノードを起動した場合、ワーカーノードはエンドポイントを解決できない可能性があります。

注: エンドポイントへのパブリックアクセスが無効であり、プライベートアクセスのみが有効な場合、エンドポイントは解決されません。詳細については、「Amazon EKS クラスターエンドポイントで DNS 解決を有効にする」を参照してください。

kubelet が必要なエンドポイントに到達できるかどうかを確認する

kubelet がエンドポイントに到達できるかどうかをテストするには、次のコマンドを実行します。

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

$ nc -vz dkr.ecr.region.amazonaws.com 443

$ nc -vz api.ecr.region.amazonaws.com 443

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

注: region を実際のリージョンに置き換えてください。

クラスターロールが正しく構成されていることを確認する

AmazonEKSClusterPolicy を Amazon EKS クラスターの IAM ロールにアタッチする必要があります。さらに、クラスターの信頼関係は、eks.amazonaws.com サービスに sts:AssumeRole を許可する必要があります。

信頼ポリシーの例:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

リージョナル STS エンドポイントが有効であることを確認する

クラスターが STS エンドポイントをサポートするリージョンに配置されている場合は、kubelet の認証用にリージョナル STS エンドポイントを有効にします。この設定を行うと、kubelet がノードオブジェクトを作成できます。

AMI が EKS と連携するよう構成されており、AMI に必須コンポーネントが含まれていることを確認する

Amazon EKS 最適化 Amazon Linux AMI には、EKS クラスターとの連携に必要なコンポーネントが含まれています。ワーカーノードの AMI が Amazon EKS 最適化 Amazon Linux AMI ではない場合は、次の Kubernetes コンポーネントのステータスが Active であることを確認します。

• kubelet
• AWS IAM Authenticator
• Docker (Amazon EKS バージョン 1.23 以前)
• containerd

SSH を使用して EKS ワーカーノードのインスタンスに接続し、kubelet エージェントログを確認する

kubelet エージェントが EKS ワーカーノードのインスタンスで systemd サービスとして構成されていることを確認します。

kubelet ログを検証するには、次のコマンドを実行します。

journalctl -f -u kubelet

問題を解決方法については、「Amazon EKS クラスターとノードに関する問題のトラブルシューティング」を参照してください。

Amazon EKS ログコレクタースクリプトを使用してエラーをトラブルシューティングする

ログファイルとオペレーティングシステム (OS) ログを利用して Amazon EKS クラスターの問題をトラブルシューティングします。Amazon EKS クラスターのワーカーノードは、/var/log/cloud-init-output.log および /var/log/cloud-init.log に cloud-init 初期化ログを保存します。

EKS ログコレクタースクリプトを使用してログを収集するには、SSH を使用して問題が発生したワーカーノードに接続する必要があります。次に、以下のスクリプトを実行します。

curl -O https://raw.githubusercontent.com/awslabs/amazon-eks-ami/master/log-collector-script/linux/eks-log-collector.sh

sudo bash eks-log-collector.sh

ワーカーノードの Amazon VPC サブネットに空き IP アドレスがあることを確認する

Amazon VPC に空き IP アドレスがない場合は、セカンダリ CIDR を既存の Amazon VPC に関連付けることができます。詳細については、「VPC とサブネットの Amazon EKS ネットワーク要件を確認する」を参照してください。EKS 最適化 AMI には、EKS クラスターとの連携に必要なコンポーネントが含まれています。