גישה פרטית ל-Apigee מ-Gemini Enterprise Agent Platform

הדף הזה רלוונטי ל-Apigee, אבל לא ל-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

במאמר הזה מוסבר איך להגדיר קישוריות פרטית מסוכן שנפרס ב-Agent Runtime של Gemini Enterprise Agent Platform לממשקי API ולכלים של Model Context Protocol‏ (MCP) שפורסמו ב-Apigee, באמצעות Private Service Connect. בתבנית הזו, התנועה מהסוכן אל Apigee נשארת פרטית לחלוטין ולא עוברת דרך האינטרנט הציבורי.

סקירה כללית

‫Agent Runtime פורס את הסוכן ברשת מאובטחת שמנוהלת על ידי Google, בלי גישה לרשת הענן הווירטואלי הפרטי (VPC). באופן דומה, פלטפורמת Apigee פועלת ברשת מאובטחת שמנוהלת על ידי Google. אם רוצים שהשיחות של סוכן עם מודל שפה גדול (LLM) או עם כלי MCP שנחשפים דרך Apigee יתבצעו באופן פרטי, צריך לגשר בין שתי הרשתות שמנוהלות על ידי Google באמצעות רשת VPC שאתם שולטים בה.

במסמך הזה מתוארת התבנית הבאה לגשר הזה:

בהגדרה הזו, כשהסוכן שלכם מבצע קריאה ל-https://APIGEE_HOSTNAME/..., הבקשה מנותבת לכתובת ה-IP של נקודת הקצה של Private Service Connect ב-VPC, מועברת דרך קובץ השירות למופע Apigee שלכם ומעובדת על ידי ה-proxy ל-API שתואם לנתיב הבקשה.

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

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

  • ‫APIGEE_PROJECT_ID: Google Cloud מזהה הפרויקט שמכיל את הארגון שלכם ב-Apigee.
  • ‫SERVICE_PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו אתם פורסים את הסוכן ב-Agent Runtime. יכול להיות שזה יהיה אותו פרויקט כמו APIGEE_PROJECT_ID או פרויקט אחר, בהתאם לאופן שבו אתם מארגנים את המשאבים שלכם ב-Google Cloud.
  • ‫SERVICE_PROJECT_NUMBER: מספר הפרויקט המספרי של SERVICE_PROJECT_ID. אפשר לאחזר אותו באמצעות הפקודה gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
  • ‫HOST_PROJECT_ID: מזהה הפרויקט Google Cloud שמכיל את רשת ה-VPC של הלקוח, את תת-הרשת ואת האזור הפרטי של Cloud DNS. הערך הזה זהה לערך של SERVICE_PROJECT_ID, אלא אם משתמשים בVPC משותף. במקרה כזה, זהו הפרויקט המארח שאליו מצורף פרויקט השירות.
  • ‫REGION: האזור של מכונת Apigee (לדוגמה, us-west1).
  • ‫VPC_NAME: השם של רשת ה-VPC של הצרכן ב-HOST_PROJECT_ID.
  • ‫SUBNET_NAME: השם של תת-רשת ב-VPC_NAME שנמצאת ב-REGION.
  • ‫APIGEE_HOSTNAME: שם המארח שהגדרתם בקבוצת הסביבות של Apigee (לדוגמה, api.internal.example.com).
  • ‫BASE_PATH: נתיב הבסיס של ה-proxy ל-API שפריסתם ב-Apigee (לדוגמה, /mcp או /orders).
  • ‫PARENT_DNS_NAME: דומיין ה-DNS הראשי של APIGEE_HOSTNAME שרוצים להציג מאזור פרטי (לדוגמה, internal.example.com.). הערך חייב להסתיים בנקודה.
  • ‫APIGEE_INSTANCE_NAME: השם של מופע Apigee ב-REGION.

