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

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

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

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

始める前に

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

現在の権限を表示できます。

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

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

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

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

Google Cloud コンソール

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

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

    [エージェント プール] ページが開き、既存のエージェント プールが一覧表示されます。

  2. [別のプールを作成] をクリックします。

  3. プールに名前を付け、必要に応じて説明を入力します。

  4. プール全体に適用される帯域幅上限を設定できます。指定された帯域幅（MB/秒）は、プール内のすべてのエージェント間で分割されます。詳細については、ネットワーク帯域幅の管理をご覧ください。

  5. [作成] をクリックします。

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 AGENT_POOL

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

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

  • --no-async を使用すると、プールが作成されるまでターミナル内の他のタスクがブロックされます。指定しない場合は、プールの作成が非同期で実行されます。

  • --bandwidth-limit には、このプールのエージェントが利用できる帯域幅の量を MB/秒単位で定義します。帯域幅の上限はプール内のすべてのエージェントに適用されます。この上限により、プールの転送ワークロードによって、帯域幅を共有するほかのオペレーションが中断される事態を防ぐことができます。たとえば、「50」と入力すると、帯域幅の上限が 50 MB/秒に設定されます。このフラグを指定しないと、このプールのエージェントは使用可能なすべての帯域幅を使用します。

  • --display-name は、このプールを識別するための名前です。この名前は変更可能です。プールの一意の完全なリソース名に一致しない詳細情報を含めることもできます。

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

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

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

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

Google Cloud コンソール

  1. [エージェント プール] ページで、エージェントを割り当てるプールを選択します。

  2. [エージェントをインストール] をクリックします。エージェント インストール ガイドが表示されます。

  3. 手順に沿って、このエージェント プールにエージェントを作成します。

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=AGENT_POOL

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

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

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

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

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

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

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

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

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:"displayName,NEW_DISPLAY_NAME"

ここで

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

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

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

ここで

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

gcloud CLI

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

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

次の引数は必須です。

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

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

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

  • --display-name を更新または削除するには、--clear-display-name フラグを使用します。

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

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

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

Google Cloud コンソール

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

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

  2. [削除] をクリックします。ポップアップの内容を確認し、[削除] をクリックして確定します。

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

REST API

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

DELETE https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

ここで

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

gcloud CLI

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

gcloud transfer agent-pools delete AGENT_POOL

次の引数は必須です。

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

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

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

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

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

Google Cloud コンソール

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

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

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

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

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

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

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

REST API

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

GET https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

ここで

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

gcloud CLI

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

gcloud transfer agent-pools describe AGENT_POOL

次の引数は必須です。

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

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

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

Google Cloud コンソール

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

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

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

REST API

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

GET https://storagetransfer.googleapis.com/v1/projects/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