排解 GKE 中的網路隔離問題

本頁面說明如何解決 Google Kubernetes Engine (GKE) 網路隔離問題。

GKE 叢集未執行

刪除以下項目會導致叢集停止運作：允許從叢集控制層輸入流量到通訊埠 10250 上的節點的防火牆規則，以及預設網際網路閘道的預設路徑。如果刪除預設路徑，請務必確保流量會轉送至必要的Google Cloud 服務。詳情請參閱自訂路徑。

建立叢集時逾時

問題

在 1.28 版或更早版本中建立的叢集，如果使用私人節點，則需要 VPC 之間的對等互連路徑。不過，一次只能執行一項對等互連作業。如果嘗試同時建立多個具有上述特徵的叢集，叢集建立作業可能會逾時。

解決方法

請使用下列其中一種解決方案：

• 依序建立 1.28 以下版本的叢集，這樣後續每個沒有外部端點的叢集，都會有虛擬私有雲對等互連路由。如果虛擬私有雲正在執行作業，嘗試建立單一叢集也可能會逾時。

• 建立 1.29 以上版本的叢集。

不慎刪除 VPC 網路對等互連連線

問題

如果不小心刪除虛擬私有雲網路對等互連連線，叢集會進入修復狀態，所有節點都會顯示 UNKNOWN 狀態。由於與控制層的連線已中斷，您將無法對叢集執行任何作業。檢查控制層時，記錄會顯示類似下列的錯誤：

error checking if node NODE_NAME is shutdown: unimplemented

可能原因

您不小心刪除了 VPC 網路對等互連連線。

解決方法

1. 建立新的 GKE 叢集，版本須早於 PSC 切換時間，並使用特定設定。這項操作會強制重新建立虛擬私有雲對等互連連線，讓舊版叢集恢復正常運作。
   • 請為新叢集使用下列特定設定：
     • 發布版本：延長版
     • 叢集版本：1.29 之前的版本，例如 1.28.15-gke.2403000
     • 主要 IPv4 CIDR：特定 IP 位址範圍，例如 --master-ipv4-cidr=172.16.0.192/28
2. 監控原始叢集狀態。
   • 建立新叢集 (並重新建立 VPC 對等互連) 後，原始叢集應會從修復狀態復原，節點也會恢復 Ready 狀態。
3. 刪除暫時建立的 GKE 叢集。
   • 原始叢集完全還原並正常運作後，即可刪除暫時建立的 GKE 叢集。

不慎刪除 Private Service Connect 端點和轉送規則

問題

如果不小心刪除 Private Service Connect 端點或轉送規則，叢集會進入修復狀態，所有節點都會顯示 UNKNOWN 狀態。由於控制層的存取權已中斷，您將無法對叢集執行任何作業。檢查控制層時，記錄會顯示類似下列的錯誤：

error checking if node NODE_NAME is shutdown: unimplemented

可能原因

您不小心刪除了 Private Service Connect 端點或轉送規則。這兩個資源都命名為 gke-[cluster-name]-[cluster-hash:8]-[uuid:8]-pe，並允許控制層和節點私下連線。

解決方法

輪替控制層 IP 位址。

叢集與使用中的對等互連重複

問題

如果嘗試建立沒有外部端點的叢集，會傳回類似下列的錯誤：

Google Compute Engine: An IP range in the peer network overlaps with an IP
range in an active peer of the local network.

可能原因

您選擇了重複的控制層 CIDR。

解決方法

請使用下列其中一種解決方案：

• 刪除叢集，並使用另一個控制層 CIDR 重新建立叢集。
• 在 1.29 版中重新建立叢集，並加入 --enable-private-nodes 旗標。

無法連線至沒有外部端點的叢集控制層

實作任何叢集端點存取設定，提高叢集控制層可連線的機率。詳情請參閱叢集端點存取權。

問題

建立沒有外部端點的叢集後，嘗試對叢集執行 kubectl 指令時，會傳回類似下列其中一個的錯誤：

Unable to connect to the server: dial tcp [IP_ADDRESS]: connect: connection
timed out.

Unable to connect to the server: dial tcp [IP_ADDRESS]: i/o timeout.

可能原因

kubectl 無法與叢集控制層通訊。

解決方法

請使用下列其中一種解決方案：

• 啟用 DNS 存取權，簡化叢集的安全存取方式。詳情請參閱以 DNS 為基礎的端點。

