פתרון בעיות ב-Agent Gateway

אם בקשה יוצאת מהסוכן של Cloud Run נכשלת או עוקפת את Agent Gateway, אתם יכולים לעקוב אחרי נתיב הבקשה באמצעות הבדיקות הבאות או לעיין בקטע בעיות נפוצות ופתרונות. הוראות להגדרה מופיעות במאמר ניהול סוכנים באמצעות Agent Gateway.

לפני שהתנועה מגיעה ל-Agent Gateway, שרת ה-proxy של Envoy ב-Cloud Run מאחזר את הגדרות הניתוב והאישורים מ-Traffic Director API. ה-sidecar שולח תנועה יוצאת דרך מנהרת mTLS CONNECT אל Secure Web Proxy.

אימות הניתוב היוצא ביומני הגישה של Envoy sidecar

כש-Cloud Run Envoy sidecar מיירט חיבור TCP יוצא, הוא כותב רשומת יומן גישה בפורמט JSON ב-run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log עם השדה jsonPayload.upstream_host.

מפעילים בקשה יוצאת משירות Cloud Run ושולחים שאילתה ליומני הגישה של קובץ העזר:

gcloud logging read \
    'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND jsonPayload.upstream_host:*' \
    --project=PROJECT_ID \
    --freshness=7d \
    --limit=20 \
    --format="table(timestamp, jsonPayload.sni, jsonPayload.upstream_host, jsonPayload.response_flags, jsonPayload.bytes_sent, jsonPayload.bytes_received, jsonPayload.duration)"

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

  • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

TIMESTAMP                     SNI          UPSTREAM_HOST                      RESPONSE_FLAGS  BYTES_SENT  BYTES_RECEIVED  DURATION
2026-10-09T05:07:48.340693Z   example.com  envoy://tunnel_internal_listener/  -               4101        2899            489

בודקים את הערכים של UPSTREAM_HOST ו-RESPONSE_FLAGS:

  • אם הערך של UPSTREAM_HOST הוא envoy://tunnel_internal_listener/ והערך של RESPONSE_FLAGS הוא -, החיבור תקין. ה-sidecar של Envoy תאם למדיניות EgressRouting והעביר את החיבור ל-Agent Gateway.
  • אם UPSTREAM_HOST היא כתובת IP ויציאה של יעד, כמו 93.184.216.34:443, ה-API של Traffic Director לא הצליח להתאים למדיניות EgressRouting או לפתור את שער היעד. ‫Envoy השתמש ב-ORIGINAL_DST passthrough ועקף את Agent Gateway. בדיקת מזהי ה-URI של המשאבים EgressRouting ו-AgentGateway
  • אם הערך של UPSTREAM_HOST הוא envoy://tunnel_internal_listener/ והערך של RESPONSE_FLAGS הוא UF או UH, או שהערך של BYTES_RECEIVED הוא 0, Envoy לא הצליח לפתוח את המנהרה CONNECT ל-Secure Web Proxy. בודקים את הקישוריות של רשת המשנה של הענן הווירטואלי הפרטי (VPC) או קוראים את המאמר עדכון השער של Secure Web Proxy משבש את ה-tunneling של Envoy.
  • אם לא מופיעות שורות, בודקים את run.googleapis.com%2Frequests כדי לוודא שהבקשה הגיעה למאגר Cloud Run. מוודאים שהגרסה הפעילה מאפשרת את --ambient-networking. אם השורות עדיין לא מופיעות, עיינו בקטע בדיקת יומני החיבור ו-xDS של Envoy sidecar.

בדיקת יומני החיבור ו-xDS של Envoy sidecar

אם יומני הגישה של Envoy sidecar לא מחזירים רשומות או מציגים כשל בחיבור, בודקים את יומני החיבור של xDS ו-upstream ב-sidecar:

  1. בודקים אם יש שגיאות בסטרימינג של xDS ב-Traffic Director API או את סטטוס ההפעלה:

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (severity>=INFO OR textPayload:"DeltaAggregatedResources")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

  2. בודקים את ניסיונות החיבור של המנהרה בכיוון upstream אל ambient-swp-connect-cluster:

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (textPayload:"ambient-swp-connect-cluster" OR jsonPayload.message:"ambient-swp-connect-cluster" OR jsonPayload.message:"tunnel_internal_listener")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

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

    • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

