הפעלת Model Context Protocol‏ (MCP) ב-Apigee Hybrid

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

אפשר לעיין במסמכי העזרה של Apigee Edge.

בדף הזה מוסבר איך להפעיל את Model Context Protocol‏ (MCP) באשכול Apigee hybrid קיים שפועלת בו גרסה 1.17.0 ואילך. אחרי שמסיימים את התהליך הזה, באשכול מופעל מישור נתונים חדש של MCP בתוך האשכול, ומעבד ההודעות מוכן להפנות אליו קריאות לכלים של MCP. אחר כך תוכלו לפרוס את ה-MCP הראשון שלכם באמצעות המדריך המהיר המשותף ל-MCP.

למידע על המושגים, הארכיטקטורה והתכונות של MCP שמשותפים ל-Apigee ול-Apigee Hybrid, אפשר לעיין בסקירה הכללית של MCP ב-Apigee.

מה עושים בתהליך הזה

הפעלת MCP באשכול Apigee Hybrid גורמת לשינויים הבאים:

  1. נותן לזהות apigee-watcher גישה להגדרות MCP במישור הבקרה של Apigee. מוסיפים את חשבון השירות apigee-watcher לרשימה watcher_identities במשאב controlPlaneAccess של ארגון Apigee, כדי שמנגנון ה-sidecar של MCP יוכל לשלוף חבילות של הגדרות MCP ממישור הבקרה של Apigee. זהו שינוי במישור הבקרה, שמוגבל לארגון Apigee, וזהו שלב חד-פעמי לכל ארגון, ללא קשר למספר האשכולות שמשרתים את הארגון הזה.
  2. נוסף מישור נתונים חדש של MCP בתוך האשכול. נוצרת קבוצה חדשה של פודים של MCP באותו מרחב שמות של Kubernetes שבו מותקן Apigee Hybrid (ברירת המחדל היא apigee), יחד עם משאבי Kubernetes התומכים (Service,‏ Horizontal Pod Autoscaler ו-RBAC) שנדרשים להפעלתם. הפעלת כלי MCP מתבצעת על ידי הפודים האלה.
  3. מגדירים את מעבד ההודעות כך שיגיע למישור הנתונים של MCP. האופרטור של Apigee מעדכן את מפרט ה-pod של מעבד ההודעות כך שמעבד ההודעות ינתב קריאות לכלי MCP למישור הנתונים החדש של MCP בתוך האשכול. החלת השינוי הזה מפעילה הפצה מדורגת של Message Processor (מעבד ההודעות) (שמנוהל על ידי בקר ApigeeDeployment); הפוד הקודם ממשיך לטפל בתנועה עד שהפוד החדש יהיה Ready. ההודעה נשלחת רק במעברים של הפעלה והשבתה, ולא בפעילות שוטפת של MCP או בתנועה יציבה של MCP. מריצים את התהליך הזה בחלון זמן לתחזוקה מאושר ומחכים שההפצה תסתיים לפני שממשיכים.

שלב 1: עריכה overrides.yaml

פותחים את קובץ overrides.yaml שבו משתמשים לתרשימי Helm של Apigee Hybrid. ברמה העליונה של הקובץ, מוסיפים:

enableMcpServer: true

זו ההגדרה המינימלית שנדרשת כדי להפעיל את ה-MCP. היא משתמשת בערכי ברירת המחדל המובנים מהתרשים apigee-org: שני עותקים משוכפלים של מישור הנתונים של MCP שמתבצעת בהם התאמה אוטומטית של קנה המידה עד עשרה עותקים בשימוש של 70% ב-CPU, עם בקשות למשאבים של 500m CPU ו-512Mi זיכרון ומגבלות של 2000m CPU ו-1Gi זיכרון במאגר של מישור הנתונים של MCP. כדי להתאים אישית את מספר העותקים, בקשות המשאבים או חשבון השירות של MCP, אפשר לעיין בקטע הפניה: שדות MCP בקובץ overrides.yaml בהמשך הדף.

בהמשך מופיעות דוגמאות מלאות של קובץ overrides.yaml משולב, אחת לכל סגנון אימות. משתמשים בדוגמה שמתאימה לאופן שבו מוגדרת ההתקנה הבסיסית הקיימת. השורות שספציפיות ל-MCP מודגשות באמצעות הערות, והן זהות בכל שלושת הווריאציות.

בוחרים את הכרטיסייה שמתאימה לאופן שבו ההתקנה הבסיסית מאמתת רכיבי Apigee ב-Google Cloud. הבחירה חלה על כל בלוק קוד בהיקף וריאנט בדף הזה.

Workload Identity‏ (GKE)

משתמשים בגרסה הזו אם ההתקנה הבסיסית מאמתת רכיבי Apigee ב-Google Cloud באמצעות Workload Identity ב-GKE (אין קובצי מפתח של חשבון שירות בדיסק).

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
  workloadIdentity:
    enabled: true
    gsa: apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

מפתחות של חשבונות שירות מבוססי-קובץ

משתמשים בגרסה הזו אם ההתקנה הבסיסית מאמתת רכיבי Apigee ב-Google Cloud באמצעות קובצי מפתחות של חשבונות שירות שמופצים לכל אשכול.

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
guardrails:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
mart:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
connectAgent:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
watcher:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json  # MCP also uses this key file
envs:
- name: my-env
  serviceAccountPaths:
    synchronizer: ./service-accounts/apigee-non-prod.json
    runtime:      ./service-accounts/apigee-non-prod.json

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

איחוד שירותי אימות הזהות של עומסי עבודה (AKS/EKS)

משתמשים בגרסה הזו אם ההתקנה הבסיסית היא ב-AKS או ב-EKS והאימות מתבצע ל-Google Cloud דרך איחוד שירותי אימות הזהות של עומסי עבודה. ‫MCP משתמש בקובץ התצורה של פרטי הכניסה ש-apigee-watcher כבר משתמש בו, מ-watcher.serviceAccountPath, כך שלא צריך להוסיף הגדרות זהות ספציפיות ל-MCP. אם אתם מאחסנים את הגדרות האישורים בסוד של Kubernetes, כדאי לעיין במאמר מנגנוני זיהוי אחרים.

