הגדרת Agent Gateway חוצה-עננים (cross-cloud)

במדריך הזה מוסבר איך לפרוס את Agent Gateway לאשכולות Kubernetes רגילים חוצי-עננים, כדי להרחיב את הפיקוח של Gemini Enterprise Agent Platform לסביבה שלכם. סקירה כללית על Agent Gateway חוצה-עננים

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

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

  • אשכול Kubernetes שתואם ל-Cloud Native Computing Foundation‏ (CNCF).
  • Service mesh או מקבץ רשת (network stack) קיימים שמוגדרים באשכול.
  • קישוריות לרשת יוצאת מהאשכול לממשקי ה-API של Google Cloud באמצעות HTTPS (יציאת TCP‏ 443).
  • גרסה 591.0.0 ומעלה של Google Cloud CLI. כדי לעדכן לגרסה העדכנית, מריצים את gcloud components update.
  • תפקידי ניהול הזהויות והרשאות הגישה (IAM) בפרויקט ב- Google Cloud שנדרשים כדי להפעיל ממשקי API, ליצור מאגר זהויות של עומסי עבודה וספק, ולהקצות תפקידי IAM.

הפעלת ממשקי API ורישום האשכול

מפעילים את ממשקי ה-API הנדרשים ב- Google Cloud ורושמים את האשכול החיצוני.

הפעלת ממשקי ה-API הנדרשים

כדי להפעיל את ממשקי ה-API שנדרשים ל-Agent Gateway חוצה-עננים, מריצים את הפקודה הבאה:

gcloud services enable \
    agentregistry.googleapis.com \
    apphubendpoint.googleapis.com \
    cloudresourcemanager.googleapis.com \
    cloudtrace.googleapis.com \
    iam.googleapis.com \
    iamcredentials.googleapis.com \
    iap.googleapis.com \
    logging.googleapis.com \
    modelarmor.googleapis.com \
    monitoring.googleapis.com \
    networkservices.googleapis.com \
    serviceextensions.googleapis.com \
    sts.googleapis.com \
    telemetry.googleapis.com \
    trafficdirector.googleapis.com \
    --project=PROJECT_ID

מחליפים את PROJECT_ID במזהה הפרויקט ב-Google Cloud .

חילוץ המפתח הציבורי של שרת ה-API של Kubernetes

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

  1. מגדירים את ההקשר הנוכחי של kubectl לאשכול שרוצים לרשום.

  2. מאחזרים את קבוצת מפתחות האינטרנט של JSON‏ (JWKS) של האשכול, ואז ממירים את מפתח ה-RSA הראשון לקובץ מפתח ציבורי בשם pubkey.pem:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    
    N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    
    openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \
      | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pem
    

    כדי להריץ את הפקודות האלה צריך מעטפת Bash ואת כלי העזר jq ו-openssl.

רישום האשכול

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

  1. מאחזרים את כתובת ה-URL של מנפיק ה-OpenID Connect (OIDC) של האשכול:

    kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
    

    הפלט הוא הערך של הדגל --service-account-issuer של שרת ה-API של Kubernetes באשכול. יכול להיות שהערך הזה יהיה שונה מכתובת ה-URL החיצונית של שרת ה-API של Kubernetes. מעתיקים את הפלט בדיוק כמו שהוא. אל תוסיפו או תסירו לוכסן בסוף.

  2. רושמים את האשכול:

    gcloud alpha network-services registered-clusters create CLUSTER_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --oidc-issuer-url=OIDC_ISSUER_URL \
        --api-server-public-key="$(cat pubkey.pem)"
    

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

    • ‫CLUSTER_NAME: שם לאשכול הרשום.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
    • ‫LOCATION: האזור ב- Google Cloud של האשכול הרשום, לדוגמה us-central1.
    • ‫OIDC_ISSUER_URL: כתובת ה-URL המדויקת של המנפיק שקיבלתם בשלב הקודם. כתובת ה-URL חייבת להתחיל ב-https://.

