Storage Transfer Service エージェントは、Docker コンテナ内で実行されるアプリケーションで、Storage Transfer Service と連携してファイル システムや S3 互換ストレージに関連する転送を行います。
転送にファイル システムや S3 互換ストレージが関係しない場合は、エージェントを設定する必要はありません。
このドキュメントでは、サーバー上の転送エージェントを管理する方法について説明します。
概要
エージェント プロセスは動的です。転送の実行中にエージェントを追加し、パフォーマンスを改善できます。新しく開始したエージェントは、割り当てられたエージェント プールに参加し、既存の転送から処理を実行します。これにより、実行中のエージェントの数を調整するか、または、転送量の変化に合わせて転送のパフォーマンスを調整できます。
エージェント プロセスはフォールト トレラントな集合体です。1 つのエージェントが停止した場合でも、残りのエージェントは作業を継続します。すべてのエージェントが停止した場合、エージェントを再起動すると、エージェントが停止したところから転送が再開します。これにより、エージェントのモニタリング、転送の再試行、リカバリ ロジックの実装を回避できます。Google Kubernetes Engine でエージェントを調整することで、転送を停止せずにエージェント プールのパッチ適用、移動、動的スケーリングを行うことができます。
たとえば、2 つのエージェントの実行中に 2 つの転送を行うとします。マシンの再起動やオペレーティング システムのパッチ適用でいずれかのエージェントが停止した場合、残りのエージェントは作業を継続します。2 つの転送はまだ実行中ですが、1 つのエージェントでデータの転送が行われるため、処理が遅くなります。残りのエージェントも停止すると、実行中のエージェントがなくなるため、すべての転送が停止します。エージェント プロセスを再起動すると、転送は中断したところから再開します。
エージェント プロセスはプールに属します。データの転送を並列で行います。このため、プール内のすべてのエージェントは、転送するデータソースに対して同じアクセス権を持っている必要があります。
たとえば、特定のファイル システムからデータを転送する場合は、エージェント プールでエージェントをホストしているすべてのマシンにファイル システムをマウントする必要があります。プール内の一部のエージェントがデータソースに到達でき、その他のエージェントが到達できない場合、そのデータソースからの転送は成功しません。
準備
転送を構成する前に、ユーザーとサービス アカウントのアクセス権を構成していることを確認してください。
gcloud
コマンドを使用する場合は、gcloud CLI をインストールします。
転送エージェントをインストールして実行する
エージェント プールごとに少なくとも 3 つのエージェントを、可能であれば別々のマシンにインストールすることをおすすめします。実行するエージェントの数の決定方法については、転送エージェントのパフォーマンスを最大化するをご覧ください。
エージェント ID 接頭辞に、個人を特定できる情報(PII)やセキュリティ データなどの機密情報を含めないでください。リソース名は、他の Google Cloud リソースの名前に反映され、プロジェクト外部の Google 内部システムに公開される場合があります。転送エージェントをインストールして実行する手順は次のとおりです。
Google Cloud コンソール
Google Cloud コンソールで、[エージェント プール] ページに移動します。
新しいエージェントを追加するエージェント プールを選択します。
[エージェントをインストール] をクリックします。
表示された手順でエージェントをインストールして実行します。
エージェントのコマンドライン オプションの詳細については、エージェントのコマンドライン オプションをご覧ください。
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
フラグを使用するディレクトリ制限は適用されません。--creds-file=CREDENTIAL_FILE
には、JSON 形式のサービス アカウントの認証情報ファイルのパスを指定します。--enable_mount_directory
を使用している場合を除き、次のことを行う必要があります。-v
フラグを使用して認証情報ファイルをマウントします。--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
エージェント接続を確認する
エージェントが接続されていることを確認するには:
Google Cloud コンソールで、[エージェント プール] ページに移動します。
接続済みのエージェント数とエージェント プールが表示されます。
エージェント プールを選択すると、接続されているエージェントの詳細が表示されます。
新しいエージェントが作成時から 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 を見つけてエージェントを停止するには:
Google Cloud コンソールで、[エージェント プール] ページに移動します。
停止するエージェントが含まれるエージェント プールを選択します。
リストからエージェントを選択します。[フィルタ] フィールドを使用して、接頭辞、エージェントのステータス、エージェントの経過時間などを検索します。
[STOP AGENT] をクリックします。特定のコンテナ ID を含む
docker stop
コマンドが表示されます。エージェントが実行されているマシンでコマンドを実行します。
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 にはディレクトリの概念がないため、空のソース ディレクトリは転送されません。