יכול להיות שחלק מהמידע בדף הזה או כולו לא רלוונטי ל-Cloud de Confiance by S3NS. פרטים נוספים מופיעים במאמר מה ההבדל מ-Google Cloud.

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

בידוד של ביצוע קוד מבוסס-AI באמצעות ארגז חול של סוכן

טייס אוטומטי רגילה

במאמר הזה מוסבר איך להתקין ולהפעיל את בקר Agent Sandbox באשכול Google Kubernetes Engine ‏ (GKE). בנוסף, במאמר מוסבר איך לפרוס סביבת ארגז חול באשכול שבו אפשר לבדוק פקודות shell לא מהימנות.

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

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

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

במאמר הזה מפורטות הוראות להרצת Agent Sandbox באשכול GKE Autopilot או באשכול רגיל.

‫Agent Sandbox הוא פרויקט קוד פתוח. מידע נוסף על תרומה לפרויקט או על פרטים טכניים מעמיקים יותר זמין בפרויקט הקוד הפתוח של Agent Sandbox.

עלויות

ביצוע השלבים שמפורטים במסמך הזה יגרום לחיובים בחשבון Cloud de Confiance by S3NS שלכם. העלויות מתחילות כשיוצרים אשכול GKE. העלויות האלה כוללות חיובים לכל אשכול ב-GKE, כפי שמפורט בדף התמחור, וחיובים על הפעלת מכונות וירטואליות ב-Compute Engine.

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

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

In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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 Cloud de Confiance project.
Enable the Artifact Registry, Google Kubernetes Engine APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

In the Cloud de Confiance console, activate Cloud Shell.

Activate Cloud Shell

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

כדי לפשט את הפקודות שמריצים במסמך הזה, אפשר להגדיר משתני סביבה ב-Cloud Shell. ב-Cloud Shell, מריצים את הפקודות הבאות כדי להגדיר את משתני הסביבה השימושיים הבאים:
```
export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
```
הסבר על משתני הסביבה האלה:
- ‫PROJECT_ID: המזהה של הפרויקט הנוכחי ב- Cloud de Confiance by S3NS . הגדרת המשתנה הזה עוזרת לוודא שכל המשאבים, כמו אשכול GKE, נוצרים בפרויקט הנכון.
- ‫CLUSTER_NAME: השם של אשכול GKE, לדוגמה agent-sandbox-cluster.
- ‫GKE_LOCATION: האזור שבו ייצרו את אשכול GKE ואת מאגר Artifact Registry, לדוגמה, us-central1. Cloud de Confiance by S3NS מומלץ למקם אותם באותו מיקום כי זה מקטין את זמן האחזור של משיכת התמונות.
- ‫AGENT_SANDBOX_VERSION: הגרסה של בקר ארגז החול של הסוכן שתיפרס באשכול.
- ‫NODE_POOL_NAME: השם של מאגר הצמתים שיפעיל עומסי עבודה בארגז חול, לדוגמה, agent-sandbox-node-pool.
- ‫MACHINE_TYPE: סוג המכונה של הצמתים במאגר הצמתים, לדוגמה e2-standard-2. פרטים על סדרות שונות של מכונות ואפשרויות שונות זמינים במאמר השוואה בין משפחות של מכונות ומשאבים.
פריסת ארגז חול של סוכנים

אחרי שהגדרתם את הפרויקט ואת סביבת Cloud Shell, אתם מוכנים להקצות את התשתית הנדרשת ולפרוס את Agent Sandbox. Cloud de Confiance by S3NS

יצירת אשכול GKE

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

אפשר ליצור אשכול במצב Autopilot או אשכול רגיל. במצב Autopilot,‏ gVisor מופעל באופן אוטומטי, אבל באשכולות רגילים צריך ליצור מאגר צמתים עם gVisor באופן ידני:
טייס אוטומטי
כדי ליצור אשכול Autopilot באמצעות ה-CLI של gcloud, מריצים את הפקודה הבאה:
```
gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}
```
רגילה
כדי ליצור אשכול רגיל באמצעות ה-CLI של gcloud, מבצעים את השלבים הבאים:
1. יוצרים את האשכול:
  gcloud container clusters create ${CLUSTER_NAME} \ --location=${GKE_LOCATION}
