Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

REST API를 사용하여 Filestore 에이전트 볼륨 만들기 및 관리

자체 조정 플랫폼, VM 기반 샌드박스 또는 Google Kubernetes Engine(GKE) 이외의 컨테이너 환경에서 Filestore 에이전트 볼륨을 사용하는 경우 Filestore REST API를 사용하여 볼륨 풀 내의 개별 볼륨을 직접 프로비저닝하고 관리할 수 있습니다.

시작하기 전에

Filestore 에이전트 볼륨 설정에서 초기 프로젝트 및 Private Service Connect(PSC) 네트워킹 설정을 완료합니다.
볼륨 풀 만들기 및 관리에서 리전 볼륨 풀을 만듭니다.

볼륨 만들기

REST API

볼륨 풀 내에서 개별 볼륨을 프로비저닝하려면 HTTP POST 요청을 volumes.create 엔드포인트로 보냅니다.

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

볼륨 마운트

볼륨을 프로비저닝한 후 조정자는 볼륨의 NFSv3 내보내기를 동일한 VPC 네트워크에 연결된 모든 클라이언트 VM 또는 컨테이너 호스트에 직접 마운트할 수 있습니다.

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"

스냅샷에서 볼륨 클론은 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 에이전트 볼륨 만들기 및 관리