• 確認已為 kubeconfig 產生叢集的憑證，或已啟用正確的環境。如要進一步瞭解如何設定叢集憑證，請參閱產生 kubeconfig 項目。

• 確認系統允許使用外部 IP 位址存取控制層。停用叢集控制層的外部存取權，可將叢集與網際網路隔離。完成這項設定後，只有授權的內部網路 CIDR 範圍或保留網路，才能存取控制層。

  1. 確認來源 IP 位址已獲授權可連線至控制層：

       gcloud container clusters describe CLUSTER_NAME \
           --format="value(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetworksConfig)"\
           --location=COMPUTE_LOCATION
     

     更改下列內容：

     • CLUSTER_NAME：叢集名稱。
     • COMPUTE_LOCATION：叢集的 Compute Engine 位置。

     如果來源 IP 位址未獲授權，輸出內容可能會傳回空白結果 (只有大括號)，或是不含來源 IP 位址的 CIDR 範圍

     cidrBlocks:
       cidrBlock: 10.XXX.X.XX/32
       displayName: jumphost
       cidrBlock: 35.XXX.XXX.XX/32
       displayName: cloud shell
     enabled: true
     

  2. 新增授權網路，存取控制層。

• 如果您從地端部署環境或與叢集位置不同的區域執行 kubectl 指令，請務必啟用控制層私人端點全域存取權。詳情請參閱「從任意區域透過控制層的內部 IP 位址存取」。

  1. 描述叢集，查看控制存取權設定的回應：

     gcloud container clusters describe CLUSTER_NAME \
         --location=COMPUTE_LOCATION \
         --flatten "controlPlaneEndpointsConfig.ipEndpointsConfig.globalAccess"
     

     更改下列內容：

     • CLUSTER_NAME：叢集名稱。
     • COMPUTE_LOCATION：叢集的 Compute Engine 位置。

     成功輸出結果會與下列內容相似：

       enabled: true
     

  2. 如果傳回 null，請從任意區域透過控制層的內部 IP 位址啟用存取權。

由於 IPv4 CIDR 區塊重複而無法建立叢集

問題

gcloud container clusters create 會傳回類似以下的錯誤：

The given master_ipv4_cidr 10.128.0.0/28 overlaps with an existing network
10.128.0.0/20.

可能原因

您指定的控制層 CIDR 區塊與虛擬私有雲中現有的子網路重複。

解決方法

為 --master-ipv4-cidr 指定一個未與現有子網路重複的 CIDR 區塊。

由於服務範圍已由其他叢集使用，因此無法建立叢集

問題

嘗試建立叢集時，會傳回類似以下的錯誤：

Services range [ALIAS_IP_RANGE] in network [VPC_NETWORK], subnetwork
[SUBNET_NAME] is already used by another cluster.

可能原因

下列設定可能會導致這項錯誤：

• 您選擇的服務範圍仍由其他叢集使用，或叢集未刪除。
• 該服務範圍曾用於某個叢集，但該叢集已刪除，且次要範圍中繼資料未正確清除。GKE 叢集的次要範圍會儲存在 Compute Engine 中繼資料中，叢集刪除後應一併移除。即使叢集已成功刪除，中繼資料可能也不會移除。

解決方法

步驟如下：

1. 檢查現有叢集是否正在使用服務範圍。您可以使用搭配 filter 標記的 gcloud container clusters list 指令來搜尋叢集。如果現有叢集使用服務範圍，您必須刪除該叢集或建立新的服務範圍。
2. 如果現有叢集未使用服務範圍，請手動移除與要使用的服務範圍相符的中繼資料項目。

無法建立子網路

問題

嘗試使用自動子網路建立叢集，或建立自訂子網路時，可能會遇到下列任一錯誤：

An IP range in the peer network overlaps
with an IP range in one of the active peers of the local network.

Error: Error waiting for creating GKE cluster: Invalid value for field
PrivateClusterConfig.MasterIpv4CidrBlock: x.x.x.x/28 conflicts with an
existing subnet in one of the peered VPCs.

可能原因

您指定的控制層 CIDR 範圍與叢集中的另一個 IP 範圍重複。如果您嘗試重複使用最近刪除的叢集所用的 master-ipv4-cidr CIDR，也可能會發生這個子網路建立錯誤。

解決方法

請嘗試使用不同的 CIDR 範圍。

無法從公開 Docker Hub 中提取映像檔

問題

在叢集中執行的 Pod 在 kubectl describe 中顯示警告：