מוסיפים את מפתח ה-MCP ברמה העליונה ל-WIF הקיים overrides.yaml:

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

משאירים את הערכים mcpServer.gsa ו-mcpServer.serviceAccountPath לא מוגדרים. ‫ MCP sidecar משתמש באותו קובץ תצורה של פרטי הכניסה כמו apigee-watcher, מתוך watcher.serviceAccountPath.

שלב 2: מעניקים לזהות הצופה גישה להגדרת ה-MCP במישור הבקרה

ה-sidecar של MCP מאחזר את חבילת ההגדרות שלו ממישור הבקרה של Apigee באמצעות חשבון השירות של Google Cloud של רכיב apigee-watcher (הזהות שבחרתם בשלב 1). לפני שמתחילים את הפודים של MCP, מוסיפים את חשבון השירות הזה לרשימת watcher_identities במשאב controlPlaneAccess של הארגון ב-Apigee. בלי ההרשאה הזו, הקריאות של ה-sidecar של ה-MCP אל apigee.googleapis.com כדי לאחזר את ההפניה להגדרת ה-MCP מחזירות 404 Not Found, ומישור הנתונים של ה-MCP אף פעם לא מוכן להצגת תנועת משתמשים בכלי.

זהו שלב חד-פעמי לכל הארגון (לא לכל אשכול). אפשר לדלג על השלב הזה אם כבר הענקתם גישה לאשכול קודם באותו ארגון Apigee.

  1. מגדירים את משתני ה-Shell שמשמשים לקריאה ל-API. שימוש חוזר בערכים מההתקנה: 
    export ORG_NAME=YOUR_ORG_NAME
export PROJECT_ID=YOUR_GCP_PROJECT_ID
export WATCHER_SA=apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com
export TOKEN=$(gcloud auth print-access-token)

    כאשר:

    • ‫YOUR_ORG_NAME הוא השם של הארגון ב-Apigee Hybrid.
    • ‫YOUR_GCP_PROJECT_ID הוא פרויקט בענן של Google שמארח את הארגון שלכם ב-Apigee Hybrid.
    • ‫WATCHER_SA היא כתובת האימייל של חשבון השירות apigee-watcher. אם ביטלתם את ברירת המחדל watcher.gsa ב-overrides.yaml, השתמשו בערך הזה במקום בברירת המחדל apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com.
  2. קוראים ל-API‏ updateControlPlaneAccess כדי להוסיף את חשבון השירות של השירות למעקב לרשימה watcher_identities:

    אין מיקום אחסון נתונים

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
  -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"

    מיקום אחסון הנתונים

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
  -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"

    כאשר CONTROL_PLANE_LOCATION הוא המיקום של נתוני מישור הבקרה אם בהתקנת Apigee Hybrid נעשה שימוש במיקום אחסון הנתונים. רשימת המיקומים הזמינים מופיעה במאמר אזורי מישור הבקרה של Apigee API שזמינים לשימוש.

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

  3. מוודאים שהמענק התקבל. קוראים לפונקציה getControlPlaneAccess ומאשרים שחשבון השירות של שירות הצפייה מופיע בשדה watcherIdentities של התגובה:

    אין מיקום אחסון נתונים

    curl -X GET -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"

    מיקום אחסון הנתונים

    curl -X GET -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"

    התשובה צריכה לכלול מערך watcherIdentities שמכיל את חשבון השירות של הכלי למעקב. לדוגמה:

    {
  "synchronizerIdentities": [ ... ],
  "analyticsPublisherIdentities": [ ... ],
  "watcherIdentities": [
    "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID.iam.gserviceaccount.com"
  ]
}

    אם watcherIdentities לא מופיע בתגובה או לא מכיל את חשבון השירות של שירות הצפייה, מריצים מחדש את פקודת ה-PATCH ובודקים את סטטוס הפעולה כדי לוודא שאין שגיאות לפני שממשיכים.

שלב 3: שדרוג התרשים apigee-operator

קודם משדרגים את תרשים האופרטור. תרשים האופרטור מכיל את הסכימה של משאבי ה-MCP החדשים, והתרשים הארגוני מפנה אליהם. שדרוג בסדר שגוי יוביל להצלחה של helm upgrade שלא תיצור תרמילי MCP.

helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

הפקודה תושלם תוך פחות מדקה. מוודאים שה-Deployment של האופרטור הושלם עם התמונה החדשה (‫apigee-controller-manager Deployment הוא משאב ב-Kubernetes רגיל, לא ApigeeDeployment, ולכן kubectl rollout status deploy היא הפקודה הנכונה כאן):

kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m

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

deployment "apigee-controller-manager" successfully rolled out

שלב 4: שדרוג התרשים apigee-org

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

שני לולאות של התאמה פועלות עכשיו במקביל:

  • אופרטור Apigee יוצר את הפריסה, השירות, ה-HPA, חשבון השירות, התפקיד וה-RoleBinding של MCP. תאי MCP מופעלים שניים בכל פעם (בכפוף לתזמון של Kubernetes). קונטיינר ה-sidecar בכל תא מבצע את השליפה הראשונה של ההגדרות ממישור הבקרה של Apigee זמן קצר אחרי ההפעלה.
  • האופרטור של Apigee מוסיף את הרשומה hostAliases למפרט של פוד Message Processor, שגורם ליצירת גרסה של apigee-runtime ApigeeDeployment.

שלב 5: אימות ההתקנה

אימות של הפעלת מישור הנתונים של MCP

בודקים את ארבעת המשאבים שקשורים ל-MCP שהאופרטור יצר. שמות המשאבים כוללים סיומת שנגזרת מהארגון. בדוגמאות הבאות, ORG_CR_SUFFIX משמש כמחזיק המקום לסיומת הזו. הסיומות של ה-Pod ושל ה-ClusterIP של השירות יהיו שונות בסביבה שלכם.

