ファイル システム転送のトラブルシューティング

このドキュメントでは、転送とエージェントに関する問題のトラブルシューティングと解決方法について説明します。また、問題のトラブルシューティングに役立つエージェント ログを探す方法も説明します。

エラー

次の表に、転送エラー メッセージとその解決方法を示します。

エラー メッセージ エラーの種類 エラーの意味 エラーの解決方法
Modified during transfer FILE_MODIFIED_FAILURE Storage Transfer Service がソースファイルをコピーを試みるたびに、転送中にソースファイルが変更されました。 次の Storage Transfer Service オペレーションが実行されている間は、指定したファイルに書き込まないようにします。
Failed to transfer PRECONDITION_FAILURE Storage Transfer Service がファイルをアップロードするたびに、ソースファイルに関連付けられた Cloud Storage オブジェクトが変更されます。 転送ジョブを作成するときに一意の Cloud Storage オブジェクト接頭辞を使用し、複数の転送ジョブで同じファイルを同じ Cloud Storage バケットに書き込まないようにします。
Source directory not found SOURCE_DIR_NOT_FOUND 指定されたソースパスが正しくありません。また、正しいパスを指定していても、一部のエージェントがパスにアクセスできない場合があります。 転送ジョブの構成で次のことを確認します。
Could not find the job's source or destination directory ROOT_DIR_NOT_FOUND 指定されたソース/宛先のパスが正しくありません。また、正しいパスを指定していても、一部のエージェントがパスにアクセスできない場合があります。 転送ジョブの構成で次のことを確認します。
ファイルが見つかりません FILE_NOT_FOUND_FAILURE ソースファイルが見つかりましたが、Cloud Storage に転送される前に削除されました。 ファイルが誤って削除された場合は、ファイルを復元し、次の転送ジョブでアップロードできるようにします。
Failed to find the destination bucket BUCKET_NOT_FOUND 転送先バケットが Cloud Storage に存在しません。 転送先バケットのスペルが正しいことと、転送先バケットが存在することを確認します。
Failed to find an internal metadata object METADATA_OBJECT_
NOT_FOUND_FAILURE
Storage Transfer Service は、接頭辞 storage-transfer を付けてメタデータを転送先バケットに保存します。対応する転送オペレーションが完了する前にメタデータ ファイルが削除されると、このエラーが表示されます。 すべての転送ジョブが完了するまで、転送先バケット内にある接頭辞が storage-transfer/ のオブジェクトは削除しないでください。
Failed due to invalid file name INVALID_FILE_NAME ソースファイルのパスが無効です。 指定したファイルパスを確認して修正します。パスに Cloud Storage でサポートされている文字が使用されていることを確認します。
Failed due to invalid storage class INVALID_FILE_STORAGE_CLASS 指定されたソースのストレージ クラスでは読み取りができません。 クラウド プロバイダのドキュメントを参照して、データをコピーできるストレージ クラスにデータを格納する方法を確認します。
Failed due to invalid resumable upload session URI SESSION_URI_INVALID 再開可能なアップロードの ID またはセッション URI が期限切れか、キャンセルされました。 失敗は正しく再試行されていません。サポートにお問い合わせください。
Failed due to invalid file size INVALID_FILE_SIZE ファイルサイズが無効です。 Cloud Storage に転送するファイルのサイズが 0 以上 5 TiB(最大 Cloud Storage オブジェクト サイズ)以下であることを確認します。
Failed due to permissions PERMISSION_FAILURE と UNAUTHENTICATED オペレーションの実行に必要な権限が転送エージェントにありませんでした。このエラーには 2 つの可能性があります。
  • エージェントに十分な Google Cloud 権限がない。
  • ソース ファイルシステムの権限が不十分なため、エージェントがファイルまたはディレクトリを読み取れない。

以下を確認してください。

