הרצת קוד ב-Cloud Run

תצוגה מקדימה — ארגזי חול של Cloud Run

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

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

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

ארגזי חול של Cloud Run מספקים את היתרונות המרכזיים הבאים:

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

• אבטחה: ארגזי חול מבודדים את ביצוע התהליך. כברירת מחדל, לאר Sandboxes אין גישה לעומס העבודה של ההורה, למשתני הסביבה, לסודות או לשרת המטא-נתונים Google Cloud . כל ארגזי החול מבודדים לחלוטין זה מזה.

• בקרת גישה וסביבה: התהליכים מופעלים עם הרשאות sudo כמשתמשים לא-בסיסיים, כך שאתם יכולים להתקין כלים באמצעות מנהלי חבילות כמו apt, pip או npm במהלך ההפעלה. סביבת הארגז חול היא זמנית ונמחקת בסיום השימוש, אבל אתם יכולים להשתמש בספריות קבועות או בתמונות מצב כדי לשמור נתונים ספציפיים של סביבות עבודה או נתוני מפות בקטגוריה של Cloud Storage.

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. מתקינים ומפעילים את ה-CLI של gcloud.
2. פריסת משאב Cloud Run, כמו שירות, משימה, מאגר עובדים או אירוע מהדור השני.

הפעלת ארגזי חול

כדי להשתמש בארגזי חול, צריך קודם להפעיל אותם במשאב Cloud Run באמצעות הדגל --sandbox-launcher או מאפיין ה-YAML‏ sandboxLauncher. כדי לראות את שלבי ההגדרה המפורטים, בוחרים את סוג המשאב הרצוי:

• שירותים
• משימות
• מאגרי Worker
• Instances (תצוגה מקדימה)

הפעלת ארגזי חול

אחרי שמפעילים את ארגזי החול, אפשר להפעיל אותם מתוך סביבת ההפעלה של מאגר התגים. קובץ ה-binary של ארגז החול נמצא ב-/usr/local/gcp/bin/sandbox.

בדוגמאות במדריך הזה נעשה שימוש בפקודה sandbox במקום בנתיב המוחלט שלה /usr/local/gcp/bin/sandbox.

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

Node.js

כדי להריץ את פקודת הסביבה המבודדת מאפליקציית Node.js, מוסיפים את הקוד הבא:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

כדי להריץ את פקודת הסביבה החולית מאפליקציית Python, צריך לכלול את הקוד הבא:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

המשך

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

