排解 Cloud NAT 問題

本指南可協助您診斷工作負載 (Pod 或 VM) 無法使用 Cloud NAT 存取外部網路的原因。身為開發人員,您主要會與 CloudNatGateway 資源互動。這項資源的狀態是偵錯的主要可靠資料來源。

事前準備

如要排解 Cloud NAT 設定問題,您必須具備下列條件:

  • 必要的身分和存取權角色。請要求 IAM 專案管理員授予您下列其中一或兩個角色:
    • Cloud NAT 檢視者 (cloud-nat-viewer):這個角色具備 Cloud NAT 資源的唯讀存取權。這個角色可讓您開始診斷問題。
    • Cloud NAT 開發人員 (cloud-nat-developer):這個角色提供必要權限,可讓應用程式操作員在指派的專案中,建立、讀取、更新及刪除 (CRUD) Cloud NAT 物件。這個角色可讓您執行本頁所述的多項修正。
    • 如要採取某些診斷措施和修正問題,可能需要其他角色。

初步診斷

在深入探討錯誤代碼之前,請先確認基本資源存在且可供存取。

指令:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

更改下列內容:

  • GATEWAY_NAME:CloudNatGateway 資源的名稱。
  • PROJECT_NAMESPACE:專案的命名空間。

檢查狀態條件:健康的閘道必須將下列所有條件設為 True:

  • Ready:全域健康狀態。
  • SubnetsReady:IP 集區設定有效。
  • PerimeterConfigurationReady:上游網路基礎架構已設定完成。
  • EgressRoutesReady:Pod 的路由政策已啟用。

如果其中任何一項為 False,請檢查狀態輸出內容中的 reason 和 message 欄位,並參閱下列各節中的表格。

錯誤代碼參考資料和修正方法

kubectl get cloudnatgateway 傳回的錯誤代碼主要分為三大類。

子網路錯誤 (SubnetsReady 為 False)

這表示指派給閘道的 IP 位址集區有問題。

錯誤代碼 代表意義 修復步驟
CloudNATSelectorFieldOverlapsCode 設定衝突。這個閘道的workloadSelector與專案中另一個閘道的工作負載相同。無法確定流量轉送路徑。
  1. 列出專案中的所有 Cloud NAT 閘道:kubectl get cloudnatgateway
  2. 比較這個閘道的workloadSelector與其他閘道。
  3. 修改標籤,確保沒有任何 Pod/VM 會由多個閘道選取。
CloudNATSubnetRefsFieldInvalidCode

子網路無效。subnetRefs 中指定的子網路無法使用。常見原因:

  • 子網路不存在。
  • 子網路未處於Ready狀態。
  • 子網路類型不是 Leaf。
  1. 確認子網路是否存在:kubectl get subnet <SUBNET_NAME>
  2. 確認子網路狀態為 Ready。
  3. 確認子網路 type 為 Leaf (Cloud NAT 無法使用根或回送子網路)。
CloudNATSubnetAlreadyInUseCode 子網路衝突。您要求的子網路已由另一個 Cloud NAT 閘道「擁有」。子網路一次只能連結至一個閘道。
  1. 請為這個閘道選擇其他子網路。
  2. 或者,請先從其他閘道移除子網路。
UNETAPIServerErrorCode 系統錯誤。控制器無法與 API 伺服器通訊,因此無法驗證子網路。 行動:這可能是暫時性的平台問題。如果問題持續發生,請與平台管理員聯絡。

perimeter 設定錯誤 (PerimeterConfigurationReady 為 False)

這項條件反映了 perimeter 閘道的狀態。

錯誤代碼 代表意義 修復步驟
NET-E0305 設定衝突。(同上)。選取器重疊會導致系統無法計算正確的轉送群組。
  1. 列出專案中的所有 Cloud NAT 閘道:kubectl get cloudnatgateway
  2. 比較這個閘道的workloadSelector與其他閘道。
  3. 修改標籤,確保沒有任何 Pod/VM 會由多個閘道選取。