Failed to pull image: rpc error: code = Unknown desc = Error response
from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled
while waiting for connection (Client.Timeout exceeded while awaiting
headers)

可能原因

只有私人 IP 位址的節點需要額外設定，才能符合網際網路存取需求。不過，如果您啟用私人 Google 存取權並符合網路需求，節點就能存取 Google Cloud API 和服務，包括 Artifact Registry。

解決方法

請使用下列其中一種解決方案：

• 將叢集中的映像檔從 Docker Hub 複製到 Artifact Registry。詳情請參閱「遷移第三方登錄檔中的容器」。

• GKE 會自動檢查mirror.gcr.io經常存取的 Docker Hub 映像檔是否有快取副本。

• 如必須從 Docker Hub 或其他公開存放區提取映像檔，請使用 Cloud NAT，或是靜態 0.0.0.0/0 路徑目標的執行個體 Proxy。

觸發准入 Webhook 超時的 API 要求

問題

如果 API 要求觸發的許可控制 Webhook 設定為使用 targetPort 不是 443 的服務，要求就會逾時，導致失敗：

Error from server (Timeout): request did not complete within requested timeout 30s

可能原因

根據預設，防火牆不允許 TCP 連線到節點，但通訊埠 443 (HTTPS) 和 10250 (kubelet) 除外。如果沒有允許流量的自訂防火牆規則，嘗試透過通訊埠 443 以外的通訊埠與 Pod 通訊的准入 Webhook 就會失敗。

解決方法

針對特定用途新增防火牆規則。

由於健康狀態檢查失敗而無法建立叢集

問題

使用私人節點集區建立標準叢集後，叢集會停留在健康狀態檢查步驟，並回報類似下列其中一項的錯誤：

All cluster resources were brought up, but only 0 of 2 have registered.

All cluster resources were brought up, but: 3 nodes out of 4 are unhealthy

可能原因

下列設定可能會導致這項錯誤：

• 叢集節點無法從 Cloud Storage API (storage.googleapis.com) 下載必要二進位檔。
• 限制輸出流量的防火牆規則。
• 共用虛擬私有雲 IAM 權限不正確。
• 私人 Google 存取權需要為 *.gcr.io 設定 DNS。

解決方法

請使用下列其中一種解決方案：

• 在子網路上啟用私人 Google 存取權，讓節點網路存取 storage.googleapis.com，或啟用 Cloud NAT，允許節點與 storage.googleapis.com 端點通訊。

• 如要讓節點讀取 storage.googleapis.com，請確認指派給叢集節點的服務帳戶具有儲存空間讀取權限。

• 請確認您已設定Google Cloud 防火牆規則，允許所有輸出流量，或設定防火牆規則，允許節點輸出流量至叢集控制平面和 *.googleapis.com。

• 為 *.gcr.io 建立 DNS 設定。

• 如果您使用非預設的防火牆或路徑設定，請設定私人 Google 存取權。

• 如果您使用 VPC Service Controls，請為 GKE 叢集設定 Container Registry 或 Artifact Registry。

• 確認您未刪除或修改 Ingress 的自動建立防火牆規則。

• 如要使用共用虛擬私有雲，請務必設定必要的 IAM 權限。

kubelet Failed to create pod sandbox

問題

使用私人節點建立叢集後，系統會回報類似下列其中一個的錯誤：

Warning  FailedCreatePodSandBox  12s (x9 over 4m)      kubelet  Failed to create pod sandbox: rpc error: code = Unknown desc = Error response from daemon: Get https://registry.k8s.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized

可能原因

calico-node 或 netd Pod 無法連上 *.gcr.io。

解決方法

請確認您已完成 Container Registry 或 Artifact Registry 的必要設定。

已建立私人節點，但未加入叢集

如果叢集使用的節點只有私人 IP 位址，通常是在虛擬私有雲上使用自訂路由和第三方網路設備時，預設路由 (0.0.0.0/0) 會重新導向至設備，而不是預設網際網路閘道。除了控制層連線能力，您還需要確保可連線至下列目的地：

• *.googleapis.com
• *.gcr.io
• gcr.io

為這三個網域設定私人 Google 存取權。這項最佳做法可讓新節點啟動並加入叢集，同時限制網際網路繫結流量。

GKE 叢集上的工作負載無法存取網際網路

在具有私人 IP 位址的節點中執行的 Pod 無法存取網際網路。舉例來說，在 Pod exec shell 中執行 apt update 指令後，系統會回報類似下列的錯誤：

