転送エージェントを管理する

Storage Transfer Service エージェントは、Docker コンテナ内で実行されるアプリケーションで、Storage Transfer Service と連携してファイル システムや S3 互換ストレージに関連する転送を行います。

転送にファイル システムや S3 互換ストレージが関係しない場合は、エージェントを設定する必要はありません。

Amazon S3 からの転送には、エージェントは必要ありません。S3 互換ストレージとは、S3 API を使用しているものの、Amazon で直接ホストされていないストレージ システムのことです。

このドキュメントでは、サーバー上の転送エージェントを管理する方法について説明します。

概要

• エージェント プロセスは動的です。転送の実行中にエージェントを追加し、パフォーマンスを改善できます。新しく開始したエージェントは、割り当てられたエージェント プールに参加し、既存の転送から処理を実行します。これにより、実行中のエージェントの数を調整するか、または、転送量の変化に合わせて転送のパフォーマンスを調整できます。

• エージェント プロセスはフォールト トレラントな集合体です。1 つのエージェントが停止した場合でも、残りのエージェントは作業を継続します。すべてのエージェントが停止した場合、エージェントを再起動すると、エージェントが停止したところから転送が再開します。これにより、エージェントのモニタリング、転送の再試行、リカバリ ロジックの実装を回避できます。Google Kubernetes Engine でエージェントを調整することで、転送を停止せずにエージェント プールのパッチ適用、移動、動的スケーリングを行うことができます。

  たとえば、2 つのエージェントの実行中に 2 つの転送を行うとします。マシンの再起動やオペレーティング システムのパッチ適用でいずれかのエージェントが停止した場合、残りのエージェントは作業を継続します。2 つの転送はまだ実行中ですが、1 つのエージェントでデータの転送が行われるため、処理が遅くなります。残りのエージェントも停止すると、実行中のエージェントがなくなるため、すべての転送が停止します。エージェント プロセスを再起動すると、転送は中断したところから再開します。

• エージェント プロセスはプールに属します。データの転送を並列で行います。このため、プール内のすべてのエージェントは、転送するデータソースに対して同じアクセス権を持っている必要があります。

  たとえば、特定のファイル システムからデータを転送する場合は、エージェント プールでエージェントをホストしているすべてのマシンにファイル システムをマウントする必要があります。プール内の一部のエージェントがデータソースに到達でき、その他のエージェントが到達できない場合、そのデータソースからの転送は成功しません。

準備

転送を構成する前に、ユーザーとサービス アカウントのアクセス権を構成していることを確認してください。

gcloud コマンドを使用する場合は、gcloud CLI をインストールします。

転送エージェントをインストールして実行する

重要: 転送ジョブを作成できるユーザーは、エージェントからアクセス可能な任意のファイル システム ディレクトリに対してデータの取得やダウンロードを行うことができます。エージェントが root として実行され、ファイル システム全体にアクセスできる場合、悪意のある操作者がホストを乗っ取るおそれがあります。必要なディレクトリのみにエージェントのアクセスを制限することを強くおすすめします。

エージェント プールごとに少なくとも 3 つのエージェントを、可能であれば別々のマシンにインストールすることをおすすめします。実行するエージェントの数の決定方法については、転送エージェントのパフォーマンスを最大化するをご覧ください。

エージェント ID 接頭辞に、個人を特定できる情報（PII）やセキュリティ データなどの機密情報を含めないでください。リソース名は、他の Google Cloud リソースの名前に反映され、プロジェクト外部の Google 内部システムに公開される場合があります。

転送エージェントをインストールして実行する手順は次のとおりです。

2023 年 4 月 12 日: S3 互換ストレージからの転送に使用するエージェントは、サービス アカウント キーで認証する必要があります。--creds-file フラグを使用して、サービス アカウント キー ファイルのパスを指定します。サービス アカウントを使用しないと転送が停止します。ジョブは進行中と表示されますが、データは転送されません。

問題が解決されると、この通知は削除されます。

Google Cloud コンソール

1. Google Cloud コンソールで、[エージェント プール] ページに移動します。

   [エージェント プール] に移動

2. 新しいエージェントを追加するエージェント プールを選択します。

3. [エージェントをインストール] をクリックします。

4. 表示された手順でエージェントをインストールして実行します。

   エージェントのコマンドライン オプションの詳細については、エージェントのコマンドライン オプションをご覧ください。

gcloud CLI

gcloud CLI を使用して 1 つ以上のエージェントをインストールするには、gcloud transfer agents install を実行します。

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

手順に沿って、エージェントのインストール手順を確認します。このコマンドを実行すると、POOL_NAME として指定したプール名にマッピングされた NUM_AGENTS エージェントがマシンにインストールされ、gcloud 認証情報を使用してエージェントが認証されます。存在するプール名を使用する必要があります。存在しない場合、エラーが返されます。

--mount-directories フラグは省略可能ですが、使用することを強くおすすめします。この値は、エージェントにアクセス権を付与するファイル システム上のディレクトリのカンマ区切りのリストです。このフラグを省略すると、ファイル システム全体がエージェント コンテナにマウントされます。詳細については、gcloud のリファレンスをご覧ください。

