使用 GKE Volume Populator 在動態佈建期間從 Cloud Storage 移轉資料

只有收到邀請的單位才能使用 GKE Volume Populator。如要要求在 Google Cloud 專案中存取 GKE Volume Populator，請與您的銷售代表聯絡。

GKE Volume Populator 可在動態佈建期間，將來源儲存空間的資料預先載入至目的地 PersistentVolumeClaim，不必執行額外的指令碼或 CLI 指令來手動轉移資料。這項功能會運用 Kubernetes Volume Populator 功能，自動化及簡化資料移轉程序。這項服務提供無縫資料可攜性，因此您可以交換儲存空間類型，以享有價格或效能最佳化優勢。

如果您需要將大量資料從 Cloud Storage bucket 移轉至由其他Google Cloud 儲存空間類型 (例如 Parallelstore) 支援的 PersistentVolumeClaim，請使用這項功能。

您主要透過 gcloud CLI 和 kubectl CLI 與 GKE Volume Populator 互動。Autopilot 和 Standard 叢集都支援 GKE Volume Populator。您不需要啟用 GKE Volume Populator。這是預設啟用的 GKE 管理元件。

優點

  • 如要充分運用受管理並行檔案系統的效能，但資料儲存在 Cloud Storage 中，可以使用 GKE Volume Populator 簡化資料轉移作業。
  • GKE Volume Populator 可讓您攜帶資料。您可以視需求移動資料。
  • GKE Volume Populator 支援以 IAM 為基礎的驗證，因此您可以在傳輸資料時，維持精細的存取權控管。

使用 GKE Volume Populator 從來源資料儲存空間轉移資料，並為目的地儲存空間建立 PV

這張圖表顯示資料如何從來源儲存空間流向目的地儲存空間，以及如何使用 GKE Volume Populator 為目的地儲存空間建立 PersistentVolume。

限制

  • GKE Volume Populator 僅支援Cloud Storage bucket 做為來源儲存空間，以及 Parallelstore 執行個體做為目的地儲存空間類型。
  • GCPDataSource 自訂資源必須與 Kubernetes 工作負載位於相同命名空間。系統不支援使用跨命名空間資料來源的磁碟區。
  • GKE Volume Populator 僅支援 Workload Identity Federation for GKE，可將 IAM 服務帳戶繫結至 Kubernetes 服務帳戶。系統不支援直接將 IAM 權限授予 Kubernetes 服務帳戶。

事前準備

開始之前，請確認你已完成下列工作：

  • 啟用 Parallelstore API 和 Google Kubernetes Engine API。
    • 啟用 API
  • 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update，取得最新版本。

需求條件

如要使用 GKE Volume Populator，叢集必須符合下列需求：

  • 使用 GKE 叢集 1.31.1-gke.1729000 以上版本。
  • 啟用 Parallelstore CSI 驅動程式。在新的和現有的 GKE Autopilot 叢集上，GKE 預設會為您啟用 CSI 驅動程式。在新叢集和現有 Standard 叢集上，您需要啟用 CSI 驅動程式。

準備環境

本節說明如何建立 GKE 叢集，以及設定使用 GKE Volume Populator 的必要權限。

設定虛擬私有雲網路

建立 Parallelstore 執行個體和用戶端 Compute Engine VM 或 GKE 叢集時，您必須指定相同的虛擬私有雲 (VPC) 網路。如要讓虛擬私有雲以不公開的方式連線至 Google Cloud服務，且不將流量暴露於公開網際網路，您需要一次性設定私人服務存取權 (PSA)，前提是您尚未完成這項設定。

