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


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

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 インスタンスのみをサポートしています。
  • GKE Volume Populator は、volumeBindingModeImmediate に設定されている StorageClass リソースのみをサポートします。
  • 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 を実行して最新のバージョンを取得する。

要件

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

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

環境を準備する

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

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

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

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

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

    ロールを付与するには、次のコマンドを実行します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="user:EMAIL_ADDRESS" \
        --role=roles/compute.networkAdmin
    

    EMAIL_ADDRESS は実際のメールアドレスに置き換えます。

  2. サービス ネットワーキングを有効にします。

    gcloud services enable servicenetworking.googleapis.com
    
  3. VPC ネットワークを作成します。

    gcloud compute networks create NETWORK_NAME \
      --subnet-mode=auto \
      --mtu=8896 \
      --project=PROJECT_ID
    

    次のように置き換えます。

    • NETWORK_NAME: Parallelstore インスタンスを作成する VPC ネットワークの名前。
    • PROJECT_ID: Google Cloud プロジェクト ID
  4. 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 範囲の名前に置き換えます。

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

    CIDR_RANGE=$(
      gcloud compute addresses describe IP_RANGE_NAME \
        --global  \
        --format="value[separator=/](address, prefixLength)" \
        --project=PROJECT_ID \
    )
    
  6. 作成した 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 トラフィックを許可するファイアウォール ルールの名前に置き換えます。

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

    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 ドライバと Workload Identity Federation for GKE を有効にした 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 の権限を設定する必要があります。

  1. Kubernetes Namespace を作成します。

    kubectl create namespace NAMESPACE
    

    NAMESPACE は、ワークロードが実行される名前空間に置き換えます。

  2. Kubernetes サービス アカウントを作成します。

    kubectl create serviceaccount KSA_NAME \
        --namespace=NAMESPACE
    

    KSA_NAME は、Pod が API の認証に使用する Kubernetes サービス アカウントの名前に置き換えます。 Google Cloud

  3. IAM サービス アカウントを作成する。組織内の任意のプロジェクトで既存の IAM サービス アカウントを使用することもできます。

    gcloud iam service-accounts create IAM_SA_NAME \
        --project=PROJECT_ID
    

    次のように置き換えます。

    • IAM_SA_NAME: IAM サービス アカウントの名前。
    • PROJECT_ID: Google Cloud プロジェクト ID
  4. 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 バケット名に置き換えます。

  5. 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]"
    
  6. GKE がサービス アカウント間のリンクを認識できるように、Kubernetes サービス アカウントにアノテーションを付けます。

    kubectl annotate serviceaccount KSA_NAME \
        --namespace NAMESPACE \
        iam.gke.io/gcp-service-account=IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    
  7. Parallelstore サービス ID を作成します。

    gcloud beta services identity create \
        --service=parallelstore.googleapis.com \
        --project=PROJECT_ID
    
  8. Parallelstore サービス ID にロール roles/iam.serviceAccountTokenCreator を付与して、IAM サービス アカウントの権限借用を許可します。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 値は、プロジェクトに対して自動生成される一意の識別子です。この値を確認する方法については、プロジェクトの作成と管理をご覧ください。

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

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

  1. GCPDataSource リソースを作成する
  2. Parallelstore StorageClass を作成する
  3. PersistentVolumeClaim を作成してボリュームにアクセスする
  4. PersistentVolumeClaim のプロビジョニングが完了したことを確認します
  5. (省略可)データ転送の進行状況を確認する
  6. ボリュームを消費する Pod を作成します。

GCPDataSource リソースを作成する

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

  1. 次のマニフェストを 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 が API の認証に使用する Kubernetes サービス アカウントの名前。 Google Cloud cloudStorage.serviceAccountName の値は、必要な権限を設定する手順で Workload Identity Federation for GKE 用に設定した Kubernetes サービス アカウントにする必要があります。
    • GCS_BUCKET: Cloud Storage バケット名。また、uri フィールドに gs://GCS_BUCKET/PATH_INSIDE_BUCKET/ を指定することもできます。
  2. 次のコマンドを実行して GCPDataSource リソースを作成します。

    kubectl apply -f gcpdatasource.yaml
    

Parallelstore StorageClass を作成する

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

  1. 次のマニフェストを parallelstore-class.yaml として保存します。StorageClass 定義の volumeBindingMode フィールドが Immediate に設定されていることを確認します。

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: parallelstore-class
    provisioner: parallelstore.csi.storage.gke.io
    volumeBindingMode: Immediate
    reclaimPolicy: Delete
    
  2. 次のコマンドを実行して StorageClass を作成します。

    kubectl apply -f parallelstore-class.yaml
    

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

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

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

  1. 次のマニフェストを 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 リファレンスをご覧ください。
  2. 次のコマンドを実行して PersistentVolumeClaim を作成します。

    kubectl apply -f volume-populator-pvc.yaml
    

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

