バケットを再配置する

このページでは、バケットをあるロケーションから別のロケーションに再配置するプロセスについて説明します。バケットの再配置については、バケットの再配置をご覧ください。

始める前に

バケットの再配置プロセスを開始する前に、次の手順を完了します。

  1. 管理ハブを有効にします。

  2. 削除（復元可能）を有効にします。

  3. 割り当てと上限を確認して、新しいロケーションにバケットのデータに対応できる十分な割り当てがあることを確認します。

  4. バケットの再配置タイプを決定して、書き込みのダウンタイムが必要かどうかを確認します。

  5. 既存のバケットタグを削除します。

  6. インベントリ レポートを使用する場合は、構成を保存します。

必要なロール

バケットをあるロケーションから別のロケーションに再配置する権限を取得するには、プロジェクトに対するストレージ管理者（roles/storage.admin）ロールを付与するよう管理者に依頼してください。

このロールには、バケットをあるロケーションから別のロケーションに再配置するための一連の権限が付与されています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

この方法を使用するには、認証されたユーザーにバケットに対する次の IAM 権限が必要です。

  • storage.buckets.relocate
  • storage.bucketOperations.get
    バケットの再配置オペレーションのステータスを表示するには、この権限が必要です。
  • storage.bucketOperations.list
    バケットの再配置オペレーションのリストを表示するには、この権限が必要です。
  • storage.bucketOperations.cancel
    バケットの再配置オペレーションをキャンセルするには、この権限が必要です。

この方法を使用するには、認証されたユーザーにバケットに対する次の権限も必要になる場合があります。

  • storage.bucket.get
    この権限は、ドライラン中とバケットの再配置オペレーションの増分データコピー中にバケットのメタデータを表示するために必要です。
  • storage.objects.list と storage.objects.get
    別のロケーションに再配置するバケット内のオブジェクトのリストを表示するには、これらの権限が必要です。

これらの権限は、カスタムロールで取得することもできます。また、他の事前定義ロールで取得することもできます。どのロールがどの権限に関連付けられているかを確認するには、Cloud Storage に適用される IAM のロールをご覧ください。

プロジェクトにロールを付与する手順については、プロジェクトへのアクセス権を管理するをご覧ください。

バケットを再配置する

このセクションでは、バケットの再配置を使用して Cloud Storage バケットをあるロケーションから別のロケーションに再配置するプロセスについて説明します。バケットを再配置する場合は、増分データコピー プロセスを開始してモニタリングし、最終同期ステップを開始します。これらの手順の詳細については、バケットの再配置プロセスを理解するをご覧ください。

ドライランの実行

バケットの再配置プロセス中に発生する可能性のある問題を最小限に抑えるため、ドライランを実行することをおすすめします。ドライランでは、データを移動せずにバケットの再配置プロセスをシミュレートするため、問題を早期に発見して解決できます。ドライランでは、次の非互換性が確認されます。

ドライランでは、リアルタイムのリソースの可用性などの要因により、ライブ マイグレーション中にのみ発生する問題があるため、考えられるすべての問題を特定することはできませんが、実際の再配置中に時間のかかる問題が発生するリスクを軽減できます。

コマンドライン

バケットの再配置のドライランをシミュレートします。

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

ここで

  • BUCKET_NAME は、再配置するバケットの名前です。

  • LOCATION は、バケットの宛先ロケーションです。

ドライランを開始すると、長時間実行オペレーションが開始されます。オペレーション ID とオペレーションの説明が返されます。ドライランの完了状況を追跡するには、進行状況を追跡する必要があります。ドライランの進行状況を追跡する方法については、長時間実行オペレーションの詳細を取得するをご覧ください。

ドライランで問題が見つかった場合は、増分データコピー ステップを開始する前に問題を解決します。

REST API

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセス トークンを生成できます。

  2. バケットの設定を含む JSON ファイルを作成します。この設定には、destinationLocation パラメータと validateOnly パラメータを含める必要があります。設定の全リストについては、Buckets: relocate のドキュメントをご覧ください。一般的な設定は次のとおりです。

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "true"
}

    ここで

    • DESTINATION_LOCATION は、バケットの宛先ロケーションです。
    • LOCATIONS は、構成可能なデュアルリージョンに使用するロケーション コードのリストです。
    • validateOnly はドライランを実行するために true に設定されています。

  3. cURL を使用して JSON API を呼び出します。

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    ここで

    • JSON_FILE_NAME は、作成した JSON ファイルの名前です。
    • BUCKET_NAME は、再配置するバケットの名前です。