S3 互換ソース

S3 互換ソースで使用するエージェントをインストールするには、アクセス認証情報を環境変数として AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY の値として指定するか、システム構成ファイルのデフォルトの認証情報として保存します。

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

サービス アカウント キーを使用する

注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

サービス アカウント キーを使用してエージェントを実行するには、--creds-file オプションを使用します。

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

詳細

省略可能なフラグの一覧については、gcloud transfer agents install --help を実行するか、gcloud transfer リファレンスをご覧ください。

docker run

docker run を使用してエージェントをインストールする前に、手順に沿って Docker をインストールしてください。

docker run コマンドにより、1 つのエージェントがインストールされます。プール内のエージェント数を増やすには、このコマンドを必要な回数だけ再実行します。

エージェントのインストール時に、gcloud のデフォルト認証情報またはサービス アカウントのいずれかを選択して認証に使用できます。

デフォルトの認証情報

Docker コンテナを gcloud のデフォルト認証情報で認証できるようにするには、次のコマンドを実行してアプリケーションのデフォルト認証情報のファイルを含む Docker ボリュームを作成します。

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

次のコマンドを使用してエージェントをインストールします。--volumes-from フラグを使用して gcloud-config 認証情報ボリュームをマウントします。

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

サービス アカウントの認証

サービス アカウントの認証情報を使用して、転送エージェント docker run をインストールして実行するには、--creds-file フラグを使用して、JSON 形式のサービス アカウント キーのパスを指定します。

パスの先頭に文字列 /transfer_root を付ける必要があります。

サービス アカウント キーの詳細については、サービス アカウント キーの作成と管理をご覧ください。

注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

オプションとフラグ

上記の例の変数を次の情報に置き換えます。

• HOST_DIRECTORY は、コピー元のホストマシン上のディレクトリです。複数の -v フラグを使用して、コピー元のディレクトリをさらに指定できます。
• CONTAINER_DIRECTORY は、エージェント コンテナ内でマッピングされたディレクトリです。HOST_DIRECTORY と同じにする必要があります。
• PROJECT_ID は、転送をホストしているプロジェクト ID です。
• POOL_NAME は、このエージェントをインストールするエージェント プールの名前です。このフラグを省略すると、エージェントはプロジェクトの transfer_service_default プールにインストールされます。

docker run コマンドは、追加のフラグをサポートします。

• --enable-mount-directory は、ファイル システム全体をコンテナの /transfer_root ディレクトリにマウントします。--enable-mount-directory を指定した場合、-v フラグを使用するディレクトリ制限は適用されません。

  注意: エージェントが root として実行され、ファイル システム全体にアクセスできる場合、悪意のある人物がホストを乗っ取るおそれがあります。必要なディレクトリのみにエージェントのアクセスを制限することを強くおすすめします。

• --creds-file=CREDENTIAL_FILE には、JSON 形式のサービス アカウントの認証情報ファイルのパスを指定します。--enable_mount_directory を使用している場合を除き、次のことを行う必要があります。

  1. -v フラグを使用して認証情報ファイルをマウントします。
  2. --creds-fileへのパスへの接頭辞を /transfer_root で指定します。

  例:

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3 は、このエージェントが S3 互換ストレージからの転送用であることを指定します。このオプションを使用してインストールされたエージェントは、POSIX ファイル システムからの転送には使用できません。

• AWS S3 または S3 互換ストレージから転送する場合は、環境変数を使用してアクセスキー ID と秘密鍵を渡します。

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY には、ネットワークの転送プロキシを指定します。PROXY の値は、プロキシ サーバーの HTTP URL とポートです。TLS 暗号化で二重ラップ リクエストを回避するため、HTTPS URL ではなく、HTTP URL を指定します。二重ラップ リクエストが発生すると、プロキシ サーバーから有効な送信リクエストが送信できなくなります。

• --agent-id-prefix=ID_PREFIX はエージェント ID の先頭に追加されるオプションの接頭辞で、Google Cloud Console でエージェントやそのマシンを識別するために使用します。接頭辞を使用する場合、エージェント ID は prefix + hostname + Docker container ID の形式になります。

• --log-dir=LOGS_DIRECTORY では、エージェントがログを書き込むディレクトリを変更します。デフォルトのディレクトリは /tmp/ です。

  --enable_mount_directory を指定していない場合は、このパスの前に /transfer_root を付ける必要があります。例: /transfer_root/logs。

• --max-physical-mem=MAX_MEMORY: エージェントは、デフォルトで最大 8 GiB のシステムメモリを使用します。このデフォルトが環境に合わない場合は、適切な最大メモリ使用量を次の形式で指定できます。

  max-physical-mem 値	最大メモリ設定
  6g	6 GB
  6gb	6 GB
  6GiB	6 GiB

エージェント接続を確認する

エージェントが接続されていることを確認するには:

1. Google Cloud コンソールで、[エージェント プール] ページに移動します。

   [エージェント プール] に移動

   接続済みのエージェント数とエージェント プールが表示されます。

2. エージェント プールを選択すると、接続されているエージェントの詳細が表示されます。