如要設定 PSA，請按照下列步驟操作：

  1. 如要為專案設定網路對等互連，請設定「Compute 網路管理員」 (roles/compute.networkAdmin) 身分與存取權管理權限。

    如要授予角色，請執行下列指令：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:EMAIL_ADDRESS" \
    --role=roles/compute.networkAdmin

    將 EMAIL_ADDRESS 替換成您的電子郵件地址。

  2. 啟用服務聯播網：

    gcloud services enable servicenetworking.googleapis.com

  3. 建立虛擬私人雲端網路：

    gcloud compute networks create NETWORK_NAME \
  --subnet-mode=auto \
  --mtu=8896 \
  --project=PROJECT_ID

    更改下列內容：

    • NETWORK_NAME：您要在其中建立 Parallelstore 執行個體的虛擬私有雲網路名稱。
    • PROJECT_ID：您的 Google Cloud 專案 ID。

  4. 建立 IP 範圍。

    如要使用私人服務存取權，請提供前置字串長度至少為 /24 (256 個位址) 的 IP 位址範圍 (CIDR 區塊)。Parallelstore 會為每個執行個體保留 64 個位址，因此您可以在需要時，將這個 IP 範圍重複用於其他服務或其他 Parallelstore 執行個體。

    gcloud compute addresses create IP_RANGE_NAME \
  --global \
  --purpose=VPC_PEERING \
  --prefix-length=24 \
  --description="Parallelstore VPC Peering" \
  --network=NETWORK_NAME \
  --project=PROJECT_ID

    將 IP_RANGE_NAME 替換為虛擬私有雲網路 IP 範圍名稱。

  5. 使用與您在上一步驟中建立的範圍相關聯的 CIDR 範圍，設定環境變數：

    CIDR_RANGE=$(
  gcloud compute addresses describe IP_RANGE_NAME \
    --global  \
    --format="value[separator=/](address, prefixLength)" \
    --project=PROJECT_ID \
)

  6. 建立防火牆規則，允許來自您建立的 IP 範圍的 TCP 流量：

    gcloud compute firewall-rules create FIREWALL_NAME \
  --allow=tcp \
  --network=NETWORK_NAME \
  --source-ranges=$CIDR_RANGE \
  --project=PROJECT_ID

    將 FIREWALL_NAME 替換為防火牆規則的名稱，允許來自您建立的 IP 範圍的 TCP 流量。

  7. 連結對等互連：

    gcloud services vpc-peerings connect \
  --network=NETWORK_NAME \
  --ranges=IP_RANGE_NAME \
  --project=PROJECT_ID \
  --service=servicenetworking.googleapis.com

如果在設定 VPC 網路時遇到問題，請參閱 Parallelstore 疑難排解指南。

建立 GKE 叢集

建議您使用 Autopilot 叢集，享受全代管的 Kubernetes 體驗。如要選擇最符合工作負載需求的 GKE 作業模式，請參閱「選擇 GKE 作業模式」。

Autopilot

如要使用 Autopilot 建立 GKE 叢集，請執行下列指令：

gcloud container clusters create-auto CLUSTER_NAME  \
    --network=NETWORK_NAME  \
    --cluster-version=CLUSTER_VERSION \
    --location=CLUSTER_LOCATION

在 Autopilot 叢集中，GKE 預設會啟用 GKE 適用的工作負載身分聯盟和 Parallelstore CSI 驅動程式。

替換下列值：

  • CLUSTER_NAME：叢集名稱。
  • CLUSTER_VERSION：GKE 版本號碼。您必須指定 1.31.1-gke.1729000 以上的版本。
  • NETWORK_NAME：您為 Parallelstore 執行個體建立的 VPC 網路名稱。詳情請參閱「設定虛擬私有雲網路」。
  • CLUSTER_LOCATION：您要在其中建立叢集的區域。建議您在支援的 Parallelstore 位置建立叢集，以獲得最佳效能。如要在不支援 Parallelstore 的位置建立叢集，建立 Parallelstore StorageClass 時，必須指定自訂拓撲，使用支援的 Parallelstore 位置，否則佈建作業會失敗。

標準

使用下列指令建立 Standard 叢集，並啟用 Parallelstore CSI 驅動程式和 GKE 適用的工作負載身分聯盟：

gcloud container clusters create CLUSTER_NAME \
    --addons=ParallelstoreCsiDriver \
    --cluster-version=CLUSTER_VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --network=NETWORK_NAME \
    --location=CLUSTER_LOCATION

