‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

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

מוסכמות לגבי placeholders בדף הזה. כל פקודה kubectl ו-helm בדף הזה משתמשת בערכי ה-placeholder הבאים. מחליפים אותם בערכים מההתקנה שלכם:

‫APIGEE_NAMESPACE — מרחב השמות של Kubernetes שבו מותקן Apigee Hybrid (ברירת המחדל היא apigee). מחפשים את השדה namespace בקובץ overrides.yaml.
‫APIGEE_OPERATOR_RELEASE_NAME – השם של מהדורת Helm של תרשים apigee-operator באשכול (בדרך כלל: operator או apigee-operator, אבל הלקוח בוחר). צריך לאשר את הפעולה באמצעות helm list -n APIGEE_NAMESPACE | grep apigee-operator.
‫APIGEE_ORG_RELEASE_NAME – שם הגרסה של Helm לתרשים apigee-org באשכול (בדרך כלל: שם הארגון או apigee-org, אבל הלקוח בוחר). צריך לאשר את הפעולה באמצעות helm list -n APIGEE_NAMESPACE | grep apigee-org.

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

פותחים את קובץ overrides.yaml שמשמש לתרשימי ה-Helm של Apigee Hybrid. ‫At the top level of the file, add:

enableMcpServer: true

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

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

המלצה: כדאי לעשות שימוש חוזר בזהות apigee-watcher. אין צורך ליצור חשבון שירות ייעודי ב-Google Cloud עבור מישור הנתונים של MCP. אם לא מגדירים את mcpServer.gsa ואת mcpServer.serviceAccountPath (כמו בכל שלושת הווריאציות שמופיעות בהמשך), מערכת MCP חוזרת לזהות apigee-watcher שכבר נמצאת בשימוש באשכול: קודם watcher.gsa (Workload Identity) או watcher.serviceAccountPath (מבוסס-קובץ), ואז gcp.workloadIdentity.gsa או envs[].serviceAccountPaths.runtime. לזהות apigee-watcher כבר יש את התפקיד roles/apigee.runtimeAgent ואת הרשאות הקריאה שנדרשות ל-MCP sidecar, כך שאפשר להשתמש בה מחדש בלי לבצע שינויים, ולשמור על טביעת רגל מינימלית של IAM. מגדירים את העקיפה mcpServer.gsa או mcpServer.serviceAccountPath רק אם הארגון דורש הפרדה של הזהויות בכל רכיב מסיבות של ביקורת.

בוחרים את הכרטיסייה שמתאימה לאופן שבו ההתקנה הבסיסית מאמתת רכיבי 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.
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
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 מקבל בירושה את הזהות שמגובה על ידי WIF, ש-apigee-watcher כבר משתמש בה באשכול שלכם – אתם לא מוסיפים הגדרת זהות ספציפית ל-MCP.

מוסיפים את מפתח ה-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 ומבצע את הפעולה באמצעות WIF.

הערה: enableMcpServer הוא מפתח ברמה העליונה. כשמוסיפים אותו ל-overrides.yaml קיים, משתמשים באותה רמת כניסה כמו instanceID, gcp ו-org – לא מכניסים אותו כרכיב בתוך mcpServer או כל קטע אחר.

מנגנוני זיהוי אחרים. אם ההתקנה הבסיסית שלכם מאחסנת את פרטי הכניסה של חשבון השירות ב-Kubernetes‏ Secret (דרך serviceAccountRef) או ב-HashiCorp Vault דרך מנהל התקן ה-CSI (דרך serviceAccountSecretProviderClass), ה-MCP יקבל בירושה את אותו מנגנון באופן אוטומטי – לא צריך להוסיף הגדרה ספציפית ל-MCP. במאמרים אחסון מפתחות של חשבונות שירות בסוד של Kubernetes ואחסון סודות של חשבונות שירות ב-HashiCorp Vault מוסבר איך מגדירים את המנגנון הבסיסי.

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

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

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

הערה: ההרשאה הזו נפרדת מההרשאות synchronizer_identities ו-analytics_publisher_identities שהגדרתם לרכיבים אחרים של Apigee Hybrid. ה-sidecar של MCP משתמש במשבצת זהות נפרדת ולא מקבל בירושה הרשאות מההרשאות האלה. מידע נוסף על ה-API הבסיסי זמין במאמר הפעלת גישה למנגנון הסנכרון (אותו API, משבצת זהות שונה).