PersistentVolumeClaim のプロビジョニングが完了したことを確認する

GKE Volume Populator は、ボリュームのプロビジョニングに gke-managed-volumepopulator Namespace 内の一時的な PersistentVolumeClaim を使用します。

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

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

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

    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 が作成されていないことを意味します。その場合は、トラブルシューティングのセクションをご覧ください。

    プロビジョニングが成功すると、出力は次のようになります。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"
    
  2. 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 トラブルシューティング ガイドを参照してください。

(省略可)データ転送の進行状況を確認する

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

  1. 次のコマンドを実行して、PersistentVolumeClaim のステータスを確認します。

    kubectl describe pvc PVC_NAME -n NAMESPACE
    
  2. PersistentVolumeClaim イベント メッセージを確認して、データ転送の進行状況を確認します。GKE はメッセージを約 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 を作成する方法の例を示します。

  1. 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 インスタンスでサポートされている必要があります。
  2. 次のコマンドを実行して、マニフェストをクラスタに適用します。

    kubectl apply -f pod.yaml
    
  3. Pod のステータスを確認し、ステータスが RUNNING になるまで待ちます。ワークロードを実行する前に、PersistentVolumeClaim をバインドする必要があります。

    kubectl describe pod POD_NAME -n NAMESPACE
    
  4. ファイルが正常に転送され、ワークロードからアクセスできることを確認します。

    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 が関連リソースを削除する前に、データ転送プロセスが完了します。

  1. ワークロード Pod が存在する場合は、次のコマンドを実行して削除します。

    kubectl delete pod POD_NAME -n NAMESPACE
    
  2. 一時的な 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
    
  3. PersistentVolume の名前を確認します。

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

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

  4. 次のコマンドを実行して PersistentVolumeClaim を削除します。ファイナライザは削除オペレーションをブロックします。Ctrl+C を押して、次のステップに進みます。

    kubectl delete pvc PVC_NAME -n NAMESPACE
    

    データ転送が完了するまで待ちます。最終的に、GKE は PersistentVolumeClaim、PersistentVolume、Parallelstore インスタンスを削除します。

  5. 一時的な PersistentVolumeClaim、PersistentVolumeClaim、PersistentVolume リソースが削除されていることを確認します。

    kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
    
  6. Parallelstore インスタンスが削除されていることを確認します。Parallelstore インスタンスは、PersistentVolume と同じ名前を共有します。手順 3 で PersistentVolume が作成されていないことを確認した場合は、このコマンドを実行する必要はありません。

    gcloud beta parallelstore instances list \
        --project=PROJECT_ID \
        --location=- | grep ${PV_NAME?}
    

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

  1. ワークロード Pod が存在する場合は削除します。

    kubectl delete pod POD_NAME -n NAMESPACE
    
  2. 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"}}'
    
  3. 一時的な 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
    
  4. 次のコマンドを実行して PersistentVolumeClaim を削除します。ファイナライザは削除オペレーションをブロックします。Ctrl+C を押して、次のステップに進みます。

    kubectl delete pvc PVC_NAME -n NAMESPACE
    
  5. 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 -
    
  6. gke-managed-volumepopulator Namespace 内の一時 PersistentVolumeClaim を削除します。

    kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator
    
  7. 一時的な PersistentVolumeClaim、PersistentVolumeClaim、PersistentVolume リソースが削除されていることを確認します。

    kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
    
  8. Parallelstore インスタンスが削除されていることを確認します。Parallelstore インスタンスは、PersistentVolume と同じ名前を共有します。手順 2 で 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")

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

  1. 次のコマンドを実行して、一時的な 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?}
    
  2. 次のコマンドを実行して、ボリューム名を取得します。

    PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
    
  3. エラー メッセージ、プロジェクト名、ボリューム名をサポートチームに連絡します。

権限の問題

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

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

これらの問題を解決するには、以下の点を確認してください。

  • Cloud Storage バケットへのアクセス: バケットが存在し、サービス アカウントに roles/storage.objectViewer permission があることを確認します。
  • サービス アカウント: Kubernetes サービス アカウントと IAM サービス アカウントの両方が存在し、正しくリンクされていることを確認します。
  • Parallelstore サービス アカウント: 存在し、必要な権限(IAM アカウントの roles/iam.serviceAccountTokenCreatorroles/iam.serviceAccountUser)があることを確認します。

詳しい手順と検証コマンドについては、必要な権限を設定するをご覧ください。エラーが解決しない場合は、エラー メッセージ、プロジェクト名、Cloud Storage バケット名を添えてサポートにお問い合わせください。

無効な引数エラー

InvalidArgument エラーが発生した場合は、GCPDataSource または PersistentVolumeClaim のいずれかに誤った値が指定されている可能性があります。エラーログには、無効なデータを含むフィールドが正確に示されます。Cloud Storage バケットの URI とその他の関連フィールドが正しいことを確認します。

次のステップ