増分データコピーを開始する

コマンドライン

バケットの再配置オペレーションを開始します。

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

ここで

  • BUCKET_NAME は、再配置するバケットの名前です。

  • LOCATION は、バケットの宛先ロケーションです。

REST API

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセス トークンを生成できます。

  2. バケットの設定を含む JSON ファイルを作成します。設定の全リストについては、Buckets: relocate のドキュメントをご覧ください。一般的な設定は次のとおりです。

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "false"
}

    ここで

    • DESTINATION_LOCATION は、バケットの宛先ロケーションです。
    • LOCATIONS は、構成可能なデュアルリージョンに使用するロケーション コードのリストです。
    • validateOnly は false に設定され、バケットの再配置の増分データコピー ステップが開始されます。

  3. cURL を使用して JSON API を呼び出します。

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    ここで

    • JSON_FILE_NAME は、作成した JSON ファイルの名前です。
    • BUCKET_NAME は、再配置するバケットの名前です。

増分データコピーをモニタリングする

バケットの再配置プロセスは長時間実行オペレーションであるため、進行状況を確認するためにモニタリングする必要があります。長時間実行オペレーションのリストを定期的に確認して、増分データコピー ステップのステータスを見ることができます。長時間実行オペレーションの詳細を取得する方法、長時間実行オペレーションのリストを表示する方法、長時間実行オペレーションをキャンセルする方法については、Cloud Storage で長時間実行オペレーションを使用するをご覧ください。

次の例は、増分データコピー オペレーションによって生成される出力を示しています。

done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
  createTime: '2024-10-21T04:26:59.666Z
  endTime: '2024-12-29T23:39:53.340Z'
  progressPercent: 99
  requestedCancellation: false
  type: relocate-bucket
  updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
  byteProgressPercent: 100
  discoveredBytes: 200
  remainingBytes: 0
  discoveredObjectCount: 10
  remainingObjectCount: 8
  objectProgressPercent: 100
  discoveredSyncCount: 8
  remainingSyncCount: 0
  syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
  '@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
  selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w

次の表は、増分データコピー オペレーションによって生成される出力のキーフィールドに関する情報を示したものです。

フィールド名 説明 設定可能な値
done バケットの再配置オペレーションの完了を示します。 true、false
kind このリソースがストレージ オペレーションを表すことを示します。
metadata オペレーションに関する情報を示します。
metadata.@type オペレーションのタイプをバケットの再配置として示します。
metadata.commonMetadata すべてのオペレーションに共通のメタデータ。
metadata.commonMetadata.createTime 長時間実行オペレーションが作成された時刻。
metadata.commonMetadata.endTime 長時間実行オペレーションが終了した時刻。
metadata.commonMetadata.progressPercent 長時間実行オペレーションの推定進行状況（パーセント）。 0～100% の値。-1 の値は、進行状況が不明または該当しないことを意味します。
metadata.commonMetadata.requestedCancellation ユーザーが長時間実行オペレーションのキャンセルをリクエストしたかどうかを示します。 true、false
metadata.commonMetadata.type 長時間実行オペレーションのタイプを示します。
metadata.commonMetadata.updateTime 長時間実行オペレーションが最後に更新された時刻。
metadata.destinationLocation バケットの宛先ロケーション。
metadata.finalizationState 最終同期ステップ開始の準備状況を示します。
  • READY: 最終同期ステップを開始できることを示します。ただし、progressPercent フィールドの値が 99 に達するまで待つことをおすすめします。
  • WAITING_ON_SYNC: 最終同期ステップを開始できないことを示します。
  • NOT_REQUIRED: このバケットでは最終同期ステップが不要であり、スキップできることを示します。
  • BLOCKED_ON_ERRORS: エラーが原因でファイナライズ ステップが一時停止されていることを示します。ステップを続行するには、エラーを解決する必要があります。
  • RUNNING: ファイナライズ ステップが進行中であることを示します。
  • FINALIZED: ファイナライズ ステップが正常に完了したことを示します。