Object is subject to bucket's retention policy and cannot be deleted, overwritten or archived PERMISSION_FAILURE バケットに保持ポリシーがあり、オブジェクトがすでにバケットに存在します。Storage Transfer Service は、バケット内の既存のオブジェクトを上書きできません。このエラーは、ソースでファイルが変更された場合、またはネットワークの状態が原因で Storage Transfer Service がアップロードを 2 回試行し、最初のアップロードが成功した場合に表示されます。 Cloud Storage バケット内のデータが、想定どおりの内容であることを確認します。ジョブを再実行してエラーがないことを確認することで、ソースファイルのサイズと修正時間(mtime)が Cloud Storage オブジェクトの対応するものと一致することを確認できます。
Service lacked sufficient permissions SERVICE_PERMISSION_FAILURE オペレーションの実行に必要な権限が Storage Transfer Service にありません。 Storage Transfer Service は、Google が管理するサービス アカウント(通常、project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com の形式)を使用してリソースにアクセスします。特定の PROJECT_NUMBER を確認するには、googleserviceaccounts.get API 呼び出しを使用します。サービス アカウントに次のロールがあることを確認します。
  • プロジェクトに対する roles/storagetransfer.serviceAgent
  • すべての転送先バケットに対する roles/storage.admin
Agent unsupported AGENT_UNSUPPORTED_VERSION エージェントのバージョンが Storage Transfer Service と互換性がありません。 これは一時的なエラーです。エージェントの更新の不備が原因で発生しています。この場合は、次のように対応します。
  1. すべてのエージェントを停止します
  2. sudo docker pull gcr.io/cloud-ingest/tsop-agent を実行して、最新の Docker イメージを pull します。
  3. Docker run コマンドを発行して、すべてのエージェント コンテナを起動します。
問題が解決しない場合は、サポートチームにお問い合わせください。
Failed due to hash mismatch HASH_MISMATCH_FAILURE Storage Transfer Service がこのファイルのアップロードを試みたときに、アップロードされたバイト数が破損しました。これにより、オンプレミス ファイルのハッシュが Cloud Storage オブジェクトのハッシュと一致しません。 このエラーは、さまざまな問題が原因で発生する可能性があります。大量の転送でハッシュ不一致エラーの割合が低い場合(1% 未満)は、失敗したファイルを再試行します。ハッシュ不一致エラーの割合が高い場合(1% 以上)は、エージェント マシンのメモリ、CPU、その他のハードウェア障害の可能性について調査することをおすすめします。
Failed due to an unsupported file mode UNSUPPORTED_FILE_MODE Storage Transfer Service が、サポートされていないモードのファイル(デバイス、ソケット、名前付きパイプ、異常なファイルなど)を検出しました。 これらの特殊なファイル形式をソース ディレクトリから削除します。
Failed due to an error in the filesystem FILESYSTEM_ERROR 読み取り、シーク、統計などのファイルシステム オペレーションを実行したときに、エージェントがファイルシステムまたはオペレーティング システムのエラーを検出しました。 エラーの説明を確認し、エラーが発生したファイルシステム オペレーションを特定します。オンプレミス エージェントがファイル システムにアクセスし、基本的なファイル オペレーションに応答できるようにします。
不明なエラーにより失敗しました UNKNOWN_FAILURE 予期しないエラーが発生しました。 障害の説明を読みます。障害の説明に、問題解決に必要な情報が記載されていない場合は、サポートにお問い合わせください。
無効な仕様のため失敗しました INVALID_SPEC 破損した内部仕様をエージェントが受信しました。 エージェントのホストでデータ破損を確認し、見つからない場合は、サポートまでお問い合わせください。
Failed due to an empty or invalid manifest file CONFORMANCE_FAILURE フォーマットまたは CSV エントリが無効であるため、エージェントは有効な CSV バイトの読み取りや取得ができません。 マニフェスト エントリが有効なファイルパスであることを確認します。障害の説明に、問題解決に必要な情報が記載されていない場合は、サポートにお問い合わせください。
Falling back to resumable uploads instead of multipart uploads due to permission denied error PERMISSION_FAILURE この転送ではマルチパート アップロードが有効になっていますが、バケットに正しい権限が設定されていません。 必要な権限については、ファイル システムの権限マルチパート アップロードをご覧ください。

エージェント ログの表示

