エージェントプールの管理

エージェントプールは、ソースと移行先への統一されたアクセスと可視性を持つ、同じ構成を使用するエージェントの集合です。エージェントプールでは、転送の帯域幅の上限も制御できます。

すべてのエージェントはエージェントプールに属している必要があります。

このガイドでは、エージェントプールの使用方法について説明します。

始める前に

エージェントプールを操作するには、プロジェクトに対する適切な権限が必要です。詳しくは、IAM によるアクセス制御をご覧ください。

gcloud コマンドを使用するには、gcloud コマンドラインツールをインストールします。

エージェントプールの作成

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

エージェントプールを作成するには:

Google Cloud コンソール

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

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

[エージェントプール] ページが開き、既存のエージェントプールが一覧表示されます。
[別のプールを作成] をクリックします。
プールに名前を付け、必要に応じて説明を入力します。
プール全体に適用される帯域幅上限を設定できます。指定された帯域幅（MB/秒）は、プール内のすべてのエージェント間で分割されます。詳細については、ネットワーク帯域幅の管理をご覧ください。
[作成] をクリックします。

REST API

projects.agentPools.create を使用します。

POST https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools?agent_pool_id=AGENT_POOL_ID

ここで

PROJECT_ID: エージェントプールを作成するプロジェクト ID。
AGENT_POOL_ID: 作成するエージェントプール ID。

エージェントプールが Creating 状態で 30 分以上停止している場合は、エージェントプールを削除して再作成することをおすすめします。

エージェントプールが Creating 状態にあるときに、プロジェクトから必要な Storage Transfer Service の権限を取り消すと、サービスで誤った動作が発生します。

gcloud CLI

gcloud コマンドラインツールを使用してエージェントプールを作成するには、gcloud transfer agent-pools create を実行します。

gcloud transfer agent-pools create NAME \
  [--no-async] \
  [--bandwidth-limit=BANDWIDTH_LIMIT] \
  [--display-name=DISPLAY_NAME]

次のオプションがあります。

NAME は、このプールの一意の永続的な識別子です。
--no-async を使用すると、プールが作成されるまでターミナル内の他のタスクがブロックされます。指定しない場合は、プールの作成が非同期で実行されます。
--bandwidth-limit には、このプールのエージェントが利用できる帯域幅の量を MB/秒単位で定義します。帯域幅の上限はプール内のすべてのエージェントに適用されます。この上限により、プールの転送ワークロードによって、帯域幅を共有するほかのオペレーションが中断される事態を防ぐことができます。たとえば、「50」と入力すると、帯域幅の上限が 50 MB/秒に設定されます。このフラグを指定しないと、このプールのエージェントは使用可能なすべての帯域幅を使用します。
--display-name は、このプールを識別するための名前です。この名前は変更可能です。プールの一意の完全なリソース名に一致しない詳細情報を含めることもできます。

エージェントをプールに割り当てる

新しいエージェントプールは空です。エージェントを割り当てる必要があります。エージェントは、エージェントの作成時にのみ、エージェントプールに割り当てることができます。

エージェントプールが指定されていない場合、エージェントは transfer_service_default プールに割り当てられます。

エージェントを作成してプールに割り当てるには:

Google Cloud コンソール

[エージェントプール] ページで、エージェントを割り当てるプールを選択します。
[エージェントをインストール] をクリックします。エージェントインストールガイドが表示されます。
手順に沿って、このエージェントプールにエージェントを作成します。

gcloud CLI

gcloud コマンドラインツールを使用してエージェントを作成し、プールに割り当てるには、gcloud transfer agents install を実行します。エージェントは、ファイルシステムに対して root 権限を持つマシンにインストールする必要があります。

gcloud transfer agents install --pool=AGENT_POOL

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

詳細については、転送エージェントを管理するをご覧ください。

その他のオプションについては、高度なエージェントオプションをご覧ください。

エージェントを管理するには、転送エージェントの管理をご覧ください。

