排查 GKE Volume Populator 数据传输问题

Autopilot Standard

GKE Volume Populator 可帮助将数据传输到 GKE 集群。不过，在数据转移过程中可能会出现问题，导致无法创建 PersistentVolumeClaim (PVC) 或无法正确填充数据。

您可以使用本文档解决使用 GKE Volume Populator 时遇到的常见问题。了解如何通过检查组件状态、验证配置以及解决资源或权限错误来排查数据传输问题。

对于使用 GKE Volume Populator 将数据植入 GKE 卷的应用开发者以及平台管理员和运维人员，此信息非常重要。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE 用户角色和任务。

检查临时 Kubernetes 资源

以下是 GKE 卷填充器使用临时资源的方式：

1. 在 gke-managed-volumepopulator 命名空间中创建临时 PVC。
2. 对于转移涉及的每个可用区，系统会在 PVC 的命名空间中创建一个转移作业、PV 和 PVC。
3. 数据传输完成后，GKE 卷填充器会自动移除所有这些临时资源。

如需检查临时资源，请按以下步骤操作：

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 替换为其他数字。

检查是否已启用工作负载身份联合

借助工作负载身份联合，迁移 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，请启用适用于 GKE 的工作负载身份联合。

转移路径无效

如果您遇到类似于以下内容的错误，则表示 GCPDatasource 资源中指定的转移路径不正确，转移将失败。

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

如需解决此问题，请删除 GCPDatasource 资源，使用正确的值更新 uri 字段，然后重新创建资源。

权限不足，无法访问相应存储桶

如果 Kubernetes 服务账号无权访问 GCPDatasource 资源中指定的存储桶 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 存储桶名称。
• PROJECT_NUMBER：您的 Google Cloud 项目编号。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• NAMESPACE：工作负载在其中运行的命名空间。
• KSA_NAME：您的 Kubernetes 服务账号的名称。
• ROLE：提供访问相应存储桶所需权限的 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 节点。在节点自动预配功能扩缩新节点后，此错误应会在几分钟内自行解决。

转移 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 \
       --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 以再次启动转移进程。

后续步骤

• 如果您在文档中找不到问题的解决方案，请参阅获取支持。