Amazon EKS クラスターとノードグループに関する eksctl の問題をトラブルシューティングするにはどうすればよいですか?

簡単な説明

eksctl を使用して Amazon EKS クラスターまたはノードグループを作成または管理するときに発生する可能性がある一般的な問題は次のとおりです。

• eksctl を使用してクラスターを作成する方法がわからない。「Amazon EKS の開始方法 – eksctl」および「Amazon EKS クラスターの作成」の「eksctl」のセクションを参照してください。
• マネージドノードグループに kubelet ブートストラップオプションを指定する方法がわからない。解決方法の kubelet ブートストラップオプションを指定するのセクションの手順に従います。
• 既存のノードグループのインスタンスタイプを変更する方法がわからない。新しいノードグループを作成する必要があります。「新しいノードグループへの移行」および「Nodegroup immutability」(Nodegroup のイミュータビリティ) (eksctl ウェブサイト) を参照してください。
• AWS リソースの最大数に達した。リソースをチェックして、使用していないリソースを削除できるかどうかを確認してください。さらに容量が必要な場合は、Requesting a quota increase を参照してください。
• 容量が限られているアベイラビリティーゾーンでコントロールプレーンインスタンスを起動している。「Amazon EKS でクラスター作成エラーを解決する方法を教えてください」を参照してください。
• ノードが [Ready] (準備完了) 状態に移行しない。解決方法の操作タイムアウトに関する問題を解決するのセクションの手順に従います。
• クラスターにエクスポート値が存在しない。解決方法のプライベートサブネットでノードグループを作成するのセクションの手順に従います。
• サポートされていないインスタンスタイプを使用してクラスターまたはノードグループを作成した。解決方法のインスタンスタイプがサポートされているか確認するのセクションの手順に従います。

解決方法

kubelet ブートストラップオプションを指定する

デフォルトでは、eksctl はブートストラップスクリプトを作成し、ブートストラッププロセス中にワーカーノードが実行する起動テンプレートに追加します。独自の kubelet ブートストラップオプションを指定するには、overrideBootstrapCommand 仕様を使用して eksctl ブートストラップスクリプトをオーバーライドします。overrideBootstrapCommand は、マネージドノードグループとセルフマネージドノードグループに使用します。

設定ファイルの仕様:

managedNodeGroups:
  name: custom-ng
  ami: ami-0e124de4755b2734d
  securityGroups:
    attachIDs: ["sg-1234"]
  maxPodsPerNode: 80
  ssh:
    allow: true
  volumeSize: 100
  volumeName: /dev/xvda
  volumeEncrypted: true
  disableIMDSv1: true
  overrideBootstrapCommand: |
  #!/bin/bash
  /etc/eks/bootstrap.sh managed-cluster --kubelet-extra-args '--node-labels=eks.amazonaws.com/nodegroup=custom-ng,eks.amazonaws.com/nodegroup-image=ami-0e124de4755b2734d'

注: overrideBootstrapCommand を使用できるのは、カスタム AMI を使用する場合のみです。AMI ID を指定しない場合、クラスターの作成は失敗します。

カスタム AMI ID が指定されなかった

マネージドノードグループの作成時にカスタム AMI ID を指定しない場合、Amazon EKS はデフォルトで Amazon EKS 最適化 AMI およびブートストラップスクリプトを使用します。Amazon EKS 最適化 AMI をカスタムユーザーデータとともに使用してブートストラップパラメータを指定するには、マネージドノードグループ設定で AMI ID を指定します。

最新の Amazon EKS 最適化 AMI の最新の AMI ID を取得するには、次のコマンドを実行します。

aws ssm get-parameter --name /aws/service/eks/optimized-ami/1.21/amazon-linux-2/recommended/image_id --region Region --query "Parameter.Value" --output text

注: Region を、ご利用の AWS リージョンに置き換えます。

オペレーションタイムアウトに関する問題を解決する

ノードの作成時に次のエラーが表示される場合は、ノードグループにタイムアウトの問題がある可能性があります。

waiting for at least 1 node(s) to become ready in "nodegroup"

eksctl で EKS ノードグループを作成すると、eksctl CLI は API サーバーに接続し、Kubernetes ノードのステータスを継続的にチェックします。CLI はノードが [Ready] (準備完了) 状態に移行するのを待ち、ノードが移行に失敗すると最終的にタイムアウトします。

ノードが [Ready] (準備完了) 状態に移行しない理由は次のとおりです。

• Kubelet が、ブートストラッププロセス中に EKS API サーバーエンドポイントと通信または認証できない。
• aws-node および kube-proxy ポッドが [Running] (実行中) 状態ではない。
• Amazon Elastic Compute Cloud (Amazon EC2) ワーカーノードのユーザーデータが正常に実行されなかった。

kubelet が EKS API サーバーエンドポイントと通信できない

kubelet がブートストラッププロセス中に EKS API サーバーエンドポイントと通信できない場合は、EKS API サーバーエンドポイントを取得します。

ワーカーノードで次のコマンドを実行します。

curl -k https://123456DC0A12EC12DE0C12BC312FCC1A.yl4.us-east-1.eks.amazonaws.com
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    
  },
  "status": "Failure",
  "message": "forbidden: User \"system:anonymous\" cannot get path \"/\"",
  "reason": "Forbidden",
  "details": {
    
  },
  "code": 403
}

前述のコマンドは HTTP 403 ステータスコードを返すはずです。コマンドがタイムアウトした場合は、EKS API サーバーとワーカーノード間のネットワーク接続に問題がある可能性があります。

接続の問題を解決するには、ユースケースに関連する次のいずれかの手順を実行します。

