ניהול ארגזי חול

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

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

כדי לנהל ארגזי חול, צריך את התפקידים הבאים בפרויקט:

  • משתמש ב-Agent Platform (roles/aiplatform.user)

ניהול סביבות ה-Sandbox

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

הצגת רשימה של ארגזי חול

כדי להציג רשימה של כל ארגזי החול שמשויכים למכונה של Agent Platform:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של המכונה של Agent Platform. Google Cloud אזורים נתמכים
  • ‫INSTANCE_ID: המזהה של המכונה ב-Agent Platform.

הצגת פרטי ארגז החול

כדי לראות את ההגדרות והסטטוס של ארגז חול ספציפי:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של המכונה של Agent Platform. Google Cloud אזורים נתמכים
  • ‫INSTANCE_ID: המזהה של המכונה ב-Agent Platform שמכילה את ארגז החול.
  • ‫SANDBOX_ID: המזהה של ארגז החול הקיים.

הפלט כולל פרטים כמו זמן היצירה, המצב (לדוגמה, STATE_RUNNING) והמפרט של ארגז החול.

השהיית ארגז חול (sandbox)

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

לארגזי חול מושהים יש את המאפיינים הבאים:

  • לשמור את מזהה ארגז החול, המטא-נתונים של החיבור וכל נקודת קצה (endpoint) של Private Service Connect.
  • לשמור את כל המצב של מערכת הקבצים בתוך הקונטיינר ברגע ההשהיה.
  • מעבר אל STATE_PAUSED. בקשות לנקודת הקצה (endpoint) של מישור הנתונים שלהם יחזירו שגיאות עד שתמשיכו את הפעילות.

כדי להשהות ארגז חול פעיל, מריצים את הקוד הבא:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של המכונה של Agent Platform. Google Cloud אזורים נתמכים
  • ‫INSTANCE_ID: המזהה של המכונה ב-Agent Platform שמכילה את ארגז החול.
  • ‫SANDBOX_ID: המזהה של ארגז החול הקיים.

המשך של ארגז חול

כשממשיכים ארגז חול מושהה, המחשוב שלו חוזר למצב אונליין. ארגז החול שומר על אותו מזהה, אותה נקודת קצה (כולל כל חיבור לשירות Private Service Connect) ואותו מצב של מערכת הקבצים שהיו לו ברגע ההשהיה. אפשר לשלוח שוב בקשות למישור הנתונים של ארגז החול ברגע שפעולת ההמשך מסתיימת.

כדי להמשיך ארגז חול מושהה, מריצים את הקוד הבא:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של המכונה של Agent Platform. Google Cloud אזורים נתמכים
  • ‫INSTANCE_ID: המזהה של המכונה ב-Agent Platform שמכילה את ארגז החול.
  • ‫SANDBOX_ID: מזהה ארגז החול שהושהה.

מחיקת סביבת Sandbox

כדי למחוק באופן מפורש סביבת ארגז חול ולפנות משאבים:

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

רישום ביומן הביקורת ומעקב

כשאתם מנהלים ומריצים פקודות בארגזי חול, פלטפורמת Agent מתעדת את הפעילות ברמת ה-API ביומני הביקורת של Cloud, בשם השירות aiplatform.googleapis.com ובסוג המשאב במעקב audited_resource:

  • יומני Admin Activity (ADMIN_WRITE): מתועדים באופן אוטומטי למוטציות במחזור החיים של מישור הבקרה, כולל CreateSandboxEnvironment,‏ PauseSandboxEnvironment,‏ ResumeSandboxEnvironment,‏ SnapshotSandboxEnvironment ו-DeleteSandboxEnvironment (נדרשות הרשאות IAM מסוג aiplatform.sandboxEnvironments.*).
  • יומני Data Access‏ (ADMIN_READ): מתועדים כשהם מופעלים לפעולות קריאה של מטא-נתונים, כולל GetSandboxEnvironment ו-ListSandboxEnvironments.
  • יומני גישה לנתונים (DATA_WRITE): מתועדים כשהם מופעלים להרצת פקודות במישור הנתונים ולקריאות לאישור גישה, כולל ExecuteSandboxEnvironment,‏ BidiExecuteSandboxEnvironment,‏ AuthorizeSandboxEnvironmentAccess ו-ExecuteCode. במשאבים שמוגנים על ידי VPC Service Controls, נתוני המטען הייעודי (payload) של הבקשה והתגובה מושמטים מיומני הביקורת.

חשוב לזכור את הגבולות הבאים של ניראות וזיהוי איומים:

  • פעילות של תהליכים וסטרימינג בתוך קונטיינר: יומני הביקורת של Cloud מתעדים את בקשת ה-API שמפעילה את הרצת הפקודה או מאשרת חיבור, אבל לא מתעדים תהליכי צאצא ספציפיים שנוצרו בתוך הקונטיינר, שינויים במערכת הקבצים או פריימים אינטראקטיביים שנשלחו לאחר מכן דרך WebSocket פתוח, פרוטוקול כלי פיתוח ל-Chrome‏ (CDP) או סשן PTY.
  • רישום ביומן של קונטיינרים ב-stdout וב-stderr: איסוף אוטומטי של Cloud Logging ל-Agent Runtime (כמו reasoning_engine_stdout ו-reasoning_engine_stderr) חל רק על מכונת ההורה של ReasoningEngine, ולא אוסף באופן אוטומטי יומנים ממשאבי הצאצא של ארגז החול. פלט הפקודה (stdout,‏ stderr וקודי יציאה) מוחזר בתגובת ההפעלה לסוכן הראשי, שבה אפשר לבדוק ולכתוב רשומות מובְנות ב-Cloud Logging.
  • זיהוי איומים ובדיקת רשת: ארגזי חול אוכפים את ההכלה באמצעות בידוד ליבה של gVisor וזהות ללא הרשאות בתוך ארגז החול, ללא פרטי כניסה Google Cloud סביבתיים. כדי לעקוב אחרי התנהגות חריגה או תעבורת נתונים יוצאת לא מורשית ברשת, שלבו את יומני הביקורת של DATA_WRITE עם זיהוי אנומליות אצל סוכנים בסוכן הראשי, ונתבו את תעבורת הנתונים היוצאת של ארגז החול דרך ממשק Private Service Connect עם יומנים של תעבורת הנתונים ב-VPC, רישום ביומן של כללי Cloud Next Generation Firewall ‏(Cloud NGFW) ובדיקה של Secure Web Proxy. למידע נוסף, קראו את המאמר גבולות האבטחה, הזהות והניטור.