Certificat CA mTLS MCP non valide

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 found
  • secret has no usable "cacert" entry

Solution

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    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.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp-cacert.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (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
...
  1. Vérifiez si le secret existe et comporte une entrée cacert, où MCP_CA_SECRET_NAME est le secret nommé dans Spec.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.caCertPath existe 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éfinissez mcpMtls.disableChainValidation: true et supprimez mcpMtls.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.

  2. 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
...
  1. 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é par mcpMtls.sslSecret :

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template ne vérifie pas l'existence des secrets. Seuls helm install et helm upgrade le font. Par conséquent, une exécution helm template propre 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éfinissez mcpMtls.disableChainValidation: true dans overrides.yaml et 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.

  2. 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 certificate
  • holds N trailing bytes that are not PEM

Solution

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    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.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp-cacert.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (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
...
  1. Validez le contenu du fichier référencé par mcpMtls.caCertPath 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-----
  2. 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
...
  1. Validez le contenu du fichier de certificat CA (MCP_TRUST_CA_FILE) que vous stockez dans l'entrée cacert du 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-----
  2. 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

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    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.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp-cacert.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (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
...
  1. Recompilez le fichier référencé par mcpMtls.caCertPath 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, 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
  2. 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
...
  1. 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
  2. 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 :

  1. L'ID du projet Google Cloud .
  2. Nom de l'organisation Apigee Hybrid
  3. Champ Spec.Details de ApigeeIssue
  4. (Facultatif) Certificat dans le fichier référencé par mcpMtls.caCertPath ou dans l'entrée cacert du secret, pour l'hôte virtuel concerné.