מניעת מחיקה מקרית של משאבים

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

  • הגנה על הפרויקט Google Cloud באמצעות שעבודים: החילו שעבוד פרויקט על הפרויקטGoogle Cloud שמארח את האשכול הרשום, Agent Registry ומאגרי הזהויות המאוחדות כדי לחסום מחיקה מקרית של הפרויקט עד שכל האשכולות חוצי-העננים יושבתו.
  • הגבלת הרשאות IAM הרסניות: הגבילו את ההרשאות שמאפשרות למחוק אשכולות רשומים או משאבי שער (כמו networkservices.registeredClusters.delete ו-networkservices.agentGateways.delete) לתפקידי אדמין ייעודיים בפלטפורמה.
  • ‫Retain Kubernetes resource finalizers: לא להסיר את ה-finalizers במשאבים בהתאמה אישית בתוך האשכול שמנוהלים על ידי הבקר של agent-governance-cross-cloud-controller. ה-finalizers מוודאים שרישומי Google Cloud במישור הבקרה יוסרו בצורה נקייה לפני הסרת המשאבים של האשכול המקומי.
  • מחיקת משאבים בהתאמה אישית לפני הסרת הבקר: לפני שמסירים את תרשים ה-Helm של agent-governance-cross-cloud או מוחקים את אשכול Kubernetes, צריך למחוק את כל המשאבים בהתאמה אישית של GCPExtensionBinding ו-GCPAgentGateway ולהמתין עד שהמחיקה תסתיים. אם תסירו קודם את הבקר, המשאב התואם של Agent Gateway יישאר מיותם ב-Network Services. השער היתום חוסם את המחיקה של תבנית הקישוריות של הסוכן ושל האשכול הרשום.

הגדרה של איחוד שירותי אימות הזהות של עומסי עבודה

הרכיבים באשכול של Agent Gateway ל-cross-cloud (הבקר של agent-governance-cross-cloud-controller, אוסף הטלמטריה ושרת ה-Proxy) משתמשים באיחוד זהויות של עומסי עבודה כדי לאמת את ממשקי ה-API שלGoogle Cloud . כל רכיב מחליף את אסימון חשבון השירות שלו ב-Kubernetes‏ (KSA) באסימון גישה מאוחד. אתם מקצים תפקידי IAM ישירות לזהויות המאוחדות האלה, כך שאין צורך ליצור חשבונות שירות או לאחסן מפתחות של חשבונות שירות באשכול שלכם.Google Cloud

ה-sidecar של Agent Identity Runtime‏ (AIR) שפועל עם כל שרת proxy משתמש במאגר הזהויות של עומסי העבודה כדי לספק זהויות SPIFFE לעומסי העבודה של הסוכן. הזהויות האלה הן הזהויות של הסוכנים שלכם. כללי המדיניות של Model Armor ו-IAP מזהים סוכנים לפי זהות הסוכן שלהם, ולא לפי הזהויות המאוחדות של הרכיבים באשכול. הפורמט של הישות המורשית מופיע במאמר זיהוי הישות המורשית של הסוכן.

יצירה של ספק ומאגר זהויות של עומסי עבודה

