排解 Amazon EKS 叢集和節點問題

此章節涵蓋一些您在使用 Amazon EKS 時可能遇到的常見錯誤，並提供解決方法。如果您需要針對特定 Amazon EKS 區域進行疑難排解，請參閱個別 疑難排解 IAM、排解 Amazon EKS 連接器問題 和針對使用 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 中的子網路來建立您的叢集，叢集 VPC 託管於此錯誤訊息傳回之可用區域之中。

有些可用區域是叢集無法駐留的。將子網路所在的可用區域與子網路要求與考量中的可用區域清單進行比較。

節點無法加入叢集

有幾個常見的原因會阻擋節點加入叢集：

若要識別和疑難排解導致 Worker 節點無法加入叢集的常見原因，您可以使用 AWSSupport-TroubleshootEKSWorkerNode Runbook。如需詳細資訊，請參閱 AWS Systems Manager 自動化執行手冊參考中的 AWSSupport-TroubleshootEKSWorkerNode 。

未經授權或存取遭拒 (kubectl)

如果您在執行 kubectl 命令時，收到以下其中一個錯誤，則表示未為 Amazon EKS 正確設定 kubectl，或者表示您使用的 IAM 主體 (角色或使用者) 憑證並未映射到對 Amazon EKS 叢集上的 Kubernetes 物件具有足夠許可的 Kubernetes 使用者名稱。

這種情況可能由下列原因之一造成：

安裝和設定 AWS CLI 時，您可以設定使用的 IAM 憑證。如需詳細資訊，請參閱《AWS 命令列介面使用者指南》中的設定 AWS CLI。如果您透過擔任 IAM 角色來存取叢集上的 Kubernetes 物件，則也可以將 kubectl 設定為使用 IAM 角色。如需詳細資訊，請參閱 透過建立 kubeconfig 檔案將 kubectl 連線至 EKS 叢集。

hostname doesn’t match

您的系統 Python 版本必須為 2.7.9 或更新版本。否則，對 Amazon EKS 發出 AWS CLI 呼叫時您會收到 hostname doesn’t match 錯誤。如需詳細資訊，請參閱 Python 請求常見問答集中的 什麼是「主機名稱不相符」錯誤？。

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 管理主控台 中收到錯誤 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 錯誤訊息的一個潛在原因是使用私有 Amazon EKS Windows AMI 啟動 Windows 受管節點群組。發布全新 Windows AMI 之後，AWS 會將超過 4 個月的 AMI 設定為私有，這會使其不再可供存取。如果您的受管節點群組使用私有 Windows AMI，請考慮更新 Windows 受管節點群組。雖然我們不能保證向已經設定為私有的 AMI 提供存取權，但您可藉由向 AWS Support 提交工單來請求存取權。如需詳細資訊，請參閱Amazon EC2 使用者指南中的修補程式。

節點進入 NotReady 狀態

若節點進入 NotReady 狀態，這可能表明節點狀況不佳，並且無法排程新的 Pod。發生這種情況可能出於各種原因，例如，節點缺少 CPU、記憶體或可用磁碟空間等充足的資源。

若是 Amazon EKS 最佳化 Windows AMI，依預設，kubelet 組態中不會保留運算資源。為協助避免資源問題，可向 kubelet 提供 kube-reserved 及/或 system-reserved 的組態值，藉此來為系統程序預留運算資源。您可使用引導指令碼中的 -KubeletExtraArgs 命令列參數來執行此動作。如需詳細資訊，請參閱《Kubernetes 文件》中的為系統常駐程式預留運算資源，以及本《使用者指南》中的 引導指令碼組態參數。

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 日誌獲取更多詳細資訊。

容器執行階段網路尚未就緒

您可能會收到類似下列的 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 伺服器端點。在控制平面中執行叢集滾動更新 (例如組態變更或版本更新) 的任何程序期間，也可能會暫時發生錯誤。

若要解決此問題，請檢查路由表和安全群組，以確保來自節點的流量可以到達公有端點。

InvalidClientTokenId

如果您使用針對部署至中國 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

若要解決此問題，您需要將 AWS_DEFAULT_REGION 環境變數新增至您的 Pod 或 Daemonset 規格，如下列範例 Pod 規格所示。

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 版本

