**協助改進此頁面** 

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 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>

混合節點上執行的 Pod 無法從 VPC 中的資源連線，例如 EC2 執行個體、負載平衡器或 Kubernetes 控制平面。

 **可能原因：**
+ VPC 路由表項目遺失或指向錯誤的 ENI。
+ 閘道領導者 Pod 未執行或未完成設定。
+ 混合節點上未啟用或設定 Cilium VTEP。
+ 閘道 EC2 執行個體上已啟用來源/目的地檢查。

 **診斷步驟：**

1.  **檢查 VPC 路由表項目。**確認混合 Pod CIDRs路由是否存在，並指向作用中閘道執行個體的主要 ENI：

   ```
   aws ec2 describe-route-tables \
     --route-table-ids {{ROUTE_TABLE_ID}} \
     --query "RouteTables[].Routes[?DestinationCidrBlock=='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 路由表，再將其轉送至閘道的 ENI。使用 中的步驟，確認 VPC 路由表項目正確無誤[無法從 VPC 連線混合節點上的 Pod](#hybrid-nodes-gateway-ts-unreachable)。

1.  **檢查 CiliumVTEPConfig 資源。**驗證資源是否存在，且 `tunnelEndpoint`符合目前領導者的節點 IP：

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

   如果通道端點過時 （指向先前的領導者），閘道可能尚未完成領導者設定序列。檢查閘道日誌在 `CiliumVTEPConfig` upsert 期間是否有錯誤。

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

閘道日誌會顯示與 VPC 路由表操作相關的錯誤，而且混合 Pod CIDRs路由不會建立或更新。

 **可能原因：**
+ 閘道的 IAM 角色沒有必要的 EC2 許可。
+ 組態中的路由表 IDs 不正確或路由表不存在。
+ 閘道無法連線到 EC2 API 端點。

 **診斷步驟：**

1.  **驗證 IAM 許可。**閘道需要下列 IAM 動作：
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

     檢查連接至閘道節點執行個體描述檔或 Pod 身分組態的 IAM 角色。

1.  **檢查組態中的路由表 IDs。**確認`ROUTE_TABLE_IDS`環境變數在閘道部署中包含有效的路由表 IDs：

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

   確認您的 VPC 中存在路由表 IDs：

   ```
   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 許可和路由表 IDs。
   +  `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 日誌中看到的錯誤訊息及其解決方法。


| 錯誤訊息 | 原因 | Resolution | 
| --- | --- | --- | 
|  `IP forwarding is not enabled`  | 核心參數`net.ipv4.ip_forward`未在閘道節點`1`上設定為 。 | 透過 kubelet 組態或執行 來啟用 IP 轉送`sysctl -w net.ipv4.ip_forward=1`。 | 
|  `Failed to setup VXLAN`  | 閘道無法建立 VXLAN 網路介面。這通常發生在 Pod 缺少 `NET_ADMIN`功能時。 | 驗證 部署規格是否包含在 `NET_ADMIN`中`securityContext.capabilities.add`。檢查 Helm Chart 是否正確部署。 | 
|  `Failed to verify route table access`  | 閘道無法在啟動時描述一或多個 VPC 路由表。 | 確認 IAM 角色具有`ec2:DescribeRouteTables`許可，且組態中的路由表 IDs 正確。 | 
|  `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`旗標。 | `status.hostIP` 使用 驗證`NODE_IP`來自 的 Pod 規格集`fieldRef`。檢查 Helm Chart 是否正確部署。 | 
|  `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` 值已設定，但在剖析後不包含有效的路由表 IDs。 | 檢查 `routeTableIDs` Helm 值是否有格式錯誤。路由表 IDs應以逗號分隔 （例如 `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 CIDRs。 | 確認混合節點上的 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) — 監控、容錯移轉行為和擴展指引。