볼륨 풀 만들기 및 관리

볼륨 풀은 프로젝트 및 가상 프라이빗 클라우드 (VPC) 네트워크의 스토리지 용량과 IOPS의 공유 풀을 관리하는 최상위 리전 리소스입니다. 볼륨 풀 내에서 AI 에이전트 샌드박스, 개발자 작업공간 또는 일반 다중 테넌트 워크로드를 위해 최대 100만 개의 독립적인 경량 볼륨을 프로비저닝할 수 있습니다.

시작하기 전에

Filestore 에이전트 볼륨 설정에 설명된 기본 요건을 완료합니다.

볼륨 풀 만들기

REST API

볼륨 풀을 만들려면 volumePools.create 엔드포인트에 HTTP POST 요청을 보냅니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "description": "Production volume pool for AI agent sandboxes",
    "network": "projects/PROJECT_ID/global/networks/VPC_NETWORK",
    "defaultVolumeQuotaMib": 2048,
    "labels": {
      "env": "production",
      "workload": "ai-sandboxes"
    }
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools?volumePoolId=VOLUME_POOL_ID"

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 풀이 배포된 리전(예: us-central1)
  • VOLUME_POOL_ID: 볼륨 풀의 식별자입니다. ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$와 일치합니다.
  • VPC_NETWORK: 기존 VPC 네트워크의 이름입니다.

요청 필드

요청 본문에는 다음 필드가 포함됩니다.

필드 유형 필수 설명
network string 필수 VPC 네트워크의 리소스 경로입니다. 형식은 projects/{project}/global/networks/{network}입니다. 네트워크에 유효한 PSC 서비스 연결 정책이 있어야 합니다.
defaultVolumeQuotaMib int64 선택사항 볼륨당 기본 할당량(MiB)입니다. 값은 100MiB에서 102,400MiB (100GiB) 사이여야 합니다. 기본값은 1024MiB입니다.
description string 선택사항 볼륨 풀에 대한 사용자 친화적인 설명입니다.
labels map[string, string] 선택사항 Google Cloud에서 리소스를 정리하고 필터링할 수 있는 키-값 쌍입니다.

응답

이 메서드는 장기 실행 작업 (LRO) 객체를 반환합니다.

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1694000000000-abcde",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.filestore.v1beta1.OperationMetadata",
    "createTime": "2026-09-08T10:00:00.000Z",
    "target": "projects/my-project/locations/us-central1/volumePools/my-volume-pool",
    "verb": "create"
  },
  "done": false
}

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"

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 볼륨 풀이 배포된 리전입니다(예: us-central1).
  • OPERATION_ID: 생성 응답에서 반환된 작업 ID입니다.

완료되면 작업은 상태가 READY인 VolumePool 객체를 반환합니다.

볼륨 풀 관리

기존 볼륨 풀에 관한 세부정보를 확인하거나, 리전 내 풀을 나열하거나, 라벨 및 용량 할당량과 같은 구성을 업데이트하거나, 볼륨 풀을 삭제할 수 있습니다.

REST API

다음 각 요청에서 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 볼륨 풀이 배포된 리전입니다(예: us-central1).
  • VOLUME_POOL_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"

볼륨 풀 나열

지정된 리전의 모든 볼륨 풀을 나열하려면 다음을 실행하세요.

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

볼륨 풀 업데이트

기존 볼륨 풀의 설명, 라벨 또는 기본 할당량을 업데이트하려면 updateMask 쿼리 매개변수를 사용하여 HTTP PATCH 요청을 보냅니다.

curl -X PATCH \
  -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?updateMask=description,labels" \
  -d '{
    "description": "Updated pool description",
    "labels": {
      "env": "production",
      "owner": "platform-team"
    }
  }'

볼륨 풀 삭제

볼륨 풀을 삭제하기 전에 풀 내에서 프로비저닝된 모든 하위 볼륨을 삭제해야 합니다. 볼륨 풀을 삭제하려면 다음 단계를 따르세요.

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"

REST API를 사용하여 볼륨 관리

스토리지를 위해 자체 오케스트레이션 플랫폼을 통해 GKE 없이 Filestore 에이전트 볼륨을 사용하려면 REST API를 사용하여 개별 볼륨을 직접 프로비저닝하고 관리하면 됩니다.

REST API

다음 각 요청에서 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 상위 볼륨 풀이 포함된 리전입니다.
  • VOLUME_POOL_ID: 상위 볼륨 풀의 식별자입니다.
  • VOLUME_ID: 볼륨의 식별자로, ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$와 일치합니다.

볼륨 만들기

볼륨 풀 내에서 개별 볼륨을 프로비저닝하려면 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"
    }
  }'

볼륨 프로비저닝은 1초 이내에 완료됩니다. API는 Volume 리소스를 직접 반환합니다.

{
  "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 내보내기 경로 구성요소입니다.

볼륨 세부정보 가져오기

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"

풀의 볼륨 나열

볼륨 풀에 프로비저닝된 모든 볼륨을 나열하려면 다음 단계를 따르세요.

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"

볼륨 삭제

에이전트 세션이 종료되거나 임시 샌드박스가 종료되면 볼륨을 삭제하여 풀 내에서 할당량을 회수합니다.

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"

다음 단계