View a markdown version of this page

Amazon EKS 混合节点功能网关问题排查 - Amazon EKS
无法从 VPC 访问混合节点上的容器组（pod）对混合节点的 Webhook 调用失败VPC 路由表更新失败网关容器组（pod）无法启动或运行状况不佳主节点选举问题常见错误消息相关主题

帮助改进此页面

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的在 GitHub 上编辑此页面链接。

Amazon EKS 混合节点功能网关问题排查

本页为诊断和解决 Amazon EKS 混合节点功能网关的常见问题提供了指导。每个小节都描述了症状、可能的原因、诊断步骤和解决方案。有关操作详细信息，请参阅 Amazon EKS 混合节点功能网关操作。

无法从 VPC 访问混合节点上的容器组（pod）

无法从 VPC 中的资源（如 EC2 实例、负载均衡器或 Kubernetes 控制面板）访问混合节点上运行的容器组（pod）。

可能的原因：

  • VPC 路由表条目缺失或指向错误的 ENI。

  • 网关主节点容器组（pod）未运行或尚未完成设置。

  • 未在混合节点上启用或配置 Cilium VTEP。

  • 已在网关 EC2 实例上启用源/目标检查。

诊断步骤：

  1. 检查 VPC 路由表条目。验证您的混合容器组（pod）CIDR 的路由是否存在，并指向活动网关实例的主 ENI：

    aws ec2 describe-route-tables \
  --route-table-ids ROUTE_TABLE_ID \
  --query "RouteTables[].Routes[?DestinationCidrBlock=='[.replaceable]`POD_CIDR`']"

    如果缺少路由，请检查网关日志中是否存在路由表错误。如果路由指向错误的 ENI，则失效转移可能未成功完成。

  2. 检查网关容器组（pod）状态和主节点选举。确认两个网关容器组（pod）正在运行，其中一个持有主节点租约：

    kubectl get pods -n eks-hybrid-nodes-gateway
kubectl get lease -n eks-hybrid-nodes-gateway

    如果没有容器组（pod）持有租约，请参阅主节点选举问题。

  3. 检查混合节点上的 Cilium VTEP 配置。验证 CiliumVTEPConfig 资源是否存在且包含主节点 IP：

    kubectl get ciliumvtepconfig hybrid-gateway -o yaml

    spec.endpoints[0].tunnelEndpoint 应与主节点网关节点的 IP 地址相匹配。如果资源缺失或有陈旧的 IP，则网关可能尚未完成主节点设置。

  4. 进行源/目标检查。验证网关 EC2 实例上是否已禁用源/目标检查：

    aws ec2 describe-instance-attribute \
  --instance-id GATEWAY_INSTANCE_ID \
  --attribute sourceDestCheck

    如果 sourceDestCheck 为 true，则将其禁用。请参阅开始使用 EKS 混合节点功能的网关。

对混合节点的 Webhook 调用失败

Kubernetes API 服务器无法访问在混合节点上运行的 Webhook 端点。Webhook 准入请求超时或返回连接错误。

可能的原因：

  • 网关没有将流量从控制面板路由到混合容器组（pod）。

  • CiliumVTEPConfig 资源缺失或有陈旧的端点 IP。

诊断步骤：

  1. 验证控制面板能否访问网关节点 IP。控制面板将流量发送到 VPC 路由表，VPC 路由表将其转发到网关的 ENI。使用无法从 VPC 访问混合节点上的容器组（pod）中的步骤确认 VPC 路由表条目是否正确。

  2. 检查 CiliumVTEPConfig 资源。验证资源是否存在，且 tunnelEndpoint 是否与当前主节点 IP 相匹配：

    kubectl get ciliumvtepconfig hybrid-gateway -o yaml

    如果隧道端点已过时（指向先前的主节点），网关可能尚未完成主节点设置序列。在 CiliumVTEPConfig 更新插入期间，检查网关日志中是否存在错误。

VPC 路由表更新失败

网关日志显示与 VPC 路由表操作相关的错误，并且未创建或更新混合容器组（pod）CIDR 的路由。

可能的原因：

  • 网关的 IAM 角色没有所需的 EC2 权限。

  • 配置中的路由表 ID 不正确或路由表不存在。

  • 网关无法访问 EC2 API 端点。