替換下列值：

  • CLUSTER_NAME：叢集名稱。
  • CLUSTER_VERSION：GKE 版本號碼。您必須指定 1.31.1-gke.1729000 以上的版本。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • NETWORK_NAME：您為 Parallelstore 執行個體建立的 VPC 網路名稱。詳情請參閱「設定虛擬私有雲網路」。
  • CLUSTER_LOCATION：要建立叢集的區域或可用區。建議您在支援的 Parallelstore 位置建立叢集，以獲得最佳效能。如要在不支援 Parallelstore 的位置建立叢集，建立 Parallelstore StorageClass 時，必須指定自訂拓撲，使用支援的 Parallelstore 位置，否則佈建作業會失敗。

設定必要權限

如要從 Cloud Storage 值區轉移資料，您需要為 GKE 適用的工作負載身分聯盟設定權限。

  1. 建立 Kubernetes 命名空間：

    kubectl create namespace NAMESPACE

    將 NAMESPACE 替換為工作負載執行的命名空間。

  2. 建立 Kubernetes 服務帳戶。

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

    將 KSA_NAME 替換為 Kubernetes 服務帳戶的名稱，Pod 會使用該帳戶向 Google Cloud API 進行驗證。

  3. 建立 IAM 服務帳戶。您也可以使用機構中任何專案的現有 IAM 服務帳戶：

    gcloud iam service-accounts create IAM_SA_NAME \
    --project=PROJECT_ID

    更改下列內容：

    • IAM_SA_NAME：IAM 服務帳戶的名稱。
    • PROJECT_ID：您的 Google Cloud 專案 ID。

  4. 將 roles/storage.objectViewer 角色授予 IAM 服務帳戶，以便存取 Cloud Storage 值區：

    gcloud storage buckets \
    add-iam-policy-binding gs://GCS_BUCKET \
    --member "serviceAccount:IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/storage.objectViewer"

    將 GCS_BUCKET 替換為 Cloud Storage 值區名稱。

  5. 建立 IAM 允許政策，授予 Kubernetes 服務帳戶模擬 IAM 服務帳戶的權限：

    gcloud iam service-accounts \
    add-iam-policy-binding IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

  6. 為 Kubernetes 服務帳戶加上註解，讓 GKE 看到服務帳戶之間的連結。

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    iam.gke.io/gcp-service-account=IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com

  7. 建立 Parallelstore 服務身分：

    gcloud beta services identity create \
    --service=parallelstore.googleapis.com \
    --project=PROJECT_ID

  8. 如要允許 Parallelstore 服務身分模擬 IAM 服務帳戶，請將 roles/iam.serviceAccountTokenCreator 角色授予 Parallelstore 服務身分。設定 PROJECT_NUMBER 環境變數，以便在後續步驟中使用。

    export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
gcloud iam service-accounts \
    add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
    --role=roles/iam.serviceAccountTokenCreator

    PROJECT_NUMBER 值是系統為專案自動產生的專屬 ID。如要尋找這個值，請參閱「建立與管理專案」。

  9. 如要允許 Parallelstore 服務身分存取身分與存取權管理服務帳戶可存取的所有資源，請將 roles/iam.serviceAccountUser 角色授予 Parallelstore 服務身分：

    gcloud iam service-accounts \
    add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
    --role=roles/iam.serviceAccountUser

  10. 如要允許 GKE 服務身分存取身分與存取權管理服務帳戶可存取的所有資源，請將 roles/iam.serviceAccountUser 角色授予 GKE 服務身分。如果 GKE 叢集和 IAM 服務帳戶位於同一個專案，則不需要執行這個步驟。

    gcloud iam service-accounts \
    add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --member=serviceAccount:"service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
    --role=roles/iam.serviceAccountUser

建立預先載入資料的 Parallelstore 磁碟區

以下各節說明使用 GKE Volume Populator，從 Cloud Storage bucket 預先載入資料，建立 Parallelstore 磁碟區的一般程序。

  1. 建立 GCPDataSource 資源。
  2. 建立 Parallelstore StorageClass。
  3. 建立 PersistentVolumeClaim 來存取磁碟區。
  4. (選用) 查看資料轉移進度。
  5. 建立會耗用磁碟區的工作負載。