エージェント ログにはエージェント プロセスに関連する情報が記録されています。この情報は、エージェントの接続に関する問題のトラブルシューティングに役立ちます。Google Cloud Console でエージェントが接続済みと表示されていて、転送に失敗する場合は、エラーの表示で転送エラーのサンプルをご確認ください。転送中に Storage Transfer Service が処理したすべてのファイルが記録されているログを表示するには、転送ログの表示をご覧ください。

デフォルトでは、エージェント ログは /tmp に保存されます。保存場所を変更するには、--log-dir=logs-directory コマンドライン オプションを使用します。

ログの名前は次のとおりです。

agent.hostname.username.log.log-level.timestamp

ここで

  • hostname - エージェントが実行されているホスト名。
  • username - エージェントを実行しているユーザー名。
  • log-level は次のいずれかです。
    • INFO - 情報メッセージ。
    • ERROR - 転送中にエラーが発生しましたが、転送ジョブを続行できます。
    • FATAL - 転送ジョブの続行を妨げるエラーが発生しました。
  • timestamp - YYYYMMDD-hhmmss.thread-id 形式のタイムスタンプ。

logs ディレクトリには、各優先レベルの最新ログへのシンボリック リンクが含まれています。

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

転送速度が遅い

データの転送に時間がかかる場合は、次の点をご確認ください。

  1. ファイル システムの読み取りスループットは、目的のアップロード速度の約 1.5 倍にしてください。FIO を使用して、ファイル システムの読み取りスループットをテストできます。

    fio をインストールします。

     sudo apt install -y fio
     

    新しい fiotest ディレクトリを作成します。

     TEST_DIR=/mnt/mnt_dir/fiotest
     sudo mkdir -p $TEST_DIR
     

    読み取りスループットをテストします。

     sudo fio --directory=$TEST_DIR --direct=1
        --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
        --time_based=1 --runtime=180 --name=read_test --size=1G
     

    上記のコマンドを実行すると、Fio はレポートを生成します。「bw」というラベルの付いた行は、すべてのスレッドの集約帯域幅の合計を表し、読み取りスループットのプロキシとして使用できます。

  2. iPerf3 を使用して、Storage Transfer Service で利用可能なインターネット帯域幅を確認します。

  3. 各転送エージェントに、少なくとも 4 個の vCPU と 8 GB の RAM があることを確認します。

上記の条件を満たしていても転送時間が長い場合は、エージェントを追加して、データのファイル システムへの同時接続数を増やすことができます。

転送エージェントのパフォーマンスを最大化する方法については、エージェントのベスト プラクティスをご覧ください。

エージェント エラーのトラブルシューティング

以降のセクションでは、転送エージェントのエラーのトラブルシューティングと解決方法について説明します。

エージェントが接続されていない

転送エージェントが Google Cloud コンソールで接続済みとして表示されない場合:

  1. エージェントが Cloud Storage API に接続できることを確認します。

    1. 転送エージェントと同じマシンから次のコマンドを実行して、エージェントと Cloud Storage API との接続をテストします。

      gcloud storage cp test.txt gs://my-bucket

      以下のように置き換えます。

      my-bucket: Cloud Storage バケットの名前。

  2. プロジェクトで VPC Service Controls を使用している場合は、エージェント ログを表示してエラーを確認します。VPC Service Controls の構成に誤りがあると、INFO エージェント ログに次のエラーが記録されます。

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    この出力で:

エージェントは接続されているがジョブが失敗する

エージェントが接続済みとして表示されていても転送ジョブが失敗する場合は、失敗したジョブのエラーの詳細を確認します。

プロキシが IP アドレスを拒否する

Squid などのプロキシの背後で実行していて、許可リストを使用している場合、ホスト名の代わりに IP アドレスが使用されているためにリクエストが拒否されることがあります。

この問題を解決するには、docker run コマンドを使用してエージェントを実行し、次のフラグを追加します。

--transfer-service-endpoint=storagetransfer.googleapis.com:443

別のエンドポイントを使用して googleapis.com に到達する場合は(Private Service Connect など)、googleapis.com を代替エンドポイントに置き換えます。