metadata.progress 再配置オペレーションの進行状況の詳細。
metadata.progress.byteProgressPercent コピーされたバイト数の進行状況（%）。 0～100% の値。-1 の値は、進行状況が不明または該当しないことを意味します。
metadata.progress.discoveredBytes ソースバケットで検出されたバイト数。
metadata.progress.discoveredObjectCount ソースバケットで検出されたオブジェクトの数。
metadata.progress.discoveredSyncCount ソースバケットで検出されたオブジェクト メタデータの更新数。
metadata.progress.objectProgressPercent コピーされたオブジェクトの進捗状況（%）。 0～100% の値。-1 の値は、進行状況が不明または該当しないことを意味します。
metadata.progress.remainingBytes ソースバケットから宛先バケットにコピーする残りのバイト数。
metadata.progress.remainingObjectCount ソースバケットから宛先バケットにコピーする残りのオブジェクトの数。
metadata.progress.remainingSyncCount 同期する残りのオブジェクト メタデータの更新数。
metadata.progress.syncProgressPercent 同期するオブジェクト メタデータの更新の進行状況（%）。 0～100% の値。-1 の値は、進行状況が不明または該当しないことを意味します。
metadata.relocationState バケットの再配置の全体的な状態
  • SYNCING: 増分データコピー ステップで、ソースバケットから宛先バケットにオブジェクトがアクティブにコピーされていることを示します。
  • FINALIZING: ファイナライズ ステップが開始されたことを示します。
  • FAILED: 増分データコピー ステップでエラーが発生し、正常に完了しなかったことを示します。
  • SUCCEEDED: 増分データコピー ステップが正常に完了したことを示します。
  • CANCELLED: 増分データコピー ステップがキャンセルされたことを示します。
metadata.sourceLocation バケットのソース ロケーション。
metadata.validateOnly バケットの再配置のドライランが開始されたかどうかを示します。 true、false
metadata.writeDowntimeExpireTime 書き込みのダウンタイムが終了する時刻。
name この再配置オペレーションの固有識別子。
形式: projects/_/buckets/bucket-name/operations/operation-id
response オペレーションのレスポンス。
response.@type レスポンスのタイプ。
selfLink このオペレーションへのリンク。

他の Cloud Storage 機能と連携する際に、制限事項によって問題が発生する可能性があります。制限事項の詳細については、制限事項をご覧ください。

最終同期ステップを開始する

最終同期ステップでは、バケットに対して書き込みオペレーションを実行できない期間があります。最終同期ステップは、アプリケーションの中断を最小限に抑える時間にスケジュールすることをおすすめします。

続行する前に、増分データコピー プロセスをモニタリングするステップの出力で finalizationState 値を確認して、バケットが完全に準備されていることを確認します。最終同期ステップに進むには、finalizationState 値が READY である必要があります。

最終同期ステップを早期に開始すると、コマンドからエラー メッセージ The relocate bucket operation is not ready to advance to finalization running state が返されますが、再配置プロセスは続行されます。

progressPercent 値が 99 になるまで待ってから、最終同期ステップを開始することをおすすめします。

コマンドライン

finalizationState の値が READY になったら、バケットの再配置オペレーションの最終同期ステップを開始します。

gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

