このページは Cloud Translation API によって翻訳されました。

GKE Volume Populator を使用して動的プロビジョニング中に Cloud Storage からデータを転送する

Autopilot Standard

GKE Volume Populator は招待制です。 Google Cloud プロジェクトで GKE Volume Populator へのアクセス権をリクエストする場合は、営業担当者にお問い合わせください。

GKE Volume Populator を使用すると、動的プロビジョニング中に、ソースストレージから宛先 PersistentVolumeClaim にデータをプリロードできます。手動でデータ転送を行うための追加のスクリプトや CLI コマンドを実行する必要はありません。この機能は、Kubernetes Volume Populator 機能を利用して、データ転送プロセスの自動化と効率化を処理します。シームレスなデータポータビリティを提供するため、ストレージタイプを切り替えて、価格やパフォーマンスの最適化を活用できます。

この機能は、Cloud Storage バケットから別のGoogle Cloud ストレージタイプ（Parallelstore など）でサポートされている PersistentVolumeClaim に大量のデータを転送する必要がある場合に使用します。

GKE Volume Populator は、主に gcloud CLI と kubectl CLI を介して操作します。GKE Volume Populator は、Autopilot クラスタと Standard クラスタの両方でサポートされています。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 バケット、宛先ストレージタイプとして Parallelstore インスタンスのみをサポートします。
GCPDataSource カスタムリソースは、Kubernetes ワークロードと同じ Namespace に存在する必要があります。Namespace 間のデータソースを含むボリュームはサポートされていません。
GKE Volume Populator は、IAM サービスアカウントと Kubernetes サービスアカウントの Workload Identity Federation for GKE バインディングのみをサポートしています。Kubernetes サービスアカウントに IAM 権限を直接付与することはできません。

始める前に

作業を始める前に、次のことを確認してください。

Parallelstore API と Google Kubernetes Engine API を有効にします。

API を有効にする

このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。

制限事項と要件については、Parallelstore CSI ドライバの概要をご覧ください。
転送するデータが入力された Cloud Storage バケットを作成します。

要件

GKE Volume Populator を使用するには、クラスタが次の要件を満たしている必要があります。

GKE クラスタバージョン 1.31.1-gke.1729000 以降を使用します。
Parallelstore CSI ドライバが有効になっていること。GKE は、新規および既存の GKE Autopilot クラスタでデフォルトで CSI ドライバを有効にします。新規および既存の Standard クラスタでは、CSI ドライバを有効にする必要があります。

環境を準備する

このセクションでは、GKE クラスタを作成し、GKE Volume Populator を使用するために必要な権限を設定する手順について説明します。

VPC ネットワークを設定する

Parallelstore インスタンスとクライアント Compute Engine VM または GKE クラスタを作成するときに、同じ Virtual Private Cloud（VPC）ネットワークを指定する必要があります。トラフィックをパブリックインターネットに公開せずに VPC が Google Cloudサービスにプライベート接続できるようにするには、まだ行っていない場合は、プライベートサービスアクセス（PSA）の 1 回限りの構成を行う必要があります。

PSA を構成する手順は次のとおりです。

プロジェクトのネットワークピアリングを設定するには、Compute ネットワーク管理者（roles/compute.networkAdmin）IAM 権限を構成します。

ロールを付与するには、次のコマンドを実行します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:EMAIL_ADDRESS" \
    --role=roles/compute.networkAdmin
```
EMAIL_ADDRESS は実際のメールアドレスに置き換えます。
サービスネットワーキングを有効にします。
```
gcloud services enable servicenetworking.googleapis.com
```
VPC ネットワークを作成します。
```
gcloud compute networks create NETWORK_NAME \
  --subnet-mode=auto \
  --mtu=8896 \
  --project=PROJECT_ID
