GKE Volume Populator のデータ転送に関する問題のトラブルシューティング

このガイドでは、GKE Volume Populator を使用して GKE クラスタにデータを転送する際に発生する一般的な問題を解決する方法について説明します。PersistentVolumeClaim（PVC）と PersistentVolume（PV）の作成、ディスク パフォーマンス、データ転送ジョブの実行に関連する問題のデバッグについて説明します。

一時的な Kubernetes リソースを検査する

GKE Volume Populator が一時リソースを使用する方法は次のとおりです。

1. 一時 PVC が gke-managed-volumepopulator Namespace に作成されます。
2. 転送に関与するゾーンごとに、転送ジョブ、PV、PVC が PVC の Namespace に作成されます。
3. データ転送が完了すると、GKE Volume Populator はこれらのすべての一時リソースを自動的に削除します。

一時リソースを調べる手順は次のとおりです。

1. 環境変数を保存します。

   export PVC_NAME=PVC_NAME
   export NAMESPACE=NAMESPACE
   

   次の値を置き換えます。

   • PVC_NAME: PersistentVolumeClaim リソースの名前。
   • NAMESPACE: ワークロードが実行される 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 Namespace の一時 PVC を検査します。

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

4. Namespace 内の一時 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 は、各ゾーンに転送 Job を作成します（単一ゾーンの Hyperdisk ML ボリュームの場合は 1 つ、マルチゾーンの 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. 転送 Job を調べます。

   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 と転送 Job リソースを作成します。移行に関与するすべてのゾーンのリソースを検査するには、TEMP_PVC_LIST のインデックスの 0 を他の数値に置き換えます。

Workload Identity 連携が有効になっているかどうかを確認する

Workload Identity 連携を使用すると、転送 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 がない場合は、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 フィールドを正しい値で更新して、リソースを再作成します。

バケットにアクセスするための十分な権限がありません

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: ワークロードが実行される Namespace。
• KSA_NAME: Kubernetes サービス アカウントの名前。
• ROLE: バケットへのアクセスに必要な権限を提供する IAM ロール。たとえば、roles/storage.objectViewer を使用してバケットへの読み取り専用アクセス権を付与します。

エラー: error generating accessibility requirements

gke-managed-volumepopulator Namespace で 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: 実際の 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 クラスタの場合は、転送 Job 用に作成したノードに必要なコンピューティング クラスラベルがあることを確認します。

   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 Volume Populator によって作成された一時 PVC に関連付けられているイベントログを調べます。手順は次のとおりです。

1. 関連する環境変数を保存します。

   export PVC_NAME=PVC_NAME
   export NAMESPACE=NAMESPACE
   

   次の値を置き換えます。

   • PVC_NAME: PersistentVolumeClaim リソースの名前。
   • NAMESPACE: ワークロードが実行される 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 を再作成して転送プロセスを再開します。

次のステップ

• このドキュメントに問題の解決策が見当たらない場合は、サポートを受けるをご覧ください。