0% [Connecting to deb.debian.org (199.232.98.132)] [Connecting to security.debian.org (151.101.130.132)]

如果叢集 Pod 使用的子網路次要 IP 位址範圍未在 Cloud NAT 閘道上設定，Pod 就無法連線至網際網路，因為 Cloud NAT 閘道未設定外部 IP 位址。

請務必設定 Cloud NAT 閘道，為叢集使用的子網路套用至少下列子網路 IP 位址範圍：

• 子網路主要 IP 位址範圍 (節點使用)
• 叢集中 Pod 所用的子網路次要 IP 位址範圍
• 叢集中服務使用的子網路次要 IP 位址範圍

詳情請參閱如何新增 Pod 所用的次要子網路 IP 範圍。

公開叢集無法停用直接 IP 存取權

問題

停用 IP 位址端點後，您會看到類似以下的錯誤訊息：

Direct IP access can't be disabled for public clusters

可能原因

叢集使用舊版網路。

解決方法

將叢集遷移至 Private Service Connect。如要進一步瞭解遷移狀態，請 與支援團隊聯絡 。

如果叢集正在進行 PSC 遷移，就無法停用直接 IP 存取權

問題

停用 IP 位址端點後，您會看到類似以下的錯誤訊息：

Direct IP access can't be disabled for public clusters

可能原因

叢集使用舊版網路。

解決方法

請使用下列其中一種解決方案：

• 手動以不同版本重新建立所有節點集區。
• 等待 GKE 在維護事件期間自動升級節點集區。

無法啟用控制層內部端點

問題

嘗試啟用叢集控制層的內部端點時，您會看到類似下列內容的錯誤訊息：

private_endpoint_enforcement_enabled can't be enabled when envoy is disabled

private_endpoint_enforcement_enabled is unsupported. Please upgrade to the minimum support version

可能原因

叢集需要執行 IP 位址輪替或版本更新。

解決方法

請使用下列其中一種解決方案：

• 輪替控制層 IP 位址，啟用 Envoy。
• 將叢集升級至 1.28.10-gke.1058000 以上版本。

定義機構政策時，叢集建立作業會失敗

問題

嘗試建立叢集時，您會看到類似下列內容的錯誤訊息：

compute.disablePrivateServiceConnectCreationForConsumers violated for projects

可能原因

叢集端點或後端遭到消費者組織政策封鎖。

解決方法

如要允許執行個體使用 compute.restrictPrivateServiceConnectProducer 限制建立端點，請完成「消費者端機構政策」中的步驟。

刪除叢集時，Private Service Connect 端點可能會洩漏

問題

建立叢集後，您可能會看到下列其中一種徵兆：

• 您無法在以 Private Service Connect 為基礎的叢集中，查看 Private Service Connect 下的已連線端點。

• 如果叢集使用 Private Service Connect，您就無法刪除為內部端點分配的子網路或虛擬私有雲網路。系統會顯示類似以下的錯誤訊息：

  projects/<PROJECT_ID>/regions/<REGION>/subnetworks/<SUBNET_NAME> is already being used by projects/<PROJECT_ID>/regions/<REGION>/addresses/gk3-<ID>
  

可能原因

在採用 Private Service Connect 的 GKE 叢集上，GKE 會使用轉送規則部署 Private Service Connect 端點，在控制層網路中分配內部 IP 位址，以存取叢集的控制層。為了使用 Private Service Connect 保護控制平面與節點之間的通訊，GKE 會隱藏端點，因此您無法在Google Cloud 主控台或 gcloud CLI 中看到端點。

解決方法

為防止在叢集刪除前洩漏 Private Service Connect 端點，請完成下列步驟：

1. 將 Kubernetes Engine Service Agent role 指派給 GKE 服務帳戶。
2. 請確認 GKE 服務帳戶未明確拒絕 compute.forwardingRules.* 和 compute.addresses.* 權限。

如果發現 Private Service Connect 端點外洩，請 與支援團隊聯絡 。

無法剖析叢集的授權網路

問題

您無法在 1.29 以上版本中建立叢集。系統會顯示類似以下的錯誤訊息：

Unable to parse cluster.master_ipv4_cidr "" into a valid IP address and mask

可能原因

您的 Google Cloud 專案使用以私人 IP 為基礎的 Webhook。因此，您無法使用 Private Service Connect 建立叢集。叢集會改用 VPC 網路對等互連，剖析 master-ipv4-cidr 旗標。

解決方法

請使用下列其中一種解決方案：

