Amazon EKS クラスターとノードに関する問題をトラブルシューティングする

この章では、Amazon EKS の使用中に表示される一般的なエラーとその回避方法について説明します。特定の Amazon EKS 領域のトラブルシューティングが必要な場合、別の IAM のトラブルシューティング、Amazon EKS Connector の問題をトラブルシューティングする、および「EKS アドオンを使用した ADOT のトラブルシューティング」を参照してください。

その他のトラブルシューティング情報についてはAWS re:Post の「Amazon Elastic Kubernetes Service に関するナレッジセンターのコンテンツ」を参照してください。

容量不足

Amazon EKS クラスターを作成しようとするときに次のエラーが表示された場合、指定したいずれかのアベイラビリティーゾーンに、クラスターをサポートするための十分な容量がありません。

Cannot create cluster 'example-cluster' because region-1d, the targeted Availability Zone, does not currently have sufficient capacity to support the cluster. Retry and choose from these Availability Zones: region-1a, region-1b, region-1c

このエラーメッセージによって返されるアベイラビリティーゾーンでホストされているクラスター VPC 内のサブネットを使用して、クラスターを再作成してください。

クラスターを配置できないアベイラビリティーゾーンがあります。サブネットが属するアベイラビリティーゾーンを、サブネットの要件と考慮事項内のアベイラビリティーゾーンのリストと比較してください。

ノードをクラスターに結合できません

ノードをクラスターに結合できない一般的な理由はいくつかあります。

ワーカーノードがクラスターに参加できない一般的な原因を特定してトラブルシューティングするにはAWSSupport-TroubleshootEKSWorkerNode ランブックを使用できます。詳細についてはAWS システム・マネージャー Automation ランブックリファレンスの「 AWSSupport-TroubleshootEKSWorkerNode 」を参照してください。

許可されていないか、アクセスが拒否されました (kubectl)

kubectl コマンドの実行中に次のいずれかのエラーが発生した場合は、kubectl が Amazon EKS に対して適切に設定されていないか、使用している IAM プリンシパルの認証情報 (役割またはユーザー) が、Amazon EKS クラスターで Kubernetes オブジェクトに対して十分なアクセス許可を持つ Kubernetes ユーザー名にマッピングされていません。

この原因としては次のいずれかが考えられます。

AWS CLI をインストールして設定する場合は使用する IAM 認証情報を設定できます。詳細についてはAWS コマンドラインインターフェイスユーザーガイドの「AWS CLI を設定する」を参照してください。クラスター上の Kubernetes オブジェクトにアクセスする IAM ロールを引き受ける場合は、IAM ロールを使用するように kubectl を設定することもできます。詳細については、「kubeconfig ファイルを作成して kubectl を EKS クラスターに接続する」を参照してください。

hostname doesn’t match

システムの Python のバージョンは 2.7.9 以降であることが必要です。それ以外の場合はAWS CLI で Amazon EKS を呼び出すと hostname doesn’t match エラーが表示されます。詳細については「Python Requests のよくある質問」の「What are "hostname doesn't match" errors?｣ (ホスト名の不一致」エラーとは) を参照してください。

getsockopt: no route to host

Docker は Amazon EKS クラスターの 172.17.0.0/16 CIDR 範囲で実行されます。クラスターの VPC サブネットがこの範囲と重ならないようにすることをお勧めします。重なっている場合は以下のエラーが発生します。

Error: : error upgrading connection: error dialing backend: dial tcp 172.17.<nn>.<nn>:10250: getsockopt: no route to host

Instances failed to join the Kubernetes cluster

AWS Management Console で Instances failed to join the Kubernetes cluster エラーが表示された場合、クラスターのプライベートエンドポイントアクセスが有効になっているか、パブリックエンドポイントアクセス用に CIDR ブロックが正しく設定されていることを確認します。詳細については「クラスター API サーバーエンドポイントへのネットワークアクセスを制御する」を参照してください。

マネージド型ノードグループのエラー

マネージド型ノードグループでハードウェアのヘルスに問題が発生した場合は Amazon EKS によって問題の診断に役立つエラーメッセージが返されます。これらのヘルスチェックは Amazon EC2 ヘルスチェックに基づいているため、ソフトウェアの問題は検出されません。次のリストはエラーコードについての説明です。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

kubectl describe clusterrole eks:node-manager

