排解 GKE Volume Populator 資料移轉問題

GKE 磁碟區擴展器可協助將資料轉移至 GKE 叢集。不過，資料移轉程序可能會發生問題，導致 PersistentVolumeClaim (PVC) 無法建立，或資料無法正確填入。

本文說明如何解決使用 GKE 磁碟區擴展器時遇到的常見問題。瞭解如何檢查元件狀態、驗證設定，以及解決資源或權限錯誤，排解資料移轉問題。

如果您是應用程式開發人員、平台管理員或作業人員，並使用 GKE Volume Populator 將資料植入 GKE 磁碟區，請務必詳閱本文資訊。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。

檢查臨時 Kubernetes 資源

GKE Volume Populator 使用臨時資源的方式如下：

1. 系統會在 gke-managed-volumepopulator 命名空間中建立臨時 PVC。
2. 系統會為轉移作業涉及的每個可用區，在 PVC 的命名空間中建立轉移工作、PV 和 PVC。
3. 資料移轉完成後，GKE Volume Populator 會自動移除所有這些暫時資源。

如要檢查暫時資源，請按照下列步驟操作：

1. 儲存環境變數：

   export PVC_NAME=PVC_NAME
   export NAMESPACE=NAMESPACE
   

   替換下列值：

   • PVC_NAME：PersistentVolumeClaim 資源的名稱。
   • NAMESPACE：工作負載執行的命名空間。

2. 查看狀態：

   export PVC_UID=$(kubectl get pvc ${PVC_NAME} -n ${NAMESPACE} -o jsonpath='{.metadata.uid}')
   export TEMP_PVC=prime-${PVC_UID}
   echo ${TEMP_PVC}
   

3. 檢查 gke-managed-volumepopulator 命名空間中的暫時 PVC：

   kubectl describe pvc ${TEMP_PVC} -n gke-managed-volumepopulator
   

4. 取得命名空間中臨時 PVC 的名稱：

   export TEMP_PVC_LIST=($(kubectl get pvc -n "$NAMESPACE" -o json | grep -Eo "\"name\":\s*\"$TEMP_PVC[^\"]*\"" | awk -F'"' '{print $4}'))
   
   for pvc in "${TEMP_PVC_LIST[@]}"; do
     echo "$pvc"
   done
   

5. 檢查臨時 PVC：

   kubectl describe pvc "${TEMP_PVC_LIST[0]}" -n $NAMESPACE
   

6. GKE Volume Populator 會在每個可用區中建立傳輸工作 (如果是單一可用區 Hyperdisk ML 磁碟區，則為一個；如果是多可用區 Hyperdisk ML 磁碟區，則為多個)。使用下列指令取得轉移作業名稱：

   export TRANSFER_JOB=$(kubectl get pvc "${TEMP_PVC_LIST[0]}" -n "$NAMESPACE" -o "jsonpath={.metadata.annotations['volume-populator\.datalayer\.gke\.io/pd-transfer-requestid']}")
   
   echo $TRANSFER_JOB
   

7. 檢查轉移工作：

   kubectl describe job $TRANSFER_JOB -n $NAMESPACE
   

8. 從移轉工作中取得 Pod 名稱：

   export TRANSFER_POD=$(kubectl get pods -n "$NAMESPACE" -l "job-name=$TRANSFER_JOB" -o jsonpath='{.items[0].metadata.name}')
   
   echo $TRANSFER_POD
   

9. 檢查 Pod：

   kubectl describe pod $TRANSFER_POD -n $NAMESPACE
   

   如果您跨多個可用區建立 PVC，GKE Volume Populator 會為每個指定可用區建立不同的暫時性 PVC 和轉移作業資源。如要檢查移轉作業涉及的每個可用區資源，請將 TEMP_PVC_LIST 索引的 0 替換為其他數字。

檢查是否已啟用 Workload Identity Federation

Workload Identity Federation 可讓轉移 Pod 安全存取 Google Cloud 服務。如果轉移 Pod 無法向 Google Cloud進行驗證，請確認叢集已啟用 Workload Identity Federation for GKE。

