‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

בקשה של זהות סוכן לסוכן GKE

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

עומסי עבודה של סוכנים שפורסים באשכולות של Google Kubernetes Engine ‏ (GKE) צריכים לעיתים קרובות לגשת לכלים ולשירותים חיצוניים, או כזהות של הסוכן עצמו או בשם משתמשי קצה. אדמינים של אבטחה ואדמינים של פלטפורמות רוצים גם לדעת מה סוכנים שפרסו עושים בשירותים שונים. Google Cloud במסמך הזה מוסבר איך להגדיר אימות לעומסי עבודה של סוכנים על ידי שליחת בקשה לזהות סוכן עבור ה-Pods שלכם. זהות הסוכן מאפשרת להגדיר אימות בלי לנהל באופן ידני את פרטי הכניסה לתהליכי עבודה שונים, ומשלבת את סוכני GKE עם Gemini Enterprise Agent Platform. המסמך הזה מיועד למפתחי אפליקציות שיוצרים ומריצים עומסי עבודה של סוכנים באשכולות GKE.

כדאי כבר להכיר את הנושאים הבאים:

תמחור

התכונה 'זהות הסוכן' מסופקת ב-GKE ללא עלות נוספת.

מגבלות

אפשר לרשום באופן אוטומטי רק פריסות במאגר סוכנים. בקרי עומסי עבודה אחרים ו-Pods סטטיים לא תומכים ברישום אוטומטי. אפשר לבקש זהויות של סוכנים לכל סוגי עומסי העבודה, אבל רישום ב-Agent Registry מאפשר לשלב את הזהויות האלה עם Agent Platform.
אסימוני גישה של סוכן עם זהות מוגבלת משתמשים רק בהיקף ההרשאות https://www.googleapis.com/auth/cloud-platform של OAuth. אי אפשר לציין היקף שונה לטוקנים של גישה שמוגבלים לכתובת IP.

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

לפני שמתחילים, חשוב לוודא שביצעתם את המשימות הבאות:

מפעילים את ממשק ה-API של Google Kubernetes Engine.

הפעלת Google Kubernetes Engine API

כדי להשתמש ב-CLI של Google Cloud למשימה הזו, צריך להתקין ואז לאתחל את ה-CLI של gcloud. אם התקנתם בעבר את ה-CLI של gcloud, מריצים את הפקודה gcloud components update כדי לקבל את הגרסה העדכנית. יכול להיות שגרסאות קודמות של ה-CLI של gcloud לא יתמכו בהרצת הפקודות שמופיעות במסמך הזה.
הערה: אם כבר התקנתם את ה-CLI של gcloud, הקפידו להגדיר את compute/region המאפיין. אם אתם משתמשים בעיקר באשכולות אזוריים, צריך להגדיר את compute/zone במקום זאת. אם מגדירים מיקום ברירת מחדל, אפשר להימנע משגיאות ב-CLI של gcloud כמו השגיאה הבאה: One of [--zone, --region] must be supplied: Please specify location. יכול להיות שתצטרכו לציין את המיקום בפקודות מסוימות אם המיקום של האשכול שונה מברירת המחדל שהגדרתם.

מפעילים את Agent Registry API, אם הוא עדיין לא מופעל:
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים
```
gcloud services enable agentregistry.googleapis.com
```
מוודאים שיש לכם אשכול Autopilot קיים או אשכול Standard שמופעל בו איחוד זהויות של עומסי עבודה ל-GKE, ושהוא מריץ GKE בגרסה 1.37.0-gke.3503000 ואילך.
מוודאים שיש לכם מספיק מכסה לפעולות של החלפת טוקנים. שם המכסה הזו הוא Exchange Workload Identity Token Requests per minute per region (בקשות של אסימוני Exchange Workload Identity לדקה לכל אזור). מידע נוסף זמין במאמר מכסות ומגבלות.

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לבקשת זהות של סוכן ולפריסת עומסי עבודה, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Kubernetes Engine Developer (roles/container.developer) בפרויקט Google Cloud . להסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

בקשת זהות של סוכן לעומס עבודה

כדי לקבל זהות של סוכן עבור Pods, מוסיפים הערות למפרט של ה-Pod כדי לבקש מזהה SPIFFE עבור עומס העבודה ולהחדיר את חבילת אישורי X.509 לכל Pod. ב-Pods שמנוהלים על ידי Deployments, צריך גם להוסיף הערה ותווית כדי לרשום את הסוכן במרשם הסוכנים. ההרשמה היא אופציונלית, אבל רק סוכנים רשומים יכולים להשתמש בשירותי פלטפורמת הסוכנים, כמו Agent Gateway. מידע נוסף על ההערות והתוויות הספציפיות זמין במאמר הגדרות ברמת עומס העבודה.

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

למצוא את מזהה הארגון. אם הפרויקט שלכם לא נמצא בארגון, דלגו על השלב הזה ומצאו את מספר הפרויקט.
```
gcloud projects get-ancestors PROJECT_ID
```
מחליפים את PROJECT_ID במזהה הפרויקט של האשכול.

