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_INVALID wird angezeigt, wenn Ressourcen im Namespace apigee angezeigt werden.
Fehlermeldungen
Nachdem kubectl -n apigee get apigeeissues ausgeführt wurde, wird ein Fehler wie der folgende angezeigt:
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
Mögliche Ursachen
In der folgenden Tabelle sind mögliche Ursachen für dieses Problem aufgeführt:
| Ursache | Beschreibung |
|---|---|
| MCP-mTLS-Clientzertifikat-Secret oder -Eintrag fehlt |
Das Secret mit dem Namen mcpMtls ist nicht vorhanden oder hat keinen verwendbaren cert- oder key-Eintrag.
|
| MCP-mTLS-Clientzertifikat oder -schlüssel ist fehlerhaft |
Der Eintrag cert ist nicht PEM-codiert oder der Eintrag key ist nicht der passende private Schlüssel.
|
| MCP-mTLS-Clientzertifikat lässt die erweiterte Schlüsselverwendung „clientAuth“ aus |
Das Zertifikat wird geparst, aber die erweiterte Schlüsselverwendung enthält nicht clientAuth.
|
Ursache: MCP-mTLS-Clientzertifikat-Secret oder -Eintrag fehlt
Das Kubernetes-Secret, das das MCP-mTLS-Clientzertifikat enthalten soll, ist im Namespace apigee nicht vorhanden oder es ist ohne einen nicht leeren cert-Eintrag oder ohne einen key-Eintrag vorhanden. Die MCP-Datenebene hat kein Clientzertifikat, das für diese Umgebungsgruppe präsentiert werden kann. Daher schlagen MCP-Toolaufrufe an die Gruppe beim TLS-Handshake fehl.
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-invalid-my-org-my-virtualhost.
Die Ausgabe sollte in etwa so aussehen:
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
Der Inhalt von Spec.Details benennt das Secret, die ApigeeRouteConfig und das Problem. Beispiel:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
Lösung
-
Verwenden Sie
kubectl describe, um den Namen des Kubernetes-Secrets und desApigeeRouteConfiganzuzeigen, zu dem das Problem gehört:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ersetzen Sie
ISSUE_NAMEdurch den Namen des Problems, z. B.mcp-client-cert-invalid-my-org-my-virtualhost.In diesem Beispiel verweist
ApigeeRouteConfigmy-org-my-virtualhostauf das Secretmy-org-my-virtualhost-mcp. -
Ermitteln Sie den
virtualhost-Namen aus demApigeeRouteConfig.Der Name des
ApigeeRouteConfighat das Format<Apigee organization>-<virtualhost name>.In diesem Beispiel ist
my-orgdie Apigee-Organisation und der Name des virtuellen Hostsmy-virtualhost. -
Suchen Sie den entsprechenden virtuellen Host in Ihrer
overrides.yamlund prüfen Sie, welches Format dermcpMtls-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
...-
Prüfen Sie, ob das Secret vorhanden ist und beide Einträge enthält. Dabei ist MCP_CLIENT_SECRET_NAME das in
Spec.Detailsgenannte Secret. Im AbschnittDatamüssencertundkeyaufgeführt sein:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Wenn das Secret fehlt oder keinen Eintrag enthält, prüfen Sie, ob die Dateien, auf die
mcpMtls.sslCertPathundmcpMtls.sslKeyPathverweisen, vorhanden und nicht leer sind. Im nächsten Schritt wird das Secret aus diesen Dateien wiederhergestellt. -
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
...-
Prüfen Sie, ob das Secret vorhanden ist und beide Einträge enthält. Dabei ist MCP_CLIENT_SECRET_NAME das in
Spec.Detailsgenannte Secret. Im AbschnittDatamüssencertundkeyaufgeführt sein. Prüfen Sie, ob der Name inmcpMtls.sslSecretmit dem von Ihnen erstellten Secret übereinstimmt und ob sich das Secret im Namespaceapigeebefindet: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 templateprüft nicht, ob die Secrets vorhanden sind. Das tun nurhelm installundhelm upgrade. Ein fehlerfreierhelm template-Lauf ist also kein Beweis dafür, dass dieses Secret vorhanden ist. -
Erstellen oder aktualisieren Sie das Secret mit dem Zertifikat und dem zugehörigen privaten Schlüssel. Dabei ist MCP_CLIENT_SECRET_NAME das in
Spec.Detailsbenannte Secret und MCP_CLIENT_CERT_FILE und MCP_CLIENT_KEY_FILE sind das Zertifikat und der zugehörige 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 korrigierte 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 oder -schlüssel ist fehlerhaft
Der Eintrag cert enthält kein PEM-codiertes X.509-Zertifikat oder der Eintrag key ist nicht PEM-codiert oder ist nicht der private Schlüssel für dieses Zertifikat. Die MCP-Datenebene kann das Paar nicht laden.
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-invalid-my-org-my-virtualhost.
Die Ausgabe sollte in etwa so aussehen:
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
Der Inhalt von Spec.Details benennt das Secret, die ApigeeRouteConfig und das Problem. Beispiel:
-
entry holds no PEM encoded certificate: Der Eintragcertist nicht PEM. -
tls: failed to find any PEM data in key input: Der Eintragkeyist nicht PEM. -
tls: private key does not match public key: Die Einträgecertundkeysind nicht gekoppelt. -
tls: failed to parse private key: Der Schlüssel kann nicht geparst werden, normalerweise weil er verschlüsselt ist. Der Eintragkeymuss ein unverschlüsselter privater PEM-Schlüssel sein.
Lösung
-
Verwenden Sie
kubectl describe, um den Namen des Kubernetes-Secrets und desApigeeRouteConfiganzuzeigen, zu dem das Problem gehört:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ersetzen Sie
ISSUE_NAMEdurch den Namen des Problems, z. B.mcp-client-cert-invalid-my-org-my-virtualhost.In diesem Beispiel verweist
ApigeeRouteConfigmy-org-my-virtualhostauf das Secretmy-org-my-virtualhost-mcp. -
Ermitteln Sie den
virtualhost-Namen aus demApigeeRouteConfig.Der Name des
ApigeeRouteConfighat das Format<Apigee organization>-<virtualhost name>.In diesem Beispiel ist
my-orgdie Apigee-Organisation und der Name des virtuellen Hostsmy-virtualhost. -
Suchen Sie den entsprechenden virtuellen Host in Ihrer
overrides.yamlund prüfen Sie, welches Format dermcpMtls-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
...-
Validieren Sie die Zertifikatsdatei und die Schlüsseldatei, auf die von
mcpMtls.sslCertPathundmcpMtls.sslKeyPathverwiesen wird, und korrigieren Sie sie bei Bedarf. Das Zertifikat muss die Anfangs- und Endzeilen des Zertifikats enthalten und der Schlüssel muss der private Schlüssel dafür sein. Beispiel:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
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
...-
Validieren Sie die Zertifikatsdatei (MCP_CLIENT_CERT_FILE) und die Schlüsseldatei (MCP_CLIENT_KEY_FILE), die Sie in den Einträgen
certundkeydes Secrets speichern, und korrigieren Sie sie bei Bedarf. Das Zertifikat muss die Anfangs- und Endzeilen des Zertifikats enthalten und der Schlüssel muss der private Schlüssel dafür sein. Beispiel:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Aktualisieren Sie das Secret mit dem Zertifikat und dem privaten Schlüssel. Dabei ist MCP_CLIENT_SECRET_NAME das in
Spec.Detailsgenannte 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 korrigierte 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: Im MCP-mTLS-Clientzertifikat fehlt die erweiterte Schlüsselverwendung „clientAuth“
Das Zertifikat ist wohlgeformt und mit seinem Schlüssel gekoppelt, aber seine erweiterte Schlüsselverwendung (EKU) enthält nicht clientAuth. Daher kann es nicht für die Clientauthentifizierung verwendet werden und wird von der MCP-Datenebene nicht präsentiert. Das kommt häufig vor, wenn ein Serverzertifikat oder ein Zertifikat aus einem öffentlichen CA-Profil, das keine clientAuth mehr ausstellt, wiederverwendet wird.
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-invalid-my-org-my-virtualhost.
Die Ausgabe sollte in etwa so aussehen:
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
Der Inhalt von Spec.Details benennt das Secret und den ApigeeRouteConfig und listet die erweiterten Schlüsselverwendungen auf, die das Zertifikat enthält.
Lösung
-
Verwenden Sie
kubectl describe, um den Namen des Kubernetes-Secrets und desApigeeRouteConfiganzuzeigen, zu dem das Problem gehört:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ersetzen Sie
ISSUE_NAMEdurch den Namen des Problems, z. B.mcp-client-cert-invalid-my-org-my-virtualhost.In diesem Beispiel verweist
ApigeeRouteConfigmy-org-my-virtualhostauf das Secretmy-org-my-virtualhost-mcp. -
Ermitteln Sie den
virtualhost-Namen aus demApigeeRouteConfig.Der Name des
ApigeeRouteConfighat das Format<Apigee organization>-<virtualhost name>.In diesem Beispiel ist
my-orgdie Apigee-Organisation und der Name des virtuellen Hostsmy-virtualhost. -
Suchen Sie den entsprechenden virtuellen Host in Ihrer
overrides.yamlund prüfen Sie, welches Format dermcpMtls-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
...-
Stellen Sie das Clientzertifikat von Ihrer privaten Zertifizierungsstelle mit einem Profil neu aus, das die erweiterte Schlüsselverwendung
clientAuthenthält. Bestätigen Sie dies, wobei MCP_CLIENT_CERT_FILE das neu ausgestellte Zertifikat ist, und ersetzen Sie dann die Dateien, auf die vonmcpMtls.sslCertPathundmcpMtls.sslKeyPathverwiesen wird:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
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
...-
Stellen Sie das Clientzertifikat von Ihrer privaten Zertifizierungsstelle mit einem Profil neu aus, das die erweiterte Schlüsselverwendung
clientAuthenthält. Bestätigen Sie dies, bevor Sie das Secret aktualisieren, wobei MCP_CLIENT_CERT_FILE das neu ausgestellte Zertifikat ist:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Aktualisieren Sie das Secret mit dem Zertifikat und dem privaten Schlüssel. Dabei ist MCP_CLIENT_SECRET_NAME das in
Spec.Detailsgenannte 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 korrigierte 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:
- Die Google Cloud -Projekt-ID.
- Der Name der Apigee Hybrid-Organisation.
- Das Feld
Spec.DetailsvonApigeeIssue. -
(Optional) Das Zertifikat in der Datei, auf die von
mcpMtls.sslCertPathverwiesen wird, oder im Eintragcertdes Secrets für den betroffenen virtuellen Host.