כדי ליצור מאגר זהויות של עומסי עבודה וספק OIDC לאשכול:

  1. אם כתובת ה-URL של מנפיק ה-OIDC של האשכול לא נגישה באופן ציבורי, שומרים את קבוצת מפתחות האינטרנט של JSON‏ (JWKS) של האשכול בקובץ:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    

    כשמספקים את ה-JWKS לספק, Google Cloud יכול לאמת טוקנים של KSA בלי להתחבר למנפיק ה-OIDC של האשכול.

  2. יוצרים מאגר זהויות של עומסי עבודה:

    gcloud iam workload-identity-pools create POOL_ID \
        --project=PROJECT_ID \
        --location=global \
        --display-name="POOL_DISPLAY_NAME"
    
  3. יוצרים ספק OIDC במאגר:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --project=PROJECT_ID \
        --location=global \
        --workload-identity-pool=POOL_ID \
        --issuer-uri=OIDC_ISSUER_URL \
        --jwk-json-path=cluster-jwks.json \
        --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"
    

    אל תציינו את הדגל --allowed-audiences. הרכיבים חוצי-העננים מבקשים אסימונים לקהל שמוגדר כברירת מחדל, שהוא שם המשאב המלא של הספק: //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

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

  • ‫POOL_ID: מזהה של מאגר הזהויות של עומסי העבודה.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫POOL_DISPLAY_NAME: שם לתצוגה של המאגר.
  • ‫PROVIDER_ID: מזהה של ספק ה-OIDC.
  • ‫OIDC_ISSUER_URL: כתובת ה-URL המדויקת של מנפיק ה-OIDC שאחזרתם כשרשמתם את האשכול. הערך הזה חייב להיות זהה לערך שהעברתם אל --oidc-issuer-url, כולל אם הוא מסתיים בלוכסן.

פריסת מישור הבקרה

משתמשים בתרשים Helm שסופק כדי לפרוס את הבקר בתוך האשכול, agent-governance-cross-cloud-controller ואת אוסף הטלמטריה במרחב השמות geap-system.

מוודאים שהבקר מחובר לאינטרנט

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

  • ‫ממשקי API שלGoogle Cloud : לפודים של הבקר של agent-governance-cross-cloud-controller ולאוסף הטלמטריה צריכה להיות קישוריות יוצאת של HTTPS ו-gRPC ביציאת TCP ‏443 אל *.googleapis.com.
  • שרת Kubernetes API: הפודים של הבקר צריכים להיות מסוגלים להגיע לשרת API של Kubernetes כדי לצפות בשירותים, בעומסי העבודה ובמשאבים בהתאמה אישית של Kubernetes.
  • עומסי עבודה של סוכנים בכל מרחבי השמות: הפודים של הבקר צריכים להיות מסוגלים לשלוח קריאות לפודים של הסוכן ושל שרת ה-MCP בכל מרחב שמות באשכול. הבקר מאחזר את כרטיס הסוכן מכל עומס עבודה של סוכן כדי לרשום את הסוכן ב-Agent Registry.

הקצאת תפקידי IAM לבקר ולאוסף הטלמטריה

מקצים תפקידי IAM לזהויות המאוחדות של הבקר של agent-governance-cross-cloud-controller ושל אוסף נתוני הטלמטריה, שפועלים במרחב השמות geap-system:

  • מפעיל לוויין (roles/networkservices.satelliteOperator)
  • כתיבת נתוני טלמטריה ב-Cloud‏ (roles/telemetry.writer)

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

for ROLE in \
    roles/networkservices.satelliteOperator \
    roles/telemetry.writer; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done

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

התקנת תרשים Helm של מישור הבקרה

כדי להתקין את מישור הבקרה:

  1. מתקינים את תרשים Helm של agent-governance-cross-cloud במרחב השמות geap-system:

    helm upgrade --install agent-governance-cross-cloud \
        oci://gcr.io/gke-release/agent-governance-cross-cloud \
        --version 0.1.1-preview \
        --namespace geap-system \
        --create-namespace \
        --set gcp.projectId=PROJECT_ID \
        --set-string gcp.projectNumber=PROJECT_NUMBER \
        --set-string gcp.orgId=ORGANIZATION_ID \
        --set gcp.location=LOCATION \
        --set gcp.registeredCluster=CLUSTER_NAME \
        --set gcp.workloadIdentityPool=POOL_ID \
        --set gcp.identityProvider=PROVIDER_ID
    

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

    אם לצמתים של האשכול יש taints – לדוגמה, צומתי arm64 ברוב ספקי שירותי הענן, כולל Google Cloud, ‏AWS ו-Azure – צריך להגדיר tolerations של פודים בערך k8s.tolerations של Helm. הסובלנויות חלות על הבקר, על אוסף OpenTelemetry (OTel) ועל פריסות השער שהבקר יוצר. לדוגמה, שומרים את הקוד הבא בתור tolerations-values.yaml, ואז מוסיפים את --values tolerations-values.yaml לפקודה הקודמת:

    k8s:
      tolerations:
      - key: "kubernetes.io/arch"
        operator: "Equal"
        value: "arm64"
        effect: "NoSchedule"
    
  2. מחכים עד שהפריסה של הבקר תהיה מוכנה:

    kubectl rollout status deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system --timeout=180s
    

