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

הערה: נפחי האחסון לסוכנים ב-Filestore זמינים במסגרת תוכנית Allowlisted GA ‏(AGA). כדי לבקש גישה לפרויקט ב- Google Cloud , צריך לשלוח את טופס בקשת הגישה לנפחי אחסון לסוכנים ב-Filestore.

אם אתם משתמשים בנפחי אחסון לסוכנים של Filestore עם פלטפורמת תזמור משלכם, ארגזי חול שמבוססים על VM או סביבות קונטיינרים שלא שייכות ל-Google Kubernetes Engine‏ (GKE), אתם יכולים להקצות ולנהל נפחי אחסון נפרדים בתוך מאגר נפחי אחסון ישירות באמצעות ה-API בארכיטקטורת REST של Filestore.

הערה: אם אתם פורסים עומסי עבודה ב-GKE, אתם לא צריכים להקצות או לנהל אמצעי אחסון באופן ידני. מנהל ההתקן של Filestore CSI והתזמור של GKE מנהלים באופן אוטומטי את הקצאת נפחי האחסון ממאגר נפחי האחסון. מידע נוסף זמין במאמר הגדרת סביבת GKE לנפחי אחסון לסוכנים של Filestore.

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

1. משלימים את הגדרת הפרויקט הראשונית ואת הגדרת הרשת של Private Service Connect ‏(PSC) בהגדרת נפחי אחסון לסוכנים ב-Filestore.
2. יוצרים מאגר אזורי של נפחים ביצירה וניהול של מאגרי נפחים.

יצירת אמצעי אחסון

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

כדי להקצות נפח אחסון בודד בתוך מאגר נפחי אחסון, שולחים בקשת HTTP מסוג POST לנקודת הקצה (endpoint) של 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 .
• ‫LOCATION: האזור שבו נמצא מאגר הנפחים הראשי, למשל us-central1.
• ‫VOLUME_POOL_ID: המזהה של מאגר הנפחים הראשי.
• ‫VOLUME_ID: המזהה של אמצעי האחסון, שתואם ל-^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

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

טעינת אמצעי אחסון

אחרי הקצאת נפח, כלי התזמור יכול לטעון את הייצוא של NFSv3 של הנפח ישירות לכל VM של לקוח או מארח קונטיינר שמחובר לאותה רשת VPC:

1. מוודאים שכלי הלקוח של NFS מותקנים במארח (לדוגמה, nfs-common ב-Debian או ב-Ubuntu).

2. יוצרים ספריית טעינה וטוענים את אמצעי האחסון באמצעות הערכים של ipAddress ו-mountName שהוחזרו ב-mountPoint של אמצעי האחסון:

   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 שמוחזר כשיוצרים או מאחזרים את אמצעי האחסון.

ניהול אמצעי אחסון

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

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

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

עדכון מכסת הנפח

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

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"

עדכון רשימות ACL של כתובות IP של אמצעי אחסון

כדי להגביל את הגישה ל-NFS לכתובת ה-IP של לקוח ספציפי בארגז החול, או כדי לעדכן את כללי הייצוא של כתובות ה-IP, שולחים בקשת HTTP מסוג PATCH ומציינים את updateMask=ipAcls:

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, אתם יכולים ליצור תמונת מצב של נפח האחסון כדי לתעד את המצב של נפח האחסון של הסוכן בנקודת זמן מסוימת, וכך לשכפל או לפצל סביבות עבודה מאוחר יותר.

הערה: הניהול של קובצי Snapshot של נפח מתבצע באמצעות אוסף המשאבים backups עם השדה sourceVolume.

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

יצירת קובץ snapshot של אמצעי אחסון

1. שולחים בקשת HTTP מסוג POST לנקודת הקצה (endpoint) של backups.create, מציינים את שם המשאב המלא של הנפח בשדה sourceVolume ומחליפים את SNAPSHOT_ID במזהה ייחודי של קובץ ה-snapshot:

   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"
   

2. הבקשה מחזירה פעולה ממושכת (LRO). לפני שמשכפלים ממנו אמצעי אחסון, דוגמים את הפעולה או שולחים שאילתה למשאב של קובץ ה-snapshot עד שהערך של 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"
   

שכפול של אמצעי אחסון מתמונת מצב

כדי לשכפל ווליום מתמונת מצב, תמונת המצב צריכה להיות מווליום באותו מאגר ווליומים.

1. שולחים בקשת HTTP POST לנקודת הקצה (endpoint) volumes:createFromSource. כדי להגדיר הרשאות ייצוא ולהפעיל את הנפח המשוכפל ברמה HOT, מעבירים את ipAcls בגוף הבקשה:

   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: המזהה של קובץ ה-snapshot של המקור באותו מאגר נפחים.
   • ‫CLONED_VOLUME_ID: המזהה של הנפח המשוכפל החדש.

2. הבקשה מחזירה פעולה ממושכת. דוגמים את הפעולה עד שהערך של 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"
   

3. אחרי שהפעולה מסתיימת, מפעילים את 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"
   

שכפול נפח מתמונות מצב מסתיים תוך 3 שניות לכל GB או 1.5 שניות לכל 10,000 קבצים.

העברת נפח אחסון לשכבה COLD

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

כדי להעביר סביבת עבודה לא פעילה לאחסון קר, שולחים בקשת HTTP PATCH שמעדכנת את מצב הנפח ל-COLD ומנקה את ipAcls:

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 כשממשיכים את הסשן עם הנציג:

1. מפעילים את השיטה בהתאמה אישית 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"
   

2. הבקשה מחזירה פעולה ממושכת. דוגמים את הפעולה עד שהערך של 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"
   

3. כשמשחזרים נפח אחסון מהרמה COLD, שירות Filestore מקצה נקודת קצה חדשה לטעינת NFS ממאגר נפחי האחסון, ולכן הערכים של mountPoint.ipAddress ו-mountPoint.mountName משתנים. אחזור של mountPoint המעודכן מהתגובה לפעולה שהושלמה או באמצעות קריאה ל-volumes.get לפני טעינה מחדש של אמצעי האחסון:

   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"
   

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

• ניהול ומעקב אחרי מאגרי נפח אחסון.
• מגדירים את סביבת GKE לנפחי אחסון לסוכנים ב-Filestore.