**帮助改进此页面** 要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。 # 排查 AWS Outposts 上的本地 Amazon EKS 集群问题 本主题将介绍您在使用本地集群时可能会看到的一些常见错误，以及如何排查这些错误。虽然本地集群与云端 Amazon EKS 集群相似，但在 Amazon EKS 的托管方式上存在一些差异。 **重要** 若未得到 AWS Support 支持部门明确指示，切勿终止在 Outpost 上运行的任何托管 EKS 本地集群 `Kubernetes` 控制面板实例。终止这些实例会给本地集群服务可用性带来风险，包括：如果同时终止多个实例，会丢失本地集群。EKS 本地集群 `Kubernetes` 控制面板实例由 EC2 实例控制台上的 `eks-local:controlplane-name` 标签标识。 ## API 行为 本地集群是通过 Amazon EKS API 创建的，但以异步方式运行。这意味着对于本地集群，对 Amazon EKS API 的请求会立即返回。但是，这些请求可能会成功，也可能由于输入验证错误而快速失效，或者失败并出现描述性验证错误。此行为类似于 Kubernetes API。 本地集群不会过渡到 `FAILED` 状态。Amazon EKS 会尝试以连续方式协调集群状态与用户请求的所需状态。因此，本地集群可能会长时间保持在 `CREATING` 状态，直到根本问题得到解决。 ## 描述集群运行状况字段 可以使用 [describe-cluster](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-cluster.html) 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 上不可用的实例类型预调配集群。下表包括常见的运行状况相关错误。 | 错误情形 | 代码 | Message | 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 访问控制面板实例](#outposts-troubleshooting-control-plane-instances-ssm)。 | `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](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) 托管策略。所有其他 API 调用都需要与云中的 Amazon EKS 集群相同的权限集。 ## 集群卡在 `CREATING` 状态 创建本地集群所需的时间取决于多个因素。这些因素包括您的网络配置、Outpost 配置和集群配置。一般情况下，可在 15–20 分钟内创建本地集群并更改为 `ACTIVE` 状态。如果本地集群仍处于 `CREATING` 状态，您可以在 `cluster.health` 输出字段中调用 `describe-cluster` 以了解关于原因的信息。 最常见的问题如下： + 您的集群无法从 Systems Manager 所在的 AWS 区域连接到控制面板实例。您可以通过从区域内的堡垒主机调用 `aws ssm start-session --target instance-id ` 来对此进行验证。如果该命令不起作用，请检查 Systems Manager 是否在控制面板实例上运行。或者采用另一种解决方法，即删除集群，然后重新创建集群。 + 由于 EBS 卷的 KMS 密钥权限问题，无法创建控制面板实例。若使用用户管理型 KMS 密钥加密了 EBS 卷，如果密钥不可访问，控制面板实例会终止。如果实例终止，要么切换到 AWS 托管式 KMS 密钥，要么确保用户管理型密钥策略会向集群角色授予必要权限。 + Systems Manager 控制面板实例可能无法访问互联网。检查您在创建集群时提供的子网是否具有 NAT 网关和带有互联网网关的 VPC。使用 VPC Reachability Analyzer 验证控制面板实例是否可以访问互联网网关。有关更多信息，请参阅 [VPC Reachability Analyzer 入门](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html)。 + 您提供的角色 ARN 缺少策略。检查是否已从角色中移除了 [AWS 托管策略：AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy)。如果 AWS CloudFormation 堆栈配置错误，也可能会出现这种情况。 + 提供的所有子网都必须与同一 Outpost 关联，并且能够相互访问。如果在创建集群期间指定了多个子网，Amazon EKS 会尝试将控制面板实例分布到多个子网中。 + 在弹性网络接口上应用 Amazon EKS 托管安全组。但是，NACL 防火墙规则等其他配置元素也可能会与弹性网络接口的规则冲突。 + VPC 和子网 DNS 配置配置错误或缺失。查阅[为 AWS Outposts 上的 Amazon EKS 集群创建 VPC 和子网](eks-outposts-vpc-subnet-requirements.md) ## 集群卡在 `UPDATING` 状态 Amazon EKS 会自动将所有现有本地集群更新到其对应的 Kubernetes 次要版本的最新平台版本。有关平台版本的更多信息，请参阅[了解适用于 AWS Outposts 的 Kubernetes 和 Amazon EKS 平台版本](eks-outposts-platform-versions.md)。 在平台版本自动推出期间，集群状态更改为 `UPDATING`。更新过程包括将所有 Kubernetes 控制面板实例替换成包含为相应 Kubernetes 次要版本发布的最新安全补丁和错误修复的新实例。本地集群平台更新过程通常会在 30 分钟内完成，集群将变回 `ACTIVE` 状态。如果本地集群在较长时间内仍处于 `UPDATING` 状态，您可以调用 `describe-cluster`，在 `cluster.health` 输出字段中了解关于原因的信息。 为保持本地集群可用性和防止服务中断，Amazon EKS 确保至少三分之二的 Kubernetes 控制面板实例是能够正常运行的集群节点。如果本地集群停滞在 `UPDATING` 状态，通常是因为存在某些基础设施或配置问题，无法在过程继续进行时保证两个实例的最低可用性。因此，为了避免本地集群服务中断，更新过程会停止进行。 必须对卡在 `UPDATING` 状态的本地集群进行问题排查，从根本原因上解决问题，这样更新过程才能顺利完成，让本地集群恢复到 `ACTIVE` 状态，实现 3 个 Kubernetes 控制面板实例都可用的高可用性。 若未得到 AWS Support 支持部门明确指示，切勿终止在 Outpost 上的任何托管 EKS 本地集群 `Kubernetes` 实例。这对于卡在 `UPDATING` 状态的本地集群尤其重要，因为另一个控制面板节点很有可能无法完全正常运行，而终止错误的实例可能会导致服务中断，造成本地集群数据丢失的风险。 最常见的问题如下： + 自首次创建本地集群以来，由于网络配置发生了变化，一个或多个控制面板实例无法连接到 System Manager。您可以通过从区域内的堡垒主机调用 `aws ssm start-session --target instance-id ` 来对此进行验证。如果该命令不起作用，请检查 Systems Manager 是否在控制面板实例上运行。 + 由于 EBS 卷的 KMS 密钥权限问题，无法创建新的控制面板实例。若使用用户管理型 KMS 密钥加密了 EBS 卷，如果密钥不可访问，控制面板实例会终止。如果实例终止，要么切换到 AWS 托管式 KMS 密钥，要么确保用户管理型密钥策略会向集群角色授予必要权限。 + Systems Manager 控制面板实例可能已失去互联网访问权限。检查您在创建集群时提供的子网是否具有 NAT 网关和带有互联网网关的 VPC。使用 VPC Reachability Analyzer 验证控制面板实例是否可以访问互联网网关。有关更多信息，请参阅 [VPC Reachability Analyzer 入门](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html)。如果私有网络没有出站互联网连接，则确保所有必要的 VPC 端点和网关端点仍存在于集群的区域子网中（请参阅[子网对 AWS 服务的访问权限](eks-outposts-vpc-subnet-requirements.md#subnet-access-to-services)）。 + 您提供的角色 ARN 缺少策略。检查是否从角色中移除了 [AWS 托管式策略：AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy)。 + 其中一个新的 Kubernetes 控制面板实例可能遇到了意料之外的引导失败问题。如果遇到这种特殊情况，请向 [AWS Support Center](https://console.aws.amazon.com/support/home) 提交工单，获取有关问题排查和日志收集的进一步指导。 ## 无法将节点加入集群 + AMI 问题： + 当前使用的 AMI 不兼容。仅支持 Amazon EKS 优化版 Amazon Linux 2 AMI（`amazon-linux-2`、`amazon-linux-2-gpu`、`amazon-linux-2-arm64`）。若尝试将 AL2023 节点加入部署于 AWS Outposts 上的 EKS 本地集群，这些节点将无法成功加入集群。有关更多信息，请参阅[在 AWS Outposts 上创建 Amazon Linux 节点](eks-outposts-self-managed-nodes.md)。 + 如果您使用 AWS CloudFormation 模板创建您的节点，请确保它没有使用不受支持的 AMI。 + 缺失 AWS IAM 身份验证器 `ConfigMap` – 如果缺失，则必须进行创建。有关更多信息，请参阅 [将 `aws-auth` `ConfigMap` 应用到集群](auth-configmap.md#aws-auth-configmap)。 + 使用了错误的安全组 – 请确保将 `eks-cluster-sg-cluster-name-uniqueid ` 用于 Worker 节点的安全组。将通过 AWS CloudFormation 更改所选的安全组，以便在每次使用堆栈时允许新的安全组。 + 遵循意外的私有链接 VPC 步骤 - 传递错误的 CA 数据 (`--b64-cluster-ca`) 或 API 端点 (`--apiserver-endpoint`)。 ## 收集日志 如果 Outpost 与其关联的 AWS 区域断开连接，Kubernetes 集群可能会继续正常运行。但是，如果集群无法正常运行，请执行[在 AWS Outposts 上准备本地 Amazon EKS 集群以防断网](eks-outposts-network-disconnects.md)中的问题排查步骤。如果遇到任何问题，请与 AWS Support 联系。AWSSupport 会指导您如何下载和运行日志收集工具。这样一来，您就可以从 Kubernetes 集群控制面板实例中收集日志，并将其发送到 AWS Support 支持部门，以便进一步调查。 ## 无法通过 AWS Systems Manager 访问控制面板实例 当无法通过 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 和子网](eks-outposts-vpc-subnet-requirements.md)中的要求，并且您已完成《AWS Systems Manager 用户指南》内[设置 Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html) 中的步骤。