תאי MCP (שניים כברירת מחדל; שינוי גודל אוטומטי עד עשרה במקרה של עומס):

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                                                READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-abc12   2/2     Running   0          2m
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-def34   2/2     Running   0          2m

בכל פוד צריך להופיע 2/2 בעמודה READY. שני הקונטיינרים בכל פוד הם:

  • ‫apigee-mcp-server — מאגר מישורי הנתונים של MCP שאליו מתחברים תרמילי MP.
  • ‫apigee-mcp-server-config – קובץ ה-sidecar של ההגדרות (מצב של קובץ ה-apigee-watcher הבינארי) שאחראי לאחזור חבילות הגדרות ממישור הבקרה של Apigee ולכתיבתן לנפח אחסון משותף שקונטיינר מישור הנתונים של MCP קורא.

‫MCP ApigeeDeployment (משאב מותאם אישית של Kubernetes, לא Deployment):

kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                              STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   running                 2m

המצב הצפוי הוא running. כדאי גם לוודא שה-pod הבסיסי הוא 2/2 Running:

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                                    READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH   2/2     Running   0          2m

שירות MCP:

kubectl get svc -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                              TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                              AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   ClusterIP   10.96.42.17   <none>        80/TCP,443/TCP,15021/TCP,15000/TCP   2m

‫MCP HorizontalPodAutoscaler:

kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server

מוודאים ש-MINPODS תואם ל-mcpServer.replicaCountMin מ-overrides.yaml (ברירת מחדל 2) ו-MAXPODS תואם ל-mcpServer.replicaCountMax (ברירת מחדל 10). העמודות TARGETS, REPLICAS ו-AGE תלויות במדדים בזמן אמת ובמצב האשכול.

מוודאים שתאי Message Processor קיבלו את הרשומה hostAliases

בכל פוד של MP צריך להופיע הערך שהוזרק. אם הוא חסר בפוד אחד, הפוד הזה לא יכול לנתב שיחות של כלי MCP. לפרט את כל ה-pods של MP ואת hostAliases שלהם:

kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

פלט צפוי: כל פוד של MP מפרט מערך hostAliases שמכיל רשומה אחת עם שני שמות מארחים שמפנים ל-ClusterIP של שירות ה-MCP מהשלב הקודם (שם המארח השני משתמש בשם הארגון באותיות קטנות). שמות הפודים של מעבד ההודעות פועלים לפי התבנית apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, כאשר TRUNCATED_ORG הוא שם הארגון (שקוצר כדי להתאים למגבלת השם של Kubernetes של 63 תווים אם שם הארגון ארוך), ENV_GROUP_HASH הוא גיבוב של קבוצת פריסה לכל סביבה, REV הוא מספר הגרסה הנוכחית (ארבע ספרות, למשל 1170), ו-POD_HASH הוא סיומת אקראית לכל פוד. לדוגמה:

apigee-runtime-myorg-env1-abc12-1170-def34   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
apigee-runtime-myorg-env1-abc12-1170-ghi56   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]

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

kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime

בקר ApigeeDeployment ייצור מחדש את ה-pods תוך דקה. שימו לב שהפקודה kubectl rollout restart deploy (פקודת Kubernetes רגילה) לא פועלת ב-Message Processor כי Message Processor נפרס כמשאב מותאם אישית של ApigeeDeployment ולא כ-Deployment.

ההתקנה הושלמה

שלושת הבדיקות הקודמות מאשרות שמישור הנתונים של ה-MCP פועל וניתן לכתובת MP:

  • כל פוד של MCP הוא 2/2 Running. במקרים שבהם אישור ה-TLS שהונפק על ידי האופרטור לא נטען, וה-sidecar עדיין לא טען את ההגדרה הראשונית של MCP, קונטיינר מישור הנתונים של MCP לא עובר את בדיקת המוכנות של Kubernetes ביציאה 15021. לכן, בשביל פודים של Ready צריך לוודא ששני התנאים המוקדמים האלה מתקיימים.
  • המפרט של כל פוד MP מכיל את הערך hostAliases entry pinning mcp.apigee.internal ואת הערך ORG_NAME.mcp.apigee.internal ל-MCP Service ClusterIP. לכן, תרמילי MP יכולים לפתור נקודות קצה של יעד פרוקסי MCP למישור הנתונים של MCP בתוך האשכול.
  • פוד MP מבצע התאמת נתונים (resolve) של mcp.apigee.internal ל-ClusterIP של שירות ה-MCP דרך הרשומה hostAliases שמוזרקת.

אתם מאמתים את תנועת הגולשים בכלי ה-MCP מקצה לקצה (קריאה בפועל של initialize או tools/list דרך Apigee Ingress) כחלק מהמדריך המקוצר המשותף ל-MCP, אחרי שפורסים את ה-MCP Discovery Proxy הראשון.

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

שלב 6: הפעלת MCP באשכולות הנותרים

בקשות MCP לשם מארח נתון יכולות להיות מנותבות לכל אשכול שמשרת את קבוצת סביבת Apigee המתאימה. אם MCP מופעל בחלק מהאשכולות ולא באחרים באותה קבוצת סביבות, בקשות MCP שמנותבות לאשכול שבו MCP לא מופעל ייכשלו (בדרך כלל יוחזרו ללקוח כ-503 Service Unavailable).

מפעילים את MCP באופן אחיד בכל אשכול שמציג מודעות לאותה קבוצת סביבות. לכל אשכול נוסף, חוזרים על שלבים 1, 3, 4 ו-5. אין צורך לחזור על שלב 2 (הענקת גישה לזהות הצופה): הגישה הזו מוגבלת לארגון Apigee וחלה על כל האשכולות באותו ארגון.

רולבק

