**帮助改进此页面** 

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

# Amazon EKS 混合节点功能网关问题排查
<a name="hybrid-nodes-gateway-troubleshooting"></a>

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

## 无法从 VPC 访问混合节点上的容器组（pod）
<a name="hybrid-nodes-gateway-ts-unreachable"></a>

无法从 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，则失效转移可能未成功完成。

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

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

   如果没有容器组（pod）持有租约，请参阅[主节点选举问题](#hybrid-nodes-gateway-ts-leader)。

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

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

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

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

   ```
   aws ec2 describe-instance-attribute \
     --instance-id {{GATEWAY_INSTANCE_ID}} \
     --attribute sourceDestCheck
   ```

   如果 `sourceDestCheck` 为 `true`，则将其禁用。请参阅[开始使用 EKS 混合节点功能的网关](hybrid-nodes-gateway-getting-started.md)。

## 对混合节点的 Webhook 调用失败
<a name="hybrid-nodes-gateway-ts-webhooks"></a>

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

 **可能的原因：**
+ 网关没有将流量从控制面板路由到混合容器组（pod）。
+ `CiliumVTEPConfig` 资源缺失或有陈旧的端点 IP。

 **诊断步骤：**

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

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

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

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

## VPC 路由表更新失败
<a name="hybrid-nodes-gateway-ts-routes"></a>

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

 **可能的原因：**
+ 网关的 IAM 角色没有所需的 EC2 权限。
+ 配置中的路由表 ID 不正确或路由表不存在。
+ 网关无法访问 EC2 API 端点。

 **诊断步骤：**

1.  **验证 IAM 权限。**网关需要以下 IAM 操作：
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

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

1.  **检查配置中的路由表 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}}
   ```

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

   ```
   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）无法启动或运行状况不佳
<a name="hybrid-nodes-gateway-ts-pods"></a>

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

 **可能的原因：**
+ 未设置必需的环境变量（`VPC_CIDR`、`POD_CIDRS`、`ROUTE_TABLE_IDS`）。
+ 网关节点上未启用 IP 转发。
+ 节点标签或反关联性约束会阻止调度。

 **诊断步骤：**

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

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

1.  **检查必需的环境变量。**网关需要 `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 值。验证它们是否设置正确。

1.  **检查 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/` 中。

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

   ```
   kubectl describe pod -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

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

## 主节点选举问题
<a name="hybrid-nodes-gateway-ts-leader"></a>

网关容器组（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 服务器的连接。

1.  **检查 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` 动词。

1.  **检查容器组（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`。

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

   ```
   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`。如果续订截止日期超过租赁持续时间，则主节点将在续订之前失去租约。有关更多信息，请参阅[主节点选举调优](hybrid-nodes-gateway-configuration.md#hybrid-nodes-gateway-leader-tuning)。

## 常见错误消息
<a name="hybrid-nodes-gateway-ts-errors"></a>

下表列出了您在网关容器组（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 存储库](https://github.com/aws/eks-hybrid-nodes-gateway)中报告问题。 | 
|  `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 是否正确。路由表必须与网关实例存在于同一区域中。 | 

## 相关主题
<a name="hybrid-nodes-gateway-ts-related"></a>
+  [Amazon EKS 混合节点功能网关](hybrid-nodes-gateway-overview.md)：网关架构和使用案例概述。
+  [开始使用 EKS 混合节点功能的网关](hybrid-nodes-gateway-getting-started.md)：先决条件和安装说明。
+  [Amazon EKS 混合节点功能网关配置参考](hybrid-nodes-gateway-configuration.md)：Helm 值、CLI 标志和环境变量的完整参考。
+  [Amazon EKS 混合节点功能网关操作](hybrid-nodes-gateway-operations.md)：监控、失效转移行为和扩展指导。