מגדירים את משתני ה-Shell שמשמשים לקריאה ל-API. שימוש חוזר בערכים מההתקנה:
```
export ORG_NAME=YOUR_ORG_NAME
export PROJECT_ID=YOUR_GCP_PROJECT_ID
export WATCHER_SA=apigee-watcher@${PROJECT_ID}.
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}..
קוראים ל-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 שזמינים לשימוש.
הקריאה מחזירה פעולה ממושכת. צריך להמתין עד שהתהליך יושלם לפני שמבצעים את שלב האימות שבהמשך.
מוודאים שהמענק התקבל. קוראים ל-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."
  ]
}
```
אם watcherIdentities לא מופיע בתשובה או לא מכיל את חשבון השירות של שירות הצפייה, מריצים מחדש את פקודת ה-PATCH ובודקים את סטטוס הפעולה כדי לוודא שאין שגיאות לפני שממשיכים.

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

הערה: לפני שמריצים את הפקודה helm upgrade, צריך לוודא שספריות התרשימים המקומיות apigee-operator/ ו-apigee-org/ הן מגרסה 1.17.0 ואילך. אם התרשימים המקומיים עדיין מופיעים בערך 1.16.x או נמוך יותר, השלב הזה ידווח על הצלחה אבל לא יתקין את סכימת המשאבים של MCP, ושאר התהליך לא יבצע פעולות בלי תפעול (no-ops). במדריך לשדרוג Apigee Hybrid מוסבר איך לאחזר את הגרסה הנכונה של התרשים.

קודם משדרגים את תרשים האופרטור. תרשים האופרטורים הוא הבעלים של הסכימה של משאבי ה-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 מפורטות ארבע יציאות:

‫443/TCP היא היציאה שמשמשת לתנועת בקשות של MCP מ-Message Processor. כל קריאה לכלי MCP למישור הנתונים של MCP בתוך האשכול מגיעה ליציאה הזו דרך TLS.
‫15021/TCP חושף את נקודת הקצה של מישור הנתונים של ה-MCP בכתובת /healthz/ready באמצעות HTTP רגיל. ‫Kubelet משתמש בנקודת הקצה הזו (שאליה מגיעים ישירות בכל כתובת IP של פוד) כדי להחליט אם פוד MCP הוא Ready.
הפרטים של 80/TCP ושל 15000/TCP מופיעים גם במניפסט של השירות. ב-1.17.0, אף לקוח MCP בתוך האשכול לא אמור לשלוח תנועה ליציאות האלה דרך השירות. תנועה של כלי MCP משתמשת רק ב-443/TCP.

‫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. לפרט את כל הפודים של 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.apigee.internal ו-ORG_NAME.mcp.apigee.internal ניתנים לפתרון רק מתוך תרמילי Message Processor באשכול, באמצעות רשומת hostAliases שמוחדרת בהליך הזה. אין להשתמש בהן ככתובות URL של נקודות קצה של MCP שפונות ללקוח. לקוחות חיצוניים של MCP מגיעים למישור הנתונים של MCP דרך שם המארח של Apigee Ingress, באותו אופן שבו הם מגיעים לכל פרוקסי אחר של Apigee.

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

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

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

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

אתם מאמתים את תנועת הגולשים בכלי MCP מקצה לקצה (קריאה בפועל של MCP initialize או tools/list דרך ה-ingress של Apigee) כחלק מהמדריך המהיר המשותף של 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 לשימוש בהיבריד 1.17.0.