诊断步骤：

  1. 验证 IAM 权限。网关需要以下 IAM 操作：

    • ec2:DescribeRouteTables

    • ec2:CreateRoute

    • ec2:ReplaceRoute

    • ec2:DescribeInstances

      检查附加到网关节点的实例配置文件或容器组身份配置的 IAM 角色。

  2. 检查配置中的路由表 ID。验证 ROUTE_TABLE_IDS 环境变量在网关部署中是否包含有效的路由表 ID：

    kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].env}' | jq .

    确认路由表 ID 存在于 VPC 中：

    aws ec2 describe-route-tables --route-table-ids ROUTE_TABLE_ID

  3. 检查网关日志中是否存在路由表错误。查找与路由表操作相关的错误消息：

    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD | grep -i "route table"

    常见错误消息包括：

    • Failed to verify route table access：网关无法描述路由表。检查 IAM 权限与路由表 ID。

    • Failed to update route tables：网关无法创建或替换路由。检查 IAM 权限。

    • failed to access route table：路由表 ID 可能不正确或 IAM 角色缺少 ec2:DescribeRouteTables。

网关容器组（pod）无法启动或运行状况不佳

网关容器组（pod）处于 CrashLoopBackOff、Error 或 Pending 状态，或者运行状况端点返回错误。

可能的原因：

  • 未设置必需的环境变量（VPC_CIDR、POD_CIDRS、ROUTE_TABLE_IDS）。

  • 网关节点上未启用 IP 转发。

  • 节点标签或反关联性约束会阻止调度。

诊断步骤：

  1. 检查容器组（pod）日志。查看失败容器组（pod）的日志以发现错误：

    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD

  2. 检查必需的环境变量。网关需要 NODE_IP、VPC_CIDR 和 POD_CIDRS。如果缺少任何一项，网关会立即退出。验证容器组（pod）规范：

    kubectl get pod -n eks-hybrid-nodes-gateway LEADER_POD -o jsonpath='{.spec.containers[0].env}' | jq .

    • NODE_IP 是根据容器组（pod）规范中的 status.hostIP 自动设置。如果为空，则可能尚未在节点上调度容器组（pod）。

    • VPC_CIDR 和 POD_CIDRS 来自 Helm 值。验证它们是否设置正确。

  3. 检查 IP 转发。网关将检查启动时是否启用 IP 转发，如果未启用，则退出。在容器组（pod）日志中查找错误消息 IP forwarding is not enabled。在节点上启用 IP 转发：

    # Check current setting
cat /proc/sys/net/ipv4/ip_forward

# Enable if not set
sudo sysctl -w net.ipv4.ip_forward=1

    为实现持久的设置，请通过 kubelet 配置 IP 转发或将 net.ipv4.ip_forward=1 添加到 /etc/sysctl.d/ 中。

  4. 检查节点标签和调度约束。网关容器组（pod）需要带有 hybrid-gateway-node=true 标签的节点。容器组（pod）反关联性可确保每个容器组（pod）都在单独的节点上运行。如果容器组（pod）处于 Pending 状态，请检查是否存在调度问题：

    kubectl describe pod -n eks-hybrid-nodes-gateway LEADER_POD

    查找表明节点不足、标签缺失或反关联性冲突的事件。

主节点选举问题

网关容器组（pod）正在运行，但没有容器组（pod）获得主节点租约，或主节点身份频繁转换。

可能的原因：

  • 缺少租约对象的 RBAC 权限。

  • 网关容器组（pod）和 Kubernetes API 服务器之间的网络连接不可靠。

  • 主节点选举参数配置错误。

诊断步骤：

  1. 检查租约对象。验证租约是否存在并检查其当前持有人：

    kubectl get lease -n eks-hybrid-nodes-gateway hybrid-gateway-leader -o yaml

    spec.holderIdentity 字段显示了当前主节点。spec.renewTime 显示了上次续订租约的时间。如果 renewTime 已过时，则主节点可能已断开与 API 服务器的连接。

  2. 检查 RBAC 权限。网关服务账户需要权限才能获取、创建和更新网关命名空间中的租约对象。验证角色和 RoleBinding：

    kubectl get role -n eks-hybrid-nodes-gateway
kubectl get rolebinding -n eks-hybrid-nodes-gateway

    角色应包含 coordination.k8s.io API 组中 leases 资源的 get、create 和 update 动词。

  3. 检查容器组（pod）日志中是否存在租约错误。在容器组（pod）日志中查找主节点选举错误：

    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD | grep -i "leader\|lease"

    常见问题包括：

    • Failed to acquire lease：容器组（pod）无法创建或更新租约对象。检查 RBAC 权限。

    • 频繁的 Leadership ended 后跟 Leader setup complete 消息：主节点正在失去租约并重新获得租约。这可能表明容器组（pod）和 API 服务器之间的网络不稳定。请考虑增加 --leader-election-lease-duration。

  4. 检查主节点选举参数。验证配置的值：

    kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].args}'

    确保 --leader-election-renew-deadline 小于 --leader-election-lease-duration。如果续订截止日期超过租赁持续时间，则主节点将在续订之前失去租约。有关更多信息，请参阅主节点选举调优。