```
次のように置き換えます。
- NETWORK_NAME: Parallelstore インスタンスを作成する VPC ネットワークの名前。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
注: mtu（最大伝送単位。このネットワークで送信できる最大の IP パケットのサイズ）の値を許可されている最大値の 8, 896 に設定すると、デフォルト値の 1,460 バイトと比較してパフォーマンスが最大 10% 向上します。
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 は、VPC ネットワークの IP 範囲の名前に置き換えます。

前の手順で作成した範囲に関連付けられた CIDR 範囲を使用して環境変数を設定します。

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

作成した 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 トラフィックを許可するファイアウォールルールの名前に置き換えます。

ピアリングを接続します。

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

VPC ネットワークの設定中に問題が発生した場合は、Parallelstore のトラブルシューティングガイドをご覧ください。

GKE クラスタを作成する

フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用することをおすすめします。ワークロードのニーズに最適な GKE の運用モードを選択するには、GKE の運用モードを選択するをご覧ください。

Autopilot

Autopilot を使用して GKE クラスタを作成するには、次のコマンドを実行します。

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

GKE は、Autopilot クラスタでデフォルトで Workload Identity Federation for GKE と Parallelstore CSI ドライバを有効にします。

次の値を置き換えます。

CLUSTER_NAME: クラスタの名前。
CLUSTER_VERSION : GKE のバージョン番号。1.31.1-gke.1729000 以降を指定する必要があります。
NETWORK_NAME: Parallelstore インスタンス用に作成した VPC ネットワークの名前。詳細については、VPC ネットワークを構成するをご覧ください。
CLUSTER_LOCATION: クラスタを作成するリージョン。最適なパフォーマンスを得るには、サポートされている Parallelstore のロケーションにクラスタを作成することをおすすめします。サポートされていない Parallelstore ロケーションにクラスタを作成する場合は、Parallelstore StorageClass の作成時に、サポートされている Parallelstore ロケーションを使用するカスタムトポロジを指定する必要があります。指定しないと、プロビジョニングが失敗します。

標準

次のコマンドを使用して、Parallelstore CSI ドライバと GKE 用 Workload Identity 連携を有効にして Standard クラスタを作成します。

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 ネットワークの名前。詳細については、VPC ネットワークを構成するをご覧ください。
CLUSTER_LOCATION: クラスタを作成するリージョンまたはゾーン。最適なパフォーマンスを得るには、サポートされている Parallelstore のロケーションにクラスタを作成することをおすすめします。サポートされていない Parallelstore ロケーションにクラスタを作成する場合は、Parallelstore StorageClass の作成時に、サポートされている Parallelstore ロケーションを使用するカスタムトポロジを指定する必要があります。指定しないと、プロビジョニングが失敗します。

必要な権限を設定する

Cloud Storage バケットからデータを転送するには、Workload Identity Federation for GKE の権限を設定する必要があります。

Kubernetes Namespace を作成します。
```
kubectl create namespace NAMESPACE
```
NAMESPACE は、ワークロードが実行される名前空間に置き換えます。
Kubernetes サービスアカウントを作成します。
```
kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE
```
KSA_NAME は、Pod が Google Cloud API に対する認証に使用する Kubernetes サービスアカウントの名前に置き換えます。

注意: 同じ Namespace 内のワークロードでこの Kubernetes サービスアカウントを再利用すると、その Pod が Cloud Storage バケットにアクセスできるようになります。このサービスアカウントを名前空間のワークロードに再利用しないことをおすすめします。
IAM サービスアカウントを作成する。組織内の任意のプロジェクトで既存の IAM サービスアカウントを使用することもできます。
```
gcloud iam service-accounts create IAM_SA_NAME \
    --project=PROJECT_ID
```
次のように置き換えます。
- IAM_SA_NAME: IAM サービスアカウントの名前。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
Cloud Storage バケットにアクセスできるように、IAM サービスアカウントに roles/storage.objectViewer ロールを付与します。
```
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 バケット名で置き換えます。

Kubernetes サービスアカウントに IAM サービスアカウントの権限借用を許可する 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]"

GKE がサービスアカウント間のリンクを認識できるように、Kubernetes サービスアカウントにアノテーションを付けます。

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

Parallelstore サービス ID を作成します。

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

Parallelstore サービス ID に IAM サービスアカウントの権限借用を許可するには、Parallelstore サービス ID に roles/iam.serviceAccountTokenCreator ロールを付与します。以降の手順で使用できるように、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 値は、プロジェクトに対して自動的に生成される一意の識別子です。この値を確認するには、プロジェクトの作成と管理をご覧ください。

Parallelstore サービス ID が IAM サービスアカウントがアクセスできるすべてのリソースにアクセスできるようにするには、Parallelstore サービス ID に roles/iam.serviceAccountUser ロールを付与します。

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

GKE サービス ID が IAM サービスアカウントがアクセスできるすべてのリソースにアクセスできるようにするには、GKE サービス ID に roles/iam.serviceAccountUser ロールを付与します。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 バケットからデータがプリロードされた Parallelstore ボリュームを作成する一般的なプロセスについて説明します。

