Cette page s'applique à Apigee hybrid, mais pas à Apigee.
Il n'existe pas de documentation Apigee Edge équivalente pour ce sujet.
Problème constaté
Un ApigeeIssue avec Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID s'affiche lorsque vous consultez les ressources de l'espace de noms apigee.
Messages d'erreur
Une fois kubectl -n apigee get apigeeissues exécuté, une erreur semblable à celle-ci s'affiche :
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
Causes possibles
Le tableau suivant liste les causes possibles de ce problème :
| Cause | Description |
|---|---|
| Le secret ou l'entrée du certificat client mTLS MCP est manquant |
Le secret nommé par mcpMtls n'existe pas, ou ne comporte aucune entrée cert ou key utilisable.
|
| Le certificat ou la clé client mTLS MCP est incorrect |
L'entrée cert n'est pas encodée au format PEM, ou l'entrée key n'est pas la clé privée correspondante.
|
| Le certificat client mTLS MCP omet l'utilisation de la clé étendue clientAuth |
Le certificat est analysé, mais son utilisation étendue de la clé n'inclut pas clientAuth.
|
Cause : Le secret ou l'entrée du certificat client mTLS MCP est manquant
Le secret Kubernetes qui doit contenir le certificat client mTLS MCP n'existe pas dans l'espace de noms apigee, ou il existe sans entrée cert non vide ou sans entrée key. Le plan de données MCP ne dispose d'aucun certificat client à présenter pour ce groupe d'environnements. Par conséquent, les appels d'outils MCP vers le groupe échouent lors du handshake TLS.
Diagnostic
Exécutez la commande suivante :
kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
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
Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
Solution
-
Utilisez
kubectl describepour afficher le nom du secret Kubernetes etApigeeRouteConfigauquel le problème appartient :kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez
ISSUE_NAMEpar le nom du problème, par exemplemcp-client-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp. -
Déterminez le nom
virtualhostà partir deApigeeRouteConfig.Le nom de la fonction
ApigeeRouteConfigest au format suivant :<Apigee organization>-<virtualhost name>.Dans cet exemple,
my-orgest l'organisation Apigee et le nom de l'hôte virtuel estmy-virtualhost. -
Recherchez l'hôte virtuel correspondant dans votre
overrides.yamlet vérifiez quel format son blocmcpMtlsutilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.
Fichiers de certificats
Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.
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
...-
Vérifiez si le secret existe et comporte les deux entrées, où MCP_CLIENT_SECRET_NAME est le secret nommé dans
Spec.Details. La sectionDatadoit listercertetkey:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Si le secret est manquant ou ne contient pas d'entrée, assurez-vous que les fichiers référencés par
mcpMtls.sslCertPathetmcpMtls.sslKeyPathexistent et ne sont pas vides. L'étape suivante permet de restaurer le secret à partir de ces fragments. -
Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets Kubernetes
Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Vérifiez que le secret existe et qu'il comporte les deux entrées, où MCP_CLIENT_SECRET_NAME est le secret nommé dans
Spec.Details. La sectionDatadoit listercertetkey. Vérifiez que le nom dansmcpMtls.sslSecretcorrespond au secret que vous avez créé et que le secret se trouve dans l'espace de nomsapigee: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 templatene vérifie pas l'existence des secrets. Seulshelm installethelm upgradele font. Par conséquent, une exécutionhelm templatepropre ne prouve pas que ce secret est présent. -
Créez ou mettez à jour le secret avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans
Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :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 -
Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.
Cause : Le certificat ou la clé client mTLS MCP est incorrect
L'entrée cert ne contient pas de certificat X.509 encodé au format PEM, ou l'entrée key n'est pas encodée au format PEM ou n'est pas la clé privée de ce certificat. Le plan de données MCP ne peut pas charger la paire.
Diagnostic
Exécutez la commande suivante :
kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
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
Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :
-
entry holds no PEM encoded certificate: l'entréecertn'est pas au format PEM. -
tls: failed to find any PEM data in key input: l'entréekeyn'est pas au format PEM. -
tls: private key does not match public key: les entréescertetkeyne sont pas associées. -
tls: failed to parse private key: la clé ne peut pas être analysée, généralement parce qu'elle est chiffrée. L'entréekeydoit être une clé privée PEM non chiffrée.
Solution
-
Utilisez
kubectl describepour afficher le nom du secret Kubernetes etApigeeRouteConfigauquel le problème appartient :kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez
ISSUE_NAMEpar le nom du problème, par exemplemcp-client-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp. -
Déterminez le nom
virtualhostà partir deApigeeRouteConfig.Le nom de la fonction
ApigeeRouteConfigest au format suivant :<Apigee organization>-<virtualhost name>.Dans cet exemple,
my-orgest l'organisation Apigee et le nom de l'hôte virtuel estmy-virtualhost. -
Recherchez l'hôte virtuel correspondant dans votre
overrides.yamlet vérifiez quel format son blocmcpMtlsutilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.
Fichiers de certificats
Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.
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
...-
Validez le fichier de certificat et le fichier de clé référencés par
mcpMtls.sslCertPathetmcpMtls.sslKeyPath, et corrigez-les si nécessaire. Le certificat doit contenir les lignes de début et de fin du certificat, et la clé doit être la clé privée correspondante. Exemple :-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets Kubernetes
Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Validez le fichier de certificat (MCP_CLIENT_CERT_FILE) et le fichier de clé (MCP_CLIENT_KEY_FILE) que vous stockez dans les entrées
certetkeydu secret, et corrigez-les si nécessaire. Le certificat doit contenir les lignes de début et de fin du certificat, et la clé doit être la clé privée correspondante. Exemple :-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Mettez à jour le secret en place avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans
Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :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 -
Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.
Cause : Le certificat client MCP mTLS omet l'utilisation de la clé étendue clientAuth
Le certificat est bien formé et associé à sa clé, mais son utilisation étendue de la clé (EKU) n'inclut pas clientAuth. Il ne peut donc pas être utilisé pour l'authentification du client, et le plan de données MCP ne le présente pas. Cela se produit généralement lorsqu'un certificat de serveur ou un certificat d'un profil d'autorité de certification public qui n'émet plus de clientAuth est réutilisé.
Diagnostic
Exécutez la commande suivante :
kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
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
Le contenu de Spec.Details nomme le secret et le ApigeeRouteConfig, et liste les utilisations de clé étendues que le certificat comporte.
Solution
-
Utilisez
kubectl describepour afficher le nom du secret Kubernetes etApigeeRouteConfigauquel le problème appartient :kubectl -n apigee describe apigeeissue ISSUE_NAME
Remplacez
ISSUE_NAMEpar le nom du problème, par exemplemcp-client-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp. -
Déterminez le nom
virtualhostà partir deApigeeRouteConfig.Le nom de la fonction
ApigeeRouteConfigest au format suivant :<Apigee organization>-<virtualhost name>.Dans cet exemple,
my-orgest l'organisation Apigee et le nom de l'hôte virtuel estmy-virtualhost. -
Recherchez l'hôte virtuel correspondant dans votre
overrides.yamlet vérifiez quel format son blocmcpMtlsutilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.
Fichiers de certificats
Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.
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
...-
Réémettez le certificat client à partir de votre autorité de certification privée avec un profil incluant l'utilisation étendue de la clé
clientAuth. Confirmez-le, où MCP_CLIENT_CERT_FILE est le certificat réémis, puis remplacez les fichiers référencés parmcpMtls.sslCertPathetmcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets Kubernetes
Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Réémettez le certificat client à partir de votre autorité de certification privée avec un profil incluant l'utilisation étendue de la clé
clientAuth. Confirmez-le avant de mettre à jour le secret, où MCP_CLIENT_CERT_FILE est le certificat réémis :openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Mettez à jour le secret en place avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans
Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :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 -
Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.
Vous devez collecter des informations de diagnostic
Si le problème persiste, même après avoir suivi les instructions ci-dessus, rassemblez les informations de diagnostic suivantes, puis contactez Google Cloud Customer Care :
- L'ID du projet Google Cloud .
- Nom de l'organisation Apigee Hybrid
- Champ
Spec.DetailsdeApigeeIssue -
(Facultatif) Certificat dans le fichier référencé par
mcpMtls.sslCertPathou dans l'entréecertdu secret, pour l'hôte virtuel concerné.