תצטרכו את הפרטים הבאים:

  • פרויקט אחד או יותר ב-Google Cloud (כפי שמתואר בהערה הקודמת) שהחיוב בהם מופעל.
  • ארגון Apigee קיים ב-APIGEE_PROJECT_ID עם לפחות מופע אחד. במסמך הזה נוצרים כל משאבי הרשת של הצרכן (קובץ מצורף עם הרשת, נקודת קצה של Private Service Connect, פריסת Agent Runtime) באותו אזור שבו נמצא מופע Apigee שלכם, וזו ההגדרה הפשוטה ביותר.
  • קבוצת סביבות שהסביבות שלה נפרסות באותו מופע של Apigee, וכוללת את שם המארח שהסוכן צריך להתקשר אליו. במסמך הזה, שם המארח הזה נקרא APIGEE_HOSTNAME.
  • לפחות proxy ל-API אחד שנפרס בסביבה בקבוצת הסביבות הזו. צריך לוודא שאפשר להגיע לכל שרת proxy שהסוכן צריך להתקשר אליו בכתובת https://APIGEE_HOSTNAME/BASE_PATH.
  • רשת VPC ותת-רשת ב-HOST_PROJECT_ID, באותו אזור שבו נמצאת מכונת Apigee. במסמך הזה, אנחנו מתייחסים אליהם כאל VPC_NAME ו-SUBNET_NAME. ‫Agent Runtime דורש רשת משנה (subnet) של /28 לפחות, ומטיל הגבלות נוספות על טווחים. פרטים נוספים מופיעים בקטע דרישות לגבי טווח כתובות ה-IP של רשת המשנה במסמכי התיעוד של Agent Platform.
  • ממשקי ה-API הבאים מופעלים בפרויקט המתאים:
    • ‫Apigee ‏ (apigee.googleapis.com) ב-APIGEE_PROJECT_ID.
    • ‫Compute Engine ‏ (compute.googleapis.com) ו-Cloud DNS ‏(dns.googleapis.com) ב-HOST_PROJECT_ID.
    • ‫Agent Platform‏ (aiplatform.googleapis.com) ב-SERVICE_PROJECT_ID.
  • הרשאות IAM מספיקות ליצירת אזורים ורשומות של Cloud DNS, כתובות של Compute Engine, צירופי רשת וכללי העברה של Private Service Connect ב-HOST_PROJECT_ID, ולעדכון ההגדרה של מופע Apigee וקבוצת סביבות ב-APIGEE_PROJECT_ID. פרטים על התפקידים הנדרשים מופיעים במאמרים תפקידים ב-Apigee, בקרת גישה ב-Cloud DNS ותפקידי IAM ב-Compute Engine.

ארכיטקטורה

בשלבים הבאים מתואר זרימת התנועה בין סוכן שפרוס ב-Agent Runtime לבין proxy ל-API שמתארח ב-Apigee, באמצעות נקודת קצה (endpoint) של Private Service Connect ב-VPC של הצרכן כגשר.

  1. הסוכן, שפועל ב-Agent Runtime, שולח בקשת HTTPS אל APIGEE_HOSTNAME.
  2. קישור בין רשתות שכנות (peering) של DNS שהוגדר בממשק PSC של Agent Runtime מעביר את החיפוש לאזור הפרטי של Cloud DNS ב-VPC של הצרכן, שמחזיר את כתובת ה-IP של נקודת הקצה (endpoint) של Private Service Connect.
  3. הבקשה של הסוכן יוצאת דרך ממשק ה-PSC אל רשת ה-VPC של הצרכן ומגיעה לנקודת הקצה של Private Service Connect בכתובת ה-IP הזו.
  4. נקודת הקצה של Private Service Connect מעבירה את הבקשה דרך חיבור השירות לקובץ המצורף עם השירות של מופע Apigee.
  5. מופעלת הפסקת TLS במופע Apigee, שם המארח של הבקשה מותאם לקבוצת הסביבות, והבקשה מנותבת ל-API proxy הנכון.

שלב 1: הגדרת רשת ב-VPC של הצרכן

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

  • משאבי Cloud DNS (תחום פרטי ורשומה) נוצרים ב-HOST_PROJECT_ID, כי התחום הפרטי מצורף לרשת ה-VPC של הצרכן.
  • משאבי נקודת הקצה (endpoint) של Private Service Connect (כתובת IP פנימית סטטית וכלל העברה) והקובץ המצורף לרשת נוצרים ב-SERVICE_PROJECT_ID. כל אחת מהפקודות האלה משתמשת בהפניה בין-פרויקטית לרשת המשנה המשותפת או לרשת ה-VPC ב-HOST_PROJECT_ID. בפריסה של פרויקט יחיד, SERVICE_PROJECT_ID ו-HOST_PROJECT_ID זהים, ולכן לא מתבצעים שינויים בבעלות בין השלבים. מידע נוסף על מודל ה-VPC המשותף לנקודות קצה של Private Service Connect זמין במאמר יצירת נקודת קצה בפרויקט שירות של VPC משותף.

יצירת תחום פרטי ב-Cloud DNS

יוצרים תחום פרטי ב-Cloud DNS שגלוי רק ל-VPC של הצרכן. הסוכן משתמש באזור הזה (באמצעות DNS peering) כדי לפתור את APIGEE_HOSTNAME לכתובת IP פרטית. 

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

