Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

REST API を使用して Filestore エージェントボリュームを作成、管理する

独自のオーケストレーションプラットフォーム、VM ベースのサンドボックス、または Google Kubernetes Engine（GKE）以外のコンテナ環境で Filestore エージェントボリュームを使用する場合は、Filestore REST API を使用して、ボリュームプール内の個々のボリュームを直接プロビジョニングして管理できます。

始める前に

Filestore エージェントボリュームを設定するで、初期プロジェクトと Private Service Connect（PSC）ネットワーキングの設定を完了します。
ボリュームプールを作成して管理するでリージョンボリュームプールを作成する。

ボリュームを作成

REST API

ボリュームプール内に個別のボリュームをプロビジョニングするには、volumes.create エンドポイントに HTTP POST リクエストを送信します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes?volumeId=VOLUME_ID" \
  -d '{
    "description": "Dynamic tool scratchpad for Agent Worker 12",
    "labels": {
      "agent_id": "worker-12",
      "workflow": "code_eval"
    }
  }'

次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト ID。
LOCATION: 親ボリュームプールを含むリージョン（us-central1 など）。
VOLUME_POOL_ID: 親ボリュームプールの識別子。
VOLUME_ID: ボリュームの識別子。^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ と一致します。

ボリュームのプロビジョニングは 1 ～ 2 秒で完了します。API は Volume リソースを直接返します。ボリュームの作成時に、カスタムボリューム割り当て（quotaMib）と動的 NFS エクスポートオプション（ipAcls）を指定することもできます。

{
  "name": "projects/my-project/locations/us-central1/volumePools/my-volume-pool/volumes/my-volume",
  "description": "Dynamic tool scratchpad for Agent Worker 12",
  "mountPoint": {
    "ipAddress": "10.128.0.45",
    "mountName": "my_volume"
  }
}

mountPoint 内に返される値に注意してください。

ipAddress: VPC ネットワーク内の NFS マウントエンドポイントの内部 IP アドレス。
mountName: マウントする NFS エクスポートパスコンポーネント。

ボリュームをマウントする

ボリュームをプロビジョニングすると、オーケストレーターは、同じ VPC ネットワークに接続されているクライアント VM またはコンテナホストにボリュームの NFSv3 エクスポートを直接マウントできます。

NFS クライアントユーティリティがホストにインストールされていることを確認します（Debian または Ubuntu の nfs-common など）。
マウントディレクトリを作成し、ボリュームの mountPoint で返された ipAddress と mountName を使用してボリュームをマウントします。
```
sudo mkdir -p MOUNT_DIR
sudo mount -t nfs -o vers=3,proto=tcp,mountproto=tcp,port=2049,mountport=2050 \
    IP_ADDRESS:/MOUNT_NAME MOUNT_DIR
```
次のように置き換えます。
- MOUNT_DIR: ボリュームがマウントされているローカルディレクトリのパス（/workspace など）。
- IP_ADDRESS: ボリュームの作成時または取得時に返される mountPoint.ipAddress 値。
- MOUNT_NAME: ボリュームの作成時または取得時に返される mountPoint.mountName 値。

ボリュームを管理する

REST API

次の各リクエストで、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクト ID。
LOCATION: 親ボリュームプールを含むリージョン。
VOLUME_POOL_ID: 親ボリュームプールの識別子。
VOLUME_ID: ボリュームの識別子。

ボリュームの詳細を取得する

既存のボリュームの詳細（mountPoint や現在のライフサイクル state など）を表示するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

プール内のボリュームを一覧表示する

ボリュームプールにプロビジョニングされたすべてのボリュームを一覧表示するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes"

ボリューム割り当てを更新する

アクティブなボリュームの保存容量を増やすには、updateMask=quotaMib を指定して HTTP PATCH リクエストを送信します。ボリューム割り当ては増やすことのみ可能です。ボリューム割り当ての削減はサポートされていません。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "quotaMib": 4096
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=quotaMib"

ボリューム IP ACL を更新する

NFS アクセスを特定のサンドボックスクライアント IP アドレスに制限するか、IP エクスポートルールを更新するには、updateMask=ipAcls を指定して HTTP PATCH リクエストを送信します。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.50/32"],
        "accessMode": "READ_WRITE"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=ipAcls"

ボリュームを削除する

エージェントセッションが終了するか、エフェメラルサンドボックスが終了したら、ボリュームを削除してプール内の割り当てを再利用します。

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

