ワーカーノードを Amazon EKS クラスターに参加させる方法を教えてください。

解決策

ワーカーノードを Amazon EKS クラスターに参加させるには、以下の手順を実行します。

**重要:**以下の手順には、以下の条件が満たされない環境にワーカーノードを登録するために必要な構成は含まれていません。

• クラスターの仮想プライベートクラウド (VPC) では、設定パラメータ domain-name-servers が AmazonProvidedDNS に設定されています。詳細については、「Amazon Virtual Private Cloud (Amazon VPC) の DHCP オプションセット」を参照してください。
• Amazon EKS に最適化された Linux Amazon マシンイメージ (AMI) を使用してワーカーノードを起動しています。Amazon EKS に最適化された Linux AMI には、/etc/eks/bootstrap.sh ブートストラップスクリプトなど、ワーカーノードをクラスターに登録するために必要なすべての設定が用意されています。

Systems Manager オートメーションのランブックを使用して、一般的な問題を特定する

AWS Support-TroubleshootEksWorkerNode ランブックを使用して、ワーカーノードがクラスターに参加できない一般的な問題を特定します。

重要: オートメーションを正しく機能させるには、AWS Systems Manager が稼働しており、ワーカーノードに Systems Manager へのアクセス許可が付与されている必要があります。AWS Systems Manager へのアクセス許可を付与するには、AmazonSSMManagedInstanceCore ポリシーを AWS Identity and Access Management (IAM) ロールにアタッチします。この IAM ロールは Amazon Elastic Compute Cloud (Amazon EC2) インスタンスプロファイルに対応しています。この構成は、eksctl を使用して作成する Amazon EKS マネージドノードグループのデフォルト設定でもあります。

クラスター名には次の形式を使用してください:[-a-zA-Z0-9]{1,100}$

次の手順を実行します。

1. ランブックを開きます。
2. AWS マネジメントコンソールの AWS リージョンがクラスターと同じリージョンに設定されていることを確認します。
   注:ランブックの詳細については、ランブックのドキュメント詳細セクションを参照してください。
3. 「入力パラメータ」セクションの「clusterName」フィールドにクラスターの名前を指定し、「WorkerID」フィールドに Amazon EC2 インスタンス ID を指定します。
4. **(オプション) ** AutomationAssumeRole フィールドで、システムマネージャーがアクションを実行できるようにする IAM ロールを指定します。指定しない場合、現在の IAM エンティティの IAM 権限を使用して Runbook 内のアクションを実行します。
5. [実行] を選択します。
6. [出力] セクションを確認して、ワーカーノードがクラスターに参加していない理由と、それを解決するための手順を確認します。

Amazon VPC が DNS をサポートしていることを確認する

EKS クラスターの Amazon VPC で DNS ホスト名と DNS 解決がオンになっているかを確認します。

これらの属性を確認してオンにするには、次の手順を実行してください。

1. Amazon VPC コンソールを開きます。
2. ナビゲーションペインで [Your VPC] を選択します。
3. 編集する VPC を選択します。
4. 「詳細」タブから、 DNS ホスト名と DNS 解決が有効になっているかどうかを確認します。
5. オンになっていない場合は、両方の属性で [有効にする] を選択します。
6. [変更の保存] を選択します。

詳細については、「View and update DNS attributes for your VPC」を参照してください。

インスタンスプロファイルのワーカーノードに適切な権限があることを確認する

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

• AmazonEKSWorkerNodePolicy
• AmazonEKS_CNI_Policy
• AmazonEC2ContainerRegistryReadOnly

ポリシーをロールにアタッチするには、「IAM ID 権限の追加 (コンソール)」を参照してください。

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

注: AWS CloudFormation を使用してワーカーノードを起動する場合、ワーカーノードでユーザーデータを設定する必要はありません。代わりに、AWS マネジメントコンソールの「自己管理型 Amazon Linux ノードを起動する」手順に従ってください。

マネージドノードグループを使用してワーカーノードを起動する場合、Amazon EKS に最適化された Amazon Linux AMI でユーザーデータを設定する必要はありません。カスタム AMI を使用してマネージドノードグループを通じてワーカーノードを起動する場合にのみ、ユーザーデータを設定する必要があります。

カスタム起動テンプレートで Amazon マネージドノードグループを使用している場合は、起動テンプレートに正しいユーザーデータを指定してください。Amazon EKS クラスターが VPC エンドポイントを使用して接続を行う完全専用クラスターである場合は、ユーザーデータに以下を指定します。

• certificate-authority
• api-server-endpoint
• DNS クラスターの IP アドレス

必要に応じて、Amazon EKS に最適化された Linux/Bottlerocket AMI に含まれている bootstrap.sh ファイルに引数を渡すためのユーザーデータを提供してください。

ワーカーノードのユーザーデータを設定するには、 Amazon EC2 インスタンスを起動するときにユーザーデータを指定します。

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

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

重要:

• **$ {clusterName} ** をご使用の EKS クラスターの名前に置き換えてください。
• **$ {bootstraParguments} ** を追加のブートストラップ値に置き換えるか、このプロパティを空白のままにしてください。

