יצירה וניהול של מאגרי נפח

מאגר נפחים הוא משאב אזורי ברמה העליונה שמנהל מאגר משותף של קיבולת אחסון ו-IOPS לפרויקט ולרשת הענן הווירטואלי הפרטי (VPC). במאגר נפחים, אפשר להקצות עד מיליון נפחים עצמאיים וקלי משקל לארגזי חול של סוכני AI, לסביבות עבודה למפתחים או לעומסי עבודה כלליים של ריבוי דיירים.

לפני שמתחילים

משלימים את הדרישות המוקדמות שמתוארות במאמר בנושא הגדרת אמצעי אחסון של Filestore Agent.

יצירת מאגר נפחים

‫API בארכיטקטורת REST

כדי ליצור מאגר נפח, שולחים בקשת HTTP POST לנקודת הקצה volumePools.create:

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 .
  • ‫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. הערך צריך להיות בין 100 MiB ל-102,400 MiB‏ (100 GiB). ערך ברירת המחדל הוא 1,024 MiB.
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 .
  • ‫LOCATION: האזור שבו מאגר הנפחים נפרס, למשל us-central1.
  • ‫OPERATION_ID: מזהה הפעולה שמוחזר בתגובת היצירה.

בסיום, הפעולה מחזירה את האובייקט VolumePool עם המצב READY.

ניהול מאגרי נפח

אתם יכולים לראות פרטים על מאגרי נפח אחסון קיימים, לראות רשימה של מאגרי נפח אחסון באזור מסוים, לעדכן הגדרות כמו תוויות ומכסות קיבולת, או למחוק מאגרי נפח אחסון.

‫API בארכיטקטורת REST

בכל אחת מהבקשות הבאות, מחליפים את:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫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"

עדכון מאגר נפחים

כדי לעדכן את התיאור, התוויות או מכסת ברירת המחדל של מאגר נפחים קיים, שולחים בקשת HTTP PATCH עם פרמטר שאילתה updateMask:

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"

ניהול נפחי אחסון באמצעות API בארכיטקטורת REST

אם אתם רוצים להשתמש בנפחי אחסון של סוכן Filestore בלי GKE דרך פלטפורמת תזמור משלכם לאחסון, אתם יכולים להקצות ולנהל נפחי אחסון בודדים ישירות באמצעות API בארכיטקטורת REST.

‫API בארכיטקטורת REST

בכל אחת מהבקשות הבאות, מחליפים את:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור שמכיל את מאגר נפחי האחסון של ההורה.
  • ‫VOLUME_POOL_ID: המזהה של מאגר הכרכים הראשי.
  • ‫VOLUME_ID: המזהה של אמצעי האחסון, שזהה לערך של ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

יצירת נפח אחסון

כדי להקצות נפח נתונים בתוך מאגר נפחי נתונים, שולחים בקשת 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"
    }
  }'

הקצאת נפח האחסון מסתיימת תוך פחות משנייה. ה-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: כתובת ה-IP הפנימית של נקודת הקצה של NFS mount ברשת ה-VPC.
  • ‫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"

המאמרים הבאים