排查 GKE Volume Populator 数据转移问题

本指南介绍如何解决使用 GKE Volume Populator 将数据传输到 GKE 集群时出现的常见问题。它会引导您调试与 PersistentVolumeClaim (PVC) 和 PersistentVolume (PV) 创建、磁盘性能和数据传输作业执行相关的问题。

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

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

借助工作负载身份联合，迁移 Pod 可以安全地访问 Trusted Cloud by S3NS 服务。如果转移 Pod 无法向 Trusted Cloud 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：您的 Trusted 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：您的 Trusted Cloud 项目编号。
• PROJECT_ID：您的 Trusted 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：您的 Trusted Cloud 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 \
       --max-cpu MAXIMUM_CPU \
       --max-memory MAXIMUM_MEMORY
   

   替换以下内容：

   • CLUSTER_NAME：您要更新以启用节点自动预配功能的集群的名称。
   • LOCATION：集群的计算可用区或区域。例如 us-central1-a 或 us-central1。
   • PROJECT_ID：您的 Trusted Cloud 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 以再次启动转移进程。

后续步骤

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