建立 GCPDataSource 資源

如要使用 GKE Volume Populator，請建立GCPDataSource自訂資源。這個資源定義用於磁碟區填入作業的來源儲存空間屬性。

  1. 將下列資訊清單儲存至名為 gcpdatasource.yaml 的檔案。

    apiVersion: datalayer.gke.io/v1
kind: GCPDataSource
metadata:
  name: GCP_DATA_SOURCE
  namespace: NAMESPACE
spec:
  cloudStorage:
    serviceAccountName: KSA_NAME
    uri: gs://GCS_BUCKET/

    替換下列值：

    • GCP_DATA_SOURCE：GCPDataSourceCRD 的名稱，其中包含 Cloud Storage bucket 的參照。詳情請參閱 GCPDataSource CRD 參考資料。
    • NAMESPACE：工作負載執行的命名空間。命名空間值應與工作負載命名空間相同。
    • ：Kubernetes 服務帳戶的名稱，Pod 會使用這個帳戶向 Google Cloud API 進行驗證。KSA_NAMEcloudStorage.serviceAccountName 值應為您在「設定必要權限」步驟中，為 GKE 適用的 Workload Identity 聯盟設定的 Kubernetes 服務帳戶。
    • GCS_BUCKET：您的 Cloud Storage bucket 名稱。 或者，您也可以指定 gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ 欄位的 uri。

  2. 執行下列指令，建立 GCPDataSource 資源：

    kubectl apply -f gcpdatasource.yaml

建立 Parallelstore StorageClass

建立 StorageClass，將 Parallelstore CSI 驅動程式導向與 GKE 叢集相同的地區，以佈建 Parallelstore 執行個體。這有助於確保最佳 I/O 效能。

  1. 將下列資訊清單儲存為 parallelstore-class.yaml。

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: parallelstore-class
provisioner: parallelstore.csi.storage.gke.io
volumeBindingMode: Immediate
reclaimPolicy: Delete

  2. 執行下列指令來建立 StorageClass：

    kubectl apply -f parallelstore-class.yaml

如要建立具有特定拓撲的自訂 StorageClass，請參閱 Parallelstore CSI 指南。

建立 PersistentVolumeClaim 來存取磁碟區

以下資訊清單檔案範例說明如何在 ReadWriteMany 存取模式中建立 PersistentVolumeClaim，並參照您先前建立的 StorageClass。

  1. 將下列資訊清單儲存到名為 volume-populator-pvc.yaml 的檔案：

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: PVC_NAME
  namespace: NAMESPACE
spec:
  accessModes:
  -   ReadWriteMany
  storageClassName: parallelstore-class
  resources:
    requests:
      storage: 12Gi
  dataSourceRef:
    apiGroup: datalayer.gke.io
    kind: GCPDataSource
    name: GCP_DATA_SOURCE

    替換下列值：

    • PVC_NAME：您要將資料移轉至其中的 PersistentVolumeClaim 名稱。PersistentVolumeClaim 必須由 Parallelstore 執行個體支援。
    • NAMESPACE：工作負載的執行命名空間。命名空間值應與工作負載命名空間相同。
    • GCP_DATA_SOURCE：GCPDataSourceCRD 的名稱，其中包含 Cloud Storage bucket 的參照。詳情請參閱 GCPDataSource CRD 參考資料。

  2. 執行下列指令，建立 PersistentVolumeClaim：

    kubectl apply -f volume-populator-pvc.yaml

在 PersistentVolumeClaim 佈建完成前，GKE 不會排定工作負載 Pod。如要查看資料移轉進度，請參閱「查看資料移轉進度」。如果在佈建期間發生錯誤，請參閱疑難排解。

(選用) 查看資料轉移進度