kubectl describe clusterrolebinding eks:node-manager

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

kubectl apply -f eks-node-manager-role.yaml

Not authorized for images

Not authorized for images エラーメッセージの考えられる原因の 1 つは、プライベート Amazon EKS Windows AMI を使用して Windows マネージドノードグループを起動することです。新しい Windows AMI をリリースすると、AWS は 4 か月以上前の AMI を非公開にし、アクセス不可にします。マネージドノードグループがプライベート Windows AMI を使用している場合は、Windows マネージドノードグループを更新することを検討してください。非公開になった AMI へのアクセスを可能にできるかは保証できませんが、AWS サポートにチケットを提出することでアクセスをリクエストできます。詳細については「Amazon EC2 ユーザーガイド」の「パッチ」を参照してください。

ノードが NotReady 状態です

ノードが NotReady 状態になった場合は、そのノードに異常があり、新しい Pod をスケジュールできない可能性があります。これはノードに CPU、メモリ、利用可能なディスクスペースの十分なリソースがないなど、さまざまな理由で発生します。

Amazon EKS 最適化 Windows AMI の場合、kubelet 設定のデフォルトではコンピューティングリソースの予約は指定されていません。リソースの問題を防ぐために、kubelet に kube-reserved および/または system-reserved の設定値を指定することで、システムプロセスのコンピューティングリソースを予約できます。これを行うにはブートストラップスクリプトの -KubeletExtraArgs コマンドラインパラメータを使用します。詳細については、Kubernetes ドキュメントの「Reserve Compute Resources for System Daemons」、およびこのユーザーガイドの「ブートストラップスクリプトの設定パラメータ」を参照してください。

EKS ログコレクター

Amazon EKS ノードの問題をトラブルシューティングするために、ノード上の /etc/eks/log-collector-script/eks-log-collector.sh に構築済みのスクリプトが用意されています。このスクリプトを使用して、サポートケースおよび一般的なトラブルシューティングの診断ログを収集できます。

ノードでスクリプトを実行するには次のコマンドを使用します。

sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

curl -O https://amazon-eks.s3.amazonaws.com/support/log-collector-script/linux/eks-log-collector.sh
sudo bash eks-log-collector.sh

このスクリプトは次の診断情報を収集します。

$ sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

      This is version 0.7.8. New versions can be found at https://github.com/awslabs/amazon-eks-ami/blob/main/log-collector-script/

Trying to collect common operating system logs...
Trying to collect kernel logs...
Trying to collect mount points and volume information...
...
...

	Done... your bundled logs are located in /var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

診断情報が収集され、以下に保存されます。

/var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

Bottlerocket ノードのログバンドルを取得するには、「Bottlerocket Log」で詳細を参照してください。

コンテナランタイムネットワークの準備ができていません

以下のような Container runtime network not ready エラーと承認エラーが表示される場合があります。

4191 kubelet.go:2130] Container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized
4191 kubelet_node_status.go:106] Unable to register node "ip-10-40-175-122.ec2.internal" with API server: Unauthorized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized

これは次のいずれかの理由で発生します。

TLS ハンドシェイクタイムアウト

ノードがパブリック API サーバーエンドポイントへの接続を確立できない場合、次のようなエラーが発生する可能性があります。

server.go:233] failed to run Kubelet: could not init cloud provider "aws": error finding instance i-1111f2222f333e44c: "error listing AWS instances: \"RequestError: send request failed\\ncaused by: Post  net/http: TLS handshake timeout\""

kubelet プロセスはAPI サーバーエンドポイントを継続的に再生成およびテストします。このエラーはコントロールプレーンでクラスターのローリング更新を行う手順 (設定の変更やバージョンの更新など) で一時的に発生することもあります。

この問題を解決するにはルートテーブルとセキュリティグループを確認して、ノードからのトラフィックがパブリックエンドポイントに到達できることを確認します。

無効なクライアントトークンID

中国 AWS リージョンでクラスターにデプロイされている Pod または DaemonSet 用サービスアカウントの IAM ロールを使用していて、仕様に AWS_DEFAULT_REGION 環境変数を設定していない場合、Pod または DaemonSet に次のエラーが表示されることがあります。

An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid

この問題を解決するには、次の Pod の仕様例に示すように、AWS_DEFAULT_REGION 環境変数を Pod または DaemonSet の仕様に追加する必要があります。