שדה	סוג	ברירת מחדל	התאמה מומלצת
`enableMcpServer`	בוליאני	`false`	חובה. מגדירים את הערך `true` כדי להפעיל את ה-MCP באשכול הזה. החלפת המצב של השדה הזה מפעילה הפצה מדורגת של גרסה איטרטיבית לקהל מצומצם (canary release) של מעבד בקשות. הפעלה או השבתה של התכונה צריכות להתבצע רק בחלון זמן לתחזוקה, וצריך לחכות עד שההפצה תושלם לפני שממשיכים.
`mcpServer.replicaCountMin`	מספר שלם	`2`	צריך לשמור על `2` ל-HA. הגדלה רק אם יש לכם בסיס של תנועה גבוהה של MCP התנועה; ה-HPA מתרחב אוטומטית תחת לחץ CPU. אות: HPA ממושך ב-`replicaCountMax` ו-CPU מעל היעד.
`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`	אם הפודים מושבתים לעיתים קרובות בגלל חריגה ממגבלת הזיכרון (OOMKilled) או שהשימוש במעבד שלהם מוגבל (CPU-throttled) במצב יציב, כדאי להגדיל את מספר הבקשות. אות: `kubectl describe pod` מוצגים תנאים של OOMKilled או throttled.
`mcpServer.resources.limits`	ResourceList	`cpu: 2000m, memory: 1Gi`	כדאי להגדיל את מגבלת המעבד לפני שמגדילים את מספר העותקים, אם זמן האחזור של אחוזון 95 גבוה אבל קצב השאילתות הכולל נמוך (מעט בקשות יקרות). כדאי להגדיל את מגבלת הזיכרון רק אם מופיעות שגיאות מסוג 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 בהמתנה צריכות יותר זמן להשלמה במהלך ניקוי ה-pod.
`mcpServer.annotations`	מפה	`{}`	מוסיפים עוד הערות ל-Pod אם נדרש באשכול.
`mcpServer.serviceAccountPath`	מחרוזת	unset	אל תגדירו את הערך הזה אלא אם אתם צריכים הפרדה של זהויות לכל רכיב. אם לא מוגדר ערך, MCP חוזר לערך `watcher.serviceAccountPath` ואז לערך `envs[].serviceAccountPaths.runtime`. לזהות `apigee-watcher` כבר יש את ההרשאות שנדרשות ל-MCP sidecar. הנתיב לקובץ JSON של מפתח חשבון שירות ב-Google Cloud אם מבצעים שינוי. המאפיין הזה בלעדי למאפיין `mcpServer.gsa`. מומלץ להשתמש ב-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`.
`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 קבועות באופרטור ולא ניתן להגדיר אותן דרך overrides.yaml בגרסה 1.17.0. במאמר הזה מפורטות ארבעת יציאות השירות. לסיכום: ביציאה 443 עובר התנועה של כלי ה-MCP ממעבד ההודעות, והיא ממופה מחדש ליציאה 8443 של ה-pod. ביציאה 15021 נחשף נקודת הקצה של מוכנות מישור הנתונים של ה-MCP שמשמשת את kubelet. היציאות 80 ו-15000 מוצהרות גם במניפסט של השירות ולא משמשות את התנועה של כלי ה-MCP ב-1.17.0.

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

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

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

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

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

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

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

הגבלה	ערך	היקף	מצב כשל
גודל הקובץ של מפרט OpenAPI	‫3MiB	לכל קובץ `.yaml`	`400` ב-proxy validate
גודל חבילת ה-proxy של MCP (לאחר פתיחת הדחיסה)	‫50MiB	לכל שרת proxy של MCP Discovery	`400` ב-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 היא למדוד קבוצת משנה מייצגת:

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

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

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

שיתוף כלים בין שמות מארחים. מכסת התשובות tools/list היא לכל שם מארח. פיצול כלים בין כמה שמות מארחים באותה קבוצת סביבות מכפיל את המרווח לכל שם מארח (בכפוף למגבלה של 100 שמות מארחים לכל קבוצת סביבות). השימוש ב-Sharding לא מגדיל את המגבלה לכל חבילת proxy. המגבלה של 50MiB לכל חבילה ממשיכה לחול על כל שמות המארחים ב-MCP Discovery Proxy יחיד.
הגדלת מגבלת גודל התשובה של 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. ההליך המלא, כולל וריאציות של הגדרות לכל סביבה לעומת הגדרות לכל ההתקנה, הנחיות לגבי גודל הערימה של מעבד ההודעות ודוגמאות מלאות של overrides.yaml, מפורט במאמר הגדרת תמיכה במטען ייעודי (payload) של הודעות גדולות ב-Apigee Hybrid. הגדלת מגבלת התגובה לא משפיעה על מגבלת הגודל של חבילת ה-MCP proxy, שהיא 50MiB. אם הקיבולת שלכם מוגבלת בגלל המגבלה הזו, השינוי הזה לא יעזור.

הערה לגבי הגרסה: ארבע המגבלות הקשיחות שלמעלה חלות על גרסה 1.17.0 של Apigee Hybrid. אם תשדרגו לגרסה מאוחרת יותר, תצטרכו לבדוק מחדש את המגבלות האלה ולהריץ מחדש את ההערכה של המפרטים לפני שתתחייבו לקיבולת.

אבטחה

