תפוגת התוקף של אישור הלקוח של MCP mTLS

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

אין מאמרי עזרה מקבילים של Apigee Edge בנושא הזה.

תיאור הבעיה

כשמציגים משאבים במרחב השמות apigee, מוצג ApigeeIssue עם Reason AIS_MCP_MTLS_CLIENT_CERT_EXPIRY.

הודעות שגיאה

אחרי שמריצים את kubectl -n apigee get apigeeissues, מוצגת בעיה כמו זו:

NAME                                            SEVERITY   REASON                            DOCUMENTATION                                                                                 AGE
mcp-client-cert-expired-my-org-my-virtualhost   ERROR      AIS_MCP_MTLS_CLIENT_CERT_EXPIRY   https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY   5h18m

סיבות אפשריות

בטבלה הבאה מפורטות הסיבות האפשריות לבעיה הזו:

מטרה תיאור
התוקף של אישור הלקוח לשרת בחיבור mTLS של MCP יפוג בקרוב התוקף של אישור הלקוח של MCP mTLS שהוגדר יפוג תוך 14 ימים.
פג התוקף של אישור הלקוח של MCP mTLS פג התוקף של אישור הלקוח של mTLS ב-MCP שהוגדר.

הסיבה: התוקף של אישור הלקוח של MCP mTLS יפוג בקרוב

התוקף של אישור הלקוח של MCP mTLS שמאוחסן בסוד של Kubernetes שאליו מפנה ApigeeRouteConfig יפוג ב-14 הימים הקרובים.

אבחון

מריצים את הפקודה הבאה:

kubectl -n apigee describe apigeeissue ISSUE_NAME

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

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

Name:         mcp-client-cert-expiring-soon-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
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 expiring in 335h12m4s at 2026-11-26 16:15:47 +0000 UTC
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
  Severity:       WARNING
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is expiring in 335h12m4s at 2026-11-26 16:15:47 +0000 UTC

התוכן של Spec.Details מסביר את השם של ApigeeRouteConfig שמתייחס לסוד של Kubernetes שמכיל את אישור הלקוח של MCP mTLS שתוקפו עומד לפוג בקרוב.

רזולוציה

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-expiring-soon-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 mTLS מרשות האישורים, ולהחליף את האישור ואת המפתח הפרטי שלו ביחד בקבצים שאליהם מפנים 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. משיגים אישור לקוח mTLS מחודש של MCP ואת המפתח הפרטי שלו מרשות האישורים.

  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

פג התוקף של אישור הלקוח של MCP mTLS שמאוחסן בסוד של Kubernetes שאליו מפנה ApigeeRouteConfig.

אבחון

מריצים את הפקודה הבאה:

kubectl -n apigee describe apigeeissue ISSUE_NAME

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

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

Name:         mcp-client-cert-expired-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
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" expired at: 2026-11-10 17:03:43 +0000 UTC
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_EXPIRY
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" expired at: 2026-11-10 17:03:43 +0000 UTC

התוכן של Spec.Details מסביר את השם של ApigeeRouteConfig שמתייחס לסוד של Kubernetes שמכיל את אישור הלקוח של MCP mTLS שפג תוקפו.

רזולוציה

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    מחליפים את ISSUE_NAME בשם הבעיה, לדוגמה mcp-client-cert-expired-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 mTLS מרשות האישורים, ולהחליף את האישור ואת המפתח הפרטי שלו ביחד בקבצים שאליהם מפנים 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. משיגים אישור לקוח mTLS מחודש של MCP ואת המפתח הפרטי שלו מרשות האישורים.

  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 של הסוד, למארח הווירטואלי המושפע.