1. 如要檢查叢集是否已啟用 workloadIdentityConfig，請執行下列指令：

   gcloud container clusters describe CLUSTER_NAME
   --location=LOCATION \
   --project=PROJECT_ID \
   --format="value(workloadIdentityConfig)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的運算區域或可用區。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

2. 在指令中尋找下列輸出內容：

   PROJECT_ID.svc.id.goog
   

3. 如果輸出內容中缺少 workloadIdentityConfig，請啟用 Workload Identity Federation for GKE。

轉移路徑無效

如果遇到類似下列的錯誤，表示 GCPDatasource 資源上指定的轉移路徑有誤，轉移作業將會失敗。

ERROR: (gcloud.storage.cp) The following URLs matched no objects or files:
gs://datasets-pd/llama2-7b-hfa/

如要解決這個問題，請刪除 GCPDatasource 資源，使用正確的值更新 uri 欄位，然後重新建立資源。

權限不足，無法存取 bucket

如果 Kubernetes 服務帳戶無法存取 GCPDatasource 資源中指定的 bucket URI，移轉工作就會失敗。錯誤訊息應如下所示：

ERROR: (gcloud.storage.cp) [test-gke-dev.svc.id.goog] does not have permission to access b instance [small-bucket-7] (or it may not exist): Caller does not have storage.objects.list access to the Google Cloud Storage bucket. Permission 'storage.objects.list' denied on resource (or it may not exist). This command is authenticated as test-gke-dev.svc.id.goog which is the active account specified by the [core/account] property.

如要解決這個問題，請授予必要權限，將資料從儲存空間移轉至磁碟。

gcloud storage buckets \
    add-iam-policy-binding gs://GCS_BUCKET \
     --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE"

更改下列內容：

• GCS_BUCKET：Cloud Storage bucket 名稱。
• PROJECT_NUMBER：您的 Google Cloud 專案編號。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• NAMESPACE：工作負載執行的命名空間。
• KSA_NAME：Kubernetes 服務帳戶的名稱。
• ROLE：提供存取 bucket 必要權限的 IAM 角色。舉例來說，使用 roles/storage.objectViewer 授予值區的唯讀存取權。

錯誤：error generating accessibility requirements

在 gke-managed-volumepopulator 命名空間中檢查 PVC 時，您可能會看到下列暫時性錯誤：

Error: error generating accessibility requirements: no available topology found.

如果您使用 GKE Autopilot 叢集或已啟用自動佈建節點功能的 Standard 叢集，叢集中可能沒有任何節點處於 Ready 狀態，因此會發生這項錯誤。自動佈建節點擴充新節點後，錯誤應會在幾分鐘內自行解決。

Transfer Pod Pending 安排時間過長

您的 PVC 事件可能會顯示轉移 Pod 的狀態為 Pending 很久。

如要檢查轉移工作事件，確認工作排程是否失敗，請按照下列步驟操作：

1. 說明 PVC：

   kubectl describe pvc $PVC_NAME -n $NAMESPACE
   

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

   Events:
     Type     Reason             Age                From                Message
     ----     ------             ----               ----                -------
   Normal   TransferInProgress              1s (x2 over 2s)    gkevolumepopulator-populator                                                                      populateCompleteFn: For PVC pd-pvc79 in namespace default, job with request ID populator-job-0b93fec4-5490-4e02-af32-15b16435d559 is still active with pod status as - Phase: Pending
   

2. 如要檢查移轉 Pod，請按照「檢查暫時性 Kubernetes 資源」中的步驟操作。

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

   Events:
     Type     Reason             Age                From                Message
     ----     ------             ----               ----                -------
     Warning  FailedScheduling   2m50s              default-scheduler   0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had volume node affinity conflict. preemption: 0/3 nodes are available: 1 No preemption victims found for incoming pod, 2 Preemption is not helpful for scheduling.
     Warning  FailedScheduling   37s (x2 over 39s)  default-scheduler   0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had volume node affinity conflict. preemption: 0/3 nodes are available: 1 No preemption victims found for incoming pod, 2 Preemption is not helpful for scheduling.
     Normal   NotTriggerScaleUp  2m40s              cluster-autoscaler  pod didn't trigger scale-up:
   