エージェントプールをジョブに割り当てる

エージェントプールが作成されたら、ジョブの作成または更新中に、エージェントプールをジョブに割り当てることができます。

エージェントプールの更新

エージェントプールの表示名と帯域幅上限を更新できます。

エージェントプールを更新するには:

Google Cloud コンソール

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

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

次の項目を編集できます。

エージェントプールの表示名: 現在のエージェントプール名の横にある [編集] をクリックします。
エージェントプールの帯域幅上限: [帯域幅の上限を設定] をクリックし、[帯域幅の上限を設定] ダイアログで新しい帯域幅の上限を入力します。[上限を設定] をクリックして、新しい帯域幅上限を適用します。帯域幅はプール内のすべてのエージェントで共有されます。

REST API

エージェントプールを更新するには、更新するフィールドのフィールドマスクを指定して projects.agentPools.patch を使用します。次のエージェントプールフィールドを更新できます。

たとえば、displayName を my-transfer に更新するには、フィールドマスク "displayName,my-transfer" を指定します。

表示名を更新するパッチリクエストの例を次に示します。

PATCH https://storagetransfer.googleapis.com/v1/projects/{PROJECT_ID}/agentPools/{AGENT_POOL_ID}:"displayName,NEW_NAME"

ここで

PROJECT_ID: エージェントプールを更新するプロジェクト ID。
AGENT_POOL_ID: 更新するエージェントプール ID。
NEW_NAME: このエージェントプールの新しい表示名。

次に、帯域幅上限を更新するパッチリクエストの例を示します。

PATCH https://storagetransfer.googleapis.com/v1/projects/{PROJECT_ID}/agentPools/{AGENT_POOL_ID}:"bandwidthLimit,NEW_LIMIT"

ここで

PROJECT_ID: エージェントプールを更新するプロジェクト ID。
AGENT_POOL_ID: 更新するエージェントプール ID。
NEW_LIMIT: このエージェントプールの新しい帯域幅上限。

gcloud CLI

gcloud コマンドラインツールでエージェントプールを更新するには、gcloud transfer agent-pools update を実行します。

gcloud transfer agent-pools update NAME \
  [--bandwidth-limit=NEW_BANDWIDTH_LIMIT] [--clear-bandwidth-limit] \
  [--clear-display-name] [--display-name=NEW_DISPLAY_NAME]

次の引数は必須です。

NAME は、このプールの一意の永続的な識別子です。NAME には、更新するエージェントプールを指定します。これ自体を更新することはできません。

このコマンドには、次のフラグを指定できます。

--bandwidth-limit を更新または削除するには、--clear-bandwidth-limit を指定します。帯域幅の上限の詳細については、エージェントプールの作成をご覧ください。
--display-name を更新または削除するには、--clear-display-name フラグを使用します。

エージェントプールの削除

アクティブなエージェントがなく、アクティブなジョブ実行がないエージェントプールは削除できます。

エージェントプールを削除するには:

Google Cloud コンソール

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

[エージェントプール] に移動
[削除] をクリックします。ポップアップの内容を確認し、[削除] をクリックして確定します。

削除ボタンがアクティブでない場合は、このプールに関連付けられているすべてのエージェントとジョブを停止する必要があります。

REST API

projects.agentPools.delete を使用します。

DELETE https://storagetransfer.googleapis.com/v1/{name=PROJECT_ID/*/agentPools/}

ここで

PROJECT_ID: エージェントプールを削除するプロジェクト ID。

gcloud CLI

gcloud コマンドラインツールでエージェントプールを削除するには、gcloud transfer agent-pools delete を実行します。

gcloud transfer agent-pools delete NAME

次の引数は必須です。

NAME は、このプールの一意の永続的な識別子です。

プールを削除する前に、プール内のすべてのエージェントを停止する必要があります。また、プールのジョブを無効にし、このプールに進行中の転送オペレーションがないようにする必要があります。

