במאמר הזה מוסבר איך לבצע משימות תחזוקה אחרי הפריסה של משאבי Agent Gateway. אם עדיין לא יצרתם שער, קראו את המאמר הגדרת Agent Gateway.
לפני שמתחילים
לפני שאתם מנהלים את המשאבים של Agent Gateway, ודאו שאתם עומדים בדרישות המוקדמות הבאות:
- מוודאים שיש לכם את ההרשאות הנדרשות כדי להציג, לעדכן ולמחוק שערים, תבניות קישוריות, כללי מדיניות הרשאה ותוספים שמפנים לבדיקת הרשאות. לרשימה המלאה של ההרשאות, ראו ההרשאות הנדרשות.
- מפעילים את השירותים הנדרשים בפרויקט. לפרטים נוספים, קראו את המאמר ממשקי API נדרשים.
- אם אתם מתכננים לבטל את השיוך של עומסי עבודה לשער, ודאו שיש לכם גם הרשאות לנהל את הפריסות של Agent Runtime ב-Gemini Enterprise Agent Platform או את האפליקציות של Gemini Enterprise.
הצגה ובדיקה של שערים
אתם יכולים להציג את רשימת המשאבים של Agent Gateway בפרויקט ב- Google Cloud, ולבדוק את ההגדרות של השער, את התוספים שמצורפים אליו ואת המטא-נתונים לפלט בלבד.
המסוף
נכנסים לדף Gateways במסוף Google Cloud .
צפייה ברשימת השערים בפרויקט שנבחר.
לוחצים על שם השער כדי לפתוח את דף הפרטים שלו:
- בכרטיסייה Details, בודקים את הקטעים Overview, Access authorization, AI Security, Service Extensions ו-VPC configuration.
- בכרטיסייה Observability, בודקים את מדדי התנועה והמדיניות של השער. איך עוקבים אחרי התנועה ב-Agent Gateway
gcloud
הצגת רשימה של כל השערים באזור ספציפי:
gcloud network-services agent-gateways list \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את מה שכתוב בשדות הבאים:
-
LOCATION: האזור שבו נפרסו השערים, למשלus-central1. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloudשמארח את השערים.
-
בודקים את ההגדרות של שער ספציפי:
gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
AGENT_GATEWAY_NAMEבשם של המשאב Agent Gateway.
הגדרות שלא ניתן לשנות
את רוב ההגדרות של Agent Gateway, כמו המופעים המשויכים של Agent Registry ומדיניות האבטחה והפיקוח, אפשר לשנות במקום, כמו שמתואר במאמר עדכון של Agent Gateway. עם זאת, הגדרות ליבה מסוימות לא ניתנות לשינוי, וצריך לפרוס שער חלופי. לפני שמשנים את השערים, כדאי לעיין בטבלה הבאה:
| הגדרה | יכולת שינוי | דרישה או הגבלה |
|---|---|---|
| שם השער והאזור | לא ניתן לשינוי | כדי לשנות את השם או האזור, צריך לפרוס שער חלופי. |
נתיב גישה מנוהל ( |
לא ניתן לשינוי | מוגדר בזמן היצירה ב-googleManaged.governedAccessPath. אי אפשר לשנות את המיקום. |
מחבר רשת של Private Service Connect ( |
אי אפשר לשנות את השדה אחרי שמגדירים אותו | אחרי שמשייכים חיבור לרשת לשער, אי אפשר לשנות או להסיר אותו. |
תבנית הקישוריות של הנציג והגדרות ה-VPC, ה-TLS וה-DNS המשויכות אליה |
ניתן לשינוי באופן מותנה | אפשר לעדכן את ההגדרות של השער כך שיפנו לתבנית קישוריות אחרת עם הגדרות חדשות, כל עוד התבנית החדשה עדיין מפנה לאותו networkAttachment. |
החלפת שער כדי לשנות הגדרות שלא ניתנות לשינוי
אם אתם צריכים לשנות הגדרה שלא ניתנת לשינוי, כמו מחבר הרשת של PSC שמשויך לשער, אתם צריכים לפרוס שער חלופי ולהעביר את עומסי העבודה לשער החדש:
- יוצרים את ה-Agent Gateway החלופי ומגדירים את מדיניות ההרשאות וניהול הזהויות והרשאות הגישה (IAM) שלו. איך מגדירים את Agent Gateway
מעדכנים את עומסי העבודה כך שישתמשו בשער החלופי:
- אפליקציות Gemini Enterprise: מעדכנים את שם המשאב של השער בהגדרות אבטחה > הגדרה של האפליקציה. ניתוב התנועה של Gemini Enterprise דרך Agent Gateway
- סוכני Agent Runtime: בפרויקט ובאזור אחד, כל סוכני Agent Runtime חייבים להיות מקושרים לאותו שער. אי אפשר לעדכן ישירות שער אחד לשער אחר. כדי להעביר את הנציגים:
- מוודאים שכל סוכן מקושר מנתב 100% מהתנועה לגרסה האחרונה שלו (
trafficConfig.trafficSplitAlwaysLatest). - מבטלים את השיוך של כל הסוכנים בפרויקט ובאזור לשער הקודם, על ידי הגדרת
spec.deploymentSpec.agentGatewayConfigל-{}באמצעותreasoningEngines.patch, וממתינים עד שכל פעולת עדכון תסתיים. - מפעילים את
reasoningEngines.patchבכל סוכן כדי להגדיר אתspec.deploymentSpec.agentGatewayConfigלשם המשאב של שער ההחלפה. במאמר ניתוב תנועה של Agent Runtime דרך Agent Gateway מופיעות דוגמאות לבקשות.
- מוודאים שכל סוכן מקושר מנתב 100% מהתנועה לגרסה האחרונה שלו (
אחרי שכל עומסי העבודה מפסיקים להפנות לשער הקודם, פועלים לפי השלבים שמפורטים בקטע מחיקת Agent Gateway כדי להסיר את השער הקודם.
עדכון של Agent Gateway
אתם יכולים לעדכן הגדרות מסוימות של Agent Gateway ישירות במסוף Google Cloud , או להשתמש ב-CLI של gcloud כדי לייצא את הגדרות השער לקובץ YAML, לבצע את השינויים ולייבא מחדש את הקובץ.
עדכון מרשם הסוכנים
אפשר לעדכן את Agent Registry שמשויך במסוףGoogle Cloud או ב-CLI של gcloud. השער צריך להפנות למרשם האזורי היחיד שתואם לאזור של השער. אם השער מקושר לאפליקציית Gemini Enterprise, השער צריך לכלול מרשם אחד שתואם למיקום של האפליקציה.
המסוף
נכנסים לדף Gateways במסוף Google Cloud .
לוחצים על השם של השער שרוצים לעדכן.
בכרטיסייה Details, בקטע Overview לוחצים על Edit registries.
בוחרים את ה-Agent Registry האזורי שתואם לאזור שבו השער פרוס, ולוחצים על Save.
gcloud
מייצאים את הגדרות השער אל agent-gateway.yaml באמצעות gcloud
network-services agent-gateways export, עורכים את registries, description או labels (מסירים שדות פלט בלבד כמו createTime, updateTime, agentGatewayCard ו-selfLink) ומייבאים מחדש את הקובץ באמצעות gcloud network-services agent-gateways import, כמו שמוסבר בקטע עדכון תבנית הקישוריות של השער.
עדכון תבנית הקישוריות
אפשר לעדכן את תבנית הקישוריות של משאב Agent Gateway באמצעות ה-CLI של gcloud.
gcloud
יוצרים
AgentConnectivityTemplateחדש עם הגדרות הקישוריות המעודכנות, ומוודאים שהוא משתמש באותוnetworkAttachmentכמו השער הקיים. במאמר הגדרת Agent Gateway עם קישוריות VPC מוסבר בפירוט איך להגדיר את התבנית ומה התחביר שלה.מייצאים את הגדרת השער הקיימת לקובץ YAML:
gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \ --destination="agent-gateway.yaml" \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את מה שכתוב בשדות הבאים:
-
AGENT_GATEWAY_NAME: שם השער שרוצים לעדכן. -
LOCATION: האזור שבו נפרס שער הגישה. -
PROJECT_ID: מזהה הפרויקט שבו נפרס שער הגישה.
-
בקובץ
agent-gateway.yamlשיוצא, משאירים את השדותprotocols,registries,descriptionו-labelsכמו שהם, מסירים את השדות לפלט בלבד (createTime,updateTime,agentGatewayCard,selfLink) ומעדכנים אתagentConnectivityTemplateכך שיפנה לתבנית החדשה:name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME protocols: - MCP googleManaged: governedAccessPath: AGENT_TO_ANYWHERE registries: - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAMEמחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_NUMBER: מספר הפרויקט שבו השער נפרס (ב-agentConnectivityTemplateצריך להזין את מספר הפרויקט ולא את מזהה הפרויקט). -
LOCATION: האזור של השער. -
AGENT_GATEWAY_NAME: שם השער. -
NEW_TEMPLATE_NAME: השם של תבנית הקישוריות החלופית.
-
מייבאים מחדש את קובץ ה-YAML המעודכן כדי להחיל את השינויים:
gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \ --source="agent-gateway.yaml" \ --location=LOCATION \ --project=PROJECT_ID
אופציונלי: מוחקים את תבנית הקישוריות הקודמת אחרי שעדכון השער מסתיים:
gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \ --location=LOCATION \ --project=PROJECT_ID
לשנות את הגדרות ה-IAP או את התבניות של Model Armor
כדי לשנות את הגדרות האכיפה של IAP ואת התבניות של Model Armor, אתם יכולים לעדכן את התוספים שמפנים לבדיקת הרשאות שמצורפים לשער.
המסוף
נכנסים לדף Gateways במסוף Google Cloud .
לוחצים על השם של השער שרוצים לעדכן.
בכרטיסייה פרטים, מעדכנים את תוספי האבטחה המצורפים:
שינוי מצב האכיפה של IAP: בקטע Access authorization, לצד Access authorization, לוחצים על Edit access authorization. בוחרים באפשרות ביקורת בלבד (מצב פרימטר לבדיקות) או אכיפת כללי מדיניות, ואז לוחצים על שמירה.
שינוי התבניות של Model Armor: בקטע AI Security, לוחצים על Edit request template ליד Template for requests או על Edit response template ליד Template for responses. בוחרים את התבנית החלופית ולוחצים על שמירה.
gcloud
מציגים את רשימת התוספים שמפנים לבדיקת הרשאות באזור של השער כדי לזהות את שם התוסף:
gcloud service-extensions authz-extensions list \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
LOCATIONבאזור של השער ואתPROJECT_IDבמזהה הפרויקט.בודקים את ההגדרות הנוכחיות של התוסף:
gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID \ --format=yaml
מחליפים את
AUTHZ_EXTENSION_NAMEבשם של המשאב ב-IAP או ב-Model ArmorAuthzExtension.שומרים את מפרט התוסף המעודכן ב-
authz-extension.yaml, ומשמיטים שדות פלט בלבד כמוcreateTimeו-updateTime:בתוסף IAP: מוסיפים את
iamEnforcementMode: "DRY_RUN"למצב ביקורת בלבד, או מסירים אתiamEnforcementModeכדי לאכוף את כללי המדיניות:name: AUTHZ_EXTENSION_NAME service: iap.googleapis.com failOpen: false timeout: 1s metadata: iapPolicyVersion: "V2" iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policiesבתוסף Model Armor: מעדכנים את
request_template_idו-response_template_idב-metadata.model_armor_settings:name: AUTHZ_EXTENSION_NAME service: modelarmor.LOCATION.rep.googleapis.com failOpen: false timeout: 1s metadata: model_armor_settings: '[ { "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID", "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID" } ]'מחליפים את מה שכתוב בשדות הבאים:
-
AUTHZ_EXTENSION_NAME: השם של המשאבAuthzExtensionב-Model Armor. -
LOCATION: האזור של השער. -
MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמארח את התבניות של Model Armor. -
REQUEST_TEMPLATE_IDו-RESPONSE_TEMPLATE_ID: המזהים של תבניות הבקשה והתשובה.
מוודאים שלחשבון השירות של השער (
agentGatewayCard.serviceExtensionsServiceAccount) יש את התפקידroles/modelarmor.userבכל פרויקט תבנית חדש שמפנים אליו, וגם את התפקידיםroles/modelarmor.calloutUserו-roles/serviceusage.serviceUsageConsumerבפרויקט השער (ראו הקצאת הרשאות).-
מייבאים את קובץ ה-YAML המעודכן של התוסף:
gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \ --source="authz-extension.yaml" \ --location=LOCATION \ --project=PROJECT_ID
כדי לצרף כללי מדיניות הרשאה חדשים או לשנות את הכללים להתאמת תנועה ב-AuthzPolicy קיים, קראו את המאמר הקצאת הרשאות.
ביטול השיוך של עומסי עבודה ל-Agent Gateway
כדי למחוק Agent Gateway, צריך לבטל את השיוך של כל אפליקציית Gemini Enterprise וכל סוכן Agent Runtime שמפנים אל ה-gateway.
ביטול השיוך של אפליקציית Gemini Enterprise
אפשר לבטל את הקישור של Agent Gateway לאפליקציית Gemini Enterprise במסוף Google Cloud :
נכנסים לדף Gemini Enterprise במסוף Google Cloud .
לוחצים על השם של האפליקציה שמשויכת לשער.
לוחצים על אבטחה.
בכרטיסייה Configuration, בקטע Agent Gateway configuration, מוחקים את השדה Agent Gateway resource name.
לוחצים על Save.
אם מבטלים את השיוך של Agent Gateway, התנועה היוצאת של האפליקציה מפסיקה לעבור דרך השער. הסוכנים והשרתים של Model Context Protocol (MCP) שיובאו נשארים רשומים ב-Agent Registry, אבל לאפליקציה אין גישה אליהם עד שמקשרים שוב שער. חשוב לזכור שהשער החדש צריך להפנות לאותו מרשם סוכנים.
ביטול השיוך של סוכן Agent Runtime
אי אפשר לשנות את הקישורים של שער Agent Runtime במסוף Google Cloud וב-CLI של gcloud. כדי לבטל את השיוך של Agent Gateway לסוכן Agent Runtime פרוס, בלי להפסיק את הפעולה של הסוכן, אתם יכולים להפעיל את ה-method של ה-API בארכיטקטורת REST reasoningEngines.patch כדי למחוק את spec.deploymentSpec.agentGatewayConfig:
מוודאים שהנציג מנתב את כל התנועה לגרסה האחרונה (
trafficConfig.trafficSplitAlwaysLatestמוגדר ל-true, או שלא הוגדר פיצול ידני שלtrafficConfig). אם חלוקת התנועה של גרסה ידנית פעילה, אי אפשר לנקות או לשנות את הקישור לשער, וכל הגרסאות הקודמות מועברות לארכיון באופן בלתי הפיך. פרטים נוספים זמינים במאמר Agent Gateway וגרסאות.שולחים בקשת
PATCHלמנוע החשיבה הרציונלית עםupdateMask=spec.deploymentSpec.agentGatewayConfigואובייקטagentGatewayConfigריק ({}):curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": {} } } }' \ "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"מחליפים את מה שכתוב בשדות הבאים:
-
REGION: האזור שבו הסוכן פרוס. -
PROJECT_ID: מזהה הפרויקט שבו הנציג פרוס. -
RESOURCE_ID: מזהה המשאב של הנציג.
-
מחיקת Agent Gateway
Agent Gateway אוכף מעקב קפדני אחרי הפניות כדי למנוע מדיניות אבטחה מיותרת ונתיבי תנועה לא תקינים של נציגים. אי אפשר למחוק שער, והלחצן Delete במסוף Google Cloud לא זמין, אם מתקיים אחד מהתנאים הבאים:
- יש לפחות סוכן אחד של Agent Runtime או אפליקציה אחת של Gemini Enterprise שעדיין מפנים לשער.
- כל
AuthzPolicy(ל-IAP, להגנה מוגברת על המודל או לספק בהתאמה אישית) אוTelemetryPolicyעדיין מטרגטים את השער. - פעולת עדכון של הגדרת VPC עדיין פועלת בשער.
כדי למחוק את Agent Gateway ולנקות את המשאבים שמשויכים אליו, מבצעים את הפעולות הבאות לפי הסדר:
המסוף
- מוודאים שאין אפליקציות של Gemini Enterprise או סוכנים של Agent Runtime שמפנים לשער. פועלים לפי ההוראות במאמר ביטול השיוך של עומסי עבודה ל-Agent Gateway.
נכנסים לדף Gateways במסוף Google Cloud .
לוחצים על שם השער שרוצים למחוק.
בכרטיסייה Details, מסירים את כל שיוכי המדיניות שמטרגטים את השער:
- אם מופיע הקטע Access authorization, לוחצים על Remove ומאשרים את המחיקה. הפעולה הזו מוחקת גם את
AuthzPolicyשל ה-IAP וגם אתAuthzExtensionשלו. - אם מופיע הקטע AI Security, לוחצים על Remove ומאשרים את המחיקה. הפעולה הזו מוחקת גם את
AuthzPolicyשל Model Armor וגם אתAuthzExtensionשלו. - בודקים את הטבלה Service Extensions. אם נשארו משאבי
AuthzPolicyמותאמים אישית, צריך להשתמש בכרטיסייה gcloud בתהליך הזה כדי למחוק אותם לפני שממשיכים.
- אם מופיע הקטע Access authorization, לוחצים על Remove ומאשרים את המחיקה. הפעולה הזו מוחקת גם את
אחרי שמסירים את כל שיוכי המדיניות ואין עדכון VPC בתהליך, לוחצים על Delete ומאשרים את המחיקה.
מוודאים שהשער לא מופיע יותר ברשימה Gateways של הפרויקט.
אופציונלי: אם אין שער אחר שמשתמש במשאבי הקישוריות, אפשר לנקות אותם. בכרטיסייה gcloud, מוחקים את
AgentConnectivityTemplateומוחקים את חיבור הרשת.
gcloud
- מוודאים שאין אפליקציות של Gemini Enterprise או סוכנים של Agent Runtime שמפנים לשער. פועלים לפי ההוראות במאמר ביטול השיוך של עומסי עבודה ל-Agent Gateway.
מסירים את כללי מדיניות ההרשאות ואת התוספים שמפנים לבדיקת הרשאות:
מציגים את מדיניות ההרשאות באזור של השער כדי למצוא כללי מדיניות שהשדה
target.resourcesשלהם מפנה לשער, ורושמים את כל הערכים שלauthzExtensionsשאליהם מפנים:gcloud network-security authz-policies list \ --location=LOCATION \ --project=PROJECT_ID \ --format="yaml(name,target.resources,customProvider.authzExtension.resources)"
מחליפים את
LOCATIONבאזור של השער ואתPROJECT_IDבמזהה הפרויקט.מוחקים כל
AuthzPolicyשמטרגט את השער:gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
AUTHZ_POLICY_NAMEבמזהה של כל מדיניות הרשאה שמטרגטת את השער (לדוגמה,AGENT_GATEWAY_NAME-iap-authzpolicyאוAGENT_GATEWAY_NAME-aisecurity-authzpolicyלמדיניות שנוצרה במסוף).אופציונלי: אחרי שמוחקים את המשאבים של
AuthzPolicyשמפנים למשאבים של , מוחקים את המשאבים שלAuthzExtensionשלא נמצאים בשימוש של כללי מדיניות אחרים:gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
AUTHZ_EXTENSION_NAMEבמזהה של תוסף שמפנה לבדיקת הרשאות שלא בשימוש.
מוחקים את Agent Gateway:
gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
AGENT_GATEWAY_NAMEבשם של השער שרוצים למחוק.מוודאים ששער הגישה לא מופיע יותר ברשימת שערי הגישה האזוריים:
gcloud network-services agent-gateways list \ --location=LOCATION \ --project=PROJECT_ID
אופציונלי: אי אפשר למחוק
AgentConnectivityTemplateאם Agent Gateway מפנה אליו. אחרי שמוחקים את השער, מוחקים את כל תבניות הקישוריות שלא בשימוש:gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את
CONNECTIVITY_TEMPLATE_NAMEבשם של תבנית הקישוריות שלא בשימוש. אם אתם לא צריכים יותר את המשאבים הבסיסיים של Private Service Connect (מחבר הרשת, אזורי Cloud DNS פרטיים או משאביTrustConfigשל Certificate Manager), קראו את המאמר מחיקת מחברי רשת.
המאמרים הבאים
הקצאת הרשאות ל-Agent Gateway
איך להעביר את ההרשאה ל-Agent Gateway אל IAP, אל Model Armor או אל שירות הרשאות בהתאמה אישית.