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

Autopilot Standard

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

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

GKE Volume Populator では、次のように一時的なリソースが使用されます。

1. gke-managed-volumepopulator 名前空間に一時的な PVC が作成されます。
2. 転送に関与するゾーンごとに、転送ジョブ、PV、PVC が 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 ボリュームの場合は 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. その転送ジョブを検査します。

   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 連携が有効であるかどうかを確認する

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

バケットにアクセスするための権限の不足

GCPDatasource リソースで指定したバケット URI へのアクセス権が Kubernetes サービス アカウントにないと、転送ジョブは失敗します。その場合のエラー メッセージは次のようになります。

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 状態のノードがクラスタにないために、このエラーが発生することがあります。ノード自動プロビジョニングによって新しいノードがスケールアップされると、このエラーは数分以内で自動的に解決します。

スケジューリングが長時間 Pending 状態になっている転送 Pod

転送 Pod のステータスが長時間 Pending になっていることが PVC イベントで示されることがあります。

転送ジョブのスケジューリングが失敗したかどうかを、そのジョブのイベントで確認する手順は次のとおりです。

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 です。この上限は、手動で作成した既存のすべてのノードプールにわたる CPU リソースと、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 です。この上限は、手動で作成した既存のすべてのノードプールにわたる CPU リソースと、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. このエラーを解決するには、GCE の割り当てを大きくするか、スケールアップを妨げていると考えられる既存のリソースを削除します。詳細については、割り当てエラーをトラブルシューティングするをご覧ください。

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: ワークロードを運用する名前空間。

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 を再作成して転送プロセスを再開します。

次のステップ

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