排查 AWS Outposts 上的本地 Amazon EKS 集群问题 - Amazon EKS

排查 AWS Outposts 上的本地 Amazon EKS 集群问题

本主题将介绍您在使用本地集群时可能会看到的一些常见错误，以及如何排查这些错误。虽然本地集群与云端 Amazon EKS 集群相似，但在 Amazon EKS 的托管方式上存在一些差异。

本地集群是通过 Amazon EKS API 创建的，但以异步方式运行。这意味着对于本地集群，对 Amazon EKS API 的请求会立即返回。但是，这些请求可能会成功，也可能由于输入验证错误而快速失效，或者失败并出现描述性验证错误。此行为类似于 Kubernetes API。

本地集群不会过渡到 FAILED 状态。Amazon EKS 会尝试以连续方式协调集群状态与用户请求的所需状态。因此，本地集群可能会长时间保持在 CREATING 状态，直到根本问题得到解决。

可以使用 describe-cluster Amazon EKS AWS CLI 命令发现本地集群问题。本地集群问题将由 describe-cluster 命令响应的 cluster.health 字段显示。此字段中包含的消息包括错误代码、描述性消息和相关的资源 ID。此信息将仅通过 Amazon EKS API 和 AWS CLI 提供。在以下示例中，将 my-cluster 替换为您的本地集群的名称。

aws eks describe-cluster --name my-cluster --query 'cluster.health'

示例输出如下。

{
    "issues": [
        {
            "code": "ConfigurationConflict",
            "message": "The instance type 'm5.large' is not supported in Outpost 'my-outpost-arn'.",
            "resourceIds": [
                "my-cluster-arn"
            ]
        }
    ]
}

如果问题无法修复，您可能需要删除该本地集群，然后创建一个新的本地集群。例如，尝试使用 Outpost 上不可用的实例类型预调配集群。下表包括常见的运行状况相关错误。

错误情形 代码 消息 ResourceIds

无法找到提供的子网。

ResourceNotFound

The subnet ID subnet-id does not exist

所有提供的子网 ID

提供的子网不属于同一 VPC。

ConfigurationConflict

Subnets specified must belong to the same VPC

所有提供的子网 ID

提供的某些子网不属于指定的 Outpost。

ConfigurationConflict

Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn

子网 ID 有问题

提供的某些子网不属于任何 Outpost。

ConfigurationConflict

Subnet subnet-id is not part of any Outpost

子网 ID 有问题

提供的某些子网没有足够的空闲地址来为控制面板实例创建弹性网络接口。

ResourceLimitExceeded

The specified subnet does not have enough free addresses to satisfy the request.

子网 ID 有问题

Outpost 上不支持指定的控制面板实例类型。

ConfigurationConflict

The instance type type is not supported in Outpost outpost-arn

集群 ARN

您已终止控制面板 Amazon EC2 实例，或 run-instance 已成功但观察到的状态更改为 Terminated。在您的 Outpost 重新连接并且 Amazon EBS 内部错误导致 Amazon EC2 内部工作流失败后，这种情况可能会发生一段时间。

InternalFailure

EC2 instance state "Terminated" is unexpected

集群 ARN

Outpost 容量不足。在集群创建期间，如果 Outpost 与 AWS 区域断开连接，也会发生这种情况。

ResourceLimitExceeded

There is not enough capacity on the Outpost to launch or start the instance.

集群 ARN

您的账户已超出安全组配额。

ResourceLimitExceeded

Amazon EC2 API 返回的错误消息

目标 VPC ID

您的账户已超出弹性网络接口配额。

ResourceLimitExceeded

Amazon EC2 API 返回的错误消息

目标子网 ID

无法通过 AWS Systems Manager 访问控制面板实例。有关分辨率的信息，请参阅 无法通过 AWS Systems Manager 访问控制面板实例。

ClusterUnreachable

无法通过 SSM 访问 Amazon EKS 控制面板实例。请验证您的 SSM 和网络配置，并参考 Outpost 上的 EKS 故障排除文档。

Amazon EC2 实例 ID

获取托管安全组或弹性网络接口的详细信息时出错。

基于 Amazon EC2 客户端错误代码。

Amazon EC2 API 返回的错误消息

所有托管安全组 ID

授权或撤销安全组传入规则时出错。这既适用于集群安全组，也适用于控制面板安全组。

基于 Amazon EC2 客户端错误代码。

Amazon EC2 API 返回的错误消息

安全组 ID 有问题

删除控制面板实例的弹性网络接口时出错。

基于 Amazon EC2 客户端错误代码。

Amazon EC2 API 返回的错误消息

弹性网络接口 ID 有问题

下表列出了来自 describe-cluster 响应的运行状况字段中呈现的其它 AWS 服务的错误。

Amazon EC2 错误代码 集群运行状况问题代码 描述

AuthFailure

AccessDenied

有多种原因可能导致此错误。最常见的原因是，您从控制面板中意外删除了服务用于缩小服务相关角色策略范围的标签。如果出现这种情况，Amazon EKS 将无法继续管理和监控这些 AWS 资源。

UnauthorizedOperation

AccessDenied

有多种原因可能导致此错误。最常见的原因是，您从控制面板中意外删除了服务用于缩小服务相关角色策略范围的标签。如果出现这种情况，Amazon EKS 将无法继续管理和监控这些 AWS 资源。

InvalidSubnetID.NotFound

ResourceNotFound

如果无法找到安全组传入规则的子网 ID，将发生此错误。

InvalidPermission.NotFound

ResourceNotFound

如果安全组传入规则的权限不正确，将发生此错误。

InvalidGroup.NotFound

ResourceNotFound

如果无法找到安全组的传入规则组，将发生此错误。