3. 如果看到 NotTriggerScaleUp 訊息，請檢查叢集是否已啟用自動佈建節點功能：

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --format="value(autoscaling.enableNodeAutoprovisioning)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的運算區域或可用區。

4. 如果輸出內容顯示為「False」，請使用下列指令啟用自動佈建節點功能：

   gcloud container clusters update CLUSTER_NAME \
       --enable-autoprovisioning \
       --location=LOCATION \
       --project=PROJECT_ID \
       --min-cpu MINIMUM_CPU \
       --min-memory MINIMUM_MEMORY \
       --max-cpu MAXIMUM_CPU \
       --max-memory MAXIMUM_MEMORY \
       --autoprovisioning-scopes=https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring,https://www.googleapis.com/auth/devstorage.read_only
   

   更改下列內容：

   • CLUSTER_NAME：要更新並啟用自動佈建節點功能的叢集名稱。
   • LOCATION：叢集的運算可用區或區域。例如：us-central1-a 或 us-central1。
   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • MINIMUM_CPU：自動佈建的 vCPU 數量下限。例如：10。
   • MINIMUM_MEMORY：自動佈建的記憶體容量下限 (以 GiB 為單位)。例如：200。
   • MAXIMUM_CPU：自動佈建的 vCPU 數量上限。例如，100。這項限制是所有現有手動建立的節點集區，以及 GKE 可能自動建立的所有節點集區中，CPU 資源的總和。
   • MAXIMUM_MEMORY：自動佈建的記憶體上限。例如，1000。這個限制是所有現有手動建立的節點集區，以及 GKE 可能自動建立的所有節點集區的記憶體資源總和。

5. 如果已啟用自動佈建節點功能，請確認自動佈建節點功能有足夠的自動調度資源 resourceLimits，可擴充移轉工作。根據預設，移轉工作會使用 24 個 vCPU。

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --format="value(autoscaling.resourceLimits)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的運算區域或可用區。

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

   {'maximum': '1000000000', 'resourceType': 'cpu'};{'maximum': '1000000000', 'resourceType': 'memory'};
   

6. 如果自動佈建節點功能沒有足夠的自動調度資源限制，請使用正確的設定更新叢集。

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --enable-autoprovisioning \
       --max-cpu MAXIMUM_CPU \
       --max-memory MAXIMUM_MEMORY
   

   更改下列內容：

   • CLUSTER_NAME：要更新並啟用自動佈建節點功能的叢集名稱。
   • LOCATION：叢集的運算可用區或區域。例如：us-central1-a 或 us-central1。
   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • MAXIMUM_CPU：自動佈建的 vCPU 數量上限。例如，100。這項限制是所有現有手動建立的節點集區，以及 GKE 可能自動建立的所有節點集區中，CPU 資源的總和。
   • MAXIMUM_MEMORY：自動佈建的記憶體數量上限。例如，1000。這個上限是所有現有手動建立的節點集區，以及 GKE 可能自動建立的所有節點集區的記憶體資源總和。

7. 如果 Standard 叢集未啟用自動佈建節點功能，請確認您為移轉工作建立的節點具有必要的運算類別標籤：

   kubectl get node -l cloud.google.com/compute-class=gcs-to-hdml-compute-class
   

8. 如果輸出內容未列出您為轉移工作建立的節點，請將 gcs-to-hdml-compute-class 計算類別標籤新增至節點：

   kubectl label node NODE_NAME cloud.google.com/compute-class=gcs-to-hdml-compute-class
   

   將 NODE_NAME 替換為要新增運算類別標籤的節點名稱。

GCE quota exceeded 個錯誤