• 繼續建立 VPC 網路對等互連叢集，並加入 master-ipv4-cidr 定義有效的 CIDR。這項解決方案有下列限制：

  • Google Cloud 控制台已淘汰 master-ipv4-cidr 旗標。如要更新這個旗標，只能使用 Google Cloud CLI 或 Terraform。
  • GKE 1.29 以上版本已淘汰虛擬私有雲網路對等互連。

• 如要遷移以私人 IP 為基礎的 Webhook，請完成「Private Service Connect 限制」一文中的步驟。然後 與支援團隊聯絡 ，選擇使用 Private Service Connect 叢集。

無法在具有公開節點的叢集中定義內部 IP 位址範圍

問題

您無法使用 --master-ipv4-cidr 標記定義內部 IP 位址範圍。系統會顯示類似以下的錯誤訊息：

ERROR: (gcloud.container.clusters.create) Cannot specify --master-ipv4-cidr
  without --enable-private-nodes

可能原因

您在未啟用 enable-private-nodes 標記的叢集中，使用 master-ipv4-cidr 標記定義控制層的內部 IP 位址範圍。如要建立定義 master-ipv4-cidr 的叢集，您必須使用 enable-private-nodes 標記，將叢集設定為透過內部 IP 位址 (私人節點) 佈建節點。

解決方法

請使用下列其中一種解決方案：

• 使用下列指令建立叢集：

  gcloud container clusters create-auto CLUSTER_NAME \
      --enable-private-nodes \
      --master-ipv4-cidr CP_IP_RANGE
  

  更改下列內容：

  • CLUSTER_NAME：叢集名稱。
  • CLUSTER_NAME：控制層的內部 IP 位址範圍。

• 更新叢集，只透過 IP 位址佈建節點。詳情請參閱「設定叢集」。

無法在 Autopilot 叢集上排定公開工作負載

問題

在 Autopilot 叢集中，如果叢集只使用私人節點，您就無法使用 cloud.google.com/private-node=false nodeSelector 在公開 Pod 中排定工作負載。

可能原因

只有 1.30.3 以上版本的叢集，才能在 Pod 的 nodeSelector 中設定 private-node 旗標為 false。

解決方法

將叢集升級至 1.30 以上版本。

無法存取以 DNS 為基礎的端點

問題

嘗試對叢集執行 kubectl 指令時，會傳回類似下列的錯誤：

couldn't get current server API group list:
control_plane_endpoints_config.dns_endpoint_config.allow_external_traffic is
disabled

可能原因

叢集已停用以 DNS 為基礎的存取權。

解決方法

啟用控制層的存取權，方法是使用控制層的 DNS 型端點。詳情請參閱「修改控制層存取權」。

節點在擴充期間無法分配 IP 位址

問題

嘗試將子網路的主要 IP 位址範圍擴展至授權網路清單時，會傳回類似以下的錯誤：

 authorized networks fields cannot be mutated if direct IP access is disabled

可能原因

您已停用叢集的以 IP 為基礎的端點。

解決方法

使用 enable-ip-access 旗標停用及啟用叢集以 IP 為基礎的端點。

CIDR 區塊過多

嘗試建立或更新的叢集具有超過 50 個 CIDR 區塊時，gcloud 會傳回下列錯誤：

ERROR: (gcloud.container.clusters.update) argument --master-authorized-networks: too many args

如要解決這個問題，請嘗試下列方法：

• 如果叢集未使用私人服務連線或 VPC 網路對等互連，請確保指定的 CIDR 區塊不超過 50 個。
• 如果叢集使用 Private Service Connect 或 VPC 網路對等互連，請指定最多 100 個 CIDR 區塊。

無法連線至伺服器

kubectl 指令因 CIDR 區塊設定錯誤而發生逾時：

Unable to connect to the server: dial tcp MASTER_IP: getsockopt: connection timed out

當您建立或更新叢集時，請確保指定正確的 CIDR 區塊。

後續步驟

• 如果無法在說明文件中找到問題的解決方法，請參閱「取得支援」一文，尋求進一步的協助， 包括下列主題的建議：

  • 與 Cloud 客戶服務聯絡，建立支援案件。
  • 在 StackOverflow 上提問，並使用 google-kubernetes-engine 標記搜尋類似問題，向社群尋求支援。你也可以加入 #kubernetes-engine Slack 頻道，取得更多社群支援。
  • 使用公開問題追蹤工具回報錯誤或提出功能要求。