בודקים את הודעות היומן:

  • אם היומנים מכילים את DeltaAggregatedResources gRPC config stream ואת The caller does not have permission, לזהות השירות חסרה ההרשאה roles/trafficdirector.client. ה-sidecar של Envoy לא יכול לקבל הגדרות xDS.
  • אם היומנים מכילים את הערך Creating connection to cluster ambient-swp-connect-cluster, סימן ש-Envoy קיבל את ההגדרות של EgressRouting וניסה להתחבר ל-Secure Web Proxy.

בדיקת מזהי ה-URI של המשאבים EgressRouting ו-AgentGateway

כשמריצים את gcloud alpha network-services egress-routings create או את gcloud beta network-services agent-gateways import, ה-API מאמת את התחביר של ה-URI בלי לבדוק אם משאבי המטרה קיימים. טעות הקלדה בשם המשאב או באזור גורמת ל-Traffic Director API לדלג על התרגום של EgressRouting, ו-Envoy משתמש בניתוב מסוג passthrough.

בודקים את כתובות ה-URI ששמורות ומשווים אותן למשאבים שנפרסו:

  1. בודקים את המשאב EgressRouting. הפלט מנרמל את מזהי הפרויקטים למספרי פרויקטים:

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
   --location=REGION \
   --project=PROJECT_ID

  2. מציגים את כל המשאבים של EgressRouting באזור כדי לוודא שאין מדיניות כפולה שמטרגטת את אותו שירות:

    gcloud alpha network-services egress-routings list \
   --location=REGION \
   --project=PROJECT_ID

  3. מוודאים ששער היעד של Secure Web Proxy תואם ל-URI ב-EgressRouting.gateway וב-AgentGateway.selfManaged.resourceUris:

    gcloud network-services gateways describe SWP_NAME \
   --location=REGION \
   --project=PROJECT_ID

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

    • ‫EGRESS_ROUTING_NAME: השם של המשאב ב-EgressRouting.
    • ‫REGION: האזור של הפריסה.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫SWP_NAME: השם של שער Secure Web Proxy.

מוודאים שכל שלושת מזהי ה-URI תואמים למזהה או למספר הפרויקט, לאזור ולשם המשאב:

  • EgressRouting.sources[].workloadUri:
    • ברמת השירות: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • ברמת הפרויקט: //run.googleapis.com/projects/PROJECT_ID או //run.googleapis.com/projects/PROJECT_NUMBER
  • EgressRouting.gateway: //networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
  • AgentGateway.selfManaged.resourceUris[]: projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME

בדיקת יומני העסקאות של Secure Web Proxy

אם שרת ה-proxy של Envoy מעביר תנועה ל-Secure Web Proxy אבל הבקשות נכשלות, בדקו את יומני ה-proxy כמו שמתואר בקטע הצגת יומני העסקאות של שרת ה-proxy:

  • אם לא מופיעה תנועה ביומני ה-proxy, הבקשות לא מגיעות ל-Secure Web Proxy. בודקים את ההגדרות של EgressRouting במאמרים בדיקת כתובות ה-URI של המשאבים EgressRouting ו-AgentGateway ובעיות נפוצות ופתרונות.
  • אם אתם רואים החלטות DENY או ALLOW לא צפויות, בדקו את jsonPayload.authzPolicyInfo ו-jsonPayload.agentGatewayInfo ברשומת היומן כדי לבחון את המטא-נתונים התואמים של AuthzPolicy והיעד, וודאו את כללי ExtensionBinding שמצורפים למשאב Agent Gateway. אחרי שיוצרים או מעדכנים משאב ExtensionBinding, יכול להיות שיעברו עד חמש דקות עד שהשינויים בהגדרות יתעדכנו בשער.

בעיות נפוצות ופתרונות

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

תנועה יוצאת עוקפת את Agent Gateway בגלל חוסר התאמה ב-URI של המשאב

תנועה יוצאת מ-Cloud Run עוקפת את Agent Gateway או שהזמן הקצוב לתפוגה מסתיים אחרי ש-egress-routings create מצליח. ב-envoy_sidecar_log, השדה jsonPayload.upstream_host מציג את כתובת ה-IP והיציאה של היעד במקום envoy://tunnel_internal_listener/.