כדי להשבית את ה-MCP באשכול, מגדירים את enableMcpServer: false (או מסירים את השדה לגמרי) ב-overrides.yaml, ואז משדרגים את התרשים apigee-org:

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml

השדה enableMcpServer משמש רק בתרשים apigee-org, ולכן אין צורך לשדרג את תרשים האופרטור במהלך השבתה. האופרטור של Apigee (ללא שינוי) מאתר את שינוי ההגדרה במשאב המותאם אישית ApigeeOrganization, מוחק את משאבי ה-MCP ומסיר את הרשומה hostAliases ממפרט ה-pod של מעבד ההודעות, מה שגורם לשחרור של apigee-runtime ApigeeDeployment. החזרה לגרסה קודמת בחלון זמן לתחזוקה שאושר.

אחרי החזרה לגרסה הקודמת, שרתי ה-proxy של MCP Discovery שפרסתם בסביבת Apigee עדיין נמצאים במישור הבקרה של Apigee, אבל אף אשכול בקבוצת הסביבות הזו לא משרת תנועה של MCP. כדי להשבית את התכונה באופן מלא, צריך לבטל את הפריסה של שרתי ה-Proxy של MCP Discovery, או להשאיר אותם פרוסים ולהפעיל מחדש את MCP באשכולות מאוחר יותר.

מקור: שדות MCP ב-overrides.yaml

בטבלה הבאה מפורטים כל השדות של Apigee hybrid overrides.yaml ששולטים בהתנהגות של MCP בגרסה 1.17.0. חובה למלא רק את השדה enableMcpServer. בשאר השדות יש ערכי ברירת מחדל בטוחים שמתאימים לרוב ההתקנות.

הגדרות השדות תואמות לברירות המחדל של תרשים Helm‏ apigee-org ל-hybrid 1.17.0.

שדה סוג ברירת מחדל התאמה מומלצת
enableMcpServer בוליאני false חובה. מגדירים את הערך true כדי להפעיל את ה-MCP באשכול הזה. החלפת הערך בשדה הזה מפעילה הפצה מדורגת של גרסה איטרטיבית לקהל מצומצם (canary release) של מעבד בקשות. הפעילו את המתג רק בחלון זמן לתחזוקה והמתינו לסיום ההפצה לפני שתמשיכו.
mcpServer.replicaCountMin מספר שלם 2 צריך להשאיר את הערך 2 לזמינות גבוהה. הגדלה מומלצת רק אם יש לכם בסיס של תנועה גבוהה של MCP;‏ ה-HPA מתרחב אוטומטית במקרה של עומס על המעבד. אות: שימוש גבוה מתמשך במעבד (HPA) ב-replicaCountMax והשימוש במעבד מעל היעד.
mcpServer.replicaCountMax מספר שלם 10 אם תראו שה-HPA מוגבל ל-10 במהלך השיא, כדאי להגדיל את הערך. אות: ‫kubectl top pods -l app=apigee-mcp-server shows all pods near their CPU limit at peak. אם metrics-server לא מותקן, משתמשים ב-kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server ובודקים אם העמודה REPLICAS נמצאת בערך המקסימלי MAXPODS.
mcpServer.targetCPUUtilizationPercentage מספר שלם 70 מורידים את הערך ל-50 עד 60 לעומסי עבודה (workloads) שרגישים לזמן הטעינה (ההתאמה מתבצעת מוקדם יותר). הגדלה ל-80–85 כדי לצמצם את מספר העותקים המשוכפלים באשכולות שבהם העלות היא שיקול חשוב. אות: זמן הטעינה של בקשת p95 מתואם עם מעבד לכל פוד.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi אם תרמילי ה-pods מושבתים לעיתים קרובות בגלל חריגה ממגבלת הזיכרון (OOMKilled) או שהשימוש במעבד מוגבל (CPU-throttled) במצב יציב, כדאי להגדיל את מספר הבקשות. אות: kubectl describe pod מוצגים תנאים של OOMKilled או throttling.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi כדאי להגדיל את מגבלת המעבד לפני שמגדילים את מספר העותקים, אם זמן האחזור של p95 גבוה אבל קצב השאילתות הכולל נמוך (מעט בקשות יקרות). כדאי להגדיל את מגבלת הזיכרון רק אם מופיעות שגיאות מסוג OOMKills.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi כמעט אף פעם לא צריך לבצע שינויים. ה-sidecar יוצר וכותב חבילות הגדרה באופן תקופתי, והשימוש במעבד במצב יציב הוא מינימלי.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi כמעט אף פעם לא צריך לבצע שינויים. צריך להגדיל את הזיכרון רק אם פורסים מספר גדול במיוחד של כלי MCP בשרת Discovery Proxy יחיד.
mcpServer.terminationGracePeriodSeconds מספר שלם 30 כמעט אף פעם לא צריך לבצע שינויים. הגדלה אם בקשות MCP ארוכות טווח שעדיין לא הושלמו צריכות יותר זמן להשלמה במהלך ניקוי של פוד.
mcpServer.annotations מפה {} מוסיפים הערות נוספות ל-Pod אם נדרש.
mcpServer.serviceAccountPath מחרוזת unset אל תגדירו את הערך הזה אלא אם אתם צריכים הפרדה של זהויות לכל רכיב. כשהמדיניות לא מוגדרת, MCP משתמש ב-watcher.serviceAccountPath. ב-MCP לא נעשה שימוש ב-envs[].serviceAccountPaths.runtime. apigee-watcher לזהות כבר יש את ההרשאות שנדרשות ל-MCP sidecar. אם מחליפים את הערך בשדה הזה, צריך לציין את הנתיב לקובץ JSON של Google Cloud מפתח חשבון השירות. בלעדיות הדדית עם mcpServer.gsa.

אם Workload Identity לא מופעל, ולא הגדרתם את mcpServer.serviceAccountRef או את serviceAccountSecretProviderClass, אתם צריכים להגדיר את mcpServer.serviceAccountPath או את watcher.serviceAccountPath. אם לא מגדירים אף אחד מהם, הפעולה helm upgrade נכשלת ומוצגת השגיאה mcpServer.serviceAccountPath or watcher.serviceAccountPath is required!!.