Amazon VPC サブネットにネットワークが正しく設定されているか確認する

• インターネットゲートウェイを使用する場合は、ルートテーブルに正しくアタッチされ、ヌルルートへのリダイレクトがないことを確認してください。
• NAT ゲートウェイを使用する場合は、パブリックサブネットで正しく設定されているかを確認してください。また、ルートテーブルにヌルルートが含まれていないかを確認してください。
• 完全プライベートクラスターに VPC プライベートエンドポイントを使用する場合は、次のエンドポイントがあることを確認してください。
  com.amazonaws.region.ec2 (インターフェイスエンドポイント)
  com.amazonaws.region.ecr.api (インターフェイスエンドポイント)
  com.amazonaws.region.ecr.dkr (インターフェイスエンドポイント)
  com.amazonaws.region.s3 (ゲートウェイエンドポイント)
  com.amazonaws.region.sts (インターフェイスエンドポイント)
• サービスアカウントの IAM ロールを使用して設定したポッドは、AWS セキュリティトークンサービス (AWS STS) API 呼び出しから認証情報を取得します。アウトバウンドのインターネットアクセスがない場合は、VPC に AWS STS VPC エンドポイントを作成して使用する必要があります。
• VPC エンドポイントのセキュリティグループには、ポート 443 からのトラフィックを許可するインバウンドルールが必要です。詳細については、「セキュリティグループを使用してリソースへのトラフィックを制御する」を参照してください。
• IAM ユーザーまたはロールにアタッチされているポリシーに必要なアクセス許可があることを確認します。

注: 他の AWS サービスを使用している場合は、上記のエンドポイントを作成する必要があります。「インターネットアクセスが制限されたプライベートクラスターのデプロイ」を参照し、一般的に使われるサービスとエンドポイントを確認してください。また、ユースケースに基づいてエンドポイントサービスを作成することもできます。

ワーカーノードが EKS クラスターと同じ Amazon VPC にあることを確認する

次の手順を実行します。

1. Amazon EKS コンソールを開きます。
2. [クラスター] を選択し、次にクラスターを選択します。
3. ネットワーキングセクションで、クラスターに関連付けられているサブネットを特定します。

**注:**ワーカーノードを起動するサブネットはさまざまな設定が可能です。サブネットは同じ Amazon VPC に存在し、適切にタグ付けされている必要があります。Amazon EKS は、クラスターの作成時に設定したサブネットのタグのみを自動的に管理します。そのため、サブネットには必ず適切なタグを付けてください。

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

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

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

aws-auth ConfigMap ファイルを確認するには、以下のコマンドを実行します。

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

ワーカーノードのセキュリティグループ要件を満たしてください

コントロールプレーンのセキュリティグループとワーカーノードセキュリティグループが、インバウンドとアウトバウンドトラフィックのベストプラクティス設定で構成されていることを確認します。また、カスタムネットワーク ACL ルールが、ポート 80 、443 、および 1025-65535 の 0.0.0.0/0 からのトラフィックを許可するように設定されていることを確認してください。

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

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

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

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

ルートテーブルに関連付けられているサブネットでワーカーノードを起動できることを確認します。ルートテーブルは、NAT またはインターネットゲートウェイ経由で API エンドポイントにルーティングする必要があります。

制限付きのプライベートネットワークでワーカーノードを起動する場合は、ワーカーノードが EKS API サーバーエンドポイントに到達できることを確認してください。

AmazonProvidedDNS ではなく、カスタム DNS を使用する Amazon VPC でワーカーノードを起動する場合、ノードがエンドポイントを解決できない場合があります。エンドポイントへのパブリックアクセスが非アクティブ化され、プライベートアクセスのみがアクティブ化されると、未解決のエンドポイントが発生します。詳細については、「Amazon EKS クラスターエンドポイントの DNS 解決を有効にする」を参照してください。

クラスターロールがクラスターに正しく設定されているかを確認します

クラスターには、AmazonEKSClusterPolicy の最低限の権限を持つクラスターロールが必要です。また、クラスターとの信頼関係によっては、eks.amazonaws.com サービスが sts:AssumeRole に対応している必要があります。以下はその例です。

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

詳細については、「Amazon EKS クラスター IAM ロール」を参照してください。

リージョナル STS エンドポイントがアクティブになっていることを確認する

クラスターが STS エンドポイントをサポートするリージョンにある場合は、リージョナル STS エンドポイントをアクティブ化して kubelet を認証します。そうすることで、kubelet はノードオブジェクトを作成できるようになります。

AMI が EKS と連携するよう設定されており、必要なコンポーネントが含まれていることを確認してください。

ワーカーノードに使用されている AMI が Amazon EKS に最適化された Amazon Linux AMI ではない場合、次の Kubernetes コンポーネントがアクティブな状態であることを確認してください。

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

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

kubelet エージェントは systemd サービスとして設定されています。

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

journalctl -f -u kubelet

問題を解決するには、Amazon EKS トラブルシューティングガイドで一般的なエラーを確認してください。

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

ログファイルとオペレーティングシステムログを使用して Amazon 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 EKS マネージドノードグループの作成におけるエラーをトラブルシューティングする方法を教えてください