Ablauf des MCP-mTLS-Clientzertifikats

Diese Seite gilt für Apigee Hybrid, aber nicht für Apigee.

Für dieses Thema gibt es keine entsprechende Apigee Edge-Dokumentation.

Symptom

Ein ApigeeIssue mit Reason AIS_MCP_MTLS_CLIENT_CERT_EXPIRY wird angezeigt, wenn Ressourcen im Namespace apigee angezeigt werden.

Fehlermeldungen

Nachdem kubectl -n apigee get apigeeissues ausgeführt wurde, wird ein Problem wie das folgende angezeigt:

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

Mögliche Ursachen

In der folgenden Tabelle sind mögliche Ursachen für dieses Problem aufgeführt:

Ursache Beschreibung
MCP-mTLS-Clientzertifikat läuft bald ab Das konfigurierte MCP-mTLS-Clientzertifikat läuft innerhalb von 14 Tagen ab.
MCP-mTLS-Clientzertifikat ist abgelaufen Das konfigurierte MCP-mTLS-Clientzertifikat ist abgelaufen.

Ursache: MCP-mTLS-Clientzertifikat läuft bald ab

Das MCP-mTLS-Clientzertifikat, das im Kubernetes-Secret gespeichert ist, auf das ein ApigeeRouteConfig verweist, läuft innerhalb der nächsten 14 Tage ab.

Diagnose

Führen Sie dazu diesen Befehl aus:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ersetzen Sie ISSUE_NAME durch den Namen des Problems, z. B. mcp-client-cert-expiring-soon-my-org-my-virtualhost.

Die Ausgabe sollte in etwa so aussehen:

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

Der Inhalt von Spec.Details erläutert den Namen der ApigeeRouteConfig, die sich auf das Kubernetes-Secret mit dem MCP-mTLS-Clientzertifikat bezieht, das bald abläuft.

Lösung

  1. Verwenden Sie kubectl describe, um den Namen des Kubernetes-Secrets und des ApigeeRouteConfig anzuzeigen, zu dem das Problem gehört:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ersetzen Sie ISSUE_NAME durch den Namen des Problems, z. B. mcp-client-cert-expiring-soon-my-org-my-virtualhost.

    In diesem Beispiel verweist ApigeeRouteConfig my-org-my-virtualhost auf das Secret my-org-my-virtualhost-mcp.

  2. Ermitteln Sie den virtualhost-Namen aus dem ApigeeRouteConfig.

    Der Name des ApigeeRouteConfig hat das Format <Apigee organization>-<virtualhost name>.

    In diesem Beispiel ist my-org die Apigee-Organisation und der Name des virtuellen Hosts my-virtualhost.

  3. Suchen Sie den entsprechenden virtuellen Host in Ihrer overrides.yaml und prüfen Sie, welches Format der mcpMtls-Block verwendet (siehe mTLS zwischen der MCP-Datenebene und dem Ingress-Gateway konfigurieren). Wählen Sie den entsprechenden Tab aus und folgen Sie der Anleitung.

Zertifikatsdateien

Wenn Sie Dateipfade (sslCertPath, sslKeyPath, caCertPath) verwenden, erstellt und verwaltet das Virtualhost-Diagramm die Secrets aus dem Dateiinhalt.

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. Fordern Sie bei Ihrer Zertifizierungsstelle ein neues MCP-mTLS-Clientzertifikat an und ersetzen Sie das Zertifikat und den zugehörigen privaten Schlüssel in den Dateien, auf die in mcpMtls.sslCertPath und mcpMtls.sslKeyPath verwiesen wird.

  2. Aktualisieren Sie den virtuellen Host, damit das Diagramm das Secret umschreibt:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes-Secrets

Wenn Sie eine Kubernetes-Secret-Referenz (sslSecret) verwenden, liest die MCP-Datenebene die Zertifikatswerte direkt aus den von Ihnen erstellten Secrets und Aktualisierungen werden automatisch angewendet. Es ist kein helm upgrade erforderlich.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Fordern Sie bei Ihrer Zertifizierungsstelle ein neues MCP-mTLS-Clientzertifikat und den zugehörigen privaten Schlüssel an.

  2. Aktualisieren Sie das Secret mit dem Zertifikat und dem privaten Schlüssel. Dabei ist MCP_CLIENT_SECRET_NAME das in Spec.Details genannte Secret und MCP_CLIENT_CERT_FILE und MCP_CLIENT_KEY_FILE sind das Zertifikat und der private Schlüssel:

    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 -