מומלץ להשתמש ב-Workload Identity‏ (GKE) או באיחוד שירותי אימות הזהות של עומסי עבודה (AKS/EKS) ככל האפשר. צריך להחליף מפתחות של חשבונות שירות שמבוססים על קבצים, לאחסן אותם בצורה מאובטחת, להפיץ אותם לכל אשכול, והם המקור הנפוץ ביותר לדליפות לתוך ארטיפקטים של תמיכה (ראו בקשות תמיכה).
mcpServer.gsa מחרוזת unset אל תגדירו את הערך הזה אלא אם אתם צריכים הפרדה של זהויות לכל רכיב. אם הערך לא מוגדר, MCP חוזר לערך watcher.gsa ואז לערך gcp.workloadIdentity.gsa. לזהות apigee-watcher כבר יש את ההרשאות שנדרשות ל-sidecar של MCP, ולכן מומלץ להשתמש בה מחדש. אפשר להגדיר כתובת אימייל ייעודית של חשבון שירות ב-Google Cloud רק אם הארגון שלכם דורש זהות נפרדת עבור ה-sidecar של MCP מסיבות שקשורות לביקורת.
mcpServer.serviceAccountRef מחרוזת unset מתקדם. השם של סוד קיים ב-Kubernetes במרחב השמות של Apigee, שמכיל מפתח של חשבון שירות ב-Google Cloud עבור MCP sidecar. משתמשים באפשרות הזו רק אם אתם מנהלים סודות של מפתחות לחשבונות שירות מחוץ לתרשימי ה-Helm של Apigee. האפשרויות mcpServer.serviceAccountPath ו-mcpServer.gsa הן בלעדיות הדדית.

‫MCP לא משתמש ב-watcher.serviceAccountRef. אם ההתקנה הבסיסית שלכם מאחסנת את המפתח apigee-watcher בסוד של Kubernetes עם watcher.serviceAccountRef, צריך להגדיר את המאפיין הזה לאותו שם סוד.
mcpServer.podDisruptionBudget מפה unset תקציב אופציונלי להפרעות בפודים של MCP. אפשר להזין את הערכים minAvailable או maxUnavailable (מספר שלם או מחרוזת של אחוזים). צריך להגדיר אחד מהם, לא את שניהם. לא מגדירים את המדיניות אלא אם באשכול יש מדיניות קפדנית של שיבושים מרצון שדורשת תקציב מפורש.
mcpServer.tolerations list ‫unset (חוזר לרמה העליונה tolerations) סבילות סטנדרטית של Kubernetes לקבוצות Pod של MCP. ההגדרה הזו נדרשת רק אם תרמילי MCP צריכים להיות סובלניים להכתמות שרכיבי Apigee אחרים לא סובלניים להן.
mcpServer.image.pullPolicy מחרוזת IfNotPresent מדיניות שליפת תמונות עבור מאגר התגים בצד השרת של שרת MCP. השינוי מתבצע לעיתים רחוקות.
mcpServer.sidecar.image.pullPolicy מחרוזת IfNotPresent מדיניות שליפת תמונות עבור קונטיינר ה-sidecar של MCP. השינוי מתבצע לעיתים רחוקות.

הערכת הקיבולת של כלי ה-MCP

ב-Apigee Hybrid אין מספר מקסימלי קבוע של כלי MCP לכל ארגון. במקום זאת, הקיבולת של הכלי מוגבלת על ידי ארבע מגבלות גודל קשיחות שנאכפות בזמן הפריסה או בזמן הבקשה. התשובה לשאלה אם מספר מסוים של כלים מתאים תלויה בגודל של כל כלי, שנגזר ממפרט OpenAPI שמגדיר את הכלי.

קיבולת אופיינית

ברוב מפרטי OpenAPI – שילוב של כלים עם מספרים שונים של פרמטרים, גדלים שונים של גוף הבקשה ואורכים שונים של תיאורים, כאשר רוב הכלים נכללים בטווח הגדלים הקטן עד הבינוני – בדרך כלל אפשר לצפות להתאמה של 10,000 כלים של MCP לכל ארגון במגבלת גודל התגובה שמוגדרת כברירת מחדל tools/list.

הקיבולת בפועל משתנה בהתאם לצורה הספציפית של מפרט OpenAPI. ארגונים שהמפרטים שלהם כוללים בעיקר כלים עם הרבה פרמטרים, גופי בקשות גדולים או תיאורים ארוכים, יכולים להוסיף פחות כלים לפני שהם מגיעים לאחד מארבעת המגבלות הקשיחות שמופיעות בהמשך. כדי לאמת את הקיבולת של המפרטים הספציפיים שלכם, פועלים לפי ההוראות במאמר הערכת הקיבולת של המפרט שבהמשך.

מגבלות קשיחות

יש ארבע מגבלות גודל בגרסת Apigee Hybrid‏ 1.17.0. ההגבלה הנמוכה ביותר שחלה היא המחייבת, והגדלה של אחת מההגבלות לא מגדילה את ההגבלות האחרות.

הגבלה ערך היקף מצב כשל
גודל הקובץ של מפרט OpenAPI ‫3MiB לכל קובץ .yaml ‫400 at proxy validate
גודל חבילת ה-proxy של MCP (לאחר פתיחת הדחיסה) ‫50MiB לכל שרת proxy של MCP Discovery ‫400 at proxy validate
גודל התגובה: tools/list ‫‎10 MiB (ברירת מחדל) לכל שם מארח 502 עם TooBigBody
שמות מארחים לכל קבוצת סביבות 100 לכל קבוצת סביבות 400 בעדכון של קבוצת סביבות

מה משפיע על הגודל של כל כלי