ここで

  • BUCKET_NAME は、再配置するバケットの名前です。
  • OPERATION_ID: 長時間実行オペレーションの ID。この ID は、呼び出したメソッドのレスポンスとして返されます。たとえば、gcloud storage operations list の呼び出しから次のレスポンスが返された場合、長時間実行オペレーション ID は AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74 です。
 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`

ttl フラグを設定すると、再配置プロセスをより細かく制御できます。例:

gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

ここで

TTL_DURATION は、再配置プロセス中の書き込みダウンタイム フェーズの有効期間（TTL）です。文字列として表されます（12 時間の場合は 12h など）。TTL_DURATION は、書き込みのダウンタイム フェーズで許容される最長時間を決定します。書き込みのダウンタイムがこの上限を超えると、再配置プロセスは自動的に増分コピーステップに戻り、バケットへの書き込みオペレーションが再度有効になります。値は 6h（6 時間）～48h（48 時間）の範囲内である必要があります。指定しない場合、デフォルト値は 12h（12 時間）です。

REST API

JSON API

  1. gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセス トークンを生成できます。

  2. バケットの再配置の設定を含む JSON ファイルを作成します。設定の全リストについては、Buckets: advanceRelocateBucket のドキュメントをご覧ください。一般的な設定は次のとおりです。

    {
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
}

    ここで

    • EXPIRE_TIME は、書き込みのダウンタイムが期限切れになる時刻です。
    • TTL_DURATION は、再配置プロセス中の書き込みダウンタイム フェーズの有効期間（TTL）です。文字列として表されます（12 時間の場合は 12h など）。TTL_DURATION は、書き込みのダウンタイム フェーズで許容される最長時間を決定します。書き込みのダウンタイムがこの上限を超えると、再配置プロセスは自動的に増分コピーステップに戻り、バケットへの書き込みオペレーションが再度有効になります。値は 6h（6 時間）～48h（48 時間）の範囲内である必要があります。指定しない場合、デフォルト値は 12h（12 時間）です。

  3. cURL を使用して JSON API を呼び出します。

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/bucket/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"

    ここで

    • JSON_FILE_NAME は、作成した JSON ファイルの名前です。
    • BUCKET_NAME は、再配置するバケットの名前です。
    • OPERATION_ID: 長時間実行オペレーションの ID。この ID は、呼び出したメソッドのレスポンスとして返されます。たとえば、Operations: list の呼び出しから次のレスポンスが返された場合、長時間実行オペレーション ID は AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74 です。

バケットの再配置プロセスを検証する

再配置を開始したら、正常に完了したことを確認します。このセクションでは、データの転送が正常に完了したことを確認する方法について説明します。

次の方法で、再配置プロセスが正常に完了したことを確認します。

  • 長時間実行オペレーションをポーリングする: バケットの再配置は長時間実行オペレーションです。operation id を使用して長時間実行オペレーションをポーリングして、オペレーションの進行状況のモニタリングし、success 状態を検証することで、オペレーションが正常に完了したことを確認できます。これには、オペレーションが完了状態に達するまで、オペレーションのステータスを定期的にクエリする必要があります。長時間実行オペレーションのモニタリングについては、Cloud Storage で長時間実行オペレーションを使用するをご覧ください。

  • Cloud Audit Logs エントリを分析する: Cloud Audit Logs は、 Google Cloud 環境のイベントとオペレーションの詳細な記録を提供します。再配置に関連付けられた Cloud Audit Logs エントリを分析して、成功を確認できます。転送中に問題の可能性を示唆するエラー、警告、予期しない動作がないかログを分析します。Cloud Audit Logs でのログの表示については、監査ログの表示をご覧ください。

    次のログエントリは、移動が成功したかどうかを判断するのに役立ちます。

    • 再配置に成功: Relocate bucket succeeded. All existing objects are now in the new placement configuration.

    • 再配置に失敗: Relocate bucket has failed. Bucket location remains unchanged.

    Pub/Sub 通知を使用して、特定の成功または失敗イベントがログに表示されたときに通知するアラートを設定することもできます。Pub/Sub 通知の設定については、Cloud Storage の Pub/Sub 通知を構成するをご覧ください。

バケットの再配置後のタスクを完了する

バケットの再配置が正常に完了したら、次の手順を完了します。

  1. 省略可: バケットのタグベースのアクセス制御を復元します。
  2. 既存のインベントリ レポートの構成は、再配置プロセス中に保持されないため、手動で再作成する必要があります。インベントリ レポート構成の作成については、インベントリ レポート構成を作成するをご覧ください。
  3. Terraform や Google Kubernetes Engine 構成コネクタなどの Infrastructure as Code 構成を更新して、バケットの新しいロケーションを指定します。
  4. リージョン エンドポイントは特定のロケーションに関連付けられているため、新しいエンドポイントを反映するようにアプリケーション コードを変更する必要があります。

失敗したバケットの再配置オペレーションを処理する方法

失敗したバケットの再配置オペレーションを処理する前に、次の要素を検討してください。

  • バケットの再配置に失敗すると、一時ファイルや不完全なデータコピーなどの古いリソースが宛先に残る可能性があります。同じ宛先への別のバケットの再配置を開始するには、7～14 日間待つ必要があります。別の宛先へのバケットの再配置は、すぐに開始できます。

  • 宛先ロケーションがデータに最適な場所でない場合は、再配置をロールバックすることをおすすめします。ただし、すぐに再配置を開始することはできません。再び再配置プロセスを開始するには、最長 14 日間の待機期間が必要です。この制限事項は、安定性を確保し、データの競合を防ぐために設けられています。

次のステップ