常见错误消息

下表列出了您在网关容器组（pod）日志中可能看到的错误消息及其解决方案。

错误消息 原因 解决方案

IP forwarding is not enabled

网关节点上的内核参数 net.ipv4.ip_forward 未设置为 1。

通过 kubelet 配置或运行 sysctl -w net.ipv4.ip_forward=1 来启用 IP 转发。

Failed to setup VXLAN

网关无法创建 VXLAN 网络接口。这通常发生在容器组（pod）缺少 NET_ADMIN 功能时。

验证部署规范是否将 NET_ADMIN 包含在 securityContext.capabilities.add 中。检查 Helm 图表是否已正确部署。

Failed to verify route table access

启动时，网关无法描述一个或多个 VPC 路由表。

验证 IAM 角色是否具有 ec2:DescribeRouteTables 权限以及配置中的路由表 ID 是否正确。

Failed to update route tables

网关无法创建或替换 VPC 路由表中的路由。

验证 IAM 角色是否具有 ec2:CreateRoute 和 ec2:ReplaceRoute 权限。

Failed to create route table manager

网关无法初始化 AWS EC2 客户端或检索实例的主 ENI。

验证 IAM 角色是否具有 ec2:DescribeInstances 权限且实例元数据服务（IMDS）是否可访问。

NODE_IP is required

未设置 NODE_IP 环境变量或 --node-ip 标志。

使用 fieldRef 验证容器组（pod）规范是否根据 status.hostIP 设置 NODE_IP。检查 Helm 图表是否已正确部署。

Invalid NODE_IP

为 NODE_IP 提供的值不是有效的 IP 地址。

检查容器组（pod）规范中的 NODE_IP 环境变量值。

pod-cidrs and vpc-cidr are required

POD_CIDRS 或 VPC_CIDR 环境变量为空。

在安装过程中设置 podCIDRs 和 vpcCIDR Helm 值。

No valid route table IDs provided

ROUTE_TABLE_IDS 值已设置，但在解析后不包含有效的路由表 ID。

检查 routeTableIDs Helm 值是否存在格式错误。路由表 ID 应使用逗号分隔（例如 rtb-abc123,rtb-def456）。

Failed to auto-detect AWS region

网关无法从 EC2 实例元数据中检索 AWS 区域。

验证实例元数据服务（IMDS）是否可访问。或者，显式设置 --aws-region 标志或 AWS_REGION 环境变量。

Failed to auto-detect AWS instance ID

网关无法从 EC2 实例元数据中检索 实例 ID。

验证实例元数据服务（IMDS）是否可访问。或者，显式设置 --aws-instance-id 标志或 AWS_INSTANCE_ID 环境变量。

CiliumNode has no internal IP

混合节点的 CiliumNode 对象在其规范中没有内部 IP 地址。

验证混合节点是否已正确注册且 Cilium 代理是否正在运行。检查节点的 CiliumNode 资源。

CiliumNode <name> has no pod CIDRs allocated

混合节点的 CiliumNode 对象没有 Cilium IPAM 分配的容器组（pod）CIDR。

验证混合节点上的 Cilium IPAM 配置是否正确。检查 CiliumNode 资源以了解节点的 IPAM 状态。

Failed to upsert CiliumVTEPConfig

网关无法创建或更新 CiliumVTEPConfig 自定义资源。

验证 CRD 是否已安装在集群中，并且网关服务账户是否有权管理 CiliumVTEPConfig 资源。

Unable to create manager

控制器运行时管理器无法初始化。

查看容器组（pod）日志以了解其他上下文。常见原因包括 kubeconfig 无效或无法访问 Kubernetes API 服务器。

Failed to add gateway setup

无法在控制器管理器中注册由主节点选举的可运行对象。

这通常是内部错误。检查完整的容器组（pod）日志以了解其他上下文，并在 GitHub 存储库中报告问题。

Unable to create Node controller

无法在控制器管理器中注册 CiliumNode 协调程序。

查看容器组（pod）日志以了解其他上下文。验证 CiliumNode CRD 是否已安装在集群中。

Problem running manager

控制器管理器意外退出。

检查容器组（pod）日志中是否存在底层错误。常见原因包括与 Kubernetes API 服务器的连接断开，或指标或运行状况探针绑定地址上的端口冲突。

failed to access route table <id>

在启动验证检查期间，网关无法描述特定的 VPC 路由表。

验证 IAM 角色是否具有 ec2:DescribeRouteTables 权限以及路由表 ID 是否正确。路由表必须与网关实例存在于同一区域中。