ボリュームスナップショットを使用してワークスペースのクローンを作成する

READY 状態のボリュームプールと HOT 状態の既存のソースボリュームがすでにある場合は、ボリュームスナップショットを作成して、エージェントボリュームの特定時点の状態をキャプチャできます。これにより、後でワークスペースのクローンを作成したり、ブランチを作成したりできます。

REST API

ボリュームスナップショットを作成する

sourceVolume フィールドにボリュームの完全なリソース名を指定し、SNAPSHOT_ID をスナップショットの固有識別子に置き換えて、HTTP POST リクエストを backups.create エンドポイントに送信します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVolume": "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID",
    "description": "Baseline workspace snapshot"
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups?backupId=SNAPSHOT_ID"

リクエストは長時間実行オペレーション（LRO）を返します。オペレーションをポーリングするか、state が READY になるまでスナップショットリソースをクエリしてから、ボリュームのクローンを作成します。
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID"
```

スナップショットからボリュームのクローンを作成する

スナップショットからボリュームのクローンを作成するには、ソーススナップショットが同じボリュームプール内のボリュームから作成されている必要があります。

HTTP POST リクエストを volumes:createFromSource エンドポイントに送信します。リクエスト本文で ipAcls を渡して、エクスポート権限を構成し、HOT ティアでクローン作成されたボリュームを有効にします。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "backup": "projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID",
    "volumeId": "CLONED_VOLUME_ID",
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.0/24"],
        "accessMode": "READ_WRITE",
        "squashMode": "NO_ROOT_SQUASH"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes:createFromSource"

次のように置き換えます。

SNAPSHOT_ID: 同じボリュームプール内のソーススナップショットの ID。
CLONED_VOLUME_ID: 新しいクローンボリュームの ID。

このリクエストは長時間実行オペレーションを返します。done が true になるまで、オペレーションをポーリングします。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

オペレーションが完了したら、volumes.get を呼び出すか、完了したオペレーションレスポンスを調べて、マウントする前に新しいボリュームの mountPoint（ipAddress と mountName）を取得します。
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/CLONED_VOLUME_ID"
```

スナップショットからのボリュームクローン作成は、1 GB あたり 3 秒、または 10,000 ファイルあたり 1.5 秒で完了します。

ボリュームを COLD に階層化する

REST API

アイドル状態のワークスペースをコールドストレージに階層化するには、ボリュームの状態を COLD に更新し、ipAcls をクリアする HTTP PATCH リクエストを送信します。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "COLD",
    "ipAcls": []
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=state,ipAcls"

エージェントセッションの再開時にボリュームを COLD ティアから HOT ティアに復元するには:

unfreeze カスタムメソッドを呼び出し、リクエスト本文で ipAcls を渡して、クライアントアクセスを構成し、HOT ティアでボリュームのマウントポイントを有効にします。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.0/24"],
        "accessMode": "READ_WRITE",
        "squashMode": "NO_ROOT_SQUASH"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID:unfreeze"

このリクエストは長時間実行オペレーションを返します。done が true になるまで、オペレーションをポーリングします。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

ボリュームが COLD ティアから復元されると、Filestore はボリュームプールから新しい NFS マウントエンドポイントを割り当てるため、mountPoint.ipAddress と mountPoint.mountName が変更されます。完了したオペレーションレスポンスから、またはボリュームを再マウントする前に volumes.get を呼び出して、更新された mountPoint を取得します。
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"
```

次のステップ

ボリュームプールを管理、モニタリングする。
Filestore エージェントボリュームの GKE 環境を構成します。

REST API を使用して Filestore エージェント ボリュームを作成、管理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

ボリュームを作成

REST API

ボリュームをマウントする

ボリュームを管理する

REST API

ボリュームの詳細を取得する

プール内のボリュームを一覧表示する

ボリューム割り当てを更新する

ボリューム IP ACL を更新する

ボリュームを削除する

ボリューム スナップショットを使用してワークスペースのクローンを作成する

REST API

ボリューム スナップショットを作成する

スナップショットからボリュームのクローンを作成する

ボリュームを COLD に階層化する

REST API

次のステップ

REST API を使用して Filestore エージェントボリュームを作成、管理する

ボリュームスナップショットを使用してワークスペースのクローンを作成する

ボリュームスナップショットを作成する