אישור הלקוח של MCP mTLS לא תקין

הדף הזה רלוונטי ל-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 found
  • secret has no usable "cert" entry
  • secret has no "key" entry

רזולוציה

  1. משתמשים ב-kubectl describe כדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfig כדי להציג את הבעיה שאליה הוא שייך:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.

    בדוגמה הזו, ApigeeRouteConfig my-org-my-virtualhost מפנה לסוד my-org-my-virtualhost-mcp.

  2. מזהים את השם של virtualhost מתוך ApigeeRouteConfig.

    השם של ApigeeRouteConfig הוא בפורמט: <Apigee organization>-<virtualhost name>.

    בדוגמה הזו, my-org הוא הארגון ב-Apigee ושם המארח הווירטואלי הוא my-virtualhost.

  3. מאתרים את המארח הווירטואלי התואם ב-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
...
  1. בודקים אם הסוד קיים ומכיל את שני הרשומות, כאשר MCP_CLIENT_SECRET_NAME הוא הסוד שצוין ב-Spec.Details. בקטע Data צריך לציין את cert ו-key:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    אם הסוד חסר או שאין בו רשומה, צריך לוודא שהקבצים שאליהם מפנים mcpMtls.sslCertPath ו-mcpMtls.sslKeyPath קיימים ולא ריקים. בשלב הבא משחזרים את הסוד מהם.

  2. משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:

    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
...
  1. מוודאים שהסוד קיים וכולל את שני הרשומות, כאשר 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 לא מוכיחה שהסוד הזה קיים.

  2. יוצרים או מעדכנים את הסוד עם האישור והמפתח הפרטי שלו ביחד, כאשר 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.

רזולוציה

  1. משתמשים ב-kubectl describe כדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfig כדי להציג את הבעיה שאליה הוא שייך:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.

    בדוגמה הזו, ApigeeRouteConfig my-org-my-virtualhost מפנה לסוד my-org-my-virtualhost-mcp.

  2. מזהים את השם של virtualhost מתוך ApigeeRouteConfig.

    השם של ApigeeRouteConfig הוא בפורמט: <Apigee organization>-<virtualhost name>.

    בדוגמה הזו, my-org הוא הארגון ב-Apigee ושם המארח הווירטואלי הוא my-virtualhost.

  3. מאתרים את המארח הווירטואלי התואם ב-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
...
  1. צריך לאמת את קובץ האישור ואת קובץ המפתח שאליהם מפנים mcpMtls.sslCertPath ו-mcpMtls.sslKeyPath, ולתקן אותם במקרה הצורך. האישור חייב להכיל את שורות ההתחלה והסיום של האישור, והמפתח חייב להיות המפתח הפרטי שלו. לדוגמה:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. משדרגים את המארח הווירטואלי כדי שהתרשים ישכתב את הסוד:

    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
...
  1. מאמתים את קובץ האישור (MCP_CLIENT_CERT_FILE) ואת קובץ המפתח (MCP_CLIENT_KEY_FILE) שמאוחסנים ברשומות cert ו-key של הסוד, ומתקנים אותם במקרה הצורך. האישור חייב להכיל את שורות ההתחלה והסיום של האישור, והמפתח חייב להיות המפתח הפרטי שלו. לדוגמה:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. מעדכנים את הסוד במקום עם האישור והמפתח הפרטי שלו ביחד, כאשר 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, ומפרט את השימושים המורחבים במפתחות שהאישור כולל.

רזולוציה

  1. משתמשים ב-kubectl describe כדי להציג את שם הסוד של Kubernetes וב-ApigeeRouteConfig כדי להציג את הבעיה שאליה הוא שייך:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-invalid-my-org-my-virtualhost.

    בדוגמה הזו, ApigeeRouteConfig my-org-my-virtualhost מפנה לסוד my-org-my-virtualhost-mcp.

  2. מזהים את השם של virtualhost מתוך ApigeeRouteConfig.

    השם של ApigeeRouteConfig הוא בפורמט: <Apigee organization>-<virtualhost name>.

    בדוגמה הזו, my-org הוא הארגון ב-Apigee ושם המארח הווירטואלי הוא my-virtualhost.

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

    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
...
  1. מנפיקים מחדש את אישור הלקוח מה-CA הפרטי עם פרופיל שכולל את השימוש המורחב במפתח clientAuth. צריך לאמת את זה לפני שמעדכנים את הסוד, כאשר MCP_CLIENT_CERT_FILE הוא האישור שהונפק מחדש:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. מעדכנים את הסוד במקום עם האישור והמפתח הפרטי שלו ביחד, כאשר 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:

  1. מזהה הפרויקט ב- Google Cloud .
  2. שם הארגון ב-Apigee Hybrid.
  3. השדה Spec.Details של ApigeeIssue.
  4. (אופציונלי) האישור בקובץ שאליו מפנה mcpMtls.sslCertPath, או ברשומה cert של הסוד, למארח הווירטואלי המושפע.