Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 GKE Dataplane V2

Autopilot Standard

本頁說明如何為 Google Kubernetes Engine (GKE) 叢集啟用 GKE Dataplane V2，以及如何排解相關問題。

新的 Autopilot 叢集一律會啟用 GKE Dataplane V2。如果使用 GKE Dataplane V2 時發生問題，請跳到「疑難排解」。

事前準備

開始之前，請務必先完成下列工作：

啟用 Google Kubernetes Engine API。

啟用 Google Kubernetes Engine API

如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update 指令，取得最新版本。較舊的 gcloud CLI 版本可能不支援執行本文件中的指令。
注意：如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region 屬性。如果您主要使用區域叢集，請改為設定 compute/zone。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤：One of [--zone, --region] must be supplied: Please specify location。如果叢集位置與您設定的預設位置不同，您可能需要在特定指令中指定位置。

必要的角色

如要取得建立 GKE 叢集所需的權限，請要求管理員授予您專案的 Kubernetes Engine 叢集管理員 (container.clusterAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

使用 GKE Dataplane V2 建立 GKE 叢集

只有在建立新的 GKE 叢集時，才能啟用 GKE Dataplane V2。現有叢集無法修改這項設定。

如要建立使用 GKE Dataplane V2 的 Standard 叢集，請選取下列其中一個選項：

控制台

前往 Google Cloud 控制台的「Create a Kubernetes cluster」(建立 Kubernetes 叢集) 頁面。
前往「建立 Kubernetes 叢集」
點選導覽選單中的「Networking」(網路)。
展開「容器網路介面 (CNI)」專區。
勾選「Dataplane V2」核取方塊。
點選「建立」。

gcloud

執行下列指令：

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-dataplane-v2

更改下列內容：

CLUSTER_NAME：新叢集的名稱。
CONTROL_PLANE_LOCATION：叢集控制層的位置。

API

如要使用 GKE Dataplane V2 建立新叢集，請在叢集 create 要求中，指定 networkConfig 物件的 datapathProvider 欄位。

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：您的專案 ID。
CONTROL_PLANE_LOCATION：叢集控制層的位置。
CLUSTER_NAME：新叢集的名稱。

HTTP 方法和網址：

POST https://container.googleapis.com/v1/projects/PROJECT_ID/locations/CONTROL_PLANE_LOCATION/clusters

JSON 要求主體：

{
  "cluster":{
    "name": "CLUSTER_NAME",
    "location": "CONTROL_PLANE_LOCATION",
    "initialNodeCount": 1,
    "networkConfig":{
      "datapathProvider":"ADVANCED_DATAPATH"
    }
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/CONTROL_PLANE_LOCATION/clusters"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/CONTROL_PLANE_LOCATION/clusters" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "operation-1234567890",
  "zone": "us-central1-b",
  "operationType": "CREATE_CLUSTER",
  "status": "RUNNING",
  "selfLink": "https://container.googleapis.com/v1/projects/1234567890/zones/us-central1-b/operations/operation-1234567890",
  "targetLink": "https://container.googleapis.com/v1/projects/1234567890/zones/us-central1-b/clusters/example-cluster",
  "startTime": "2026-09-21T14:42:56.222681067Z"
}

排解 GKE Dataplane V2 問題

本節說明如何調查及解決 GKE Dataplane V2 的問題。

確認已啟用 GKE Dataplane V2：
```
kubectl -n kube-system get pods -l k8s-app=cilium -o wide
```
如果 GKE Dataplane V2 正在執行，輸出內容會包含前置字元為 anetd- 的 Pod。anetd 是 GKE Dataplane V2 的網路控制器。
如果問題與服務或網路政策強制執行有關，請檢查 anetd Pod 記錄。在 Cloud Logging 中使用下列記錄選取器：
```
resource.type="k8s_container"
labels."k8s-pod/k8s-app"="cilium"
resource.labels.cluster_name="CLUSTER_NAME"
```
如果 Pod 建立失敗，請查看 kubelet 記錄檔，找出線索。在 Cloud Logging 中使用下列記錄選取器：
```
resource.type="k8s_node"
log_name=~".*/logs/kubelet"
resource.labels.cluster_name="CLUSTER_NAME"
```
將 CLUSTER_NAME 替換為叢集名稱，或完全移除，即可查看所有叢集的記錄。
如果 anetd Pod 未執行，請檢查 cilium-config ConfigMap 是否經過修改。請避免變更這個 ConfigMap 中的現有欄位，因為這類變更可能會導致叢集不穩定，並中斷 anetd。只有在 ConfigMap 中新增欄位時，系統才會將其修補回預設狀態。系統不會修補現有欄位的任何變更，建議不要變更或自訂 ConfigMap。

已知問題

使用 GKE Dataplane V2 時，可能會遇到下列已知問題。

健康狀態檢查探測要求來自 GKE 1.35 以上版本中的 `169.254.4.6`

在執行 GKE 1.35.1-gke.1516000 以上版本的 GKE Dataplane V2 叢集中，CNI 設定會使用統一的 cilium-cni 外掛程式，而不是鏈結 ptp 和 cilium-cni。透過這項設定，Cilium 會將 Pod 預設閘道設為節點本機 cilium_host 介面 IP 位址 (169.254.4.6)，而非節點 Pod CIDR 範圍的 .1 位址 (例如 10.x.x.1)。

將 Pod 預設閘道設為節點本機 cilium_host 介面，節點本機 kubelet liveness、readiness 和啟動探測 (kube-probe) 和 NodeLocal DNSCache 流量就會來自 169.254.4.6。標準 Kubernetes NetworkPolicy 資源會自動允許節點本機健康狀態探查 (reserved:host)，因此您不需要對 NetworkPolicy 設定套用任何變更。不過，如果應用程式在健康檢查端點上強制執行應用程式層級的 IP 許可清單或網頁伺服器 ACL，請更新這些許可清單，允許 169.254.4.6/32 (或 169.254.0.0/16) IP 位址。

尚未就緒的 Pod 連線逾時

如果 Pod 尚未準備就緒，與相關聯服務的連線可能會逾時。這是 GKE Dataplane V2 的預期行為，與 kube-proxy 不同，後者可以傳回速度較快的 connection refused 錯誤。

Cilium 身分識別的「與身分相關的標籤」篩選功能不會生效，Pod 會停留在 ContainerCreating 狀態

受影響的版本：1.34、1.35

在 GKE Dataplane V2 叢集中，透過 kube-system/cilium-config-emergency-override ConfigMap 緊急使用 Identity-Relevant Label 篩選功能時，系統不會在受影響的版本中正確套用。

這種做法會限制用於產生 Cilium ID 的 Pod 標籤。

如果無法使用其他機制，從 Pod 中移除高基數標籤鍵/值 (例如標籤是由工具或架構套用)，則可使用「與身分相關的標籤」篩選功能，從 Cilium 身分計算中排除標籤鍵。如要進一步瞭解如何設定這些規則，請參閱 Cilium 說明文件中的「與身分相關的標籤」。

在受影響的 GKE 版本中，運算子建立的 Cilium 身分仍會包含排除的標籤。

症狀

如果 Pod 具有應篩除的標籤，Cilium 身分證件可能無法產生，導致 Pod 無法啟動並停留在 ContainerCreating 狀態。Pod 事件可能會顯示逾時錯誤：

  {"level":"warning", "msg":"Error changing endpoint identity", "error":"unable to resolve identity: timed out waiting for cilium-operator to allocate CiliumIdentity for key ...;, error: exponential backoff cancelled via context: context canceled", "k8sPodName":"...", "subsys":"endpoint"}

Pod 不會根據篩選後的標籤共用身分，而是繼續產生專屬的 Cilium 身分。這可能會導致身分急遽增加，進而耗盡可用的 Cilium 身分 (上限為 65,536 個)，並造成擴充性問題。

修正版本

如要修正這個問題，請將叢集升級至下列任一 GKE 版本：

1.34.6-gke.1307000 以上版本
1.35.2-gke.1962000 以上版本

解決方法

如要解決這個問題，請將標籤篩選規則套用至主要 cilium-config ConfigMap 中的 data.labels 欄位，然後從 cilium-config-emergency-override 中移除這些規則。在升級等控制層作業期間，這種情況會持續存在，因為 GKE 會保留使用者對 cilium-config ConfigMap 中非受管理欄位的修改。

從 cilium-config-emergency-override ConfigMap 的 data 區段中移除 labels 鍵 (如有)。

在 data 區段中新增或修改 labels 鍵，即可編輯 cilium-config ConfigMap。舉例來說，如要禁止使用名為 uuid 的標籤產生 ID，請採取下列做法：

apiVersion: v1
kind: ConfigMap
metadata:
  name: cilium-config
  namespace: kube-system
data:
  # ... other existing keys
  labels: "!uuid"
  # ... other existing keys

將控制層升級至相同版本，即可在控制層上重新啟動 anet-operator。這會強制運算子重新啟動並重新載入設定：

gcloud container clusters upgrade CLUSTER_NAME \
    --location CLUSTER_LOCATION \
    --project PROJECT_ID \
    --cluster-version $(gcloud container clusters describe CLUSTER_NAME --location CLUSTER_LOCATION --project PROJECT_ID --format="value(currentMasterVersion)") \
    --master

控制層重新啟動後，請重新啟動 anetd DaemonSet，確保節點代理程式也會套用所有必要變更：
```
kubectl rollout restart daemonset anetd -n kube-system
```

GKE Dataplane V2 叢集發生與 `NodePort` 範圍衝突相關的間歇性連線問題

在 GKE Dataplane V2 叢集中，偽裝流量或暫時性通訊埠使用情形可能會導致連線問題間歇發生。這些問題是因預留 NodePort 範圍可能發生連接埠衝突所致，通常發生於下列情況：

自訂 ip-masq-agent：如果您使用自訂 ip-masq-agent (2.10 以上版本)，且叢集具有 NodePort 或負載平衡器服務，可能會因與 NodePort 範圍發生衝突而導致連線問題。在 2.10 以上版本中，ip-masq-agent 預設會在內部實作 --random-fully 引數。為減輕這項問題的影響，請在 ip-masq-agent 設定的引數中，明確設定 --random-fully=false (適用於 2.11 以上版本)。如需設定詳情，請參閱「在標準叢集中設定 IP 偽裝代理程式」。
暫時性連接埠範圍重疊：如果 GKE 節點上定義的暫時性連接埠範圍net.ipv4.ip_local_port_range與 NodePort 範圍 (30000-32767) 重疊，也可能引發連線問題。為避免這個問題，請確保這兩個範圍不會重疊。

檢查 ip-masq-agent 設定和暫時性通訊埠範圍設定，確保這些設定不會與 NodePort 範圍衝突。如果遇到間歇性連線問題，請考慮下列可能原因，並據此調整設定。

GKE Dataplane V2 叢集中的 `hostPort` 連線問題

受影響的 GKE 版本：所有可用版本

在採用 GKE Dataplane V2 的叢集中，如果流量以節點的 IP:Port 為目標，且通訊埠是 Pod 上定義的 hostPort，您可能會遇到連線失敗的情形。這類問題主要有兩種情況：

直通式網路負載平衡器後方的節點 (hostPort)：

hostPort 會將 Pod 繫結至特定節點的通訊埠，而直通式網路負載平衡器則會在所有節點之間分配流量。使用 hostPort 和直通式網路負載平衡器將 Pod 公開至網際網路時，負載平衡器可能會將流量傳送至未執行 Pod 的節點，導致連線失敗。這是因為 GKE Dataplane V2 有已知限制，直通式網路負載平衡器流量不會穩定轉送至 hostPort Pod。

解決方法：透過直通式網路負載平衡器公開節點上的 Pod hostPort 時，請在 Pod 的 hostIP 欄位中指定網路負載平衡器的內部或外部 IP 位址。
```
ports:
- containerPort: 62000
  hostPort: 62000
  protocol: TCP
  hostIP: 35.232.62.64
- containerPort: 60000
  hostPort: 60000
  protocol: TCP
  hostIP: 35.232.62.64
  # Assuming 35.232.62.64 is the external IP address of a passthrough Network Load Balancer.
```
hostPort與保留的 NodePort 範圍衝突：

如果 Pod 的 hostPort 與保留的 NodePort 範圍 (30000-32767) 衝突，Cilium 可能無法將流量轉送至 Pod。發生這種情況是因為 Cilium 會管理 hostPort 功能，取代先前的 Portmap 方法。這是 Cilium 的預期行為，相關說明請參閱公開文件。

我們不打算在後續版本中修正這些限制。這些問題的根本原因與 Cilium 的行為有關，且超出 GKE 的直接控管範圍。

建議：建議您遷移至 NodePort 服務，而非 hostPort，以提升可靠性。NodePort 服務提供類似功能。

網路政策的通訊埠範圍未生效

受影響的 GKE 版本：1.32 之前的版本

如果叢集已啟用 GKE Dataplane V2，且執行 1.32 之前的 GKE 版本，Kubernetes 會忽略 NetworkPolicy 物件中的 endPort 欄位。

Kubernetes NetworkPolicy API 可讓您指定 Kubernetes 強制執行網路政策的連接埠範圍。搭載 Calico 網路政策的叢集，以及執行 GKE 1.32 以上版本的 GKE Dataplane V2 叢集，都支援這項 API。如果 GKE Dataplane V2 叢集執行的版本低於 1.32，則不支援此 API。

如要驗證 NetworkPolicy 物件的行為，請在將物件寫入 API 伺服器後讀回。如果物件仍包含 endPort 欄位，Kubernetes 就會強制執行這項功能。如果缺少 endPort 欄位，Kubernetes 就不會強制執行這項功能。API 伺服器中儲存的物件是網路政策的可靠資料來源。

詳情請參閱「KEP-2079：支援連接埠範圍的網路政策」。

已修正的版本

如要解決這個問題，請將叢集升級至 GKE 1.32 以上版本。

節點因缺少 `containerID` 錯誤而處於 `NodeNotReady` 狀態

如果叢集升級至 GKE 1.35.1-gke.1616000 以上版本，且同時啟用 GKE Dataplane V2 和 Cloud Service Mesh，節點可能會立即進入 NodeNotReady 狀態。

原因

從 GKE 1.35.1-gke.1616000 版開始，GKE Dataplane V2 叢集的 CNI 設定檔會使用 CNI 1.1.0 版。這項變更需要下游 CNI 外掛程式 (例如 Google 管理的 Istio) 也支援 CNI 1.1.0 版。由於受管理 Istio 的推出作業延遲，部分叢集尚未收到相容版本 (1.23)，導致初始化失敗。

問題

受影響的節點會立即顯示為 NodeNotReady。containerd 記錄中會顯示下列錯誤訊息：

NetworkPluginNotReady message:Network plugin returns error: missing containerID

解決方法

如要緩解這個問題，請將受影響的叢集降級至 1.35.1-gke.1616000 之前的 GKE 版本。

自訂 eBPF 程式干擾

GKE 會使用 eBPF 程式管理 GKE Dataplane V2 的網路。如果您在 GKE 管理的節點網路介面上部署自訂 eBPF 程式，這些程式可能會干擾 GKE 管理的 eBPF 程式，導致網路問題。

GKE 不支援連結至下列網路介面的自訂 eBPF 程式：

eth*
ens4
lo
cilium*
gke*
veth*

這些介面上的自訂 eBPF 程式可能會干擾 GKE Dataplane V2 anetd 代理程式安裝的程式，進而中斷叢集網路。建議您從叢集中移除所有自訂 eBPF 程式，或注入這類程式的工作負載。

探索自訂 eBPF 程式

如要探索叢集節點上執行的自訂 eBPF 程式，您可以建立設定 hostNetwork: true 設定的 DaemonSet，使用 bpftool 查詢這類 eBPF 程式：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: bpftool-logger
  labels:
    app: bpftool-logger
spec:
  selector:
    matchLabels:
      app: bpftool-logger
  template:
    metadata:
      labels:
        app: bpftool-logger
    spec:
      hostPID: true
      hostNetwork: true
      containers:
      - name: bpftool
        image: ubuntu:22.04
        securityContext:
          privileged: true
        env:
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        command:
        - /bin/bash
        - -c
        - |
          echo "Installing dependencies..."
          apt-get update -y > /dev/null 2>&1
          apt-get install -y curl tar > /dev/null 2>&1

          echo "Downloading and setting up bpftool..."
          curl -sL https://github.com/libbpf/bpftool/releases/download/v7.7.0/bpftool-v7.7.0-amd64.tar.gz | tar xz
          chmod +x bpftool
          mv bpftool /usr/local/bin/

          echo "========== $(date) | Node: ${NODE_NAME} =========="
          bpftool net | grep -E '^(eth|ens4|lo|cilium|gke|veth)' | grep -v ' cil_'
          sleep infinity

將資訊清單儲存為 ebpf-discovery.yaml，然後套用 DaemonSet：
```
kubectl apply -f ebpf-discovery.yaml
```

等待 Pod 執行：

kubectl rollout status ds/bpftool-logger

查看 Pod 的記錄檔，找出 eBPF 程式：
```
kubectl logs -l app=bpftool-logger
```
完成後，請刪除 DaemonSet：
```
kubectl delete -f ebpf-discovery.yaml
```