本節說明如何追蹤資料從 Cloud Storage 值區轉移至 Parallelstore 磁碟區的進度。你可以藉此監控轉移狀態，確保資料順利複製。如果 PersistentVolumeClaim 繫結作業耗時過長，也應執行這項指令。

  1. 執行下列指令，確認 PersistentVolumeClaim 的狀態：

    kubectl describe pvc PVC_NAME -n NAMESPACE

  2. 檢查 PersistentVolumeClaim 事件訊息，瞭解資料轉移進度。GKE 大約每分鐘會記錄一次訊息。輸出內容類似於下列內容：

    Reason                          Message
------                          -------
PopulateOperationStartSuccess   Populate operation started
PopulateOperationStartSuccess   Populate operation started
Provisioning                    External provisioner is provisioning volume for claim "my-namespace/my-pvc"
Provisioning                    Assuming an external populator will provision the volume
ExternalProvisioning            Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
PopulateOperationStartSuccess   Populate operation started
PopulatorPVCCreationProgress    objects found 7, objects copied 7, objects skipped 0. bytes found 1000020010, bytes copied 1000020010, bytes skipped 0
PopulateOperationFinished       Populate operation finished
PopulatorFinished               Populator finished

系統可能需要一段時間才會開始填入作業，這項作業取決於檔案大小。如果幾分鐘後仍未看到任何資料轉移進度，請參閱「疑難排解」一節。

建立會耗用磁碟區的工作負載

本節提供範例，說明如何建立會耗用您先前建立的 PersistentVolumeClaim 資源的 Pod。

  1. 將下列 Pod 的 YAML 資訊清單儲存為 pod.yaml。

    apiVersion: v1
kind: Pod
metadata:
  name: POD_NAME
  namespace: NAMESPACE
spec:
  volumes:
  -   name: parallelstore-volume
    persistentVolumeClaim:
      claimName: PVC_NAME
  containers:
  -   image: nginx
    name: nginx
    volumeMounts:
    -   name: parallelstore-volume
      mountPath: /mnt/data

    替換下列值：

    • POD_NAME：執行工作負載的 Pod 名稱。
    • NAMESPACE：工作負載的執行命名空間。命名空間值應與工作負載命名空間相同。
    • PVC_NAME：您要將資料移轉至其中的 PersistentVolumeClaim 名稱。PersistentVolumeClaim 必須由 Parallelstore 執行個體支援。

  2. 執行下列指令，將資訊清單套用至叢集：

    kubectl apply -f pod.yaml

  3. 檢查 Pod 的狀態，並等待狀態變成 RUNNING。PersistentVolumeClaim 必須先繫結，工作負載才能執行。

    kubectl describe pod POD_NAME -n NAMESPACE

  4. 確認檔案已順利轉移，且工作負載可存取這些檔案。

    kubectl exec -it POD_NAME -n NAMESPACE -c nginx -- /bin/sh

    切換至 /mnt/data 目錄並執行 ls：

    cd /mnt/data
ls

    輸出內容應列出 Cloud Storage bucket URI 中的所有檔案。

在動態佈建期間刪除 PersistentVolumeClaim

如果您需要在動態佈建期間刪除 PersistentVolumeClaim，但資料仍在轉移，則有兩種做法：正常刪除和強制刪除。

溫和刪除法需要較少心力，但可能較耗時，且不會考量使用者設定錯誤導致資料無法完成轉移的情況。強制刪除是較快的替代方案，可提供更大的彈性和控制權；如果您需要快速重新啟動或修正錯誤設定，這個選項就非常適合。

安全刪除

使用這個刪除選項，可確保 GKE 在刪除相關聯的資源前，資料轉移程序已完成。

  1. 如果工作負載 Pod 存在，請執行下列指令刪除：

    kubectl delete pod POD_NAME -n NAMESPACE

  2. 找出暫時性 PersistentVolumeClaim 的名稱：

    PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
TEMP_PVC=prime-$PVC_UID

echo $TEMP_PVC

  3. 找出 PersistentVolume 的名稱：

    PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')

