הדף הזה רלוונטי ל-Apigee Hybrid, אבל לא ל-Apigee.
אין מאמרי עזרה מקבילים של Apigee Edge בנושא הזה.
תיאור הבעיה
כשמציגים משאבים במרחב השמות apigee, מוצג ApigeeIssue עם Reason AIS_MCP_MTLS_CA_CERT_INVALID.
הבעיה הזו מופיעה רק בקבוצות סביבה שהבלוק mcpMtls שלהן מוגדר לאימות שרשרת (ברירת המחדל). בקבוצה עם mcpMtls.disableChainValidation: true, מישור הנתונים של ה-MCP לא משתמש באישור CA והסוד -cacert לא נסרק.
הודעות שגיאה
אחרי שמריצים את kubectl -n apigee get apigeeissues, מוצגת שגיאה כמו זו:
NAME SEVERITY REASON DOCUMENTATION AGE mcp-ca-cert-invalid-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CA_CERT_INVALID https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID 5h18m
סיבות אפשריות
בטבלה הבאה מפורטות הסיבות האפשריות לבעיה הזו:
| מטרה | תיאור |
|---|---|
| חסר ערך או סוד של אישור CA ל-mTLS של MCP |
הסוד -cacert לא קיים, או שאין לו רשומת cacert שאפשר להשתמש בה.
|
| אישור ה-CA של MCP mTLS לא מקודד ב-PEM |
הרשומה cacert לא מכילה בלוק של אישור PEM, או מכילה בייטים מחוץ לבלוקים של ה-PEM.
|
| אישור ה-CA של MCP mTLS לא תקין או שהוא לא אישור CA |
בלוק ברשומה cacert הוא לא אישור, לא מנותח או שהוא לא אישור CA.
|
הסיבה: חסר סוד או רשומה של אישור CA של MCP mTLS
הסוד של Kubernetes שאמור להכיל את אישור ה-CA שמישור הנתונים של MCP מאמת מולו את שער הכניסה לא קיים במרחב השמות apigee, או שהוא קיים בלי רשומה לא ריקה של cacert. השם שלו הוא השם של הסוד של אישור הלקוח, בתוספת -cacert. התרשים יוצר את הסוד הזה רק כשמשתמשים בקובצי אישורים. כשמשתמשים ב-sslSecret צריך ליצור אותו בעצמכם, ולשכוח לעשות את זה היא הסיבה הכי נפוצה לבעיה הזו.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-ca-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" not found Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" not found
התוכן של Spec.Details מציין את שם הסוד, את ApigeeRouteConfig ואת הבעיה. לדוגמה:
secret not foundsecret has no usable "cacert" entry
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-ca-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp-cacert. -
מזהים את השם של
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
...-
בודקים אם הסוד קיים ויש לו רשומה של
cacert, כאשר MCP_CA_SECRET_NAME הוא הסוד שצוין ב-Spec.Details:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
אם הסוד חסר או שאין בו רשומה, צריך לוודא שהקובץ שאליו מפנה
mcpMtls.caCertPathקיים ולא ריק. בשלב הבא משחזרים את הסוד מהגרסה. אם רוצים להפעיל בלי אימות שרשרת, צריך להגדיר אתmcpMtls.disableChainValidation: trueולהסיר אתmcpMtls.caCertPath(התרשים דוחה את שניהם ביחד). חשוב לזכור שהפעולה הזו משביתה את אימות האישור של שער הכניסה על ידי מישור הנתונים של MCP. -
משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:
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
...-
מוודאים שהסוד קיים בדיוק בשם הזה עם רשומה של
cacert, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד של אישור הלקוח שנקרא על ידיmcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
הפקודה
helm templateלא בודקת אם הסודות קיימים, אלא רקhelm installו-helm upgrade. לכן, הרצה נקייה שלhelm templateלא מוכיחה שהסוד הזה קיים. אם אתם מתכוונים להפעיל את האפליקציה בלי אימות שרשרת, לא מספיק להשמיט את הסוד. מגדירים אתmcpMtls.disableChainValidation: trueב-overrides.yamlומשדרגים את המארח הווירטואלי. חשוב לדעת שהפעולה הזו משביתה את האימות של אישור שער הכניסה על ידי מישור הנתונים של MCP. -
יוצרים או מעדכנים את הסוד של אישור ה-CA, כאשר MCP_CLIENT_SECRET_NAME הוא הערך של
mcpMtls.sslSecret, הסוד של אישור ה-CA הוא השם הזה בתוספת-cacert, ו-MCP_TRUST_CA_FILE הוא קובץ אישור ה-CA:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
הסיבה: אישור ה-CA של MCP mTLS לא מקודד ב-PEM
ברשומה cacert חסרים בלוקים של טקסט בקידוד PEM, או שיש בה תוכן אחרי השורה האחרונה של -----END CERTIFICATE----- שהוא לא PEM. מישור הנתונים של MCP לא טוען אותו.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-ca-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM
התוכן של Spec.Details מציין את שם הסוד, את ApigeeRouteConfig ואת הבעיה. לדוגמה:
entry holds no PEM encoded certificateholds N trailing bytes that are not PEM
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-ca-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp-cacert. -
מזהים את השם של
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.caCertPath, ולתקן אותו במקרה הצורך. חשוב לוודא שהתוכן מכיל רק בלוקים שלמים של אישורים, כל אחד עם שורות ההתחלה והסיום שלו. לדוגמה:-----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
...-
מאמתים את התוכן של קובץ אישור ה-CA (MCP_TRUST_CA_FILE) שמאוחסן ברשומה
cacertשל הסוד, ומתקנים אותו לפי הצורך. צריך לוודא שהתוכן מכיל רק בלוקים שלמים של אישורים, כל אחד עם שורת ההתחלה והסיום שלו. לדוגמה:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
מעדכנים את הסוד של אישור ה-CA במקום, כאשר MCP_CLIENT_SECRET_NAME הוא הערך של
mcpMtls.sslSecret, הסוד של אישור ה-CA הוא השם הזה בתוספת-cacert, ו-MCP_TRUST_CA_FILE הוא קובץ אישור ה-CA:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
הסיבה: אישור ה-CA של MCP mTLS לא תקין או שהוא לא אישור CA
כל בלוק PEM ברשומה cacert חייב להיות בלוק CERTIFICATE שעובר ניתוח ומכיל את האילוץ הבסיסי של רשות האישורים. בלוק של מפתח פרטי, אישור קצה (לדוגמה, אישור השרת של שער הכניסה) או בלוק פגום הופכים את הרשומה לבלתי שמישה, ומישור הנתונים של MCP לא טוען אותה.
אבחון
מריצים את הפקודה הבאה:
kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-ca-cert-invalid-my-org-my-virtualhost.
הפלט אמור להיראות כך:
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate
התוכן של Spec.Details מציין את שם הסוד, את ApigeeRouteConfig ואת הבעיה. לדוגמה:
-
no PEM block parsed as a certificate: ...: לא ניתן לנתח אף אחד מבלוקי האישורים (לדוגמה, האישור היחיד פגום). -
block N is a "..." block, want CERTIFICATE: בלוק N הוא לא אישור (לדוגמה, מפתח פרטי). -
block N does not parse: בלוק N הוא אישור פגום. -
block N is not a CA certificate: בלוק N הוא אישור, אבל לא CA (לדוגמה, אישור קצה).
הבלוקים ממוספרים החל מ-0.
רזולוציה
-
משתמשים ב-
kubectl describeכדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfigכדי להציג את הבעיה שאליה הוא שייך:kubectl -n apigee describe apigeeissue ISSUE_NAME
מחליפים את
ISSUE_NAMEבשם הבעיה, לדוגמהmcp-ca-cert-invalid-my-org-my-virtualhost.בדוגמה הזו,
ApigeeRouteConfigmy-org-my-virtualhostמפנה לסודmy-org-my-virtualhost-mcp-cacert. -
מזהים את השם של
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.caCertPathכך שיכיל רק את אישור ה-CA (או השרשרת) שחתם על האישור של שער הכניסה. לאחר מכן, מוודאים שכל בלוק הוא אישור CA, כאשר MCP_TRUST_CA_FILE הוא הקובץ הזה:openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:
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 (MCP_TRUST_CA_FILE) כך שיכיל רק את אישור ה-CA (או השרשרת) שחתם על האישור של שער הכניסה. ואז מוודאים שכל בלוק הוא אישור CA:
openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
מעדכנים את הסוד של אישור ה-CA במקום, כאשר MCP_CLIENT_SECRET_NAME הוא הערך של
mcpMtls.sslSecret, הסוד של אישור ה-CA הוא השם הזה בתוספת-cacert, ו-MCP_TRUST_CA_FILE הוא קובץ אישור ה-CA:kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_FILE \ --dry-run=client -o yaml | kubectl apply -f -
מישור הנתונים של MCP אוסף את הסוד המתוקן ברענון התקופתי הבא שלו, בדרך כלל תוך כמה דקות, בלי להפעיל מחדש את ה-Pod, וההתראה ApigeeIssue נמחקת בסריקה הבאה.
צריך לאסוף נתוני אבחון
אם הבעיה נמשכת גם אחרי שביצעתם את ההוראות שלמעלה, אספו את פרטי האבחון הבאים ופנו לCloud Customer Care:
- מזהה הפרויקט ב- Google Cloud .
- שם הארגון ב-Apigee Hybrid.
- השדה
Spec.DetailsשלApigeeIssue. -
(אופציונלי) האישור בקובץ שאליו מפנה
mcpMtls.caCertPath, או ברשומהcacertשל הסוד, למארח הווירטואלי המושפע.