InvalidNetworkInterfaceID.NotFound

ResourceNotFound

如果无法找到安全组传入规则的网络接口 ID，将发生此错误。

InsufficientFreeAddressesInSubnet

ResourceLimitExceeded

如果超出子网资源配额，将发生此错误。

InsufficientCapacityOnOutpost

ResourceLimitExceeded

如果超出 Outpost 容量配额，将发生此错误。

NetworkInterfaceLimitExceeded

ResourceLimitExceeded

如果超出弹性网络接口配额，将发生此错误。

SecurityGroupLimitExceeded

ResourceLimitExceeded

如果超出安全组配额，将发生此错误。

VcpuLimitExceeded

ResourceLimitExceeded

在新账户中创建 Amazon EC2 实例时，将观察到此情况。错误可能类似于以下内容：“You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to. Please visit http://aws.amazon.com/contact-us/ec2-request to request an adjustment to this limit."

InvalidParameterValue

ConfigurationConflict

如果 Outpost 上不支持指定的实例类型，Amazon EC2 将返回此错误代码。

所有其他故障

InternalFailure

无

本地集群所需的权限和策略与云端托管的 Amazon EKS 集群需要的权限和策略不同。当集群创建失败并显示 InvalidPermissions 错误时，请仔细检查您使用的集群角色是否附加了 AmazonEKSLocalOutpostClusterPolicy 托管策略。所有其他 API 调用都需要与云中的 Amazon EKS 集群相同的权限集。

创建本地集群所需的时间取决于多个因素。这些因素包括您的网络配置、Outpost 配置和集群配置。一般情况下，可在 15–20 分钟内创建本地集群并更改为 ACTIVE 状态。如果本地集群仍处于 CREATING 状态，您可以在 cluster.health 输出字段中调用 describe-cluster 以了解关于原因的信息。

最常见的问题如下：

  • 您的集群无法从 Systems Manager 所在的 AWS 区域连接到控制面板实例。您可以通过从区域内的堡垒主机调用 aws ssm start-session --target instance-id 来对此进行验证。如果该命令不起作用，请检查 Systems Manager 是否在控制面板实例上运行。或者采用另一种解决方法，即删除集群，然后重新创建集群。

  • Systems Manager 控制面板实例可能无法访问互联网。检查您在创建集群时提供的子网是否具有 NAT 网关和带有互联网网关的 VPC。使用 VPC Reachability Analyzer 验证控制面板实例是否可以访问互联网网关。有关更多信息，请参阅 VPC Reachability Analyzer 入门。

  • 您提供的角色 ARN 缺少策略。检查是否已从角色中移除了 AWS 托管策略：AmazonEKSLocalOutpostClusterPolicy。如果 AWS CloudFormation 堆栈配置错误，也可能会出现这种情况。

  • 提供的所有子网都必须与同一 Outpost 关联，并且能够相互访问。如果在创建集群期间指定了多个子网，Amazon EKS 会尝试将控制面板实例分布到多个子网中。

  • 在弹性网络接口上应用 Amazon EKS 托管安全组。但是，NACL 防火墙规则等其他配置元素也可能会与弹性网络接口的规则冲突。

VPC 和子网 DNS 配置配置错误或缺失

查阅为 AWS Outposts 上的 Amazon EKS 集群创建 VPC 和子网

  • AMI 问题：

    • 您使用的是不受支持的 AMI。必须使用 v20220620 或更高版本的 Amazon EKS 优化型 Amazon Linux使用优化型 Amazon Linux AMI 创建节点。

    • 如果您使用 AWS CloudFormation 模板创建您的节点，请确保它没有使用不受支持的 AMI。

  • 缺失 AWS IAM 身份验证器 ConfigMap – 如果缺失，则必须进行创建。有关更多信息，请参阅将 aws-authConfigMap 应用到集群。

  • 使用了错误的安全组 – 请确保将 eks-cluster-sg-cluster-name-uniqueid 用于 Worker 节点的安全组。将通过 AWS CloudFormation 更改所选的安全组，以便在每次使用堆栈时允许新的安全组。

  • 遵循意外的私有链接 VPC 步骤 - 传递错误的 CA 数据 (--b64-cluster-ca) 或 API 端点 (--apiserver-endpoint)。

  • Pod 安全策略配置错误：

    • CoreDNS 和 Amazon VPC CNI plugin for Kubernetes 守护程序集必须在节点上运行，节点才能加入集群并与之通信。

    • Amazon VPC CNI plugin for Kubernetes 需要一些特权联网功能才能正常运行。您可以使用以下命令查看特权联网功能：kubectl describe psp eks.privileged。

    我们建议您不要修改默认容器组（pod）安全策略。有关更多信息，请参阅 了解 Amazon EKS 创建的容器组（pod）安全策略 (PSP)。

如果 Outpost 与其关联的 AWS 区域断开连接，Kubernetes 集群可能会继续正常运行。但是，如果集群无法正常运行，请执行在 AWS Outposts 上准备本地 Amazon EKS 集群以防断网中的问题排查步骤。如果遇到任何问题，请与 AWS Support 联系。AWSSupport 会指导您如何下载和运行日志收集工具。这样一来，您就可以从 Kubernetes 集群控制面板实例中收集日志，并将其发送到 AWS Support 支持部门，以便进一步调查。

当无法通过 AWS Systems Manager 访问 Amazon EKS 控制面板实例时，Amazon EKS 将为您的集群显示以下错误。

Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation.

要解决此问题，请确保您的 VPC 和子网满足为 AWS Outposts 上的 Amazon EKS 集群创建 VPC 和子网中的要求，并且您已完成《AWS Systems Manager 用户指南》内设置 Session Manager 中的步骤。