GCPDataSource リソースを作成します。
Parallelstore StorageClass を作成する。
ボリュームにアクセスするための PersistentVolumeClaim を作成します。
（省略可）データ転送の進行状況を確認します。
ボリュームを消費する Pod を作成します。

`GCPDataSource` リソースを作成する

GKE Volume Populator を使用するには、GCPDataSource カスタムリソースを作成します。このリソースは、ボリュームの作成に使用するソースストレージプロパティを定義します。

次のマニフェストを 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: Cloud Storage バケットへの参照を保持する GCPDataSource CRD の名前。詳細については、GCPDataSource CRD リファレンスをご覧ください。
- NAMESPACE: ワークロードが実行される Namespace。Namespace の値は、ワークロードの Namespace と同じにする必要があります。
- KSA_NAME: Pod が Google Cloud API の認証に使用する Kubernetes サービスアカウントの名前。cloudStorage.serviceAccountName の値は、必要な権限を設定するステップで Workload Identity Federation for GKE 用に設定した Kubernetes サービスアカウントにする必要があります。
- GCS_BUCKET: Cloud Storage バケット名。または、uri フィールドに gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ を指定することもできます。
次のコマンドを実行して GCPDataSource リソースを作成します。
```
kubectl apply -f gcpdatasource.yaml
```

Parallelstore StorageClass を作成する

Parallelstore CSI ドライバに、GKE クラスタと同じリージョンに Parallelstore インスタンスをプロビジョニングするように指示する StorageClass を作成します。これにより、最適な I/O パフォーマンスが確保されます。

次のマニフェストを parallelstore-class.yaml として保存します。

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

次のコマンドを実行して StorageClass を作成します。
```
kubectl apply -f parallelstore-class.yaml
```

特定のトポロジを持つカスタム StorageClass を作成する場合は、Parallelstore CSI ガイドをご覧ください。

ボリュームにアクセスするための PersistentVolumeClaim を作成する

次のマニフェストファイルは、前に作成した StorageClass を参照する ReadWriteMany アクセスモードで PersistentVolumeClaim を作成する方法の例を示しています。

次のマニフェストを 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: ワークロードが実行される Namespace。Namespace の値は、ワークロード Namespace と同じにする必要があります。
- GCP_DATA_SOURCE: Cloud Storage バケットへの参照を保持する GCPDataSource CRD の名前。詳細については、GCPDataSource CRD リファレンスをご覧ください。
次のコマンドを実行して PersistentVolumeClaim を作成します。
```
kubectl apply -f volume-populator-pvc.yaml
```

GKE は、PersistentVolumeClaim のプロビジョニングが完了するまで、ワークロード Pod をスケジュールしません。データ移行の進行状況を確認するには、データ移行の進行状況を確認するをご覧ください。プロビジョニング中にエラーが発生した場合は、トラブルシューティングを参照してください。

（省略可）データ転送の進行状況を表示する

このセクションでは、Cloud Storage バケットから Parallelstore ボリュームへのデータ転送の進行状況を追跡する方法について説明します。これにより、転送のステータスをモニタリングし、データが正常にコピーされたことを確認できます。PersistentVolumeClaim のバインディングオペレーションに時間がかかりすぎる場合も、このコマンドを実行する必要があります。

次のコマンドを実行して、PersistentVolumeClaim のステータスを確認します。
```
kubectl describe pvc PVC_NAME -n NAMESPACE
```

PersistentVolumeClaim イベントメッセージを確認して、データ転送の進行状況を確認します。GKE は、メッセージを 1 分に 1 回程度ログに記録します。出力は次のようになります。

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 を作成する方法の例を示します。

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: ワークロードが実行される Namespace。Namespace の値は、ワークロード Namespace と同じにする必要があります。
- PVC_NAME: データを転送する PersistentVolumeClaim の名前。PersistentVolumeClaim は Parallelstore インスタンスによってバックアップされている必要があります。
次のコマンドを実行して、マニフェストをクラスタに適用します。
```
kubectl apply -f pod.yaml
```
Pod のステータスを確認し、ステータスが RUNNING になるまで待ちます。ワークロードを実行する前に、PersistentVolumeClaim をバインドする必要があります。
```
kubectl describe pod POD_NAME -n NAMESPACE
```
ファイルが正常に転送され、ワークロードからアクセスできることを確認します。
```
kubectl exec -it POD_NAME -n NAMESPACE -c nginx -- /bin/sh
```
/mnt/data ディレクトリに移動して ls を実行します。
```
cd /mnt/data
ls
```
出力には、Cloud Storage バケット URI に存在するすべてのファイルが一覧表示されます。