פריסת מישור הנתונים

פורסים את Agent Gateway לשרת proxy חוצה-עננים (שרת proxy של Envoy) על ידי יצירת משאב בהתאמה אישית של GCPAgentGateway. שרת ה-proxy בודק את התנועה ואוכף את כללי המדיניות על עומסי העבודה של הסוכן שהוא מנהל. כל שרת proxy פועל עם Agent Identity Runtime (AIR) sidecar שמתווך בין Workload Identity, אישורי Secret Discovery Service (SDS) והחלפת אסימונים מקומיים בשביל שרת ה-proxy.

אתם צריכים לפרוס את Agent Gateway ל-cross-cloud במרחב שמות ייעודי (לדוגמה, agent-gateway-system) שלא מכיל עומסי עבודה של סוכנים, שרתי MCP או pod-ים אחרים של אפליקציות. שער יחיד במרחב השמות הייעודי הזה יכול לנהל את התנועה היוצאת מעומסי העבודה של הסוכנים באשכול.

הקצאת תפקידי IAM לשער

מקצים תפקידי IAM לזהויות המאוחדות של Agent Gateway לשרת proxy חוצה-עננים. הקישור חל על כל חשבונות ה-KSA במרחב השמות של השער, לכן צריך להקצות את התפקידים האלה לכל מרחב שמות של שער:

  • לקוח של Traffic Director‏ (roles/trafficdirector.client)
  • צפייה בנקודות קצה ב-App Hub‏ (roles/apphubendpoint.viewer)
  • צפייה ב-Agent Registry‏ (roles/agentregistry.viewer)
  • עריכת Service Extensions‏ (roles/serviceextensions.editor), שמאפשרת לשרת ה-proxy להפעיל קריאות מדיניות של Service Extensions

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

for ROLE in \
    roles/trafficdirector.client \
    roles/apphubendpoint.viewer \
    roles/agentregistry.viewer \
    roles/serviceextensions.editor; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
  • ‫GATEWAY_NAMESPACE: מרחב שמות ייעודי לשער. אסור שמרחב השמות הזה יכיל עומסי עבודה של סוכנים.

יצירת תבנית לקישוריות של סוכנים

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

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

כדי ליצור תבנית קישוריות של נציג:

  1. שומרים את הגדרת התבנית הבאה בתור act.yaml:

    description: "Agent connectivity template for CLUSTER_NAME"
    agentCompute: K8S
    registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
    
  2. מייבאים את התבנית:

    gcloud alpha network-services agent-connectivity-templates import ACT_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --source=act.yaml
    

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

יצירת השער

כדי ליצור את השער:

  1. אם מרחב השמות של השער עדיין לא קיים, יוצרים אותו:

    kubectl create namespace GATEWAY_NAMESPACE
    

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

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

    apiVersion: networkservices.googleapis.com/v1alpha1
    kind: GCPAgentGateway
    metadata:
      name: GATEWAY_NAME
      namespace: GATEWAY_NAMESPACE
    spec:
      agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
    

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

  3. מחילים את המניפסט:

    kubectl apply -f agent-gateway.yaml
    
  4. מחכים שהשער ייפרס ויהיה מוכן:

    kubectl wait --for=condition=Reconciled=True \
        gcpagentgateway/GATEWAY_NAME \
        -n GATEWAY_NAMESPACE \
        --timeout=300s
    

    כשהשער מוכן, הפקודה מחזירה את הערך gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.

  5. מגדירים את Service mesh כך שתעביר את תנועת הסוכנים היוצאת, כמו בקשות של מודל שפה גדול (LLM), של Model Context Protocol‏ (MCP) ושל Agent-to-Agent‏ (A2A), דרך השער.