אחד ממזהי ה-URI של המשאבים EgressRouting או AgentGateway מפנה לשם משאב שלא קיים או לאזור לא תואם. אם Traffic Director API לא מצליח לפתור את השרשרת משירות Cloud Run ל-Secure Web Proxy, הוא מדלג על תרגום המנהרה ומציג את ORIGINAL_DST.

מריצים את הפקודות בקטע בדיקת כתובות ה-URI של המשאבים EgressRouting ו-AgentGateway כדי למצוא את כתובת ה-URI שלא תואמת. מעדכנים את ההגדרה עם שם המשאב והאזור התואמים, ויוצרים מחדש את המשאב AgentGateway או EgressRouting.

‫Envoy sidecar לא יכול לקבל הגדרות xDS

בקשות יוצאות מהקונטיינר של Cloud Run נכשלות או שנגמר הזמן הקצוב שלהן, וב-envoy_sidecar_log מופיעה השגיאה הבאה:

DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission

לזהות השירות של סביבת זמן הריצה של Cloud Run אין את ההרשאה roles/trafficdirector.client. כברירת מחדל, פריסת שירות באמצעות --functional-type=agent ו---identity-type=agent-identity מעניקה את ההרשאה roles/run.agentDefaultAccess, שכוללת את roles/trafficdirector.client ו-roles/cloudtrace.agent. אם ההרשאות האלה חסרות בזהות השירות, צריך להקצות את התפקידים:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/cloudtrace.agent"

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫REGION: האזור של השירות.
  • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run. אם השירות משתמש בחשבון שירות במקום ב-Agent Identity, מגדירים את --member לערך serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

מוודאים שלסוכן השירות של Cloud Run יש גישה לרשת ה-VPC. כברירת מחדל, התפקיד roles/run.serviceAgent כולל את ההרשאות האלה. אם שיניתם את ההרשאות של סוכן השירות, צריך לתת את ההרשאה roles/compute.networkUser:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

עדכון השער של Secure Web Proxy משבש את המנהור של Envoy

אחרי שמעדכנים את ServerTlsPolicy, האישור, כתובת ה-IP או היציאה של שער Secure Web Proxy קיים, בקשות יוצאות נכשלות עם השגיאות 502,‏ 503 או 504, או ש-envoy_sidecar_log מדווח על RESPONSE_FLAGS: UF.

אי אפשר לשנות את addresses או את ports אחרי שיוצרים שער של Secure Web Proxy. בנוסף, עדכונים של serverTlsPolicy או certificateUrls בשער קיים של Secure Web Proxy לא מופצים לנקודות קצה (endpoint) של EgressRouting ב-Traffic Director API.

כדי לשנות את השדות האלה ב-Secure Web Proxy בלי זמן השבתה של עומס העבודה, מבצעים את הפעולות הבאות:

  1. יוצרים שער חלופי ל-Secure Web Proxy עם שם משאב אחר וההגדרה המעודכנת.
  2. מעדכנים את selfManaged.resourceUris במשאב AgentGateway כך שיפנה ל-URI של שער ה-Secure Web Proxy החלופי.
  3. יוצרים מחדש את המשאב EgressRouting כך שיפנה לשער החלופי של Secure Web Proxy.
  4. אחרי ששער ה-proxy החלופי מנתב את התנועה, מסירים את שער ה-proxy הישן של Secure Web Proxy מהמשאב AgentGateway ומוחקים את שער ה-proxy הישן של Secure Web Proxy.

‫Secure Web Proxy חוסם את כל התנועה היוצאת

כל הבקשות היוצאות מסוכן Cloud Run נכשלות עם שגיאות 403 אחרי שיוצרים מדיניות EgressRouting או מצרפים ExtensionBinding.

כברירת מחדל, Secure Web Proxy חוסם את כל התנועה עד ש-ALLOW AuthzPolicy במשאב Agent Gateway מאפשר אותה. אם מצרפים ExtensionBinding, התנועה לא תתאפשר בלי ALLOW AuthzPolicy, וכללי המדיניות שמצורפים למשאב Gateway הבסיסי של Secure Web Proxy לא יחולו.

