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_CA_CERT_INVALID s'affiche lorsque vous consultez les ressources de l'espace de noms apigee.
Ce problème ne se produit que pour les groupes d'environnements dont le bloc mcpMtls a activé la validation de la chaîne (par défaut). Pour un groupe avec mcpMtls.disableChainValidation: true, le plan de données MCP n'utilise pas de certificat CA et le secret -cacert n'est pas analysé.
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-ca-cert-invalid-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CA_CERT_INVALID https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_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 CA mTLS MCP est manquant |
Le secret -cacert n'existe pas ou ne contient aucune entrée cacert utilisable.
|
| Le certificat CA mTLS MCP n'est pas encodé au format PEM |
L'entrée cacert ne contient aucun bloc de certificat PEM ou contient des octets en dehors des blocs PEM.
|
| Le certificat CA mTLS MCP est incorrect ou n'est pas un certificat CA |
Un bloc de l'entrée cacert n'est pas un certificat, ne s'analyse pas ou n'est pas un certificat CA.
|
Cause : Le secret ou l'entrée du certificat CA mTLS MCP est manquant
Le secret Kubernetes qui doit contenir le certificat CA par rapport auquel le plan de données MCP valide la passerelle d'entrée n'existe pas dans l'espace de noms apigee, ou il existe sans entrée cacert non vide. Son nom est le nom du secret du certificat client, suivi de -cacert. Le graphique ne crée ce secret que lorsque vous utilisez des fichiers de certificat. Avec sslSecret, vous devez le créer vous-même, et l'oublier est la cause la plus fréquente de ce problème.
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-ca-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" not found Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" 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 "cacert" 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-ca-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp-cacert. -
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 une entrée
cacert, où MCP_CA_SECRET_NAME est le secret nommé dansSpec.Details:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
Si le secret est manquant ou ne contient pas d'entrée, assurez-vous que le fichier référencé par
mcpMtls.caCertPathexiste et n'est pas vide. L'étape suivante consiste à restaurer le secret à partir de ce fichier. Si vous souhaitez exécuter sans validation de la chaîne, définissezmcpMtls.disableChainValidation: trueet supprimezmcpMtls.caCertPath(le graphique rejette les deux ensemble). Sachez que cela désactive la validation du certificat de la passerelle d'entrée par le plan de données MCP. -
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 exactement sous ce nom avec une entrée
cacert, où MCP_CLIENT_SECRET_NAME est le secret du certificat client nommé parmcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
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. Si vous avez l'intention d'exécuter sans validation de la chaîne, l'omission du secret ne suffit pas. DéfinissezmcpMtls.disableChainValidation: truedansoverrides.yamlet mettez à niveau l'hôte virtuel. Sachez que cela désactive la validation du certificat de la passerelle d'entrée par le plan de données MCP. -
Créez ou mettez à jour le secret du certificat CA, où MCP_CLIENT_SECRET_NAME est la valeur de
mcpMtls.sslSecret, le secret du certificat CA est ce nom suivi de-cacert, et MCP_TRUST_CA_FILE est le fichier du certificat CA :kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_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 CA mTLS MCP n'est pas encodé au format PEM
L'entrée cacert ne contient pas les blocs de texte encodés au format PEM, ou elle contient du contenu après la dernière ligne -----END CERTIFICATE----- qui n'est pas au format PEM. Le plan de données MCP ne le charge pas.
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-ca-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM
Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :
entry holds no PEM encoded certificateholds N trailing bytes that are not PEM
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-ca-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp-cacert. -
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 contenu du fichier référencé par
mcpMtls.caCertPathet corrigez-le si nécessaire. Vérifiez que le contenu ne contient que des blocs de certificats complets, chacun avec ses lignes de début et de fin. 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 contenu du fichier de certificat CA (MCP_TRUST_CA_FILE) que vous stockez dans l'entrée
cacertdu secret, et corrigez-le si nécessaire. Vérifiez que le contenu ne contient que des blocs de certificats complets, chacun avec ses lignes de début et de fin. Exemple :-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Mettez à jour le secret du certificat CA en place, où MCP_CLIENT_SECRET_NAME est la valeur de
mcpMtls.sslSecret, le secret du certificat CA est ce nom auquel est ajouté-cacert, et MCP_TRUST_CA_FILE est le fichier du certificat CA :kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_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 CA mTLS MCP est incorrect ou n'est pas un certificat CA
Chaque bloc PEM de l'entrée cacert doit être un bloc CERTIFICATE qui analyse et possède la contrainte de base de l'autorité de certification. Un bloc de clé privée, un certificat d'entité finale (par exemple, le certificat de serveur de la passerelle d'entrée) ou un bloc corrompu rend l'entrée inutilisable, et le plan de données MCP ne la charge pas.
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-ca-cert-invalid-my-org-my-virtualhost.
Le résultat doit ressembler à ce qui suit :
Name: mcp-ca-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID Reason: AIS_MCP_MTLS_CA_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate
Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :
-
no PEM block parsed as a certificate: ...: aucun des blocs de certificat ne peut être analysé (par exemple, le seul certificat est corrompu). -
block N is a "..." block, want CERTIFICATE: le bloc N n'est pas un certificat (par exemple, une clé privée). -
block N does not parse: le bloc N est un certificat corrompu. -
block N is not a CA certificate: le bloc N est un certificat, mais pas une autorité de certification (par exemple, un certificat d'entité finale).
Les blocs sont numérotés à partir de 0.
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-ca-cert-invalid-my-org-my-virtualhost.Dans cet exemple,
ApigeeRouteConfigmy-org-my-virtualhostfait référence au secretmy-org-my-virtualhost-mcp-cacert. -
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
...-
Recompilez le fichier référencé par
mcpMtls.caCertPathafin qu'il ne contienne que le certificat CA (ou la chaîne) qui a signé le certificat de la passerelle d'entrée. Vérifiez ensuite que chaque bloc est un certificat CA, où MCP_TRUST_CA_FILE est ce fichier :openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
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
...-
Recompilez le fichier de certificat CA (MCP_TRUST_CA_FILE) afin qu'il ne contienne que le certificat CA (ou la chaîne) qui a signé le certificat de la passerelle d'entrée. Vérifiez ensuite que chaque bloc est un certificat CA :
openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
Mettez à jour le secret du certificat CA en place, où MCP_CLIENT_SECRET_NAME est la valeur de
mcpMtls.sslSecret, le secret du certificat CA est ce nom auquel est ajouté-cacert, et MCP_TRUST_CA_FILE est le fichier du certificat CA :kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \ --from-file=cacert=MCP_TRUST_CA_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.caCertPathou dans l'entréecacertdu secret, pour l'hôte virtuel concerné.