הגודל של כל כלי מורכב כמעט כולו מ-inputSchema של הכלי, שנגזר מ-parameters ו-requestBody של הפעולה במפרט OpenAPI. יש שלושה מאפיינים שחשובים במיוחד:

  • מספר הפרמטרים. כל פרמטר שמוזן תורם בערך 100 בייט לגודל הכלי בתשובה.tools/list
  • מספר המאפיינים בגוף הבקשה. כל מאפיין בגוף הבקשה תורם בערך 100 בייטים. לכן, פעולות עם גוף בקשה (בדרך כלל POST ו-PUT) גדולות משמעותית מפעולות בלי גוף בקשה (בדרך כלל GET ו-DELETE).
  • אורך התיאור. תיאורי הפעולות מועתקים כמעט מילה במילה לכלי, ולכן תיאור ארוך יותר מגדיל ישירות את הגודל של הכלי.

סכימות של תגובות לא נכללות בתקציב הגודל. רק הערכים parameters ו-requestBody מגיעים להגדרות של MCP. לכן, אם מתבססים רק על הגודל של קובץ OpenAPI כדי להעריך את הקיבולת, בדרך כלל העלות תהיה גבוהה יותר מהעלות בפועל, כי רוב מפרטי OpenAPI האמיתיים כוללים הגדרות של סכימת תגובה שלא משפיעות על גודל הכלי.

הערכת הקיבולת של המפרט

הדרך הכי אמינה להעריך את קיבולת הכלי עבור מפרטי OpenAPI היא למדוד קבוצת משנה מייצגת:

  1. פריסת שרת proxy של MCP Discovery שמפנה לקבוצת משנה קטנה ומייצגת של הכלים שאתם מתכננים לפרסם (לדוגמה, 50 עד 100 כלים שמשקפים את השילוב של מספר הפרמטרים, גדלי גוף הבקשה ואורכי התיאור במפרט המלא).
  2. מבצעים קריאה ל-tools/list מול ה-proxy שפרסתם ומתעדים את גודל התגובה בבייטים ואת מספר הכלים שהוחזרו.
  3. מחלקים את גודל התגובה במספר הכלים כדי לקבל את הגודל הממוצע לכל כלי במפרט.
  4. מחלקים את מגבלת גודל התגובה הרלוונטית tools/list (10MiB כברירת מחדל) בממוצע הזה כדי להעריך את המספר המקסימלי של כלים שיכולים להתאים לשם מארח אחד עבור מפרט מהצורה הזו.

הגדלת הקיבולת

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

  • חלוקת כלי ה-shard בין שמות מארחים. tools/list מגבלת התשובות היא לכל שם מארח. פיצול כלים על פני כמה שמות מארחים באותה קבוצת סביבות מכפיל את המרווח לכל שם מארח (בכפוף למגבלה של 100 שמות מארחים לכל קבוצת סביבות). החלוקה לא מגדילה את מגבלת הגודל של חבילת הנתונים לכל שרת proxy. המגבלה של 50MiB ממשיכה לחול על כל שמות המארחים בשרת proxy יחיד של MCP Discovery.
  • הגדלת מגבלת גודל התשובה של tools/list מגבלת ברירת המחדל היא 10MiB לכל שם מארח. אפשר להגדיל את הנפח עד 30MiB. לפחות, צריך להגדיר את envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory ו-envs.components.runtime.cwcAppend.bin_setenv_max_mem ב-overrides.yaml, ואז להריץ את helm upgrade בתרשים apigee-org. במאמר הגדרת תמיכה במטען ייעודי (payload) של הודעות גדולות ב-Apigee Hybrid מוסבר על התהליך המלא, כולל וריאציות של הגדרות לכל סביבה לעומת הגדרות לכל ההתקנה, הנחיות לגבי גודל הערימה של מעבד ההודעות ודוגמאות מלאות של overrides.yaml. הגדלת מגבלת התגובה לא משפיעה על מגבלת הגודל של חבילת ה-proxy של MCP‏ (50MiB). אם הקיבולת שלכם מוגבלת בגלל המגבלה הזו, השינוי הזה לא יעזור.

אבטחה

גבולות האמון

מישור הנתונים של MCP פועל בתוך אשכול Kubernetes משלכם. ל-Google אין גישה בזמן ריצה למישור הנתונים. מישור הבקרה של Apigee מספק לכם הגדרת MCP שנגזרת ממפרט OpenAPI שלכם, אבל הוא לא עוקב אחרי תנועת הבקשות של MCP. נתוני ההגדרות במנוחה מאוחסנים בקטגוריה של Cloud Storage שמנוהלת על ידי Apigee, בהיקף של פרויקט הדייר של Apigee. נתוני ההגדרות מאוחזרים על ידי MCP sidecar באמצעות חשבון שירות Google Cloud הסביבתי שלו.

האופרטור של Apigee מקצה Kubernetes בהיקף MCP‏ Role ו-RoleBinding במרחב השמות של Apigee (APIGEE_NAMESPACE) עבור חשבון השירות של מישור הנתונים של MCP. התפקיד מעניק הרשאת קריאה בלבד:

  • ‫get, ‏list, ‏watch ב-services בקבוצת ה-API המרכזית.
  • ‫get, ‏list, ‏watch ב-apigeeroutes בקבוצת ה-API‏ apigee.cloud.google.com.

התפקיד לא מעניק פעלים של כתיבה ולא גישה אל Secrets,‏ ConfigMaps או סטטוס הפוד. הבודק יכול לאמת את הכללים המדויקים ישירות מהאשכול באמצעות:

APIGEE_ORG_CR=$(kubectl get apigeeorganization -n APIGEE_NAMESPACE \
  -o jsonpath='{.items[0].metadata.name}')
kubectl get role,rolebinding -n APIGEE_NAMESPACE \
  --field-selector metadata.name=apigee-mcp-server-$APIGEE_ORG_CR -o yaml