הוספת tolerations לשערים קיימים

אם מוסיפים את הערך k8s.tolerations של Helm אחרי שיוצרים משאב GCPAgentGateway, צריך לבצע את הפעולות הבאות כדי שהבקר ייצור מחדש את פריסת השער עם הטולרנטיות החדשה:

  1. מריצים את הפקודה helm upgrade --install מתוך התקנת תרשים Helm של מישור הבקרה עם --values tolerations-values.yaml.

  2. מוחקים את פריסת השער הקיימת:

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    חוזרים על השלב הזה לכל שער באשכול.

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

    kubectl rollout restart deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system
    

התהליך הזה לא משפיע על המשאב Google Cloud AgentGateway או על משאבי GCPExtensionBinding שמצורפים אליו. תנועה יוצאת דרך השער מופסקת עד שהבקר יוצר מחדש את פריסת השער.

איך מאפשרים קישוריות יוצאת ל-Google APIs

מוודאים של-Agent Gateway לפודים של שרתי פרוקסי חוצי-עננים יש קישוריות יוצאת של HTTPS ו-gRPC אל *.googleapis.com ביציאת TCP‏ 443.

הגדרת בדיקת TLS

מגדירים בדיקת Transport Layer Security (TLS) כדי לוודא ש-Agent Gateway ל-cross-cloud יכול לבדוק ולנהל את התנועה היוצאת.

אבטחת הסוד של רשות האישורים לבדיקת TLS

ב-Agent Gateway ל-cross-cloud, רשות אישורי בסיס (CA) מנפיקה את האישורים שמוצגים כשהוא בודק תעבורת נתונים יוצאת ב-TLS. הבקר יוצר את רשות האישורים הזו כשהוא מתחיל לפעול. רשות האישורים, כולל המפתח הפרטי שלה, מאוחסנת במשאבי Secret של Kubernetes בשני מרחבי שמות: מרחב השמות של הבקר (geap-system) ומרחב השמות של השער, שבו פרוסים Agent Gateway לשרת proxy חוצה-עננים ו-AIR sidecar. כל מי שיכול לקרוא את המשאבים האלה של Secret יכול להתחזות לנקודות קצה חיצוניות בעומסי העבודה של הסוכן. כדי להגן על ה-CA, צריך להפעיל את אמצעי ההגנה הבאים:

  • הגבלת הגישה של RBAC ל-Secret: הגבלת ההרשאות get,‏ list ו-watch במשאבי Secret במרחבי השמות geap-system ו-gateway ל-Agent Gateway לחשבונות שירות חוצי-עננים ולאדמינים ייעודיים של הפלטפורמה. ההרשאות list ו-watch חושפות גם את התוכן של Secret.
  • בידוד מרחבי השמות של הבקר והשער: משתמשים שיכולים ליצור פודים במרחב שמות יכולים לטעון כל Secret במרחב השמות הזה. מריצים רק את Agent Gateway לרכיבים חוצי-עננים במרחב השמות geap-system ובמרחב השמות של השער. אל תפרסו עומסי עבודה של סוכנים או פודים אחרים במרחבי השמות האלה. הגבילו את ההרשאות ליצירה או לשינוי של פודים, פריסות ומשאבים אחרים של עומסי עבודה במרחבי השמות האלה לאדמינים מהימנים.
  • הצפנת נתונים במנוחה של Secret: הפעילו הצפנה במנוחה למשאבי Secret במאגר הנתונים etcd של האשכול. אם אפשר, השתמשו בספק KMS כדי לנהל את מפתחות ההצפנה.
  • ביקורת על הגישה אל Secret: מפעילים את רישום הביקורת ביומן של Kubernetes ומנטרים את גישת הקריאה אל ה-CA Secret.

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