Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הרצת קוד ב-Cloud Run

הסביבה 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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

מתקינים ומפעילים את ה-CLI של gcloud.
פריסה של שירות ב-Cloud Run בסביבת הביצוע מהדור השני.

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

כשמפעילים ארגזי חול, השירות של Cloud Run נפרס בסביבת ההפעלה מהדור השני. כדי להפעיל ארגזי חול בשירותי Cloud Run, משתמשים ב-Google Cloud CLI או בהגדרת YAML:

gcloud

כדי לפרוס או לעדכן את השירות, מציינים את הדגל --sandbox-launcher:

כדי לפרוס שירות חדש, מריצים את הפקודה הבאה:
```
gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫SERVICE: השם של שירות Cloud Run.
- ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר, לדוגמה, us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, צריך ליצור מראש את המאגר REPO_NAME. כתובת ה-URL היא בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
כדי לעדכן שירות קיים, מריצים את הפקודה הבאה:
```
gcloud beta run services update SERVICE --sandbox-launcher
```

YAML

אם אתם יוצרים שירות חדש, דלגו על השלב הזה. כדי לעדכן שירות קיים, מורידים את הגדרות ה-YAML שלו:
```
gcloud run services describe SERVICE --format export > service.yaml
```
מעדכנים את קובץ ה-YAML של השירות כך שיכלול את מאפיין sandboxLauncher עם הערך true בתוך הגדרת הקונטיינר:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        sandboxLauncher: true
        port: 8080
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫SERVICE: השם של שירות Cloud Run.
- ‫CONTAINER: השם של הקונטיינר.
- ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר, לדוגמה, us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, צריך ליצור מראש את המאגר REPO_NAME. כתובת ה-URL היא בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
יוצרים או מעדכנים את השירות באמצעות הפקודה הבאה:
```
gcloud run services replace service.yaml
```
אם קיים קובץ service.yaml, הפקודה gcloud run services replace משתמשת בו כברירת מחדל.

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

השבתת ארגזי חול

כדי להשבית את האפשרות להפעיל ארגז חול בשירות, משתמשים ב-Google Cloud CLI או בהגדרת YAML:

gcloud

כדי לעדכן את השירות באמצעות הדגל --no-sandbox-launcher, מריצים את הפקודה הבאה:

gcloud beta run services update SERVICE --no-sandbox-launcher

מחליפים את SERVICE בשם השירות.

YAML

אם אתם יוצרים שירות חדש, דלגו על השלב הזה. כדי לעדכן שירות קיים, מורידים את הגדרות ה-YAML שלו:
```
gcloud run services describe SERVICE --format export > service.yaml
```
מעדכנים את קובץ ה-YAML של השירות כדי להסיר את המאפיין sandboxLauncher בהגדרת מאגר התגים:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        port: 8080
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫SERVICE: השם של שירות Cloud Run.
- ‫CONTAINER: השם של הקונטיינר.
- ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר, לדוגמה, us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, צריך ליצור מראש את המאגר REPO_NAME. כתובת ה-URL היא בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
יוצרים או מעדכנים את השירות באמצעות הפקודה הבאה:
```
gcloud run services replace service.yaml
```
אם קיים קובץ service.yaml, הפקודה gcloud run services replace משתמשת בו כברירת מחדל.

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

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

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

Node.js

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

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

Python

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

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

המשך

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

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

Sandbox CLI

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

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

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

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

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

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

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

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

מפעיל סביבת Sandbox‏ (sandbox run).
מריץ את הפקודה שצוינה (sandbox exec).
מחיקת ארגז החול אחרי ביצוע מוצלח (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: מבצע סנכרון דו-כיווני על ידי ייבוא לפני ההפעלה וייצוא בסיום.

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

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

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

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

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.

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

פורסים ארגז חול עם שם ברקע עם גישת כתיבה מופעלת, ויוצרים קובץ בסביבת העבודה שלו:
```
sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
```
כדי ליצור קובץ snapshot של מערכת הקבצים ששונתה בארגז החול הפועל, משתמשים בפקודה sandbox tar:
```
sandbox tar my-sandbox --file=/tmp/foo.tar
```
מחפשים את קובץ הארכיון של תמונת המצב ומוודאים שהוא מכיל את הנתונים שנכתבו בארגז החול:
```
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.

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

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

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

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

יוצרים סקריפט Python במאגר התגים המארח:

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

מוודאים שהקובץ קיים באופן מקומי:
```
cat /tmp/my-scripts/task.py
```
מריצים את הקובץ בארגז החול:
```
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:

יוצרים ספרייה של נפח משותף במאגר המארח ומאכלסים אותה בקובץ ראשוני:
```
mkdir -p /tmp/my-volume
echo 'read' > /tmp/my-volume/readwrite.txt
```
מריצים את ארגז החול כדי לקרוא את הקובץ מנתיב הטעינה:
```
sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
```
הפקודה הזו מחזירה את הערך read.
מריצים את ארגז החול כדי לכתוב נתונים חדשים בחזרה למארח מתוך הנקודה שבה הכונן מחובר:
```
sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
```
מוודאים במאגר המארח שארגז החול שינה את הקובץ בהצלחה:
```
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.

ממשק ה-CLI של sandbox כותב פלט רגיל (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()

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

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

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

gcloud

YAML

השבתת ארגזי חול

gcloud

YAML

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

Node.js

Python

המשך

Sandbox CLI

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

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

Node.js

Python

המשך

Sandbox CLI

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

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

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

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

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

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

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

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

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

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

Node.js

Python

המשך

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

הרצת קוד ב-Cloud Run