動的プロビジョニング中に PersistentVolumeClaim を削除する

動的プロビジョニング中にデータが転送されている間に PersistentVolumeClaim を削除する必要がある場合は、正常な削除と強制削除の 2 つの方法があります。

正常な削除は労力が少なくて済みますが、時間がかかる可能性があり、データ転送の完了を妨げるユーザーの誤った構成は考慮されません。強制削除は、柔軟性と制御性を高めることができる高速な代替手段です。このオプションは、誤った構成をすばやく再起動または修正する必要がある場合に適しています。

正常な削除

この削除オプションを使用すると、GKE が関連リソースを削除する前にデータ転送プロセスが完了します。

次のコマンドを実行して、ワークロード Pod が存在する場合は削除します。
```
kubectl delete pod POD_NAME -n NAMESPACE
```

一時的な 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

PersistentVolume の名前を確認します。

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

echo ${PV_NAME?}

出力が空の場合、PersistentVolume はまだ作成されていません。

次のコマンドを実行して PersistentVolumeClaim を削除します。
```
kubectl delete pvc PVC_NAME -n NAMESPACE
```
データ転送が完了するまで待ちます。GKE は最終的に PersistentVolumeClaim、PersistentVolume、Parallelstore インスタンスを削除します。
一時的な PersistentVolumeClaim、PersistentVolumeClaim、PersistentVolume リソースが削除されていることを確認します。
```
kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
```
Parallelstore インスタンスが削除されていることを確認します。Parallelstore インスタンスは、PersistentVolume と同じ名前を共有します。
```
gcloud beta parallelstore instances list \
    --project=PROJECT_ID \
    --location=- | grep ${PV_NAME?}
```

強制削除

この削除オプションは、データ転送プロセスが完了する前に PersistentVolumeClaim とその関連リソースを削除する必要がある場合に使用します。このオプションは、データ転送に時間がかかりすぎる場合やエラーが発生した場合、またはリソースを迅速に再利用する必要がある場合に使用します。

ワークロード Pod が存在する場合は削除します。
```
kubectl delete pod POD_NAME -n NAMESPACE
```
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"}}'
```

一時的な 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

次のコマンドを実行して PersistentVolumeClaim を削除します。ファイナライザーは削除オペレーションをブロックします。Ctrl+C キーを押して、次の手順に進みます。
```
kubectl delete pvc PVC_NAME -n NAMESPACE
```
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 -
```
gke-managed-volumepopulator Namespace の一時 PersistentVolumeClaim を削除します。
```
kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator
```
一時的な PersistentVolumeClaim、PersistentVolumeClaim、PersistentVolume リソースが削除されていることを確認します。
```
kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
```
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")

この問題を解決するには、次の手順に沿ってサポート用のデータを収集する必要があります。

次のコマンドを実行して、一時的な 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?}
```

次のコマンドを実行して、ボリューム名を取得します。

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

エラーメッセージ、プロジェクト名、ボリューム名を添えて、サポートチームにお問い合わせください。

権限の問題

ボリュームの入力中に次のようなエラーが発生した場合は、GKE で権限の問題が発生したことを示します。

Cloud Storage バケットが存在しない: PopulateOperationStartError（code = PermissionDenied）
Cloud Storage バケットまたはサービスアカウントに対する権限がない: "code: "xxx" message:"Verify if bucket "xxx" exists and grant access" を含む PopulateOperationFailed。
サービスアカウントが見つかりません: code = Unauthenticated を含む PopulateOperationStartError。

これらのエラーを解決するには、次の点を確認してください。

Cloud Storage バケットへのアクセス: バケットが存在し、サービスアカウントに 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 Namespace の一時的な PersistentVolumeClaim を使用します。

一時的な PersistentVolumeClaim は、転送中の PersistentVolumeClaim（データが完全に読み込まれるのを待機中）のスナップショットです。名前の形式は prime-YOUR_PVC_UID です。

ステータスを確認するには:

次のコマンドを実行します。

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"

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 のトラブルシューティングガイドを参照してください。