Expiration du certificat client mTLS MCP

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_EXPIRY 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é, un problème semblable à celui-ci s'affiche :

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

Causes possibles

Le tableau suivant liste les causes possibles de ce problème :

Cause Description
Le certificat client mTLS MCP arrive bientôt à expiration Le certificat client mTLS MCP configuré expire dans 14 jours.
Le certificat client mTLS MCP a expiré Le certificat client mTLS MCP configuré a expiré.

Cause : Le certificat client mTLS MCP arrive bientôt à expiration

Le certificat client mTLS MCP stocké dans le secret Kubernetes référencé par un ApigeeRouteConfig expire dans les 14 prochains jours.

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-expiring-soon-my-org-my-virtualhost.

Le résultat doit ressembler à ce qui suit :

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

Le contenu de Spec.Details explique le nom du ApigeeRouteConfig qui fait référence au secret Kubernetes contenant le certificat client mTLS MCP qui expire bientôt.

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-client-cert-expiring-soon-my-org-my-virtualhost.

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

  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. Obtenez un certificat client mTLS MCP renouvelé auprès de votre autorité de certification, puis remplacez le certificat et sa clé privée dans les fichiers référencés par mcpMtls.sslCertPath et mcpMtls.sslKeyPath.

  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. Obtenez un certificat client mTLS MCP renouvelé et sa clé privée auprès de votre autorité de certification.

  2. 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 mis à jour lors de son prochain rafraîchissement 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 a expiré

Le certificat client mTLS MCP stocké dans le secret Kubernetes référencé par un ApigeeRouteConfig a expiré.

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-expired-my-org-my-virtualhost.

Le résultat doit ressembler à ce qui suit :

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

Le contenu de Spec.Details explique le nom du ApigeeRouteConfig qui fait référence au secret Kubernetes contenant le certificat client mTLS MCP qui a expiré.

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-client-cert-expired-my-org-my-virtualhost.

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

  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. Obtenez un certificat client mTLS MCP renouvelé auprès de votre autorité de certification, puis remplacez le certificat et sa clé privée dans les fichiers référencés par mcpMtls.sslCertPath et mcpMtls.sslKeyPath.

  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. Obtenez un certificat client mTLS MCP renouvelé et sa clé privée auprès de votre autorité de certification.

  2. 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 mis à jour lors de son prochain rafraîchissement 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.sslCertPath ou dans l'entrée cert du secret, pour l'hôte virtuel concerné.