排解 GKE Volume Populator 資料移轉問題

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

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

如果您是應用程式開發人員、平台管理員或作業人員，並使用 GKE Volume Populator 將資料植入 GKE 磁碟區，請務必詳閱本文資訊。如要進一步瞭解我們在 Cloud de Confiance by S3NS 內容中提及的常見角色和範例工作，請參閱「常見的 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 安全存取 Cloud de Confiance by S3NS 服務。如果轉移 Pod 無法向 Cloud de Confiance by S3NS進行驗證，請確認叢集已啟用 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：您的 Cloud de Confiance 專案 ID。

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

   PROJECT_ID.s3ns.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.s3ns.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.s3ns.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.s3ns.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE"

更改下列內容：

• GCS_BUCKET：Cloud Storage bucket 名稱。
• PROJECT_NUMBER：您的 Cloud de Confiance 專案編號。
• PROJECT_ID：您的 Cloud de Confiance 專案 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：您的 Cloud de Confiance by S3NS 專案 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：您的 Cloud de Confiance by S3NS 專案 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，再次啟動轉移程序。

後續步驟

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