Amazon EKS 故障排除

本章介绍使用 Amazon EKS 时可能遇到的一些常见错误以及相应的错误处理方式。如果您需要对特定的 Amazon EKS 区域进行故障排除，请参阅单独的IAM 故障排除、排查 Amazon EKS Connector 中的问题和排查 ADOT Amazon EKS 附加组件中的问题主题。

容量不足

如果您在尝试创建 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 中使用此错误消息所返回的可用区中托管的子网重新尝试创建集群。

节点未能加入集群

有几种常见原因会阻止节点加入集群：

要确定导致 Worker 节点无法加入集群的常见原因并进行问题排查，您可以使用 AWSSupport-TroubleshootEKSWorkerNode 运行手册。有关更多信息，请参阅 Amazon Systems Manager Automation 运行手册参考中的 AWSSupport-TroubleshootEKSWorkerNode。

未经授权或访问被拒绝 (kubectl)

如果您在运行 kubectl 命令时收到以下错误之一，则说明您的 kubectl 未针对 Amazon EKS 正确配置，或您使用的 IAM 主体凭证未映射到 Amazon EKS 集群中具有足够权限的 Kubernetes RBAC 用户。

这可能是因为集群是使用一个 IAM 主体的凭证创建的，并且 kubectl 在使用另一个 IAM 主体的凭证。

创建 Amazon EKS 集群后，创建集群的 IAM 主体将作为管理员（具有 system:masters 权限）添加到 Kubernetes RBAC 授权表中。最初，仅该主体可以使用 kubectl 调用 Kubernetes API 服务器。有关更多信息，请参阅让 IAM 主体访问您的集群。如果使用控制台创建集群，请确保在集群上运行 kubectl 命令时，相同的 IAM 凭证位于 Amazon SDK 凭证链中。

如果安装和配置 Amazon CLI，则可配置您使用的 IAM 凭证。有关更多信息，请参阅 Amazon Command Line Interface 用户指南中的配置 Amazon CLI。

如果您已代入一个角色来创建 Amazon EKS 集群，则必须确保 kubectl 已配置为代入相同的角色。使用以下命令更新您的 kubeconfig 文件以使用 IAM 角色。有关更多信息，请参阅为 Amazon EKS 集群创建或更新 kubeconfig 文件。

aws eks update-kubeconfig \
    --region region-code \
    --name my-cluster \
    --role-arn arn:aws:iam::111122223333:role/role_name

要将 IAM 主体映射到 Kubernetes RBAC 用户，请参阅让 IAM 主体访问您的集群。

aws-iam-authenticator 未找到

如果收到错误 "aws-iam-authenticator": executable file not found in $PATH，则表示未对 Amazon EKS 配置 kubectl。有关更多信息，请参阅安装 aws-iam-authenticator。

hostname doesn't match

系统的 Python 版本必须为 2.7.9 或更高版本。否则，在 Amazon CLI 调用 Amazon EKS 时会收到 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

托管节点组错误

如果您在Amazon Web Services Management Console中收到 Instances failed to join the kubernetes cluster 错误，请确保已启用集群的私有端点访问，或者您已正确配置 CIDR 块以用于公有端点访问。有关更多信息，请参阅Amazon EKS 集群端点访问控制。

如果您的托管节点组遇到硬件运行状况问题，则 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

CNI 日志收集工具

Amazon VPC CNI plugin for Kubernetes 具有自己的问题排查脚本，该脚本可在 /opt/cni/bin/aws-cni-support.sh 的节点上找到。您可以使用该脚本收集有关支持案例和常规故障排除的诊断日志。

使用以下命令可在您的节点上运行脚本：

sudo bash /opt/cni/bin/aws-cni-support.sh

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

该脚本收集以下诊断信息。您已部署的 CNI 版本可以早于脚本版本。

      This is version 0.6.1. New versions can be found at https://github.com/awslabs/amazon-eks-ami

Trying to collect common operating system logs... 
Trying to collect kernel logs... 
Trying to collect mount points and volume information... 
Trying to collect SELinux status... 
Trying to collect iptables information... 
Trying to collect installed packages... 
Trying to collect active system services... 
Trying to collect Docker daemon information... 
Trying to collect kubelet information... 
Trying to collect L-IPAMD information... 
Trying to collect sysctls information... 
Trying to collect networking information... 
Trying to collect CNI configuration information... 
Trying to collect running Docker containers and gather container data... 
Trying to collect Docker daemon logs... 
Trying to archive gathered information... 

	Done... your bundled logs are located in /var/log/eks_i-0717c9d54b6cfaa19_2020-03-24_0103-UTC_0.6.1.tar.gz

诊断信息收集并存储在：