cmd := exec.Command("sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

Sandbox CLI

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

sandbox do -- /bin/echo "Hello"

כדי לראות את הרשימה המלאה של הפקודות הזמינות, מריצים את הפקודה sandbox -h.

שימוש ביכולות של שורת הפקודה בארגז החול

כלי שורת הפקודה sandbox כולל פקודות להרצה, להגדרה ולניהול של ארגזי חול.

הרצת פקודה בארגז החול

אפשר להריץ הוראה בארגז חול חדש וזמני באמצעות הפקודה sandbox do. הפקודה sandbox do מבצעת את המשימות הבאות:

1. מפעיל סביבת ארגז חול (sandbox run).
2. מריץ את הפקודה שצוינה (sandbox exec).
3. מחיקת ארגז החול אחרי ביצוע מוצלח (sandbox delete).

לדוגמה, כדי לבצע חישוב מתמטי בתוך ארגז החול, מריצים את קטעי הקוד הבאים בשפה המועדפת. מוודאים שכל פקודה או כלי שמריצים, כמו python3, מותקנים בקובץ אימג' של קונטיינר:

Node.js

כדי להריץ את פקודת הסביבת ארגז חול מאפליקציית Node.js:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

כדי להריץ את פקודת הסביבת ארגז חול מאפליקציית Python:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

המשך

כדי להריץ את פקודת הסביבת ארגז חול מאפליקציית Go:

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

Sandbox CLI

כדי להריץ את פקודת ארגז החול ישירות משורת הפקודה:

sandbox do -- /usr/bin/python3 -c "print(1+2)"

אם מריצים פקודה לפי שם בלי הנתיב המוחלט שלה, כמו python3 במקום /usr/bin/python3, צריך להגדיר במפורש את משתנה הסביבה PATH בסביבת הארגז באמצעות הדגל --env.

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

כברירת מחדל, ארגז חול הוא זמני. כדי לשמור נתונים בין הרצות שונות של ארגז חול באותו מופע של Cloud Run, אפשר לייבא ולייצא את מצב מערכת הקבצים של סביבת העבודה באמצעות tar קובצי ארכיון רגילים. אפשר גם להגדיר bind mounts כדי לשתף ספריות ישירות בין קונטיינר המארח לבין סביבות הארגז החול.

משתמשים בדגלים הבאים כשמריצים את הפקודה sandbox do:

• ‫--export-tar: בסיום, הקבצים של שכבות העל ששונו נשמרים בקובץ ארכיון tar.
• ‫--import-tar: חילוץ קבצים מקובץ ארכיון tar אל ארגז החול לפני ההפעלה.
• ‫--sync-tar: מבצע סנכרון דו-כיווני על ידי ייבוא לפני ההפעלה וייצוא בסיום.

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

1. לכתוב נתונים בתוך ארגז חול ולייצא את המצב לקובץ ארכיון:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"
   

2. מייבאים את קובץ הארכיון בקריאה הבאה כדי לאחזר את הנתונים:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /tmp/work/status.txt"
   

לחלופין, כדי לייבא אוטומטית את מצב הארכיון הקיים ולייצא שינויים חדשים בפקודה אחת, משתמשים ב---sync-tar=/tmp/work.tar. כשמסיים תהליך של ארגז חול, Cloud Run מוחק באופן סופי קבצים זמניים של שכבת-על שלא יוצאו לקובץ ארכיון.

הפעלת פקודה ברקע

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

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

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

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

לדוגמה, כדי להריץ פקודת בדיקה בתוך ארגז החול הקיים ברקע של my-web-server, מריצים את הפקודה הבאה:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

הגדרת משתני סביבה

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

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

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

מומלץ להימנע מהעברת סודות באמצעות הדגל env, כי הם עשויים להיות גלויים לתהליכי ארגז החול.

יצירת תמונות מצב של מערכת הקבצים

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

טיפ: אם מריצים הרבה פקודות שוב ושוב בארגז חול יחיד, כדאי להפעיל ארגז חול פעם אחת עם נקודת כניסה במצב המתנה, כמו sleep 12m, ואז להריץ את הפקודה sandbox exec שמטרגטת את ארגז החול הזה כדי להריץ את הפקודה במהירות רבה.

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

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

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
   

2. כדי ליצור קובץ snapshot של מערכת הקבצים ששונתה בארגז החול הפועל, משתמשים בפקודה sandbox tar:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. מחפשים את קובץ הארכיון של תמונת המצב ומוודאים שהוא מכיל את הנתונים שנכתבו בארגז החול:

   tar -xvf /tmp/foo.tar
   

   אלה התוצאות שצריכות להתקבל:

   ./
   ./tmp/
   ./tmp/hello.txt
   

הגדרה של רשתות

כברירת מחדל, כל התנועה היוצאת מארגז החול חסומה. כדי לאפשר גישה לרשת יוצאת, משתמשים בדגל --allow-egress:

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

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

הפקודה הזו מחזירה את קוד סטטוס של HTTP‏ 200, שמציין שהחיבור בוצע בהצלחה.

גישה למערכת הקבצים

כברירת מחדל, לתהליכים שמבצעים בארגז החול יש גישת קריאה בלבד למערכת הקבצים הבסיסית של מארח הקונטיינר. אפשר להשתמש בדגל --write כדי להפעיל כתיבה לשכבת-על של מערכת קבצים זמנית (tmpfs). עם זאת, הפעולות האלה יימחקו כשהארגז יימחק. כדי להפעיל כתיבה מתמשכת לקונטיינר המארח, אפשר להגדיר bind mounts.

הרשאת גישה לקריאה בלבד שמוגדרת כברירת מחדל

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

בדוגמאות הבאות מניחים שאתם מריצים פקודות מספריית הבסיס (/) של קונטיינר המארח.

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

1. יוצרים סקריפט Python בקונטיינר המארח:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. מוודאים שהקובץ קיים באופן מקומי:

   cat /tmp/my-scripts/task.py
   

3. מריצים את הקובץ בארגז החול:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   הפקודה הזו מחזירה hi, מה שמאשר שיש לארגז החול גישת קריאה.

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

   מריצים את הפקודה הבאה כדי לכתוב למערכת הקבצים הבסיסית:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"
   

   הפקודה נכשלת עם השגיאה הבאה:

   /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

שיתוף נתונים באמצעות bind mounts

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

1. יוצרים ספרייה של נפח משותף במאגר המארח ומאכלסים אותה בקובץ ראשוני:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. מריצים את ארגז החול כדי לקרוא את הקובץ מנתיב הטעינה:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   הפקודה הזו מחזירה את הערך read.

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

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. מוודאים במאגר המארח שארגז החול שינה את הקובץ בהצלחה:

   cat /tmp/my-volume/readwrite.txt
   

   הפקודה הזו מחזירה את הערך write.

הגדרת טעינות לקריאה בלבד

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

לדוגמה, מריצים את הפקודה הבאה כדי לבדוק הגבלות כתיבה בטעינת bind במצב קריאה בלבד:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

ניסיון הכתיבה נכשל עם השגיאה הבאה:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

צפייה ביומנים

ב-Cloud Run, אירועים במחזור החיים של ארגז חול, כמו התחלה ויציאה של ביצוע, נרשמים אוטומטית ב-Cloud Logging.

ממשק sandbox CLI כותב פלט רגיל (stdout) ושגיאה רגילה (stderr) מפקודות בסביבת ארגז חול ישירות לזרמים הרגילים של התהליך המפעיל. כדי לראות את היומנים האלה ב-Cloud Logging, צריך להפנות את הזרמים לפלט הרגיל ולשגיאה הרגילה של הקונטיינר:

Node.js

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

Python

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

המשך

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

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

• מידע נוסף על אירוח סוכני AI ב-Cloud Run
• מידע נוסף על אוטומציה של דפדפנים ומערכות הפעלה ב-Cloud Run
• מעיינים בחוזה של זמן הריצה של הקונטיינר.