Die MCP-Datenebene übernimmt das aktualisierte Secret bei der nächsten regelmäßigen Aktualisierung, in der Regel innerhalb weniger Minuten, ohne dass ein Pod neu gestartet werden muss. Die ApigeeIssue wird beim nächsten Scan zurückgezogen.

Ursache: MCP-mTLS-Clientzertifikat ist abgelaufen

Das MCP-mTLS-Clientzertifikat, das im Kubernetes-Secret gespeichert ist, auf das ein ApigeeRouteConfig verweist, ist abgelaufen.

Diagnose

Führen Sie dazu diesen Befehl aus:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ersetzen Sie ISSUE_NAME durch den Namen des Problems, z. B. mcp-client-cert-expired-my-org-my-virtualhost.

Die Ausgabe sollte in etwa so aussehen:

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

Der Inhalt von Spec.Details erläutert den Namen des ApigeeRouteConfig, der sich auf das Kubernetes-Secret mit dem abgelaufenen MCP-mTLS-Clientzertifikat bezieht.

Lösung

  1. Verwenden Sie kubectl describe, um den Namen des Kubernetes-Secrets und des ApigeeRouteConfig anzuzeigen, zu dem das Problem gehört:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ersetzen Sie ISSUE_NAME durch den Namen des Problems, z. B. mcp-client-cert-expired-my-org-my-virtualhost.

    In diesem Beispiel verweist ApigeeRouteConfig my-org-my-virtualhost auf das Secret my-org-my-virtualhost-mcp.

  2. Ermitteln Sie den virtualhost-Namen aus dem ApigeeRouteConfig.

    Der Name des ApigeeRouteConfig hat das Format <Apigee organization>-<virtualhost name>.

    In diesem Beispiel ist my-org die Apigee-Organisation und der Name des virtuellen Hosts my-virtualhost.

  3. Suchen Sie den entsprechenden virtuellen Host in Ihrer overrides.yaml und prüfen Sie, welches Format der mcpMtls-Block verwendet (siehe mTLS zwischen der MCP-Datenebene und dem Ingress-Gateway konfigurieren). Wählen Sie den entsprechenden Tab aus und folgen Sie der Anleitung.

Zertifikatsdateien

Wenn Sie Dateipfade (sslCertPath, sslKeyPath, caCertPath) verwenden, erstellt und verwaltet das Virtualhost-Diagramm die Secrets aus dem Dateiinhalt.

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. Fordern Sie bei Ihrer Zertifizierungsstelle ein neues MCP-mTLS-Clientzertifikat an und ersetzen Sie das Zertifikat und den zugehörigen privaten Schlüssel in den Dateien, auf die in mcpMtls.sslCertPath und mcpMtls.sslKeyPath verwiesen wird.

  2. Aktualisieren Sie den virtuellen Host, damit das Diagramm das Secret umschreibt:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes-Secrets

Wenn Sie eine Kubernetes-Secret-Referenz (sslSecret) verwenden, liest die MCP-Datenebene die Zertifikatswerte direkt aus den von Ihnen erstellten Secrets und Aktualisierungen werden automatisch angewendet. Es ist kein helm upgrade erforderlich.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Fordern Sie bei Ihrer Zertifizierungsstelle ein neues MCP-mTLS-Clientzertifikat und den zugehörigen privaten Schlüssel an.

  2. Aktualisieren Sie das Secret mit dem Zertifikat und dem privaten Schlüssel. Dabei ist MCP_CLIENT_SECRET_NAME das in Spec.Details genannte Secret und MCP_CLIENT_CERT_FILE und MCP_CLIENT_KEY_FILE sind das Zertifikat und der private Schlüssel:

    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 -

Die MCP-Datenebene übernimmt das aktualisierte Secret bei der nächsten regelmäßigen Aktualisierung, in der Regel innerhalb weniger Minuten, ohne dass ein Pod neu gestartet werden muss. Die ApigeeIssue wird beim nächsten Scan zurückgezogen.

Erfassen von Diagnoseinformationen erforderlich

Wenn das Problem auch nach Befolgen der obigen Anweisungen weiterhin besteht, sammeln Sie die folgenden Diagnoseinformationen und wenden Sie sich dann an den Google Cloud Customer Care:

  1. Die Google Cloud -Projekt-ID.
  2. Der Name der Apigee Hybrid-Organisation.
  3. Das Feld Spec.Details von ApigeeIssue.
  4. (Optional) Das Zertifikat in der Datei, auf die von mcpMtls.sslCertPath verwiesen wird, oder im Eintrag cert des Secrets für den betroffenen virtuellen Host.