Scadenza del certificato client mTLS MCP

Questa pagina si applica ad Apigee hybrid, ma non ad Apigee.

Non esiste una documentazione di Apigee Edge equivalente per questo argomento.

Sintomo

Viene visualizzato un ApigeeIssue con Reason AIS_MCP_MTLS_CLIENT_CERT_EXPIRY quando visualizzi le risorse nello spazio dei nomi apigee.

Messaggi di errore

Dopo aver eseguito kubectl -n apigee get apigeeissues, viene visualizzato un problema simile al seguente:

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

Cause possibili

La tabella seguente elenca le possibili cause di questo problema:

Causa Descrizione
Il certificato client mTLS MCP scadrà a breve Il certificato client mTLS MCP configurato scadrà entro 14 giorni.
Il certificato client mTLS MCP è scaduto Il certificato client mTLS MCP configurato è scaduto.

Causa: il certificato client mTLS MCP scadrà a breve

Il certificato client mTLS MCP archiviato nel secret Kubernetes a cui fa riferimento un ApigeeRouteConfig scadrà entro i prossimi 14 giorni.

Diagnosi

Esegui questo comando:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-expiring-soon-my-org-my-virtualhost.

L'output dovrebbe essere simile al seguente:

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

I contenuti di Spec.Details spiegano il nome di ApigeeRouteConfig che fa riferimento al secret di Kubernetes contenente il certificato client mTLS di MCP che sta per scadere.

Risoluzione

  1. Utilizza kubectl describe per visualizzare il nome del secret di Kubernetes e ApigeeRouteConfig a cui appartiene il problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-expiring-soon-my-org-my-virtualhost.

    In questo esempio, my-org-my-virtualhost ApigeeRouteConfig fa riferimento al secret my-org-my-virtualhost-mcp.

  2. Determina il nome virtualhost da ApigeeRouteConfig.

    Il nome di ApigeeRouteConfig è nel formato: <Apigee organization>-<virtualhost name>.

    In questo esempio, my-org è l'organizzazione Apigee e il nome dell'host virtuale è my-virtualhost.

  3. Trova l'host virtuale corrispondente nel tuo overrides.yaml e controlla quale forma utilizza il suo blocco mcpMtls (consulta Configura mTLS tra il piano dati MCP e il gateway in entrata). Seleziona la scheda corrispondente e segui i passaggi indicati.

File dei certificati

Quando utilizzi i percorsi dei file (sslCertPath, sslKeyPath, caCertPath), il grafico virtualhost crea e gestisce i secret dai contenuti dei file.

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. Ottieni un certificato client mTLS MCP rinnovato dalla tua autorità di certificazione e sostituisci il certificato e la relativa chiave privata insieme nei file a cui fanno riferimento mcpMtls.sslCertPath e mcpMtls.sslKeyPath.

  2. Esegui l'upgrade del virtualhost in modo che il grafico riscriva il secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secret Kubernetes

Quando utilizzi un riferimento al secret di Kubernetes (sslSecret), il piano dati MCP legge i valori del certificato direttamente dai secret che hai creato e gli aggiornamenti vengono applicati automaticamente. Non è necessario helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Ottieni un certificato client mTLS MCP rinnovato e la relativa chiave privata dalla tua autorità di certificazione.

  2. Aggiorna il secret in loco con il certificato e la relativa chiave privata, dove MCP_CLIENT_SECRET_NAME è il secret denominato in Spec.Details e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE sono il certificato e la relativa chiave privata:

    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 -

Il piano dati MCP rileva il secret aggiornato al successivo aggiornamento periodico, in genere entro pochi minuti, senza un riavvio del pod, e il ApigeeIssue viene ritirato alla scansione successiva.

Causa: il certificato client mTLS MCP è scaduto

Il certificato client mTLS MCP archiviato nel secret Kubernetes a cui fa riferimento un ApigeeRouteConfig è scaduto.

Diagnosi

Esegui questo comando:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-expired-my-org-my-virtualhost.

L'output dovrebbe essere simile al seguente:

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

I contenuti di Spec.Details spiegano il nome di ApigeeRouteConfig che fa riferimento al secret di Kubernetes contenente il certificato client mTLS MCP scaduto.

Risoluzione

  1. Utilizza kubectl describe per visualizzare il nome del secret di Kubernetes e ApigeeRouteConfig a cui appartiene il problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-expired-my-org-my-virtualhost.

    In questo esempio, my-org-my-virtualhost ApigeeRouteConfig fa riferimento al secret my-org-my-virtualhost-mcp.

  2. Determina il nome virtualhost da ApigeeRouteConfig.

    Il nome di ApigeeRouteConfig è nel formato: <Apigee organization>-<virtualhost name>.

    In questo esempio, my-org è l'organizzazione Apigee e il nome dell'host virtuale è my-virtualhost.

  3. Trova l'host virtuale corrispondente nel tuo overrides.yaml e controlla quale forma utilizza il suo blocco mcpMtls (consulta Configura mTLS tra il piano dati MCP e il gateway in entrata). Seleziona la scheda corrispondente e segui i passaggi indicati.

File dei certificati

Quando utilizzi i percorsi dei file (sslCertPath, sslKeyPath, caCertPath), il grafico virtualhost crea e gestisce i secret dai contenuti dei file.

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. Ottieni un certificato client mTLS MCP rinnovato dalla tua autorità di certificazione e sostituisci il certificato e la relativa chiave privata insieme nei file a cui fanno riferimento mcpMtls.sslCertPath e mcpMtls.sslKeyPath.

  2. Esegui l'upgrade del virtualhost in modo che il grafico riscriva il secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secret Kubernetes

Quando utilizzi un riferimento al secret di Kubernetes (sslSecret), il piano dati MCP legge i valori del certificato direttamente dai secret che hai creato e gli aggiornamenti vengono applicati automaticamente. Non è necessario helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Ottieni un certificato client mTLS MCP rinnovato e la relativa chiave privata dalla tua autorità di certificazione.

  2. Aggiorna il secret in loco con il certificato e la relativa chiave privata, dove MCP_CLIENT_SECRET_NAME è il secret denominato in Spec.Details e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE sono il certificato e la relativa chiave privata:

    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 -

Il piano dati MCP rileva il secret aggiornato al successivo aggiornamento periodico, in genere entro pochi minuti, senza un riavvio del pod, e il ApigeeIssue viene ritirato alla scansione successiva.

Deve raccogliere informazioni diagnostiche

Se il problema persiste anche dopo aver seguito le istruzioni precedenti, raccogli le seguenti informazioni diagnostiche e poi contatta l'assistenza clienti Google Cloud:

  1. L'ID progetto Google Cloud .
  2. Il nome dell'organizzazione Apigee hybrid.
  3. Il campo Spec.Details di ApigeeIssue.
  4. (Facoltativo) Il certificato nel file a cui fa riferimento mcpMtls.sslCertPath o nella voce cert del secret per l'host virtuale interessato.