プールに関連付けられているすべてのジョブを表示するには、Google Cloud Console でプールを選択し、[転送ジョブ] タブをクリックします。

エージェントプールの取得

エージェントプールを取得するには:

Google Cloud コンソール

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

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

このページには、プロジェクトに関連付けられているすべてのエージェントプールのリストと、各エージェントプールの次の情報が表示されます。

エージェントプール名
接続ステータス
接続済みのエージェントの数
帯域幅の上限（設定されている場合）
関連付けられている転送ジョブの数
エージェントプールの表示名

特定のエージェントプールを表示するには、エージェントプールの [名前] をクリックします。

エージェントプールの情報ページでは、次の操作を行うことができます。

エージェントのインストール: 転送エージェントのインストール手順を表示します。
エージェントの停止: テーブルでエージェントを選択して、[STOP AGENT] をクリックします。
転送ジョブを一覧表示する: [転送ジョブ] をクリックして、このプールのエージェントが接続されている転送ジョブを表示します。

REST API

projects.agentPools.get を使用します。

GET https://storagetransfer.googleapis.com/v1/{name=PROJECT_ID/*/agentPools/}

ここで

PROJECT_ID: エージェントプールを取得するプロジェクト ID。

gcloud CLI

gcloud コマンドラインツールでエージェントプールを取得するには、gcloud transfer agent-pools describe を実行します。

gcloud transfer agent-pools describe NAME

次の引数は必須です。

NAME は、このプールの一意の永続的な識別子です。

エージェントプールの一覧表示

エージェントプールを一覧表示するには:

Google Cloud コンソール

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

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

すべてのエージェントプールが表示されます。

REST API

projects.agentPools.list を使用します。

GET https://storagetransfer.googleapis.com/v1/projects/{project_id=PROJECT_ID}/agentPools

ここで

PROJECT_ID: エージェントプールを取得するプロジェクト ID。

gcloud CLI

gcloud コマンドラインツールでエージェントプールの一覧を表示するには、gcloud transfer agent-pools list を実行します。

gcloud transfer agent-pools list \
  [--limit=LIMIT] \
  [--names=[NAMES,...]] \
  [--page-size=PAGE_SIZE]

このコマンドには、次のフラグを指定できます。

--limit は、返されるエージェントプールの最大数を定義します。
--names には、一覧表示するエージェントプールの名前を指定します。名前が複数ある場合は、--names=foo,bar のようにカンマで区切ります。指定しない場合、現在のプロジェクト内のすべてのエージェントプールが一覧表示されます。
--page-size は、このコマンドのバッチ処理の動作を定義します。list コマンドを実行すると、デフォルトでは、レスポンスが 256 アイテムごとに 1 つのバッチにまとめます。すべてのアイテムが一覧表示されるか limit に達するまで、次のバッチが自動的に取得されます。

このコマンドは、一致するエージェントプールとその構成の詳細のリストを返します。次の例は、レスポンスの例を示しています。

name: projects/my-project-123/agentPools/my-first-pool
state: CREATED
---
bandwidthLimit:
  limitMbps: '120'
displayName: Source A to destination Z.
name: projects/my-project-123/agentPools/a2z-pool
state: CREATED

エージェント プールの管理

始める前に

エージェント プールの作成

Google Cloud コンソール

REST API

gcloud CLI

エージェントをプールに割り当てる

Google Cloud コンソール

gcloud CLI

エージェント プールをジョブに割り当てる

エージェント プールの更新

Google Cloud コンソール

REST API

gcloud CLI

エージェント プールの削除

Google Cloud コンソール

REST API

gcloud CLI

エージェント プールの取得

Google Cloud コンソール

REST API

gcloud CLI

エージェント プールの一覧表示

Google Cloud コンソール

REST API

gcloud CLI

エージェントプールの管理

エージェントプールの作成

エージェントプールをジョブに割り当てる

エージェントプールの更新

エージェントプールの削除

エージェントプールの取得

エージェントプールの一覧表示