**帮助改进此页面** 要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。 # 排查 Amazon EKS 集群和节点问题 本章介绍使用 Amazon EKS 时可能遇到的一些常见错误以及相应的错误处理方式。如果您需要对特定的 Amazon EKS 区域进行问题排查，请参阅单独的 [IAM 故障排除](security-iam-troubleshoot.md)、[排查 Amazon EKS Connector 问题](troubleshooting-connector.md)，以及[使用 EKS 插件对 ADOT 进行问题排查](https://aws-otel.github.io/docs/getting-started/adot-eks-add-on/troubleshooting)主题。 有关其它故障排除信息，请参阅 *AWS re:Post* 上的有关 [Amazon Elastic Kubernetes Service 的知识中心内容](https://repost.aws/tags/knowledge-center/TA4IvCeWI1TE66q4jEj4Z9zg/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 中使用此错误消息所返回的可用区中托管的子网重新尝试创建集群。 有些可用区是集群无法驻留的。将子网所在的可用区与[子网要求和注意事项](network-reqs.md#network-requirements-subnets)中的可用区列表进行比较。 ## 节点未能加入集群 有几种常见原因会阻止节点加入集群： + 如果节点是托管节点，Amazon EKS 会在您创建节点组时向 `aws-auth` `ConfigMap` 中添加条目。如果该条目已被移除或修改，则需要重新添加该条目。要了解更多信息，请在您的终端中输入 `eksctl create iamidentitymapping --help`。您可以通过将以下命令中的 *my-cluster* 替换为集群名称，然后运行修改后的命令来查看当前的 `aws-auth` `ConfigMap` 条目：`eksctl get iamidentitymapping --cluster my-cluster `。您指定的角色的 ARN 不能包含 `/` 之外的[路径](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)。例如，假设角色名称为 `development/apps/my-role`，则需要在为该角色指定 ARN 时将其更改为 `my-role`。确保指定了节点 IAM 角色 ARN（非实例配置文件 ARN）。 如果节点是自主管理型的，并且您尚未为该节点的 IAM 角色的 ARN 创建[访问条目](access-entries.md)，请运行与托管式节点列出的相同命令。如果您为节点 IAM 角色的 ARN 创建了访问条目，则可能无法在访问条目中正确配置该条目。确保将节点 IAM 角色 ARN（非实例配置文件 ARN）指定为 `aws-auth` `ConfigMap` 条目或访问条目中的主体 ARN。有关访问条目的更多信息，请参阅 [使用 EKS 访问条目向 IAM 用户授予 Kubernetes 访问权限](access-entries.md)。 + 节点 AWS CloudFormation 模板中的 **ClusterName** 与您希望节点加入的集群的名称不完全匹配。将不正确的值传递到此字段会导致节点的 `/var/lib/kubelet/kubeconfig` 文件配置不正确，并且节点将无法加入集群。 + 节点不会标记为由集群*拥有*。您的节点必须应用了以下标签，其中的 *my-cluster* 替换为集群的名称。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/eks/latest/userguide/troubleshooting.html) + 节点可能无法使用公有 IP 地址访问集群。确保向部署在公有子网中的节点分配了公有 IP 地址。如果没有分配，您可以在节点启动后为其关联弹性 IP 地址。有关更多信息，请参阅[将弹性 IP 地址与正在运行的实例或网络接口关联](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html#using-instance-addressing-eips-associating)。如果公有子网未设置为自动将公有 IP 地址分配给部署到其中的实例，我们建议启用该设置。有关更多信息，请参阅[修改子网的公有 IPv4 寻址属性](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html#subnet-public-ip)。如果节点部署到私有子网，则该子网必须具有指向分配了公有 IP 地址的 NAT 网关的路由。 + 您的账户未启用节点部署所在 AWS 区域的 AWS STS 端点。要启用该区域，请参阅[在 AWS 区域中激活和停用 AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)。 + 节点没有私有 DNS 条目，从而导致 `kubelet` 日志中包含 `node "" not found` 错误。确保创建节点的 VPC 在 `DHCP options set` 中以 `Options` 的形式设置了 `domain-name` 和 `domain-name-servers` 的值。默认值为 `domain-name:.compute.internal` 和 `domain-name-servers:AmazonProvidedDNS`。有关更多信息，请参阅《Amazon VPC 用户指南》**中的 [DHCP 选项集](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS)。 + 如果托管节点组中的节点未在 15 分钟内连接到集群，则将发出运行状况问题“NodeCreationFailure”，控制台状态将设置为 `Create failed`。对于启动时间较慢的 Windows AMI，可以使用[快速启动](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/win-ami-config-fast-launch.html)来解决此问题。 要确定导致 Worker 节点无法加入集群的常见原因并进行问题排查，您可以使用 `AWSSupport-TroubleshootEKSWorkerNode` 运行手册。有关更多信息，请参阅 *AWS Systems Manager 自动化运行手册参考*中` [AWSSupport-TroubleshootEKSWorkerNode](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-troubleshooteksworkernode.html) `。 ## 未经授权或访问被拒绝 (`kubectl`) 如果您在运行 `kubectl` 命令时收到以下错误之一，则说明您未针对 Amazon EKS 正确配置 `kubectl`，或您使用的 IAM 主体（角色或用户）的凭证未映射到对 Amazon EKS 集群上的 Kubernetes 对象具有足够权限的 Kubernetes 用户名。 + `could not get token: AccessDenied: Access denied` + `error: You must be logged in to the server (Unauthorized)` + `error: the server doesn’t have a resource type "svc"` 这可能是由以下原因之一导致的： + 集群是使用一个 IAM 主体的凭证创建的，并且 `kubectl` 配置为使用另一个 IAM 主体的凭证。要解决此问题，请更新您的 `kube config` 文件以使用创建集群的凭证。有关更多信息，请参阅 [通过创建 kubeconfig 文件将 kubectl 连接到 EKS 集群](create-kubeconfig.md)。 + 如果集群满足[使用 EKS 访问条目向 IAM 用户授予对 Kubernetes 的访问权限](access-entries.md)的先决条件部分中的最低平台要求，则 IAM 主体中不存在访问条目。如果存在，则说明没有为其定义必要的 Kubernetes 组名称，或者没有与之关联的正确访问策略。有关更多信息，请参阅 [使用 EKS 访问条目向 IAM 用户授予 Kubernetes 访问权限](access-entries.md)。 + 如果集群不符合[使用 EKS 访问条目向 IAM 用户授予对 Kubernetes 的访问权限](access-entries.md)中的最低平台要求，则 `aws-auth` `ConfigMap` 中不存在具有您的 IAM 主体的条目。如果存在，则不会映射到 Kubernetes 组名称，这些名称已绑定到具有必要权限的 Kubernetes `Role` 或 `ClusterRole`。有关 Kubernetes 基于角色授权（RBAC）对象的更多信息，请参阅 Kubernetes 文档中的[使用 RBAC 鉴权](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)。您可以通过将以下命令中的 *my-cluster* 替换为集群名称，然后运行修改后的命令来查看当前的 `aws-auth` `ConfigMap` 条目：`eksctl get iamidentitymapping --cluster my-cluster `。如果 `ConfigMap` 中不存在具有您的 IAM 主体的 ARN 的条目，请在您的终端中输入 `eksctl create iamidentitymapping --help` 以了解如何创建一个。 如果安装和配置 AWS CLI，则可配置您使用的 IAM 凭证。有关更多信息，请参阅《AWS 命令行界面用户指南》**中的[配置 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。如果担任 IAM 角色来访问集群上的 Kubernetes 对象，则也可以配置 `kubectl` 使用 IAM 角色。有关更多信息，请参阅 [通过创建 kubeconfig 文件将 kubectl 连接到 EKS 集群](create-kubeconfig.md)。 ## `hostname doesn’t match` 系统的 Python 版本必须为 `2.7.9` 或更高版本。否则，在 AWS CLI 调用 Amazon EKS 时会收到 `hostname doesn’t match` 错误。有关更多信息，请参阅《Python Requests Frequently Asked Questions**》中的 [What are "hostname doesn't match" errors?](https://requests.readthedocs.io/en/latest/community/faq.html#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..:10250: getsockopt: no route to host ``` ## `Instances failed to join the Kubernetes cluster` 如果您在 AWS 管理控制台 中收到 `Instances failed to join the Kubernetes cluster` 错误，请确保已启用集群的私有端点访问，或者您已正确配置 CIDR 块以用于公有端点访问。有关更多信息，请参阅 [集群 API 服务器端点](cluster-endpoint.md)。 ## 托管节点组错误代码 如果您的托管节点组遇到硬件运行状况问题，则 Amazon EKS 返回错误代码以帮助您诊断问题。这些运行状况检查无法检测到软件问题，因为它们基于 [Amazon EC2 运行状况检查](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html)。下面的列表介绍了错误代码。 **AccessDenied** Amazon EKS 或者一个或多个托管节点无法向 Kubernetes 集群 API 服务器进行身份验证或授权。有关解决常见原因的更多信息，请参阅 [修复托管节点组的 `AccessDenied` 错误的常见原因](#access-denied-managed-node-groups)。私有 Windows AMI 也可能导致出现此错误代码以及 `Not authorized for images` 错误消息。有关更多信息，请参阅 [`Not authorized for images`](#not-authorized-for-images)。 **AmiIdNotFound** 找不到与您的启动模板关联的 AMI ID。确保 AMI 存在并与您的账户共享。 **AutoScalingGroupNotFound** 找不到与托管节点组关联的自动扩缩组。您可以重新创建具有相同设置的自动扩缩组进行恢复。 **ClusterUnreachable** Amazon EKS 或者一个或多个托管节点无法与 Kubernetes 集群 API 服务器通信。如果存在网络中断或 API 服务器处理请求时超时，则可能会发生这种情况。 **Ec2SecurityGroupNotFound** 找不到集群的集群安全组。您必须重新创建集群。 **Ec2SecurityGroupDeletionFailure** 无法删除托管节点组的远程访问安全组。从安全组中删除所有依赖关系。 **Ec2LaunchTemplateNotFound** 找不到托管节点组的 Amazon EC2 启动模板。您必须重新创建节点组才能恢复。 **Ec2LaunchTemplateVersionMismatch** 托管节点组的 Amazon EC2 启动模板版本与 Amazon EKS 创建的版本不匹配。您可以恢复到 Amazon EKS 创建的版本以进行恢复。 **IamInstanceProfileNotFound** 找不到托管节点组的 IAM 实例配置文件。您可以重新创建具有相同设置的实例配置文件进行恢复。 **IamNodeRoleNotFound** 找不到托管节点组的 IAM 角色。您可以重新创建具有相同设置的 IAM 角色进行恢复。 **AsgInstanceLaunchFailures** 自动扩缩组在尝试启动实例时出现故障。 **NodeCreationFailure** 启动的实例无法注册到 Amazon EKS 集群。此故障的常见原因是[节点 IAM 角色](create-node-role.md)权限不足，或节点缺少出站 Internet 访问权限。您的节点必须符合以下要求之一： + 能够使用公有 IP 地址访问互联网。与节点所在子网关联的安全组必须允许进行通信。有关更多信息，请参阅[子网要求和注意事项](network-reqs.md#network-requirements-subnets)和[查看集群的 Amazon EKS 安全组要求](sec-group-reqs.md)。 + 节点和 VPC 必须满足[部署具有有限互联网访问权限的私有集群](private-clusters.md)中的要求。 **InstanceLimitExceeded** AWS 账户无法启动指定实例类型的更多实例。您可以请求提高 Amazon EC2 实例限制以进行恢复。 **InsufficientFreeAddresses** 与托管节点组关联的一个或多个子网没有足够的 IP 地址供新节点使用。 **InternalFailure** 这些错误一般由 Amazon EKS 服务器端问题导致。 ### 修复托管节点组的 `AccessDenied` 错误的常见原因 在托管节点组上执行操作时最常见的 `AccessDenied` 错误原因是缺少 `eks:node-manager` `ClusterRole` 或 `ClusterRoleBinding`。Amazon EKS 会在托管节点组启动的过程中在您的集群中设置这些资源，这些资源是管理节点组所必需的。 `ClusterRole` 可能随着时间的推移而改变，但它应该类似于以下示例： ``` 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 ``` `ClusterRoleBinding` 可能随着时间的推移而改变，但它应该类似于以下示例： ``` 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 ``` 验证 `eks:node-manager` `ClusterRole` 是否存在。 ``` kubectl describe clusterrole eks:node-manager ``` 如果存在，则将输出与上一个 `ClusterRole` 示例进行比较。 验证 `eks:node-manager` `ClusterRoleBinding` 是否存在。 ``` kubectl describe clusterrolebinding eks:node-manager ``` 如果存在，则将输出与上一个 `ClusterRoleBinding` 示例进行比较。 如果您发现在请求托管节点组操作期间，由于 `ClusterRole` 或 `ClusterRoleBinding` 缺失或损坏造成了 `AcessDenied` 错误，则可还原它们。将以下内容保存到名为 *eks-node-manager-role.yaml* 的文件中。 ``` 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 设为私有，这会使得这些 AMI 不再可访问。如果您的托管节点组使用的是私有 Windows AMI，则请考虑[更新 Windows 托管节点组](update-managed-node-group.md)。虽然我们不能保证可以提供对已设为私有的 AMI 的访问权限，但您可以通过向 AWS Support 提交服务单来请求访问权限。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[修补](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/aws-windows-ami.html#ami-patches-security-ID)。 ## 节点处于 `NotReady` 状态 如果节点进入 `NotReady` 状态，可能表示该节点运行状况不佳，无法调度新的容器组（pod）。这可能是由于各种原因造成的，例如节点缺少足够的 CPU、内存或可用磁盘空间资源。 对于 Amazon EKS 优化版 Windows AMI，在 `kubelet` 配置中没有默认指定的计算资源预留。为帮助防止出现资源问题，您可以为系统进程预留计算资源，方法是为 `kubelet` 提供 [kube-reserved](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#kube-reserved) 和/或 [system-reserved](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#system-reserved) 的配置值。您可以使用引导脚本中的 `-KubeletExtraArgs` 命令行参数来执行此操作。有关更多信息，请参阅 Kubernetes 文档中的[为系统守护进程预留计算资源](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/)和本用户指南中的[引导脚本配置参数](eks-optimized-windows-ami.md#bootstrap-script-configuration-parameters)。 ## 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](https://github.com/bottlerocket-os/bottlerocket?tab=readme-ov-file#logs) 了解更多详细信息。 ## 容器运行时网络未准备就绪 您可能会收到类似于以下内容的 `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 ``` 这可能是由以下原因之一导致的： 1. 您的集群上要么没有 `aws-auth` `ConfigMap`，要么其中不包含您为节点配置的 IAM 角色的条目。 要解决此问题，可以通过将以下命令中的 *my-cluster* 替换为集群名称，然后运行修改后的命令 `eksctl get iamidentitymapping --cluster my-cluster ` 来查看 `ConfigMap` 中的现有条目。如果您收到来自该命令的错误消息，则可能是因为集群没有 `aws-auth` `ConfigMap`。以下命令将条目添加到 `ConfigMap`。如果 `ConfigMap` 不存在，该命令也会创建一个。请将 *111122223333* 替换为 IAM 角色的 AWS 账户 ID，将 *myAmazonEKSNodeRole* 替换为节点角色的名称。 ``` eksctl create iamidentitymapping --cluster my-cluster \ --arn arn:aws:iam::111122223333:role/myAmazonEKSNodeRole --group system:bootstrappers,system:nodes \ --username system:node:{{EC2PrivateDNSName}} ``` 您指定的角色的 ARN 不能包含 `/` 之外的[路径](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)。例如，如果您的角色名称为 `development/apps/my-role`，则需要在指定角色的 ARN 时将其更改为 `my-role`。确保指定了节点 IAM 角色 ARN（非实例配置文件 ARN）。 1. 您的自主管理型节点位于集群中，其平台版本为[使用 EKS 访问条目向 IAM 用户授予对 Kubernetes 的访问权限](access-entries.md)主题中先决条件部分所列的最低版本，但该节点 IAM 角色的 `aws-auth` `ConfigMap` 中未列出条目（参见上一项），或者该角色不存在访问条目。要解决此问题，可以通过将以下命令中的 *my-cluster* 替换为集群名称，然后运行修改后的命令 `aws eks list-access-entries --cluster-name my-cluster ` 来查看现有访问条目。以下命令将为节点的 IAM 角色添加访问条目。请将 *111122223333* 替换为 IAM 角色的 AWS 账户 ID，将 *myAmazonEKSNodeRole* 替换为节点角色的名称。如果您有 Windows 节点，请将 *EC2\$1LINUX* 替换为 `EC2_Windows`。确保指定了节点 IAM 角色 ARN（非实例配置文件 ARN）。 ``` aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/myAmazonEKSNodeRole --type EC2_LINUX ``` ## 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 如果将服务账户的 IAM 角色用于部署到中国 AWS 区域中集群的容器组（pod）或 DaemonSet，但尚未在规范中设置 `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 版本 集群中的托管节点和 Fargate 节点的 Kubernetes 次要版本必须与控制面板的当前版本相同，然后才能将控制面板更新为新的 Kubernetes 版本。Amazon EKS `update-cluster-version` API 会拒绝请求，直到您将所有 Amazon EKS 托管节点升级为当前集群版本。Amazon EKS 提供 API 来升级托管节点。有关升级托管节点组 Kubernetes 版本的信息，请参阅[更新集群的托管式节点组](update-managed-node-group.md)。要升级 Fargate 节点的版本，请删除节点所表示的容器组（pod），然后在升级控制面板后重新部署容器组（pod）。有关更多信息，请参阅 [将现有集群更新到新的 Kubernetes 版本](update-cluster.md)。 ## 启动多个节点时，出现 `Too Many Requests` 错误 如果同时启动多个节点，您可能会在表示 `Too Many Requests` 的 [Amazon EC2 用户数据](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts)执行日志中看到错误消息。发生这种情况的原因是控制面板被 `describeCluster` 调用过载。过载导致节流，节点无法运行引导脚本，节点无法完全加入集群。 确保 `--apiserver-endpoint`、`--b64-cluster-ca` 和 `--dns-cluster-ip` 参数正在传递给节点的引导脚本。加入这些参数后，引导脚本无需调用 `describeCluster`，这有助于防止控制面板过载。有关更多信息，请参阅 [提供用户数据，将参数传递给随 Amazon EKS 优化版 Linux/Bottlerocket AMI 一起提供的 `bootstrap.sh` 文件](launch-templates.md#mng-specify-eks-ami)。 ## Kubernetes API 服务器请求的 HTTP 401 未经授权的错误响应 如果集群上容器组（pod）的服务账户令牌已到期，您就会看到这些错误。 Amazon EKS 集群的 Kubernetes API 服务器拒绝令牌超过 90 天的请求。在以前的 Kubernetes 版本中，令牌没有过期。这意味着依赖这些令牌的客户端必须在一小时内刷新它们。为防止 Kubernetes API 服务器因令牌无效而拒绝请求，工作负载使用的 [Kubernetes 客户端开发工具包](https://kubernetes.io/docs/reference/using-api/client-libraries/)版本必须相同，或者高于以下版本： + Go 版本 `0.15.7` 和更高版本 + Python 版本 `12.0.0` 和更高版本 + Java 版本 `9.0.0` 和更高版本 + JavaScript 版本 `0.10.3` 和更高版本 + Ruby `master` 分支 + Haskell 版本 `0.3.0.0` + C\$1 版本 `7.0.5` 和更高版本 您可以识别使用过时令牌的集群中的所有现有容器组（pod）。有关更多信息，请参阅 [服务账户令牌](service-accounts.md#service-account-tokens)。 ## Amazon EKS 平台版本比当前平台版本落后两个版本以上 当 Amazon EKS 无法自动更新集群的 [platform-version](https://docs.aws.amazon.com/eks/latest/userguide/platform-versions.html) 时，可能会发生这种情况。造成这种情况的原因有很多，而一些常见的原因如下。如果这些问题中的任何一个适用于您的集群，该集群可能仍然可以正常工作，但 Amazon EKS 不会更新其平台版本。 **问题** [集群 IAM 角色](cluster-iam-role.md)被删除 – 该角色是在创建集群时指定的。可使用以下命令查看所指定的角色。将 *my-cluster* 替换为您的集群的名称。 ``` aws eks describe-cluster --name my-cluster --query cluster.roleArn --output text | cut -d / -f 2 ``` 示例输出如下。 ``` eksClusterRole ``` **解决方案** 创建具有相同名称的新[集群 IAM 角色](cluster-iam-role.md)。 **问题** 集群创建期间指定的子网被删除 – 用于集群的子网是在集群创建期间指定的。可使用以下命令查看所指定的子网。将 *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 版本更新时，更新可能会因为同样的原因而失败。 + 在创建集群时指定的每个子网中，可用 IP 地址达不到至少 6 个（而我们建议 16 个）。如果子网中没有足够的可用 IP 地址，则需要释放子网中的 IP 地址，或者需要更改集群使用的子网，以使用具有足够可用 IP 地址的子网。 + 您在创建集群时启用了[密钥加密](enable-kms.md)，但您指定的 AWS KMS 密钥已被删除。如果您希望 Amazon EKS 更新集群，则需要创建一个新集群 ## 集群运行状况常见问题解答和错误代码以及解析路径 Amazon EKS 会检测 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 命令行界面内部调用。 **为什么应该使用此功能？** 您可以更清楚地了解 Amazon EKS 集群的运行状况，快速诊断和修复任何问题，而无需花时间调试或提出 AWS 支持案例。例如：您不小心删除了 Amazon EKS 集群的子网，Amazon EKS 将无法创建跨账户网络接口和 Kubernetes AWS CLI 命令，例如 `kubectl` exec 或 `kubectl` 日志。这些将失败并显示错误：`Error from server: error dialing backend: remote error: tls: internal error.` 现在您将看到一个 Amazon EKS 运行状况问题，错误消息为：`subnet-da60e280 was deleted: could not create network interface`。 **此功能如何与其它 AWS 服务相关或结合使用？** IAM 角色和 Amazon VPC 子网是集群运行状况检测到问题的两个必备基础设施示例。如果这些资源配置不正确，则此功能将返回详细信息。 **存在运行状况问题的集群是否会产生费用？** 是的，每个 Amazon EKS 集群都按标准的 Amazon EKS 定价计费。*集群运行状况*功能不收取额外费用。 **此功能是否可以与 AWS Outposts 上的 Amazon EKS 集群结合使用？** 是的，已检测到 AWS Cloud 中的 EKS 集群存在集群问题，包括 AWS Outposts 上的*扩展集群*和 AWS Outposts 上的*本地集群*。集群运行状况无法检测到 Amazon EKS Anywhere 或 Amazon EKS Distro（EKS-D）存在的问题。 **当检测到新问题时，我能否收到通知？** 是。AWS 检测到新的集群运行状况问题时，会发送电子邮件和 Personal Health Dashboard 通知。 **控制台是否会就运行状况问题向我发出警告？** 是的，任何存在运行状况问题的集群都将在控制台顶部显示一个横幅。 前两列是 API 响应值所需的列。[Health ClusterIssue](https://docs.aws.amazon.com/eks/latest/APIReference/API_ClusterIssue.html) 对象的第三个字段是 resourceIds，其返回值取决于问题类型。 | 代码 | Message | ResourceIds | 集群是否可恢复？ | | --- | --- | --- | --- | | SUBNET\$1NOT\$1FOUND | 我们找不到当前与您的集群关联的一个或多个子网。调用 Amazon EKS update-cluster-config API 来更新子网。 | 子网 ID | 是 | | SECURITY\$1GROUP\$1NOT\$1FOUND | 我们找不到当前与您的集群关联的一个或多个安全组。调用 Amazon EKS update-cluster-config API 来更新安全组 | 安全组 ID | 是 | | IP\$1NOT\$1AVAILABLE | 与集群关联的一个或多个子网没有足够的 IP 地址供 Amazon EKS 执行集群管理操作。使用 Amazon EKS update-cluster-config API 释放子网中的地址，或者将不同的子网关联到您的集群。 | 子网 ID | 是 | | VPC\$1NOT\$1FOUND | 我们找不到与您的集群关联的 VPC。您必须删除并重新创建集群。 | VPC ID | 否 | | ASSUME\$1ROLE\$1ACCESS\$1DENIED | 您的集群未使用 Amazon EKS service-linked-role。我们无法分派与您的集群关联的角色来执行所需的 Amazon EKS 管理操作。检查该角色是否存在并且是否具有所需的信任策略。 | 集群 IAM 角色 | 是 | | PERMISSION\$1ACCESS\$1DENIED | 您的集群未使用 Amazon EKS service-linked-role。与您的集群关联的角色未向 Amazon EKS 授予足够的权限来执行所需的管理操作。检查附加到集群角色的策略，以及是否应用了任何单独的拒绝策略。 | 集群 IAM 角色 | 是 | | ASSUME\$1ROLE\$1ACCESS\$1ADCESS\$1DENIED\$1USING\$1SLR | 我们无法分派 Amazon EKS 集群管理 service-linked-role。检查该角色是否存在并且是否具有所需的信任策略。 | Amazon EKS service-linked-role | 是 | | PERMISSION\$1ACCESS\$1DENIED\$1USING\$1SLR | Amazon EKS 集群管理 service-linked-role 未向 Amazon EKS 授予足够的权限来执行所需的管理操作。检查附加到集群角色的策略，以及是否应用了任何单独的拒绝策略。 | Amazon EKS service-linked-role | 是 | | OPT\$1IN\$1REQUIRED | 您的账户没有订阅 Amazon EC2 服务。在您的账户设置页面更新您的账户订阅。 | 不适用 | 是 | | STS\$1REGIONAL\$1ENDPOINT\$1DISABLED | STS 区域端点已禁用。启用 Amazon EKS 的端点以执行所需的集群管理操作。 | 不适用 | 是 | | KMS\$1KEY\$1DISABLED | 与您的集群关联的 AWS KMS 密钥已禁用。重新启用密钥以恢复集群。 | KMS 密钥 Arn | 是 | | KMS\$1KEY\$1NOT\$1FOUND | 我们找不到与您的集群关联的 AWS KMS 密钥。您必须删除并重新创建集群。 | KMS 密钥 ARN | 否 | | KMS\$1GRANT\$1REVOKED | 已撤销对与您的集群关联的 AWS KMS 密钥的授权。您必须删除并重新创建集群。 | KMS 密钥 Arn | 否 | | ETCD\$1DB\$1SIZE\$1EXCEEDED | 您的 Amazon EKS 集群已超过 etcd 数据库的大小限制。etcd 是一个在 Kubernetes 控制面板中运行的键值数据存储，用于维护集群的配置和状态。为防止集群进入降级状态，请通过删除不必要的 Kubernetes 对象来减小 etcd 数据库的大小。有关识别和清理导致数据库大小增加的对象的指导，请参阅[在 Amazon EKS 集群上管理 etcd 数据库大小](https://aws.amazon.com/blogs/containers/managing-etcd-database-size-on-amazon-eks-clusters/)。如果您在清理后仍遇到问题，请联系 AWS 支持。 | 集群 ARN | 是 |