/var/log/eks_i-0717c9d54b6cfaa19_2020-03-24_0103-UTC_0.6.1.tar.gz

容器运行时网络未准备就绪

您可能会收到类似于以下内容的 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

这些错误最有可能与 Amazon IAM Authenticator (aws-auth) 配置映射未应用到集群有关。配置映射提供了 system:bootstrappers 和 system:nodes Kubernetes RBAC 权限，以便节点注册到集群。要将配置映射应用于集群，请参阅 将 aws-authConfigMap 应用到集群。

若角色 ARN包含 / 以外的路径，如下面的示例所示，则身份验证器无法识别该 ARN：

arn:aws:iam::111122223333:role/development/apps/prod-iam-role-NodeInstanceRole-621LVEXAMPLE

当配置映射中指定的角色 ARN 包含非 / 的路径时，必须删除该路径。应将前述 ARN 指定为以下内容：

arn:aws:iam::111122223333:role/prod-iam-role-NodeInstanceRole-621LVEXAMPLE

TLS 握手超时

当节点无法建立到公有 API 服务器端点的连接时，您可能会遇到类似如下的错误。

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

kubelet 进程将持续重新生成并测试 API 服务器终端节点。在控制层面中执行集群滚动更新（例如配置更改或版本更新）的任何过程中，也可能临时发生此错误。

要解决此问题，请检查路由表和安全组，以确保来自节点的流量可以到达公有端点。

InvalidClientTokenId

如果您将 IAM 角色用于部署于中国 Amazon Web Services 区域 的集群的 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"

VPC 准入 Webhook 证书过期

如果用于签署 VPC 准入 Webhook 的证书过期，则新的 Windows pod 部署的状态将保持在 ContainerCreating。

要解决数据面板有旧版 Windows 支持的问题，请参阅 更新 VPC 准入 Webhook 证书。如果您的集群和平台版本高于 Windows 支持先决条件部分中列出的版本，则建议删除数据面板上的旧版 Windows 支持，然后为控制面板启用新版支持。执行此操作后，无需管理 webhook 证书。有关更多信息，请参阅为 Amazon EKS 集群启用 Windows 支持。

在更新控制面板前，节点组必须匹配 Kubernetes 版本

集群中的托管节点和 Fargate 节点的次要版本必须与控制面板的当前版本相同，然后才能将控制面板更新为新的 Kubernetes 版本。EKS update-cluster-version API 会拒绝请求，直到您将所有 EKS 托管节点更新为当前集群版本。EKS 提供 API 来更新托管节点。有关更新托管节点组 Kubernetes 版本的信息，请参阅 更新托管节点组。要更新 Fargate 节点的版本，请删除节点所表示的 pod，然后在更新控制面板后重新部署 pod。有关更多信息，请参阅更新 Amazon EKS 集群 Kubernetes 版本。

启动多个节点时，出现 Too Many Requests 错误

如果同时启动多个节点，您可能会在表示 Too Many Requests 的 Amazon EC2 用户数据执行日志中看到错误消息。发生这种情况的原因是控制层面被 describeCluster 调用过载。过载导致节流，节点无法运行引导脚本，节点无法完全加入集群。

确保 --apiserver-endpoint、--b64-cluster-ca 和 --dns-cluster-ip 参数正在传递给 Worker 节点引导脚本。加入这些参数后，引导脚本无需调用 describeCluster，这有助于防止控制层面过载。有关更多信息，请参阅提供用户数据以将实际参数传递给随 Amazon EKS 优化版 Linux/Bottlerocket AMI 一起提供的 bootstrap.sh 文件。

对于 Kubernetes API 服务器请求的 HTTP 401 未经授权错误响应

如果 1.21 或更高版本集群上的 pod 的服务账户令牌已过期，您将会看到这些错误。

Amazon EKS 1.21 版或更高版本集群的 Kubernetes API 服务器拒绝令牌超过 90 天的请求。在之前的 Kubernetes 版本中，令牌没有过期时间。这意味着依赖这些令牌的客户端必须在一小时内刷新它们。为防止 Kubernetes API 服务器因令牌无效而拒绝您的请求，您的工作负载使用的 Kubernetes 客户端 SDK 版本必须与以下版本相同或高于以下版本：

您可以识别您的集群中使用过时令牌的所有现有 pods。有关更多信息，请参阅 Kubernetes 服务账户。

Amazon EKS 平台版本比当前平台版本落后两个版本以上

当 Amazon EKS 无法自动更新集群的平台版本时，可能会发生这种情况。造成这种情况的原因有很多，而一些常见的原因如下。如果这些问题中的任何一个适用于您的集群，该集群可能仍然可以正常工作，但 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 版本更新时，更新可能会因为同样的原因而失败。