• ワーカーノードがプライベートサブネットにある場合は、EKS API サーバーエンドポイントが [Private] (プライベート) または [Public and Private access] (パブリックおよびプライベートアクセス) モードになっていることを確認します。
• EKS API サーバーエンドポイントが [Private] (プライベート) に設定されている場合は、プライベートホストゾーンに特定のルールを適用して API サーバーにトラフィックをルーティングする必要があります。Amazon Virtual Private Cloud (Amazon VPC) の属性である enableDnsHostnames および enableDnsSupport は True に設定する必要があります。また、Amazon VPC 用に設定された DHCP オプションは、そのドメインリストに AmazonProvideDNS を含んでいる必要があります。
• パブリックサブネットにノードグループを作成した場合は、サブネットの IPv4 パブリックアドレス属性が True に設定されていることを確認します。属性を True に設定しない場合、ワーカーノードにはパブリック IP アドレスが割り当てられず、インターネットにアクセスできません。
• Amazon EKS クラスターのセキュリティグループが、ワーカーノードのセキュリティグループからポート 443 へのイングレスリクエストを許可しているかどうかを確認します。

kubelet が EKS API サーバーエンドポイントで認証できない

ブートストラッププロセス中に kubelet が EKS API サーバーエンドポイントで認証できない場合は、次の手順を実行します。

1.    次のコマンドを実行して、ワーカーノードが STS エンドポイントにアクセスできることを確認します。

telnet sts.region.amazonaws.com 443

注: region を AWS リージョンに置き換えます。

2.    ワーカーノードの AWS Identity and Access Management (IAM) ロールが aws-auth ConfigMap に追加されていることを確認します。

例:

apiVersion:v1 kind:ConfigMap metadata:name:aws-auth namespace:kube-system data:mapRoles:|
    - rolearn: ARN of instance role (not instance profile)
      username: system:node:{EC2PrivateDNSName}}
      groups:
        - system:bootstrappers
        - system:nodes

注: Microsoft Windows ノードグループの場合、ノードグループ IAM ロールの mapRoles セクションに eks:kube-proxy-windows RBAC グループをさらに追加する必要があります。

aws-node および kube-proxy ポッドが [Running] (実行中) 状態ではない

aws-node および kube-proxy ポッドが [Running] (実行中) 状態であるかどうかを確認するには、次のコマンドを実行します。

kubectl get pods -n kube-system

aws-node ポッドが [Failing] (失敗) 状態の場合は、ワーカーノードと Amazon EC2 エンドポイント間の接続を確認します。

ec2.region.amazonaws.com

注: region を AWS リージョンに置き換えます。

AWS マネージドポリシーである AmazonEKSWorkerNodePolicy および AmazonEC2ContainerRegistryReadOnly がノードグループの IAM ロールにアタッチされていることを確認します。

ノードがプライベートサブネット内にある場合、Amazon ECR VPC エンドポイントが Amazon Elastic Container Registry (Amazon ECR) からのイメージのプルを許可するように設定します。

Amazon VPC CNI に IRSA を使用する場合は、AmazonEKS_CNI_Policy AWS マネージドポリシーを aws-node ポッドが使用する IAM ロールにアタッチします。また、IRSA を使用せずにノードグループの IAM ロールにポリシーをアタッチする必要もあります。

EC2 ワーカーノードのユーザーデータが正常に実行されなかった

ユーザーデータの実行時にエラーが発生したかどうかを確認するには、/var/log/cloud-init.log と /var/log/cloud-init-output.log にある cloud-init ログを確認します。

詳細については、ワーカーノードで EKS Logs Collector スクリプトを実行してください。

プライベートサブネットでノードグループを作成する

ノードグループの作成時に次のエラーが表示される場合は、プライベートサブネットにノードグループを作成します。

No export named eksctl--cluster::SubnetsPublic found. Rollack requested by user

PrivateOnly ネットワークで Amazon EKS クラスターを作成した場合、AWS CloudFormation はパブリックサブネットを作成できません。これは、パブリックサブネットについてエクスポート値が存在しないことを意味します。クラスターについてエクスポート値が存在しない場合、ノードグループの作成は失敗します。

この問題を解決するには、eksctl インラインコマンドを使用する際に --node-private-networking フラグを含めることができます。ノードグループ設定内で privateNetworking: true 仕様を使用して、プライベートサブネットでのノードグループの作成をリクエストすることもできます。

eksctl のバージョンを更新する、または正しい AWS リージョンを指定する

次のエラーが表示された場合は、ご利用の AWS リージョンを確認してください。

no eksctl-managed CloudFormation stacks found for "cluster-name"

0.40.0 より前の eksctl バージョンを使用する場合、eksctl で作成した Amazon EKS リソースのみを表示または管理できます。eksctl で作成されなかったリソースを管理するには、eksctl をバージョン 0.40.0 以降に更新します。eksctl で作成されていないクラスターに実行できるコマンドについては、Non eksctl-created clusters (eksctl ウェブサイト) を参照してください。

また、間違った AWS リージョンを指定した場合、eksctl マネージドの CloudFormation スタックは見つかりません。この問題を解決するには、Amazon EKS リソースが配置されている正しいリージョンを指定してください。

インスタンスタイプがサポートされているか確認する

サポートされていないインスタンスタイプを使用してクラスターまたはノードを作成した場合、次のエラーが表示されます。

You must use a valid fully-formed launch template. The requested configuration is currently not supported. Please check the documentation for supported configurations'

インスタンスタイプやその他の設定が特定の AWS リージョンでサポートされているかどうかを確認するには、次のコマンドを実行します。

aws ec2 describe-instance-type-offerings --region Region --query 'InstanceTypeOfferings[*].{InstanceType:InstanceType}'

注: Region を、ご利用の AWS リージョンに置き換えます。

---