מידע נוסף על אזורים פרטיים ב-Cloud DNS זמין במאמר אזורים פרטיים.

יצירת צירוף רשת

יוצרים חיבור לרשת באותו אזור ובאותה רשת משנה שבהם רוצים שממשק ה-PSC של Agent Runtime יופיע. Agent Runtime מאגדת את ממשק ה-PSC שלה לצירוף הזה כשהסוכן נפרס.

בפריסה של פרויקט יחיד, יוצרים את מחבר הרשת ב-SERVICE_PROJECT_ID (שהוא גם HOST_PROJECT_ID). בפריסה של VPC משותף, אפשר ליצור את מחבר הרשת בפרויקט השירות או בפרויקט המארח. Agent Platform ממליצה ליצור את מחבר הרשת בפרויקט השירות כדי לפשט את ההרשאות. במאמר שימוש בממשק Private Service Connect עם VPC משותף מוסבר איך לבחור את תפקידי ה-IAM המתאימים.

הפקודה הבאה יוצרת את קובץ הרשת המצורף ב-SERVICE_PROJECT_ID. בפריסת VPC משותף, ההפניה לתת-הרשת חייבת לכלול את מזהה הפרויקט המארח. 

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

שמירת כתובת IP פנימית סטטית

שומרים כתובת IP פנימית לשימוש ככתובת ה-IP של נקודת הקצה (endpoint) של Private Service Connect שאליה הסוכן מתחבר. יוצרים את משאב הכתובת ב-SERVICE_PROJECT_ID, ומפנים לרשת המשנה המשותפת ב-HOST_PROJECT_ID כדי שהערך של הכתובת יוקצה מתוך הטווח של רשת המשנה הזו. ההגדרה הזו תואמת להנחיות בנושא VPC משותף במאמר שימוש בכתובת IP פנימית סטטית עם VPC משותף. 

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

מאחזרים את הכתובת השמורה, שבה תשתמשו בשלבים הבאים: 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

במסמך הזה, הכתובת הזו נקראת PSC_ENDPOINT_IP.

איך מקבלים את קובץ השירות המצורף למופע Apigee

מאחזרים את ה-URI של קובץ השירות של מופע Apigee באמצעות השיטה organizations.instances.get של Apigee API. משתמשים ב-URI הזה כיעד לנקודת הקצה של Private Service Connect. 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

התשובה כוללת את השדה serviceAttachment. במסמך הזה, הערך הזה נקרא APIGEE_SERVICE_ATTACHMENT. מידע נוסף על האופן שבו Apigee חושף קובץ מצורף של שירות בכל מופע זמין במאמר בנושא ניהול מופעים.

יצירת נקודת הקצה של Private Service Connect

יוצרים כלל העברה שפועל כנקודת קצה של Private Service Connect. היא מיועדת ל-Apigee service attachment ומשתמשת בכתובת ה-IP הסטטית שהזמנתם. יוצרים את כלל ההעברה ב-SERVICE_PROJECT_ID ומפנים לרשת ה-VPC המשותפת ב-HOST_PROJECT_ID ולכתובת ב-SERVICE_PROJECT_ID. 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

מוודאים ששירות Apigee קיבל את החיבור: 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

הסטטוס צריך להיות ACCEPTED כדי שהנקודה תעביר תנועה. מידע נוסף על נקודות קצה של Private Service Connect זמין במאמר מידע על גישה לשירותים שפורסמו דרך נקודות קצה.

הוספת רשומת DNS לשם המארח

באזור הפרטי, יוצרים רשומת A שמפנה את APIGEE_HOSTNAME אל PSC_ENDPOINT_IP. הרשומה הזו גלויה רק בתוך VPC_NAME, ולכן לקוחות חיצוניים ממשיכים להחזיר את כתובת ה-IP של שם המארח דרך DNS ציבורי. 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

שלב 2: הגדרה של Apigee

הוספת פרויקט השירות לרשימת הצרכנים המותרים של המופע

מופע Apigee מקבל רק חיבורים מסוג Private Service Connect מפרויקטים של צרכנים שנמצאים ב-consumerAcceptList שלו. הצד הצרכני של החיבור משויך ל-SERVICE_PROJECT_ID, כי זה הפרויקט שבו הסוכן נפרס.

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

קודם כל, בודקים את הערך הנוכחי של consumerAcceptList באמצעות השיטה organizations.instances.get: 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

מחפשים את השדה consumerAcceptList בתשובה.