檢查移轉工作的 Pod 時，可能會看到類似下列的錯誤訊息：

Node scale up in zones us-west1-b associated with this pod failed: GCE quota exceeded. Pod is at risk of not being scheduled.

1. 如要檢查轉移 Pod，請按照「檢查暫時的 Kubernetes 資源」一文中的步驟操作。

2. 如要解決錯誤，請增加配額，或刪除可能導致無法擴充的現有資源。詳情請參閱「排解配額錯誤」。

Hyperdisk ML HDML_TOTAL_THROUGHPUT 超過配額錯誤

如果 gke-managed-volumepopulator 命名空間中的暫時性 PVC 無法佈建 Hyperdisk ML 磁碟區，可能是因為您已超出建立新 Hyperdisk ML 磁碟區的區域配額，因此無法進行資料移轉。

如要確認 Hyperdisk ML 磁碟區佈建失敗的原因是否為區域配額問題，請檢查與 GKE 磁碟區填入器建立的暫時 PVC 相關聯的事件記錄。步驟如下：

1. 儲存相關環境變數：

   export PVC_NAME=PVC_NAME
   export NAMESPACE=NAMESPACE
   

   替換下列值：

   • PVC_NAME：PersistentVolumeClaim 資源的名稱。
   • NAMESPACE：工作負載執行的命名空間。

2. 檢查暫時性 PVC 的狀態：

   export PVC_UID=$(kubectl get pvc ${PVC_NAME} -n ${NAMESPACE} -o jsonpath='{.metadata.uid}')
   export TEMP_PVC=prime-$PVC_UID
   echo $TEMP_PVC
   kubectl describe pvc $TEMP_PVC -n gke-managed-volumepopulator
   

3. 查看 PVC 事件，找出 QUOTA_EXCEEDED error，類似下列內容：

   Events:
     Type     Reason                Age                 From                                                                                              Message
     ----     ------                ----                ----                                                                                              -------
     Warning  ProvisioningFailed    105s                pd.csi.storage.gke.io_gke-3ef909a7688d424b94a2-d0d9-b185-vm_6a77d057-54e3-415a-8b39-82b666516b6b  failed to provision volume with StorageClass "pd-sc": rpc error: code = Unavailable desc = CreateVolume failed: rpc error: code = Unavailable desc = CreateVolume failed to create single zonal disk pvc-73c69fa8-d23f-4dcb-a244-bcd120a3c221: failed to insert zonal disk: unknown error when polling the operation: rpc error: code = ResourceExhausted desc = operation operation-1739194889804-62dc9dd9a1cae-9d24a5ad-938e5299 failed (QUOTA_EXCEEDED): Quota 'HDML_TOTAL_THROUGHPUT' exceeded.  Limit: 30720.0 in region us-central1
   

如何解決這個問題：

1. 要求更多配額，以便在專案中建立新的 Hyperdisk ML 磁碟區。
2. 刪除專案中未使用的 Hyperdisk ML 磁碟。

裝置沒有足夠的空間

如果 PVC 上顯示 No space left on device 錯誤訊息，表示 Hyperdisk ML 磁碟區已滿，無法再寫入資料。錯誤訊息可能如下所示：

Events:
  Type     Reason                   Age   From                          Message
  ----     ------                   ----  ----                          -------
  Warning  TransferContainerFailed  57m   gkevolumepopulator-populator  populateCompleteFn: For PVC vp-pvc in namespace default, job with request ID populator-job-c2a2a377-6168-4ff1-afc8-c4ca713c43e2 for zone us-central1-c has a failed pod container with message:  on device
ERROR: Failed to download one or more components of sliced download.
ERROR: [Errno 28] No space left on device

如要解決這個問題，請刪除 PVC、在 PVC 資訊清單中增加 spec.resources.requests.storage 欄位的值，然後重新建立 PVC，再次啟動轉移程序。

後續步驟

• 如果無法在說明文件中找到問題的解決方法，請參閱「取得支援」。