כדי לאפשר תנועה מורשית, מצרפים ALLOW AuthzPolicy שמטרגט את המשאב של Agent Gateway. הוראות מפורטות זמינות במאמר אישור תעבורת נתונים יוצאת בסיסית ותעבורת נתונים של MCP.

בקשות למודלים יוצאים נכשלות עם שגיאות 403

שיחות יוצאות מסוכן Cloud Run לנקודות קצה של מודלים כמו Vertex AI ב-REGION-aiplatform.googleapis.com נכשלות עם שגיאות 403 Forbidden אחרי שמגדירים כללי מדיניות ב-Agent Gateway.

בגלל ש---vpc-egress=all מנתב את כל תנועת ה-outbound של הקונטיינר דרך Secure Web Proxy, בקשות המודל נכשלות אם ALLOW AuthzPolicy תואם רק לשיטות של Model Context Protocol‏ (MCP) או אם ExtensionBinding של Identity-Aware Proxy‏ (IAP) תואם למארחים שאינם MCP בלי כלל הרשאה במדיניות הגישה המאוחדת של ניהול זהויות והרשאות גישה (IAM).

כדי לאפשר קריאות למודלים יוצאים, צריך לאשר את נקודות הקצה של המודל ב-ALLOW AuthzPolicy במשאב Agent Gateway. בנוסף, צריך להגדיר את ההיקף matchConditions ב-IAP ExtensionBinding ל-prefix: "urn:mcp" או להוסיף כלל הרשאה destination.unregistered.host במדיניות הגישה המאוחדת של IAM. הוראות מפורטות זמינות במאמרים אישור תעבורת נתונים יוצאת בסיסית ותעבורת נתונים של MCP והגדרת כללי מדיניות של תעבורת נתונים יוצאת ב-IAP.

‫Secure Web Proxy מתעלם מ-GatewaySecurityPolicyRules

יצרתם GatewaySecurityPolicyRules או צירפתם AuthzPolicy למשאב Gateway של Secure Web Proxy, אבל אין להם השפעה על תנועת הסוכנים היוצאת.

כש-Secure Web Proxy משויך למשאב AgentGateway, הוא אוכף רק את כללי מדיניות ההרשאה ואת קישורי התוספים שמצורפים למשאב AgentGateway. המערכת מתעלמת מכל משאב מסוג GatewaySecurityPolicyRules או AuthzPolicy שמצורף ל-Secure Web Proxy Gateway הבסיסי.

במקום זאת, צריך לצרף את המשאבים AuthzPolicy ו-ExtensionBinding למשאב Agent Gateway. איך מגדירים כללי מדיניות ב-Agent Gateway

בקשות יוצאות נכשלות בבדיקת TLS

בקשות יוצאות מסוכן Cloud Run נכשלות עם שגיאות TLS בכל חיבור.

במאגר של Certificate Authority Service חסר התפקיד roles/privateca.certificateManager בחשבון השירות של Secure Web Proxy.

מקצים את התפקיד roles/privateca.certificateManager במאגר רשויות האישורים (CA) לחשבון השירות של Secure Web Proxy. איך יוצרים חשבון שירות?

חיבורים יוצאים שנבדקים באמצעות TLS נכשלים עם השגיאה SSLV3_ALERT_HANDSHAKE_FAILURE או RemoteDisconnected

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

בחיבור הראשון שנבדק באמצעות TLS למארח יעד, Secure Web Proxy מנפיק אישור קצה משירות CA ושומר אותו במטמון, מה שעלול לגרום לשגיאת לחיצת יד זמנית. צד הלקוח ב-HTTP ששולח את Connection: close כברירת מחדל, כמו urllib.request.urlopen, עלול להיכשל עם RemoteDisconnected במהלך יירוט TLS.

כדי למנוע את השגיאות האלה בקוד של הנציג:

  • השתמשו בצד הלקוח ב-HTTP שמשתמש מחדש בחיבורים קבועים, כמו httpx.AsyncClient או requests.Session().
  • מגדירים ניסיונות חוזרים של חיבור ושל לחיצת יד בצד הלקוח ב-HTTP, כמו httpx.AsyncHTTPTransport(retries=2) או urllib3.util.Retry.

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