apiVersion: v1
kind: Pod
metadata:
  name: envar-demo
  labels:
    purpose: demonstrate-envars
spec:
  containers:
  - name: envar-demo-container
    image: gcr.io/google-samples/node-hello:1.0
    env:
    - name: AWS_DEFAULT_REGION
      value: "region-code"

コントロールプレーンをアップグレードする前に、ノードグループが Kubernetes バージョンと一致する必要があります

クラスター内の、マネージドノードと Fargate ノードのマイナーバージョンは、コントロールプレーンを新しい Kubernetes バージョンにアップグレードする前に、コントロールプレーンの現在のバージョンと同じにする必要があります。Amazon EKS update-cluster-version API はすべての EKS マネージド型ノードが現在のクラスターバージョンにアップグレードされるまで、リクエストを拒否します。Amazon EKS はマネージド型ノードをアップグレードするための API を提供します。マネージドノードグループの Kubernetes バージョンのアップグレードについては、「クラスターのためにマネージドノードグループを更新する」を参照してください。Fargate ノードのバージョンをアップグレードするには、ノードによって表されるポッドを削除し、コントロールプレーンをアップグレードした後にポッドを再デプロイします。詳細については、「既存のクラスターを新しい Kubernetes バージョンに更新する」を参照してください。

多数のノードを起動すると、Too Many Requests エラーが発生します。

多数のノードを同時に起動すると、Amazon EC2 ユーザーデータの実行ログに「Too Many Requests」というエラーメッセージが表示される場合があります。これはコントロールプレーンが describeCluster 呼び出しで過負荷になっているために発生する可能性があります。過負荷が原因で、スロットリングが発生し、ノードがブートストラップスクリプトを実行できなくなり、ノードが完全にクラスターに参加できなくなります。

--apiserver-endpoint、--b64-cluster-ca、および --dns-cluster-ip 引数がノードのブートストラップスクリプトに渡されていることを確認してください。これらの引数を含める場合、ブートストラップスクリプトが describeCluster 呼び出しを行う必要がなくなり、コントロールプレーンが過負荷になるのを防ぐのに役立ちます。詳細については、「Amazon EKS に最適化された Linux/Bottlerocket AMI に含まれる bootstrap.sh ファイルに引数を渡すためのユーザーデータを提供する」を参照してください。

Kubernetes API サーバーリクエストに対する HTTP 401 Unauthorized エラーレスポンス

これらのエラーは、Pod のサービスアカウントトークンがクラスターで期限切れになった場合に表示されます。

Amazon EKS クラスターの Kubernetes API サーバーでは、90 日を超えるトークンによるリクエストが拒否されます。以前の Kubernetes バージョンでは、トークンに有効期限はありませんでした。つまり、これらのトークンに依存しているクライアントは、1 時間以内にトークンを更新する必要があります。無効なトークンが原因で Kubernetes API サーバーによりリクエストが拒否されないようにするには、ワークロードで使用されている Kubernetes クライアント SDK バージョンを、次のバージョンと同じか、それ以降にする必要があります。

古いトークンを使用しているクラスター内の既存の Pod をすべて特定できます。詳細については、「サービスアカウントトークン」を参照してください。

Amazon EKS プラットフォームのバージョンは現在のプラットフォーム バージョンより 2 つ以上遅れています

これはAmazon EKS がクラスターのプラットフォームバージョン.を自動的に更新できない場合に発生する可能性があります。これには多くの原因がありますが、一般的な原因のいくつかが続きます。これらの問題のいずれかがクラスターに当てはまる場合、それはまだ機能する可能性がありますが、そのプラットフォームバージョンは Amazon EKS によって更新されません。

問題

クラスターIAM役割 が削除されました - この役割はクラスターの作成時に指定されました。次のコマンドで、どの役割が指定されたかを確認できます。マイクラスター の部分は自分のクラスター名に置き換えます。

aws eks describe-cluster --name my-cluster --query cluster.roleArn --output text | cut -d / -f 2

出力例は次のとおりです。

eksClusterRole

ソリューション

同じ名前で新しい クラスター IAM 役割 を作成します。

問題