2. יוצרים מאגר צמתים נפרד עם gVisor מופעל:
  gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --machine-type=${MACHINE_TYPE} \ --image-type=cos_containerd \ --sandbox type=gvisor
מאחזרים את פרטי הכניסה של האשכול כדי ש-CLI של kubectl יוכל להתחבר לאשכול. הפקודה הזו מעדכנת את קובץ התצורה של Kubernetes, שמאוחסן כברירת מחדל בספרייה ~/.kube/config. קובץ התצורה הזה מכיל את פרטי הכניסה שנדרשים ל-kubectl כדי ליצור אינטראקציה עם אשכול GKE:
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```
פריסת בקר ארגז החול של הסוכן באשכול

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

מריצים את הפקודות הבאות כדי לפרוס את בקר ארגז החול של הסוכן לאשכול GKE:
```
kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml
```
אימות הבקר של ארגז החול של הנציג

אחרי שמחילים את המניפסטים, בודקים ש-Pod של בקר Agent Sandbox פועל בצורה תקינה במרחב השמות agent-sandbox-system:
```
kubectl get pods -n agent-sandbox-system
```
מחכים עד שהסטטוס של ה-Pod יהיה 'Running' בעמודה STATUS ועד שיופיע '1/1' בעמודה READY. אם ה-Pod פועל בצורה תקינה, הפלט אמור להיראות כך:
```
NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d
```
עכשיו, כשהבקר של ארגז החול של הסוכן פועל, הוא יכול ליצור ולנהל באופן אוטומטי סביבות ארגז חול לכל משאבי Sandbox שיוצרים באשכול.

פריסת סביבת ארגז חול

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

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

הלקוח משתמש בנתב של ארגז חול כנקודת כניסה מרכזית לכל התנועה. בדוגמה שמתוארת במסמך הזה, הלקוח יוצר מנהרה לנתב הזה באמצעות הפקודה kubectl port-forward, כך שלא צריך לחשוף כתובות IP ציבוריות. חשוב לדעת שהשימוש ב-kubectl port-forward לא מאובטח, ולכן מומלץ להשתמש בו רק בסביבות פיתוח.

יצירת SandboxTemplate וSandboxWarmPool

עכשיו מגדירים את ההגדרות של ארגז החול על ידי יצירת משאב SandboxTemplate ומשאב SandboxWarmPool. ‫SandboxTemplate פועל כתוכנית פעולה לשימוש חוזר, שבעזרתה בקר ארגז החול של הסוכן יוצר סביבות ארגז חול עקביות ומוגדרות מראש. המשאב SandboxWarmPool מבטיח שמספר מסוים של Podים שחוממו מראש תמיד יפעלו ויהיו מוכנים להקצאה. ארגז חול מחומם מראש הוא Pod פעיל שכבר עבר אתחול. ההגדרה המוקדמת הזו מאפשרת ליצור ארגזי חול חדשים בפחות משנייה, ומונעת את זמן ההשהיה של הפעלה של ארגז חול רגיל:
1. ב-Cloud Shell, יוצרים קובץ בשם sandbox-template-and-pool.yaml עם התוכן הבא:
```
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template
```
2. החלת המניפסט SandboxTemplate ו-SandboxWarmPool:
```
kubectl apply -f sandbox-template-and-pool.yaml
```
פריסת נתב ארגז החול

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

בדוגמה הזו, משתמשים במצב הפיתוח של הלקוח לצורך בדיקה. השימוש במצב הזה מיועד לפיתוח מקומי, והוא מתבסס על הפקודה kubectl port-forward כדי ליצור מנהרה ישירה מהמכונה המקומית לשירות Sandbox Router שפועל באשכול. גישה זו של מנהור חוסכת את הצורך בכתובת IP ציבורית או בהגדרת Ingress מורכבת, ומפשטת את האינטראקציה עם ארגזי חול מהסביבה המקומית.

כדי לפרוס את נתב ארגז החול:
1. ב-Cloud Shell, יוצרים קובץ בשם sandbox-router.yaml עם התוכן הבא:
```
# A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 2 # Run at least two replicas for high availability
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000
```
2. מחילים את המניפסט כדי לפרוס את הנתב באשכול:
```
kubectl apply -f sandbox-router.yaml
```
התקנת לקוח Python

אחרי שרכיבים בתוך האשכול כמו Sandbox Router נפרסו, השלב האחרון בהכנה הוא להתקין את לקוח Python של Agentic Sandbox במחשב המקומי. כדאי לזכור שהלקוח הזה הוא ספריית Python שמאפשרת ליצור, להשתמש ולמחוק ארגזי חול באופן פרוגרמטי. משתמשים בו בקטע הבא כדי לבדוק את הסביבה:
1. יוצרים ומפעילים סביבה וירטואלית של Python:
```
python3 -m venv .venv
source .venv/bin/activate
```
2. מתקינים את חבילת הלקוח:
```
pip install k8s_agent_sandbox
```
בדיקת ארגז החול

אחרי שכל רכיבי ההגדרה מוכנים, אפשר ליצור ארגז חול ולקיים איתו אינטראקציה באמצעות לקוח Python של ארגז החול של Agentic.
1. בספרייה agent-sandbox, יוצרים סקריפט Python בשם test_sandbox.py עם התוכן הבא:
```
from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)
```
2. מהטרמינל (כשהסביבה הווירטואלית עדיין פעילה), מריצים את סקריפט הבדיקה:
```
python3 test_sandbox.py
```
ההודעה "Hello from the sandboxed environment!‎" אמורה להופיע. זוהי פלט מהארגז חול.

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

כשמריצים את הסקריפט, SandboxClient מטפל בכל השלבים בשבילכם. הוא יוצר את המשאב SandboxClaim כדי להפעיל את ארגז החול, מחכה שארגז החול יהיה מוכן ואז משתמש בשיטה sandbox.run() כדי להריץ פקודות של מעטפת bash בתוך הקונטיינר המאובטח. לאחר מכן הלקוח מצלם ומדפיס את stdout מהפקודה הזו. ארגז החול נמחק אוטומטית אחרי הפעלת התוכנית.

כשיוצרים משאב SandboxClaim, המערכת מקצה Pod זמין ממאגר ה-Pods הפעילים לאובייקט Sandbox ומסמנת את התלונה כ'מוכנה'. SandboxWarmPool לאחר מכן, המערכת ממלאת את המכסה באופן אוטומטי כדי לשמור על מספר העותקים שהוגדר.

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

פינוי משאבים

כדי להימנע מחיובים בחשבון Cloud de Confiance by S3NS , צריך למחוק את אשכול GKE שיצרתם:
```
gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet
```
המאמרים הבאים
- איך שומרים ומשחזרים סביבות ארגז חול של סוכנים באמצעות תמונות מצב של Pod
- מידע נוסף על פרויקט הקוד הפתוח Agent Sandbox זמין ב-GitHub.
- כדי להבין את הטכנולוגיה הבסיסית שמספקת בידוד אבטחתי לעומסי העבודה, אפשר לעיין במאמר GKE Sandbox.
- למידע נוסף על שיפור האבטחה של האשכולות ועומסי העבודה, אפשר לעיין במאמר סקירה כללית על האבטחה ב-GKE.

בידוד של ביצוע קוד מבוסס-AI באמצעות ארגז חול של סוכן

עלויות

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

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

פריסת ארגז חול של סוכנים

יצירת אשכול GKE

טייס אוטומטי

רגילה

פריסת בקר ארגז החול של הסוכן באשכול

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

פריסת סביבת ארגז חול

יצירת SandboxTemplate וSandboxWarmPool

פריסת נתב ארגז החול

התקנת לקוח Python

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

פינוי משאבים

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

יצירת `SandboxTemplate` ו`SandboxWarmPool`