לאחר מכן מעדכנים את הרשימה באמצעות הקריאה לשיטה organizations.instances.patch עם מסיכת עדכון ב-consumerAcceptList. מכיוון שהשדה מחליף את הרשימה הקיימת, צריך לכלול בו את כל מזהי הפרויקטים שצריכים לשמור על הגישה, כולל APIGEE_PROJECT_ID וכל פרויקט שירות נוסף שבו נפרסו סוכנים: 

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

כדי לאשר את העדכון, מריצים שוב את הפקודה get ומוודאים שהערך SERVICE_PROJECT_ID נכלל עכשיו ב-consumerAcceptList.

אימות שם המארח של קבוצת הסביבות

מוודאים ש-APIGEE_HOSTNAME מופיע בקבוצת הסביבות שמארחת את שרתי ה-proxy של ה-API. אם הוא לא מופיע, מוסיפים אותו.

הוראות מפורטות מופיעות במאמר בנושא עבודה עם קבוצות סביבה.

שלב 3: פריסת הסוכן באמצעות ממשק PSC ו-DNS peering

כשפורסים את הסוכן ב-Agent Runtime, מגדירים אותו עם ממשק PSC שמפנה למחבר הרשת שיצרתם, ומגדירים קישור בין רשתות שכנות (peering) של DNS לאזור הפרטי. הוראות מלאות לפריסה ומסגרות נתמכות זמינות במאמרים שימוש בממשק Private Service Connect עם Agent Runtime ופריסת סוכנים במסמכי Agent Platform.

מגדירים את שני השדות הבאים בממשק PSC של הסוכן (ראו את ההפניה PscInterfaceConfig):

  • ‫networkAttachment: מגדירים את הערך הזה לשם המשאב המלא של מחבר הרשת שנוצר בשלב 1, בתבנית projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. אם יצרתם את הקובץ המצורף של הרשת בפרויקט המארח, השתמשו ב-HOST_PROJECT_ID בנתיב הזה.
  • ‫dnsPeeringConfigs: מוסיפים רשומה אחת עם השדות הבאים, כדי ש-Agent Runtime יפתור את APIGEE_HOSTNAME דרך האזור הפרטי:
    • domain: PARENT_DNS_NAME. הערך חייב להסתיים בנקודה.
    • targetProject: HOST_PROJECT_ID. זהו הפרויקט שמכיל את ה-VPC של הצרכן ואת האזור הפרטי.
    • targetNetwork: VPC_NAME.

לסוכן השירות של Agent Platform Service‏ SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) צריכה להיות הרשאה להגדיר DNS peering ולעדכן את קובץ הצירוף לרשת. מקצים את התפקידים הנדרשים כמו שמתואר במאמר בנושא התפקיד הנדרש לסוכן השירות של Agent Platform. בפריסת VPC משותף, חלים תפקידים נוספים על הפרויקט המארח. מידע נוסף זמין במאמר שימוש בממשק Private Service Connect עם VPC משותף.

מקוד הסוכן, שולחים קריאה ל-proxy ל-API בכתובת https://APIGEE_HOSTNAME/BASE_PATH. בסביבת Agent Runtime, שם המארח הזה עובר התאמת נתונים (resolve) באמצעות קישור בין רשתות DNS שכנות (peering) ל-PSC_ENDPOINT_IP, והבקשה עוברת דרך נקודת הקצה (endpoint) של Private Service Connect אל ה-VPC שלכם ואל Apigee.

אימות הנתיב הפרטי

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

  • מוודאים שהסטטוס של כלל ההעברה הוא ACCEPTED באמצעות הפקודה בקטע יצירת נקודת קצה של Private Service Connect.
  • ממכונה וירטואלית של Compute Engine שמצורפת ל-VPC_NAME ב-REGION (בפריסת VPC משותף, המכונה הווירטואלית יכולה להיות בפרויקט המארח או בפרויקט שירות שמצורף ל-VPC המשותף), מריצים את dig +short APIGEE_HOSTNAME. התוצאה חייבת להיות PSC_ENDPOINT_IP. כך מוודאים שהאזור הפרטי פותר את שם המארח בצורה נכונה בתוך ה-VPC.
  • באותה מכונה וירטואלית, שולחים בקשה ל-proxy ל-API שפרסתם בכתובת https://APIGEE_HOSTNAME/BASE_PATH ומאשרים שקיבלתם את התשובה הצפויה.
  • מפעילים את הסוכן שפרסתם ומוודאים שהבקשה מטופלת. לאחר מכן משתמשים ב-Apigee Analytics או ב-Debug כדי לוודא שהבקשה הגיעה ל-API proxy הצפוי בשם המארח של קבוצת הסביבות.

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