‫apigee-mcp-server-APIGEE_ORG_CR Role ו-RoleBinding הם משאבי RBAC בהיקף MCP. השמות שלהם כוללים את השם המלא של ApigeeOrganization המשאב המותאם אישית (שנגזר משם הארגון שלכם ב-Apigee ומגיבוב קצר). הן לא כוללות את התווית app=apigee-mcp-server ברמת המשאב (רק התרמילים כוללים אותה), ולכן חיפוש שמבוסס על תוויות לא יחזיר תוצאות. אם הפקודה field-selector שלמעלה לא מחזירה כלום, מריצים את הפקודה הבאה כדי להציג רשימה של כל משאב RBAC שקשור ל-MCP במרחב השמות:

kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server

‫TLS בין מעבד ההודעות לבין מישור הנתונים של MCP

פודים של מעבד ההודעות מתקשרים למישור הנתונים של MCP בכתובות https://mcp.apigee.internal/ או https://ORG_NAME.mcp.apigee.internal/. שמות המארחים האלה מומרים ל-ClusterIP של שירות ה-MCP באמצעות הרשומה hostAliases שמוזרקת. קונטיינר מישור הנתונים של MCP מציג אישור TLS שחתום על ידי המנפיק שסופק על ידי Apigee-operator (ה-ClusterIssuer שנקרא apigee-ca-issuer). שמות הנושא החלופיים של האישור כוללים את שני שמות המארחים.

הגבלת גישה נכנסת לשירות MCP

ב-Apigee hybrid 1.17.0, מישור הנתונים של MCP לא מאמת את המתקשרים אליו באופן עצמאי. הוא מסתמך על כך שהבקשות שמגיעות אליו כבר אומתו על ידי שרת proxy של Apigee MCP שפועל ב-מעבד בקשות. הגורם היחיד שאמור לקרוא לשירות ה-MCP הוא מעבד ההודעות. כל עומס עבודה אחר באותו אשכול שיכול להגיע ל-ClusterIP של שירות ה-MCP ב-TCP 443 יכול להפעיל כלי MCP בלי בדיקת אימות.

הגבלת הגישה הנכנסת לתרמילי ה-MCP רק לתרמילי Message Processor, באמצעות מנוע מדיניות הכניסה של הפלטפורמה (Kubernetes NetworkPolicy,‏ Cilium,‏ Calico,‏ Istio AuthorizationPolicy או מקבילים). ההגבלה:

  • מאפשר תעבורה נכנסת לפודים עם התווית app=apigee-mcp-server במרחב השמות APIGEE_NAMESPACE ב-TCP 443 מפודים עם התווית app=apigee-runtime באותו מרחב שמות בלבד.
  • דחיית כל שאר התנועה הנכנסת ב-TCP 443 לפודים עם התווית app=apigee-mcp-server.
  • דחיית כל הכניסות בתוך האשכול ב-TCP 15021 לפודים עם התווית app=apigee-mcp-server. יציאה 15021 משמשת לנקודת קצה (endpoint) של HTTP רגיל /healthz/ready לא מאומת, שמשמשת את kubelet לבדיקת מוכנות. kubelet מגיע אליה ישירות בכתובת ה-IP של הפוד, כך שאף עומס עבודה אחר באשכול לא אמור להגיע לפודים של MCP ביציאה 15021.

כדאי להחיל את ההגבלה הזו לפני שמסיימים את המדריך למתחילים בנושא MCP ופורסים את שרת ה-Proxy הראשון של MCP Discovery בסביבה שאינה סביבת פיתוח.

הסכם בנושא עדכניות ההגדרות

כשה-sidecar של MCP משלים שליפה מוצלחת של ההגדרות, קובץ ה-bundle שנשלף נטען במאגר של מישור הנתונים של MCP, והוא ממשיך לפעול עד לשליפה המוצלחת הבאה. אם פעולות משיכה עוקבות נכשלות (אי אפשר להגיע למישור הבקרה של Apigee, אי אפשר להגיע ל-Cloud Storage, הרשאת IAM הוסרה מחשבון השירות של שירות הצפייה או שגיאה בכל שלב אחר בצינור עיבוד הנתונים למשיכה), קובץ ה-sidecar ממשיך להציג את החבילה האחרונה שהייתה תקינה ללא הגבלת זמן. אין ב-1.17.0 ערך מקסימלי מובנה לזמן שחלף מאז העדכון: ה-pod נשאר Ready והתנועה של כלי ה-MCP ממשיכה להיות מופנית לחבילה שהנתונים שלה לא עדכניים. האות לכך שההגדרה הפסיקה להתעדכן הוא שורה ביומן של ה-sidecar ברמה ERROR שכוללת מונה consecutive_failures (במאמר פתרון בעיות בפריסות של MCP מפורטות ההודעות הספציפיות שמופקות על ידי ה-sidecar בכל שלב של כשל).

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

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

דרישות רשת לשיחות יוצאות

ל-MCP sidecar (מאגר ההגדרות בתוך כל MCP pod) נדרשת גישה לרשת יוצאת לנקודות הקצה הבאות ב-TCP 443. בוחרים את הכרטיסייה שמתאימה לשימוש במיקום אחסון הנתונים בארגון Apigee שלכם. נקודות הקצה הנדרשות שונות.

אין מיקום אחסון נתונים

נקודת קצה (endpoint) משמש ל:
apigee.googleapis.com אחזור ההפניה הנוכחית להגדרות MCP עבור הארגון שלכם ממישור הבקרה של Apigee בכל רענון של ההגדרות.
storage.googleapis.com מורידים את הגדרת ה-MCP של הארגון מ-Google Cloud Storage.

מיקום אחסון הנתונים

אם בארגון שלכם ב-Apigee מוגדר מיקום אחסון נתונים, ה-sidecar של MCP יפנה לנקודת הקצה האזורית של מישור הבקרה ב-Apigee (אותה נקודת קצה שבה משתמשים רכיבים אחרים של Apigee Hybrid, שהוגדרה באמצעות ערך התרשים contractProvider ב-overrides.yaml). צריך להחליף את CONTROL_PLANE_LOCATION במיקום מישור הבקרה של הארגון (לדוגמה, us, ‏ eu).

