הדף הזה רלוונטי ל-Apigee Hybrid, אבל לא ל-Apigee.
אין מאמרי עזרה מקבילים של Apigee Edge בנושא הזה.
תיאור הבעיה
כשמציגים משאבים במרחב השמות apigee, מוצג ApigeeIssue עם Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID.
הודעות שגיאה
אחרי שמריצים את kubectl -n apigee get apigeeissues, מוצגת שגיאה כמו זו:
NAME SEVERITY REASON DOCUMENTATION AGE mcp-client-cert-invalid-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CLIENT_CERT_INVALID https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID 5h18m
סיבות אפשריות
בטבלה הבאה מפורטות הסיבות האפשריות לבעיה הזו:
| מטרה | תיאור |
|---|---|
| חסר ערך או סוד של אישור לקוח mTLS של MCP |
הסוד שנקרא mcpMtls לא קיים, או שאין לו רשומה שמישה של cert או key.
|
| אישור הלקוח או המפתח של MCP mTLS לא תקין |
הרשומה cert לא מקודדת ב-PEM, או שהרשומה key היא לא המפתח הפרטי התואם.
|
| אישור הלקוח של MCP mTLS משמיט את השימוש במפתח המורחב clientAuth |
האישור מנותח, אבל השימוש המורחב במפתח לא כולל את clientAuth.
|
הסיבה: חסר סוד או רשומה של אישור לקוח mTLS של MCP
הסוד של Kubernetes שאמור להכיל את אישור הלקוח של MCP mTLS לא קיים במרחב השמות apigee, או שהוא קיים בלי רשומה לא ריקה של cert או בלי רשומה של key. למישור הנתונים של MCP אין אישור לקוח להציג לקבוצת הסביבות הזו, ולכן קריאות API לכלי של MCP לקבוצה נכשלות בלחיצת היד בפרוטוקול TLS.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID Annotations: <none> API Version: apigee.cloud.google.com/v1alpha1 Kind: ApigeeIssue Metadata: Creation Timestamp: 2026-11-12T17:03:43Z Generation: 1 Owner References: API Version: apigee.cloud.google.com/v1alpha2 Kind: ApigeeOrganization Name: my-org UID: 7e83a52c-ce00-4bed-98be-55835ada1817 Resource Version: 3281563 UID: adc775c2-376d-4bf9-9860-500b2b2b8273 Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found
התוכן של Spec.Details מציין את שם הסוד, את ApigeeRouteConfig ואת הבעיה. לדוגמה:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-client-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp. -
מזהים את השם של
virtualhostמתוךApigeeRouteConfig.השם של
ApigeeRouteConfigהוא בפורמט:<Apigee organization>-<virtualhost name>.בדוגמה הזו,
my-orgהוא הארגון ב-Apigee ושם המארח הווירטואלי הואmy-virtualhost. -
מאתרים את המארח הווירטואלי התואם ב-
overrides.yamlובודקים באיזו צורה משתמש הבלוקmcpMtlsשלו (ראו הגדרת mTLS בין מישור הנתונים של MCP לבין שער ה-ingress). בוחרים את הכרטיסייה המתאימה ופועלים לפי השלבים שמופיעים בה.
קובצי אישורים
כשמשתמשים בנתיבי קבצים (sslCertPath, sslKeyPath, caCertPath), תרשים ה-virtualhost יוצר ומנהל את הסודות מתוכן הקובץ.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
caCertPath: ./certs/ca.pem
sslCertPath: ./certs/vhost.pem
sslKeyPath: ./certs/vhost.key
mcpMtls:
caCertPath: ./certs/mcp-ca.pem
sslCertPath: ./certs/mcp-client.pem
sslKeyPath: ./certs/mcp-client.key
...-
בודקים אם הסוד קיים ומכיל את שני הרשומות, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שצוין ב-
Spec.Details. בקטעDataצריך לציין אתcertו-key:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
אם הסוד חסר או שאין בו רשומה, צריך לוודא שהקבצים שאליהם מפנים
mcpMtls.sslCertPathו-mcpMtls.sslKeyPathקיימים ולא ריקים. בשלב הבא משחזרים את הסוד מהם. -
משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
סודות ב-Kubernetes
כשמשתמשים בהפניה לסוד של Kubernetes (sslSecret), מישור הנתונים של MCP קורא את ערכי האישורים ישירות מהסודות שיצרתם, והעדכונים חלים באופן אוטומטי. אין צורך בhelm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
מוודאים שהסוד קיים וכולל את שני הרשומות, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שצוין ב-
Spec.Details. בקטעDataצריך לציין אתcertו-key. מוודאים שהשם בשדהmcpMtls.sslSecretתואם לסוד שיצרתם, ושהסוד נמצא במרחב השמותapigee:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME kubectl get secret -A --field-selector metadata.name=MCP_CLIENT_SECRET_NAME # if the first command finds nothing
הפקודה
helm templateלא בודקת אם הסודות קיימים, אלא רקhelm installו-helm upgrade. לכן, הרצה נקייה שלhelm templateלא מוכיחה שהסוד הזה קיים. -
יוצרים או מעדכנים את הסוד עם האישור והמפתח הפרטי שלו ביחד, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שנקרא ב-
Spec.Details, ו-MCP_CLIENT_CERT_FILE ו-MCP_CLIENT_KEY_FILE הם האישור והמפתח הפרטי שלו:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \ --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
הסיבה: אישור הלקוח או המפתח של MCP mTLS לא תקינים
הרשומה cert לא מכילה אישור X.509 בקידוד PEM, או שהרשומה key לא מקודדת ב-PEM או שהיא לא המפתח הפרטי של האישור הזה. מישור הנתונים של MCP לא יכול לטעון את הצמד.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID Annotations: <none> API Version: apigee.cloud.google.com/v1alpha1 Kind: ApigeeIssue Metadata: Creation Timestamp: 2026-11-12T17:03:43Z Generation: 1 Owner References: API Version: apigee.cloud.google.com/v1alpha2 Kind: ApigeeOrganization Name: my-org UID: 7e83a52c-ce00-4bed-98be-55835ada1817 Resource Version: 3281563 UID: adc775c2-376d-4bf9-9860-500b2b2b8273 Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key
התוכן של Spec.Details מציין את שם הסוד, את ApigeeRouteConfig ואת הבעיה. לדוגמה:
-
entry holds no PEM encoded certificate: הרשומהcertהיא לא PEM. -
tls: failed to find any PEM data in key input: הרשומהkeyהיא לא PEM. -
tls: private key does not match public key: הרשומותcertו-keyלא תואמות. -
tls: failed to parse private key: אי אפשר לנתח את המפתח, בדרך כלל כי הוא מוצפן. הערך שלkeyחייב להיות מפתח פרטי לא מוצפן בפורמט PEM.
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-client-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp. -
מזהים את השם של
virtualhostמתוךApigeeRouteConfig.השם של
ApigeeRouteConfigהוא בפורמט:<Apigee organization>-<virtualhost name>.בדוגמה הזו,
my-orgהוא הארגון ב-Apigee ושם המארח הווירטואלי הואmy-virtualhost. -
מאתרים את המארח הווירטואלי התואם ב-
overrides.yamlובודקים באיזו צורה משתמש הבלוקmcpMtlsשלו (ראו הגדרת mTLS בין מישור הנתונים של MCP לבין שער ה-ingress). בוחרים את הכרטיסייה המתאימה ופועלים לפי השלבים שמופיעים בה.
קובצי אישורים
כשמשתמשים בנתיבי קבצים (sslCertPath, sslKeyPath, caCertPath), תרשים ה-virtualhost יוצר ומנהל את הסודות מתוכן הקובץ.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
caCertPath: ./certs/ca.pem
sslCertPath: ./certs/vhost.pem
sslKeyPath: ./certs/vhost.key
mcpMtls:
caCertPath: ./certs/mcp-ca.pem
sslCertPath: ./certs/mcp-client.pem
sslKeyPath: ./certs/mcp-client.key
...-
צריך לאמת את קובץ האישור ואת קובץ המפתח שאליהם מפנים
mcpMtls.sslCertPathו-mcpMtls.sslKeyPath, ולתקן אותם במקרה הצורך. האישור חייב להכיל את שורות ההתחלה והסיום של האישור, והמפתח חייב להיות המפתח הפרטי שלו. לדוגמה:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
סודות ב-Kubernetes
כשמשתמשים בהפניה לסוד של Kubernetes (sslSecret), מישור הנתונים של MCP קורא את ערכי האישורים ישירות מהסודות שיצרתם, והעדכונים חלים באופן אוטומטי. אין צורך בhelm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
מאמתים את קובץ האישור (MCP_CLIENT_CERT_FILE) ואת קובץ המפתח (MCP_CLIENT_KEY_FILE) שמאוחסנים ברשומות
certו-keyשל הסוד, ומתקנים אותם במקרה הצורך. האישור חייב להכיל את שורות ההתחלה והסיום של האישור, והמפתח חייב להיות המפתח הפרטי שלו. לדוגמה:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
מעדכנים את הסוד במקום עם האישור והמפתח הפרטי שלו ביחד, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שנקרא ב-
Spec.Detailsו-MCP_CLIENT_CERT_FILE ו-MCP_CLIENT_KEY_FILE הם האישור והמפתח הפרטי שלו:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \ --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
הסיבה: אישור הלקוח של MCP mTLS משמיט את השימוש המורחב במפתח clientAuth
האישור תקין ומשויך למפתח שלו, אבל השימוש המורחב במפתח (EKU) לא כולל את clientAuth, ולכן אי אפשר להשתמש בו לאימות הלקוח ומישור הנתונים של ה-MCP לא מציג אותו. זה קורה בדרך כלל כשמשתמשים שוב באותו אישור שרת, או באותו אישור מפרופיל של רשות אישורים ציבורית שכבר לא מנפיקה אישורי clientAuth.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID Annotations: <none> API Version: apigee.cloud.google.com/v1alpha1 Kind: ApigeeIssue Metadata: Creation Timestamp: 2026-11-12T17:03:43Z Generation: 1 Owner References: API Version: apigee.cloud.google.com/v1alpha2 Kind: ApigeeOrganization Name: my-org UID: 7e83a52c-ce00-4bed-98be-55835ada1817 Resource Version: 3281563 UID: adc775c2-376d-4bf9-9860-500b2b2b8273 Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth
התוכן של Spec.Details מציין את שם הסוד ואת ApigeeRouteConfig, ומפרט את השימושים המורחבים במפתחות שהאישור כולל.
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-client-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp. -
מזהים את השם של
virtualhostמתוךApigeeRouteConfig.השם של
ApigeeRouteConfigהוא בפורמט:<Apigee organization>-<virtualhost name>.בדוגמה הזו,
my-orgהוא הארגון ב-Apigee ושם המארח הווירטואלי הואmy-virtualhost. -
מאתרים את המארח הווירטואלי התואם ב-
overrides.yamlובודקים באיזו צורה משתמש הבלוקmcpMtlsשלו (ראו הגדרת mTLS בין מישור הנתונים של MCP לבין שער ה-ingress). בוחרים את הכרטיסייה המתאימה ופועלים לפי השלבים שמופיעים בה.
קובצי אישורים
כשמשתמשים בנתיבי קבצים (sslCertPath, sslKeyPath, caCertPath), תרשים ה-virtualhost יוצר ומנהל את הסודות מתוכן הקובץ.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
caCertPath: ./certs/ca.pem
sslCertPath: ./certs/vhost.pem
sslKeyPath: ./certs/vhost.key
mcpMtls:
caCertPath: ./certs/mcp-ca.pem
sslCertPath: ./certs/mcp-client.pem
sslKeyPath: ./certs/mcp-client.key
...-
מנפיקים מחדש את אישור הלקוח מה-CA הפרטי עם פרופיל שכולל את השימוש המורחב במפתח
clientAuth. מאשרים את זה, כאשר MCP_CLIENT_CERT_FILE הוא האישור שהונפק מחדש, ואז מחליפים את הקבצים שאליהם מפניםmcpMtls.sslCertPathו-mcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
סודות ב-Kubernetes
כשמשתמשים בהפניה לסוד של Kubernetes (sslSecret), מישור הנתונים של MCP קורא את ערכי האישורים ישירות מהסודות שיצרתם, והעדכונים חלים באופן אוטומטי. אין צורך בhelm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
מנפיקים מחדש את אישור הלקוח מה-CA הפרטי עם פרופיל שכולל את השימוש המורחב במפתח
clientAuth. צריך לאמת את זה לפני שמעדכנים את הסוד, כאשר MCP_CLIENT_CERT_FILE הוא האישור שהונפק מחדש:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
מעדכנים את הסוד במקום עם האישור והמפתח הפרטי שלו ביחד, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שנקרא ב-
Spec.Detailsו-MCP_CLIENT_CERT_FILE ו-MCP_CLIENT_KEY_FILE הם האישור והמפתח הפרטי שלו:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \ --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
צריך לאסוף נתוני אבחון
אם הבעיה נמשכת גם אחרי שביצעתם את ההוראות שלמעלה, אספו את פרטי האבחון הבאים ופנו לCloud Customer Care:
- מזהה הפרויקט ב- Google Cloud .
- שם הארגון ב-Apigee Hybrid.
- השדה
Spec.DetailsשלApigeeIssue. -
(אופציונלי) האישור בקובץ שאליו מפנה
mcpMtls.sslCertPath, או ברשומהcertשל הסוד, למארח הווירטואלי המושפע.