クラスターの作成中に指定されたサブネットが削除されました - クラスターで使用するサブネットはクラスターの作成中に指定されました。次のコマンドで、指定されたサブネットを確認できます。マイクラスター の部分は自分のクラスター名に置き換えます。

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.subnetIds

出力例は次のとおりです。

[
"subnet-EXAMPLE1",
"subnet-EXAMPLE2"
]

ソリューション

アカウントにサブネット ID が存在するかどうかを確認します。

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-subnets --filters "Name=vpc-id,Values=$vpc_id" --query "Subnets[*].SubnetId"

出力例は次のとおりです。

[
"subnet-EXAMPLE3",
"subnet-EXAMPLE4"
]

出力で返されたサブネット ID が、クラスターの作成時に指定されたサブネット ID と一致しない場合、Amazon EKS でクラスターを更新するにはクラスターで使用されるサブネットを変更する必要があります。これはクラスターの作成時に 2 つ以上のサブネットを指定した場合、Amazon EKS は指定したサブネットをランダムに選択して新しいエラスティックネットワークインターフェイスを作成するためです。これらのネットワーク インターフェイスにより、コントロールプレーンはノードと通信できます。Amazon EKS は選択したサブネットが存在しない場合、クラスターを更新しません。Amazon EKS が新しいネットワーク インターフェイスを作成するために選択する、クラスターの作成時に指定したサブネットをコントロールすることはできません。

クラスターの Kubernetes バージョンの更新を開始すると、同じ理由で更新が失敗する可能性があります。

問題

クラスターの作成中に指定されたセキュリティグループが削除されました - クラスターの作成中にセキュリティグループを指定した場合は次のコマンドでそれらの ID を確認できます。マイクラスター の部分は自分のクラスター名に置き換えます。

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.securityGroupIds

出力例は次のとおりです。

[
    "sg-EXAMPLE1"
]

[] が返された場合、クラスターの作成時にセキュリティグループが指定されておらず、セキュリティグループの欠落は問題ではありません。セキュリティグループが返された場合はセキュリティグループがアカウントに存在することを確認します。

ソリューション

これらのセキュリティグループがアカウントに存在するかどうかを確認します。

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-security-groups --filters "Name=vpc-id,Values=$vpc_id" --query "SecurityGroups[*].GroupId"

出力例は次のとおりです。

[
"sg-EXAMPLE2"
]

出力で返されたセキュリティグループ ID が、クラスターの作成時に指定されたセキュリティグループ ID と一致しない場合、Amazon EKS でクラスターを更新するにはクラスターで使用されるセキュリティグループを変更する必要があります。クラスターの作成時に指定されたセキュリティグループ ID が存在しない場合、Amazon EKS はクラスターを更新しません。

クラスターの Kubernetes バージョンの更新を開始すると、同じ理由で更新が失敗する可能性があります。

クラスターの正常性に関するよくある質問およびエラーコードと解決パス

Amazon EKS は EKS クラスターとクラスターインフラストラクチャの問題を検出し、クラスターヘルスに保存します。クラスターヘルスの情報を利用することで、クラスターの問題をより迅速に検出、トラブルシューティング、対処できます。これにより、より安全で最新のアプリケーション環境を構築できます。さらに、必要なインフラストラクチャまたはクラスター設定に問題があるため、Kubernetes の新しいバージョンにアップグレードしたり、Amazon EKS が劣化したクラスターにセキュリティ更新をインストールしたりできない場合があります。Amazon EKS は問題を検出したり、問題が解決されたことを検出したりするまでに 3 時間かかる場合があります。

Amazon EKS クラスターの状態は Amazon EKS とそのユーザー間で共有される責任です。IAM 役割や Amazon VPC サブネットの前提となるインフラストラクチャ、および事前に提供する必要があるその他の必要なインフラストラクチャはお客様の責任となります。Amazon EKS はこのインフラストラクチャとクラスターの設定の変更を検出します。

Amazon EKS コンソールでクラスターの状態にアクセスするには Amazon EKS クラスター詳細ページの [概要] タブにある [ヘルスの問題] というセクションを探してください。このデータはEKS API の DescribeCluster アクションを、例えば AWS コマンドラインインターフェイス内から呼び出すことでも使用できます。

最初の 2 つの列は API レスポンス値に必要なものです。Health ClusterIssue オブジェクトの 3 番目のフィールドは resourceIds で、返される値は課題タイプによって異なります。