נקודת קצה (endpoint) משמש ל:
CONTROL_PLANE_LOCATION-apigee.googleapis.com בכל רענון של ההגדרה, מאחזרים את הפניה להגדרת ה-MCP הנוכחית של הארגון מנקודת הקצה של מישור הבקרה האזורי של Apigee.
storage.googleapis.com מורידים את הגדרת ה-MCP של הארגון מ-Google Cloud Storage. הקטגוריה ממוקמת באזור של הארגון, ו-Cloud Storage מנתב אליה באופן אוטומטי.

בנוסף, ל-sidecar צריכה להיות אפשרות להשיג אסימוני גישה ל-Google Cloud עבור פרטי הכניסה ברקע שה-pod פועל איתם (באמצעות איחוד שירותי אימות הזהות של עומסי עבודה או מפתח של חשבון שירות מבוסס-קובץ). נקודות הקצה הספציפיות להחלפת אסימונים תלויות בנתיב האימות שלכם, והן אותן נקודות קצה שרכיבים אחרים של Apigee hybrid כבר משתמשים בהן באשכול שלכם. אם תנועה קיימת של Apigee Hybrid אל Google Cloud APIs מצליחה ממרחב השמות הזה, גם החלפת האסימון של MCP sidecar מצליחה.

בנוסף, ל-Sidecar נדרשת גישה בתוך האשכול לשרת ה-API של Kubernetes (באמצעות כתובת השירות הרגילה בתוך האשכול) כדי לפרסם את מצב הפעילות והמוכנות שלו. התנועה הזו אף פעם לא יוצאת מהאשכול.

פתרון בעיות

רשימת משימות מלאה לאבחון מופיעה במאמר פתרון בעיות בפריסות של MCP, שכולל רשימת משימות לאבחון בצד האשכול עבור Apigee Hybrid.

כשלים נפוצים בהתקנה

תיאור הבעיה סיבה ופתרון
‫helm upgrade מסתיים אבל לא מופיעים מקורות מידע של MCP. תרשים הארגון שודרג לפני תרשים המפעיל. מריצים את helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ ואז מריצים מחדש את helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/.
תאי MCP תקועים ב-ContainerCreating או ב-1/2 Ready. שתי סיבות נפוצות: עדיין לא הונפק cert-manager Certificate עבור MCP, או שהשליפה של קובץ אימג' של קונטיינר נכשלת. מריצים את הפקודה kubectl describe pod בפוד המושפע כדי לראות את הסיבה המדויקת.
דוח יומנים של Sidecar (apigee-mcp-server-config) no MCP config from CP yet; skipping tick, pod stays Ready via seed בכל סקר. מצב יציב צפוי כשעדיין לא בוצע פריסה של שרת proxy של MCP Discovery בארגון. מישור הבקרה של Apigee מחזיר הפניה ריקה להגדרות, ובמישור הנתונים של MCP טוען רק את מאזין המוכנות של Kubernetes ביציאה 15021. ליציאת הבקשה של MCP‏ 8443 עדיין אין מאזין, ובקשות אל https://mcp.apigee.internal/mcp מקבלות סירוב לחיבור. כדי לעבור למצב של הצגת מודעות, פועלים לפי ההוראות שבמדריך למתחילים בנושא MCP כדי לפרוס שרת proxy של MCP Discovery בסביבה בקבוצת הסביבות שמוצגות על ידי האשכול הזה.
ביומנים של Sidecar מופיע CP fetch failed עם HTTP מוטמע 403 או PermissionDenied. לחשבון השירות של Apigee watcher ב-Google Cloud אין יותר את התפקיד roles/apigee.runtimeAgent (שמעניק את ההרשאה apigee.runtimeconfigs.get שנדרשת ל-sidecar) בפרויקט הדייר של Apigee. התפקיד הזה מוענק אוטומטית בהתקנה בסיסית של Apigee Hybrid. אם הוא הוסר על ידי סריקה אוטומטית של IAM, צריך להקצות אותו מחדש לחשבון השירות של apigee-watcher Google Cloud.
ביומנים של Sidecar מופיעה השגיאה CP fetch failed עם context deadline exceeded, שגיאות DNS או שגיאות TLS. ל-sidecar אין גישה ל-apigee.googleapis.com או ל-storage.googleapis.com מתוך האשכול. צריך לוודא שהיציאה מתבצעת מול שלוש נקודות הקצה שמפורטות בקטע דרישות הרשת ליציאה שלמעלה.
מעבד בקשות pods לא הופעלו מחדש אחרי helm upgrade. מוודאים שהערך hostAliases מופיע בכל פוד של MP: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. אם אחד מהפודים ריק, אפשר למחוק אותו (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime) כדי לאלץ רינדור חדש. הפוד ייווצר מחדש על ידי בקר ApigeeDeployment מהמפרט הנוכחי, כולל הרשומה hostAliases. אל תשתמשו ב-kubectl rollout restart deploy, כי הוא לא רלוונטי ל-ApigeeDeployment.
ב-MP pod logs מוצגות שגיאות של לחיצת יד בפרוטוקול TLS בחיוג https://mcp.apigee.internal/ או https://ORG_NAME.mcp.apigee.internal/ אחרי שתנועת הנתונים של כלי ה-MCP מתחילה לזרום דרך המדריך למתחילים. קונטיינר מישור הנתונים של MCP מציג אישור ששמות הנושא החלופיים (SAN) שלו לא כוללים את שם המארח שאליו חויג ה-MP. מאמתים את האישור: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, ואז kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. הפרמטר dnsNames של האישור צריך לכלול גם את mcp.apigee.internal וגם את ORG_NAME.mcp.apigee.internal באותיות קטנות. אם לא, צריך למחוק את משאב ה-MCP‏ Certificate ולאפשר ל-cert-manager להנפיק מחדש.

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