NET-E0301 資源耗盡/節點故障。系統已建立設定,但無法將輸出 IP 指派給健康狀態良好的實體節點。這通常代表子網路的 IP 已用盡,或是閘道節點已關閉。
  1. 請檢查 [子網路](/distributed-cloud/hosted/docs/1.16/gdcag/platform/pa-user/subnets-overview)用量。是否已滿?
  2. 如果子網路有可用 IP 且為 Ready,表示平台端基礎架構發生故障 (例如沒有可用的健康閘道節點)。動作:聯絡平台管理員。
NET-E0001 系統錯誤。控制器通訊失敗。 動作:與平台管理員聯絡。

輸出路由錯誤 (EgressRoutesReady 為 False)

這項條件反映叢集內路由政策的狀態。

錯誤代碼 代表意義 修復步驟
NET-E0305 設定衝突。(同上)。
  1. 列出專案中的所有 Cloud NAT 閘道:kubectl get cloudnatgateway
  2. 比較這個閘道的workloadSelector與其他閘道。
  3. 修改標籤,確保沒有任何 Pod/VM 會由多個閘道選取。
NET-E0304 程式設計失敗。系統無法為特定閘道 IP 設定路由規則 (BPF)。

動作:這是內部程式設計錯誤或狀態不一致。

  1. 請嘗試對閘道進行微幅更新 (例如編輯標籤),觸發協調程序。
  2. 如果問題持續發生,請與平台管理員聯絡。

其他常見問題

如果閘道狀態為 Ready: True,但流量仍無法通過,請檢查下列常見的錯誤設定:

缺少專案層級權限

專案必須明確獲得授權,才能輸出流量。

  • 檢查:專案資源是否含有 networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true" 標籤?
  • 修正方式:請專案管理員套用這個標籤。

缺少 VM 註解 (僅限虛擬機器)

VM 會略過標準 Pod 輸出路徑,且需要明確指示才能使用 Cloud NAT。

  • 檢查:VM 的 VirtualMachineExternalAccess (VMEA) 物件是否含有 egress.networking.gke.io/use-cloud-nat: "true" 註解?
  • 修正方式:在 VMEA 物件中加入註解。

Standard 叢集節點輸出

如果您執行的是 Standard 叢集,節點本身需要具備輸出權限。

  • 檢查:Cluster 物件是否具有 cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true" 標籤?
  • 修正方式:請平台管理員為叢集物件加上標籤。

預設輸出 NAT 與 Cloud NAT 衝突

常見的設定錯誤是,工作負載設為使用舊版預設輸出 NAT 機制,同時由 Cloud NAT 閘道選取。這種組合會導致衝突,資料層會收到相互衝突的轉送指示,進而造成封包遺失或不確定的轉送行為。

診斷 Pod 衝突

如要為 Pod 啟用預設輸出 NAT,通常需要新增特定標籤。Pod 不能同時具有這個標籤,且為 Cloud NAT 閘道的目標。

  1. 找出目標 Pod:取得連線問題 Pod 的標籤。

    kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels
    
  2. 檢查標籤是否衝突:

    • Cloud NAT 選取:Pod 的標籤是否與命名空間中任何 CloudNatGateway 的 workloadSelector 相符?
    • 預設輸出標籤:Pod 是否有 egress.networking.gke.io/enabled: "true" 標籤?

    條件:如果兩者皆為 true,就會發生衝突。

  3. 解決方法:從 Pod (或其父項 Deployment/StatefulSet) 移除舊版預設輸出標籤,讓 Cloud NAT 取得專屬控制權。

診斷 VM 衝突

虛擬機器的機制則不同。具有 VirtualMachineExternalAccess (VMEA) 物件的 VM 通常會設為預設存取權。如要使用 Cloud NAT,必須明確選擇加入,方法是新增註解,停用預設路徑並啟用 Cloud NAT 路徑。

  1. 找出 VMEA:找出與 VM 相關聯的 VirtualMachineExternalAccess 物件。

    kubectl get vmea -n <NAMESPACE>
    
  2. 檢查是否缺少註解:

    • Cloud NAT 選取:VM 的標籤是否與CloudNatGateway相符?
    • 選擇加入註解:請查看 VMEA 的 egress.networking.gke.io/use-cloud-nat: "true" 註解。

    條件:如果 VM 與閘道相符,但缺少這個註解,流量就會與預設輸出系統發生衝突。

  3. 解決方法:將註解新增至 VMEA 物件。

    kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"