הפלט אמור להיראות כך:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
רושמים את הערך בשדה ID של המשאב organization.
מתחברים לאשכול:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫CLUSTER_NAME: השם של האשכול.
- ‫CONTROL_PLANE_LOCATION: האזור או האזור הזמין של מישור הבקרה של האשכול.
יוצרים מרחב שמות כדי להריץ את פריסת הדוגמה:
```
kubectl create namespace NAMESPACE_NAME
```
מחליפים את NAMESPACE_NAME בשם של מרחב השמות.
יוצרים ServiceAccount ב-Kubernetes לפריסה:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
מחליפים את SERVICEACCOUNT_NAME בשם של חשבון השירות.

שומרים את מניפסט הפריסה הבא בשם agent-identity-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-identity-deployment
  namespace: NAMESPACE_NAME
  # Add the agent to Agent Registry
  labels:
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  replicas: 2
  selector:
    matchLabels:
      workload-type: agent
  template:
    metadata:
      name: agent-identity-pod
      annotations:
        iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
        iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
        iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
      labels:
        workload-type: agent
    spec:
      serviceAccountName: SERVICEACCOUNT_NAME
      containers:
      - name: agent
        image: python:3.11-slim
        command: ["sleep","infinity"]

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

פרויקטים שנמצאים בארגון: ‫agents.global.org-ORGANIZATION_ID.system.id.goog, כאשר ORGANIZATION_ID הוא מזהה הארגון.
‫Projects that aren't in an organization: ‏agents.global.proj-PROJECT_NUMBER.system.id.goog, כאשר PROJECT_NUMBER הוא מספר הפרויקט של אשכול.

הפריסה הזו מבקשת זהות של סוכן בשביל עומס העבודה, מוסיפה את אישורי X.509 לכל Pod ל-Pods, ורושמת את הסוכן במאגר הסוכנים.

יוצרים את הפריסה:

kubectl apply -f agent-identity-deployment.yaml

מוודאים שה-Pods פועלים:

kubectl get pods -l workload-type=agent -n NAMESPACE_NAME

בדיקת הזהות של הסוכן שהוקצתה

אחרי שפורסים עומס עבודה שמבקש זהות של סוכן, אפשר לאמת את הזהות על ידי בדיקת אישורי X.509. אם משביתים את הזרקת האישורים, אפשר לקבל אסימון זהות לא קשור משרת המטא-נתונים של GKE כדי לבדוק את שדה הנושא, כמו שמתואר במאמר בנושא אימות לממשקי Google Cloud API.

כדי לקרוא את אישור X.509 ב-Pod, פועלים לפי השלבים הבאים:

בודקים אם ל-Pod יש גישה לאישור X.509 ולמפתח הפרטי:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
מחליפים את POD_NAME בשם של Pod שמשתמש בזהות של סוכן.

הפלט אמור להיראות כך:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
בפלט הזה, עוצמת הקול gke-workload-spiffe-credentials היא המיקום של האישורים המוזרקים. אם לא רואים את עוצמת הקול הזו, צריך לוודא שההערה iam.gke.io/inject-podcertificates מוגדרת לערך true במפרט של ה-Pod.
יצירת סשן של מעטפת אינטראקטיבית ב-Pod:
```
kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash
```
בסשן של מעטפת הפקודות, מציגים את רשימת פרטי הכניסה בווליום gke-workload-spiffe-credentials:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
הפלט אמור להיראות כך:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
הפלט מציג את הקבצים הבאים:
- ‫x509.credential-bundle.private-key.pem: חבילת האישורים של זהות הסוכן, שכוללת את שרשרת אישורי X.509 ומפתח פרטי שייחודי ל-Pod. חבילת פרטי הכניסה הזו משמשת לבקשת טוקני גישה וטוקנים של מזהה, ולאימות ל-APIs של Google Cloudבאמצעות mTLS.
- ‫TRUST_DOMAIN.spiffe-trust-bundle.pem: חבילת האישורים המהימנים של ה-CA הבסיסי, שמכילה את האישורים בחתימה עצמית שמהווים את ישות עוגן אמינה לפרטי הכניסה של זהות הסוכן. חבילת האישורים הזו משמשת בעיקר לאימות אישורי TLS מעומסי עבודה אחרים במהלך לחיצות יד ב-mTLS.

כדי לקבל את מזהה SPIFFE שמשויך ל-Pod, קוראים את אישור X.509:

openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout

הפלט אמור להיראות כך:

Certificate:
    Data:
    # Multiple lines are omitted here
        X509v3 extensions:
            # Multiple lines are omitted here
            X509v3 Subject Alternative Name: critical
                URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
    # Multiple lines are omitted here

בפלט הזה, הערך שנמצא בשדה URI של השדה X509v3 Subject Alternative Name הוא מזהה SPIFFE של הסוכן.

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