echo ${PV_NAME?}

    如果輸出內容為空白，表示 PersistentVolume 尚未建立。

  4. 執行下列指令，刪除 PersistentVolumeClaim。

    kubectl delete pvc PVC_NAME -n NAMESPACE

    等待資料轉移完成。GKE 最終會刪除 PersistentVolumeClaim、PersistentVolume 和 Parallelstore 執行個體。

  5. 確認暫時的 PersistentVolumeClaim、PersistentVolumeClaim 和 PersistentVolume 資源已刪除：

    kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"

  6. 確認 Parallelstore 執行個體已刪除。Parallelstore 執行個體會與 PersistentVolume 共用相同名稱。

    gcloud beta parallelstore instances list \
    --project=PROJECT_ID \
    --location=- | grep ${PV_NAME?}

強制刪除

如果需要在資料轉移程序完成前刪除 PersistentVolumeClaim 和相關聯的資源，請使用這個刪除選項。如果資料傳輸時間過長或發生錯誤，或是需要快速回收資源，您可能需要使用這個選項。

  1. 刪除工作負載 Pod (如有)：

    kubectl delete pod POD_NAME -n NAMESPACE

  2. 將 PersistentVolume 回收政策更新為 Delete。這項設定可確保在刪除相關聯的 PersistentVolumeClaim 時，系統會自動刪除 PersistentVolume 和基礎儲存空間。

    如有下列任一情況，請略過下列指令：

    • 您不想刪除 PersistentVolume 或基礎儲存空間。
    • 您目前的回收政策為 Retain，且您想保留基礎儲存空間。視需要手動清除 PersistentVolume 和儲存空間執行個體。

    • 下列 echo $PV_NAME 指令會輸出空字串，表示 PersistentVolume 尚未建立。

      PV_NAME=$(kubectl describe pvc $TEMP_PVC -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')

echo $PV_NAME

kubectl patch pv $PV_NAME -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'

  3. 找出臨時 PersistentVolumeClaim 的名稱，並為後續步驟設定環境變數：

    PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')

TEMP_PVC=prime-$PVC_UID

echo $TEMP_PVC

  4. 執行下列指令，刪除 PersistentVolumeClaim。終結器會封鎖刪除作業。按下 Control+C，然後繼續下一個步驟。

    kubectl delete pvc PVC_NAME -n NAMESPACE

  5. 從 PersistentVolumeClaim 移除 datalayer.gke.io/populate-target-protection 終結器。刪除 PersistentVolumeClaim 後，必須執行這個步驟。否則，gke-volume-populator 會將終止程式碼加回 PersistentVolumeClaim。

    kubectl get pvc PVC_NAME -n NAMESPACE -o=json | \
jq '.metadata.finalizers = null' | kubectl apply -f -

  6. 刪除 gke-managed-volumepopulator 命名空間中的臨時 PersistentVolumeClaim。

    kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator

  7. 確認暫時的 PersistentVolumeClaim、PersistentVolumeClaim 和 PersistentVolume 資源已刪除：

    kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"

  8. 確認 Parallelstore 執行個體已刪除。Parallelstore 執行個體會與 PersistentVolume 共用相同名稱。

    gcloud beta parallelstore instances list \
    --project=PROJECT_ID \
    --location=- | grep ${PV_NAME?}

疑難排解

本節說明如何解決 GKE Volume Populator 的相關問題。

繼續操作之前，請先執行下列指令，檢查 PersistentVolumeClaim 事件警告：

kubectl describe pvc PVC_NAME -n NAMESPACE

錯誤：An internal error has occurred

如果遇到下列錯誤，表示發生 Parallelstore API 內部錯誤。

Warning  PopulateOperationStartError  gkevolumepopulator-populator  Failed to start populate operation: populate data for PVC "xxx". Import data failed, error: rpc error: code = Internal desc = An internal error has occurred ("xxx")

如要解決這個問題，請按照下列步驟收集資料，以供支援團隊使用：

  1. 執行下列指令，取得暫時 PersistentVolumeClaim 的名稱，並將預留位置替換為實際名稱：

    PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')

TEMP_PVC=prime-${PVC_UID?}

echo ${TEMP_PVC?}

  2. 執行下列指令來取得磁碟區名稱：

    PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')

  3. 請將錯誤訊息、專案名稱和磁碟區名稱提供給支援團隊。

權限問題

如果在填入磁碟區時發生類似下列內容的錯誤，表示 GKE 遇到權限問題：

  • Cloud Storage bucket 不存在：PopulateOperationStartError 使用 code = PermissionDenied
  • Cloud Storage 值區或服務帳戶缺少權限： PopulateOperationFailed，並顯示 "code: "xxx" message:"Verify if bucket "xxx" exists and grant access"。
  • 找不到服務帳戶：PopulateOperationStartError，且具有 code = Unauthenticated。

如要解決這些錯誤，請仔細檢查下列項目：

  • Cloud Storage bucket 存取權：確認 bucket 存在，且服務帳戶具有 roles/storage.objectViewer permission。
  • 服務帳戶：確認 Kubernetes 服務帳戶和 IAM 服務帳戶都存在，且已正確連結。
  • Parallelstore 服務帳戶：確認 Parallelstore 服務帳戶存在，且具備必要權限 (IAM 帳戶的 roles/iam.serviceAccountTokenCreator 和 roles/iam.serviceAccountUser)。

如需詳細步驟和驗證指令，請參閱「設定必要權限」。如果錯誤持續發生，請與支援團隊聯絡，並提供錯誤訊息、專案名稱和 Cloud Storage 值區名稱。

引數無效錯誤

如果遇到 InvalidArgument 錯誤，表示您可能在 GCPDataSource 或 PersistentVolumeClaim 中提供不正確的值。錯誤記錄會指出含有無效資料的確切欄位。檢查 Cloud Storage 值區 URI 和其他相關欄位是否正確。

確認 PersistentVolumeClaim 佈建作業已完成

GKE Volume Populator 會在 gke-managed-volumepopulator 命名空間中使用暫時的 PersistentVolumeClaim 佈建磁碟區。

臨時 PersistentVolumeClaim 基本上是 PersistentVolumeClaim 的快照，但仍處於傳輸中 (等待資料完全載入)。名稱格式為 prime-YOUR_PVC_UID。

如要查看狀態，請按照下列步驟操作：

  1. 執行下列指令：

    PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')

TEMP_PVC=prime-$PVC_UID

echo $TEMP_PVC

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

    如果輸出內容為空白，表示系統未建立臨時 PersistentVolumeClaim。執行下列指令，檢查 PersistentVolumeClaim 事件警告：

    kubectl describe pvc PVC_NAME -n NAMESPACE

    如果佈建成功，輸出結果會與下列內容相似。尋找 ProvisioningSucceeded 記錄：

    Warning  ProvisioningFailed     9m12s                   parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = context deadline exceeded
Warning  ProvisioningFailed     3m41s (x11 over 9m11s)  parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = Volume pvc-808e41a4-b688-4afe-9131-162fe5d672ec not ready, current state: CREATING
Normal   ExternalProvisioning   3m10s (x43 over 13m)    persistentvolume-controller                                                                                  Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
Normal  Provisioning  8s (x13 over 10m)  "xxx"  External provisioner is provisioning volume for claim "xxx"
Normal  ProvisioningSucceeded  7s  "xxx"  Successfully provisioned volume "xxx"

  2. 檢查 Parallelstore 執行個體建立作業是否已啟動。

    gcloud beta parallelstore instances list \
    --project=PROJECT_ID \
    --location=-

    輸出結果大致如下。確認音量處於 CREATING 狀態。Parallelstore 執行個體建立完成後，狀態會變更為 ACTIVE。

    "projects/PROJECT_ID/locations/<my-location>/<my-volume>"  12000  2024-10-09T17:59:42.582857261Z  2024-10-09T17:59:42.582857261Z  CREATING  projects/PROJECT_ID/global/NETWORK_NAME

如果佈建失敗，請參閱Parallelstore 疑難排解指南，瞭解其他指引。

後續步驟