גבול האמון

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

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 וה-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/. שמות המארחים האלה מקבלים את כתובת ה-IP של אשכול שירות ה-MCP דרך הרשומה hostAliases שמוחדרת. מאגר הנתונים של MCP מציג אישור TLS שחתום על ידי הרשות המנפיקה שהוקצתה על ידי Apigee-operator (ה-ClusterIssuer שנקרא apigee-ca-issuer). שמות הנושא החלופיים של האישור כוללים את שני שמות המארחים.

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

ב-Apigee hybrid 1.17.0, מישור הנתונים של MCP לא מאמת באופן עצמאי את המתקשרים שלו. הוא מניח שהבקשות שמגיעות אליו כבר אומתו על ידי שרת proxy של Apigee MCP שפועל ב-מעבד בקשות. הגורם היחיד שאמור לקרוא לשירות ה-MCP הוא Message Processor. כל עומס עבודה אחר באותו אשכול שיכול להגיע ל-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 משלים משיכה מוצלחת של הגדרות, קונטיינר מישור הנתונים של 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) צריכה להיות גישה לרשת יוצאת לנקודות הקצה הבאות ב-TCP 443. בוחרים את הכרטיסייה שמתאימה לשימוש של הארגון שלכם ב-Apigee במיקום אחסון הנתונים. נקודות הקצה הנדרשות שונות.

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

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

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

אם בארגון שלכם ב-Apigee מוגדר מיקום אחסון נתונים, רכיב ה-sidecar של MCP יפנה לנקודת הקצה האזורית של מישור הבקרה ב-Apigee (אותה נקודת קצה שבה משתמשים רכיבים היברידיים אחרים של Apigee, שהוגדרה באמצעות ערך התרשים 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 (באמצעות Workload Identity או מפתח של חשבון שירות מבוסס-קובץ). נקודות הקצה הספציפיות להחלפת אסימונים תלויות בנתיב האימות שלכם, והן אותן נקודות קצה שרכיבים אחרים של Apigee hybrid כבר משתמשים בהן באשכול שלכם. אם תנועת נתונים קיימת של Apigee Hybrid אל Google Cloud APIs מצליחה ממרחב השמות הזה, גם החלפת האסימון של MCP sidecar מצליחה.

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

אל תוסיפו לרשימת ההיתרים רק את apigee.googleapis.com. אם אמצעי הבקרה של תעבורת נתונים יוצאת (egress) מאפשרים את הקריאה של מישור הבקרה של Apigee אבל חוסמים את storage.googleapis.com, קובץ העזר משלים את אחזור ההפניה להגדרה בהצלחה, אבל נכשל באחזור החבילה הבא. הקונטיינר של מישור הנתונים של MCP ממשיך להציג הגדרות לא עדכניות או ריקות, והכשל לא בולט: מישור הנתונים של MCP נראה תקין אבל הוא אף פעם לא מאתר פריסות חדשות של שרת ה-proxy של MCP Discovery. צריך להוסיף לרשימת ההיתרים את שתי נקודות הקצה בטבלה שלמעלה (ולשמור את תעבורת הנתונים היוצאת (egress) של החלפת הטוקנים שרכיבי Apigee Hybrid האחרים כבר מסתמכים עליה).

פתרון בעיות

רשימת משימות מלאה לאבחון מופיעה במאמר פתרון בעיות בפריסות של 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 בארגון. מישור הבקרה של Apigee מחזיר הפניה ריקה להגדרה, ובמישור הנתונים של MCP טוען רק את מאזין המוכנות של Kubernetes ביציאה `15021`. ליציאת הבקשה של MCP‏ `8443` עדיין אין מאזין, ובקשות אל `https://mcp.apigee.internal/mcp` מקבלות דחייה של החיבור. כדי לעבור למצב של הצגת מודעות, פועלים לפי ההוראות שבמדריך למתחילים של MCP כדי לפרוס פרוקסי של 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`.
בקטעי היומן של ה-pod של MP מוצגות שגיאות של לחיצת יד בפרוטוקול 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` להנפיק אותו מחדש.

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

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

הפעלת Model Context Protocol‏ (MCP) ב-Apigee Hybrid קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

Workload Identity‏ (GKE)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

חזרה לגרסה קודמת

הפניה: שדות MCP ב-overrides.yaml

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

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

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

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

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

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

אבטחה

גבול האמון

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

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

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

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

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

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

פתרון בעיות

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

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

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

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

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

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

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

הפניה: שדות MCP ב-`overrides.yaml`