在將控制平面更新為新的 Kubernetes 版本之前，您叢集中的 Kubernetes 次要版本的受管和 Fargate 節點必須要與控制平面目前版本的版本相同。在將所有 Amazon EKS 受管節點升級為目前的叢集版本前，Amazon EKS update-cluster-version API 都會拒絕請求。Amazon EKS 提供 API 來升級受管節點。如需升級受管節點群組的 Kubernetes 版本的資訊，請參閱 更新叢集的受管節點群組。若要升級 Fargate 節點的版本，請刪除節點所代表的 Pod，並在升級控制平面後重新部署 Pod。如需詳細資訊，請參閱 將現有叢集更新至全新 Kubernetes 版本。

啟動許多節點時，會出現 Too Many Requests 錯誤

如果同時啟動許多節點，您可能會 Amazon EC2 使用者資料執行日誌看見錯誤訊息，其顯示 Too Many Requests。這可能是因為控制平面因 describeCluster 呼叫超載。超載會導致調節、節點無法執行引導指令碼，以及節點無法完全加入叢集。

確認將 --apiserver-endpoint、--b64-cluster-ca 和 --dns-cluster-ip 引數傳遞至節點的引導指令碼。包含這些引數時，不需要引導指令碼進行 describeCluster 呼叫，這有助於防止控制平面超載。如需詳細資訊，請參閱 提供使用者資料將引數傳遞給 bootstrap.sh 檔案，其中包含 Amazon EKS 最佳化 Linux/Bottlerocket AMI。

針對 Kubernetes API 伺服器請求回應的 HTTP 401 未經授權的錯誤

如果叢集上的 Pod 服務帳戶字符已過期，您會看到這些錯誤。

您的 Amazon EKS 叢集的 Kubernetes API 伺服器拒絕使用超過 90 天的字符的請求。在 Kubernetes 舊版本中，字符沒有過期。這意味著倚賴這些字符的客户端必須在一小時內進行重新整理。為了防止 Kubernetes API 伺服器因無效字符而拒絕您的請求，您的工作負載使用的 Kubernetes 用戶端 SDK 版本必須與以下版本相同或為更新版本：

您可以識別叢集中所有使用過時字符的現有 Pod。如需詳細資訊，請參閱 服務帳戶字符。

Amazon EKS 平台版本比目前平台版本落後兩個版本以上

當 Amazon EKS 無法自動更新叢集的 platform-version 時，可能會發生這種情況。儘管造成這種情況的原因很多，然而一些常見的原因如下。如果這些問題中有任何一個適用於您的叢集，其可能仍然可以運作，但 Amazon EKS 不會更新其平台版本。

問題

該叢集 IAM 角色已刪除，此角色是在建立叢集時指定。您可以使用以下命令，查看指定了哪個角色。使用您叢集的名稱取代 my-cluster。

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

範例輸出如下。

eksClusterRole

解決方案

建立具有相同名稱的新叢集 IAM 角色。

問題

已刪除叢集建立期間指定的子網路 – 即叢集建立期間指定要與叢集搭配使用的子網路。您可以使用以下命令，查看指定了哪些子網路。使用您叢集的名稱取代 my-cluster。

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 更新叢集，則需要變更叢集使用的子網路。這是因為如果您在建立叢集時指定了兩個以上的子網路，Amazon EKS 會隨機選取您指定在其中建立新彈性網路介面的子網路。這些網路介面可讓控制平面與節點進行通訊。如果叢集選取的子網路不存在，Amazon EKS 將不會更新叢集。您無法控制 Amazon EKS 會從您於建立叢集時指定的子網路中選擇哪些在其中建立新網路介面。

當您啟動叢集的 Kubernetes 版本更新，該更新可能會因相同的原因而失敗。

問題

叢集建立期間指定的安全群組已刪除 – 如果您在叢集建立期間指定了安全群組，您可以使用下列命令查看其 ID。使用您叢集的名稱取代 my-cluster。

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 可偵測 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 命令列介面進行呼叫。

前兩欄是 API 回應值所需的內容。Health ClusterIssue 物件的第三個欄位是 Health ClusterIssue 物件，其傳回的值取決於問題類型。