新しいエージェントが作成時から 10 分以内にエージェント プールページに表示されない場合は、エージェントが接続されていないをご覧ください。

エージェントのアクティビティをモニタリングする

Cloud Monitoring アラートを使用して、エージェント アクティビティをモニタリングできます。

Monitoring は project、agent_pool、agent_id の各ディメンションとともに利用できます。

このモニタリング データを使用して、潜在的な転送の問題を通知するアラートを設定できます。これを行うには、次のいずれかの Google Cloud 指標でアラートを作成します。

指標名	説明	おすすめの使用例
storagetransfer.googleapis.com/agent/transferred_bytes_count	ある時点で、特定のエージェントが（サービスを提供するすべてのジョブ間で）データを移動する速度を測定します。	パフォーマンスの低下を通知するアラート。
storagetransfer.googleapis.com/agent/connected	ブール値。Google Cloud が最近ハートビート メッセージを受信したエージェントに True が表示されます。	エージェントの問題を警告する。 適切なパフォーマンスを得るために必要と考えられるエージェントの数を下回った場合に通知する。 エージェント マシンの問題を通知する。

エージェントを停止する

エージェントを停止するには、エージェントの Docker コンテナ ID で docker stop を実行します。ID を見つけてエージェントを停止するには:

1. Google Cloud コンソールで、[エージェント プール] ページに移動します。

   [エージェント プール] に移動

2. 停止するエージェントが含まれるエージェント プールを選択します。

3. リストからエージェントを選択します。[フィルタ] フィールドを使用して、接頭辞、エージェントのステータス、エージェントの経過時間などを検索します。

4. [STOP AGENT] をクリックします。特定のコンテナ ID を含む docker stop コマンドが表示されます。

5. エージェントが実行されているマシンでコマンドを実行します。docker stop コマンドが成功すると、コンテナ ID が返されます。

停止したエージェントは、エージェント プールリストで「切断済み」と表示されます。

エージェントを削除する

特定のエージェントを削除するには、マシンで実行されているエージェントを一覧表示します。

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

次に、エージェント ID を transfer agents delete に渡します。

gcloud transfer agents delete --ids=id1,id2,…

マシンで実行されているすべてのエージェントを削除するには、--all フラグまたは --uninstall フラグを使用します。どちらのフラグもマシン上のすべてのエージェントを削除します。--uninstall フラグを指定すると、エージェントの Docker イメージもアンインストールされます。

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

ファイル システム転送の詳細

増分転送

Storage Transfer Service は、転送元と転送先に存在するデータを計算し、最後の転送以降に作成、更新、削除された転送元ファイルを判別してから、すべての転送を開始します。これは、マシンから送信されるデータの量を減らして帯域幅を効率的に使用し、転送時間を短縮するためです。

ファイルが変更されたかどうかを検出するために、転送元ファイルの最終更新日時、サイズを確認し、そのファイルを最後にコピーしたときに記録した最終更新日時、サイズと比較します。新しいファイルや変更されたファイルを検出すると、ファイル全体を転送先にコピーします。ファイルの鮮度の詳細については、データの整合性の詳細をご覧ください。

デフォルトでは、転送元で削除されたファイルを検出しますが、処理は行いません。作成または編集時に同期オプション [ソースにない宛先ファイルを削除します] が選択された場合は、転送時に転送先の対応するオブジェクトを削除します。

同期オプション [ソースにない宛先ファイルを削除します] が選択された場合は、ソースで誤って削除されたファイルは転送先でも削除されます。誤って削除してデータを損失しないように、このオプションを使用する場合は、転送先バケットでオブジェクトのバージョニングを有効にすることをおすすめします。これにより、誤ってファイルを削除した場合に Cloud Storage のオブジェクトを古いバージョンで復元できます。

データの整合性の詳細

正常な転送オペレーションでは、オペレーションの全実行時間を通して存在し、変更されなかったすべての転送元ファイルが転送されます。転送中に作成、更新、削除された転送元ファイルについては、それらの変更が転送先のデータに反映される場合とされない場合があります。

Storage Transfer Service は、ファイルの最終更新日時とサイズを使用して、ファイルが変更されているかどうかを判断します。最終更新日時やサイズを変更せずにファイルが変更され、delete-objects-from-source オプションが有効になっている場合、その変更によるデータが失われる可能性があります。

delete-objects-from-source 機能を使用する場合は、データの損失を防ぐために、転送期間中にソースへの書き込みをフリーズすることを強くおすすめします。

ソースへの書き込みをフリーズするには、次のいずれかを行います。

• 転送するディレクトリのクローンを作成し、クローンを作成したディレクトリを転送のソースとして使用します。
• ソース ディレクトリに書き込むアプリケーションを停止します。

転送中に発生した変更をキャプチャする必要がある場合は、転送を再実行するか、オペレーションの実行中に転送元のファイル システムを読み取り専用に設定します。

Cloud Storage にはディレクトリの概念がないため、空のソース ディレクトリは転送されません。

重要: ソースデータを削除する前に、転送が正常に行われたことを確認することを強くおすすめします。このサービスには、Cloud Storage にデータを復元する機能はありません。