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
-
Utilizza
kubectl describeper visualizzare il nome del secret di Kubernetes eApigeeRouteConfiga cui appartiene il problema:kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci
ISSUE_NAMEcon il nome del problema, ad esempiomcp-client-cert-expiring-soon-my-org-my-virtualhost.In questo esempio,
my-org-my-virtualhostApigeeRouteConfigfa riferimento al secretmy-org-my-virtualhost-mcp. -
Determina il nome
virtualhostdaApigeeRouteConfig.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. -
Trova l'host virtuale corrispondente nel tuo
overrides.yamle controlla quale forma utilizza il suo bloccomcpMtls(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
...-
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.sslCertPathemcpMtls.sslKeyPath. -
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
...-
Ottieni un certificato client mTLS MCP rinnovato e la relativa chiave privata dalla tua autorità di certificazione.
-
Aggiorna il secret in loco con il certificato e la relativa chiave privata, dove MCP_CLIENT_SECRET_NAME è il secret denominato in
Spec.Detailse 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
-
Utilizza
kubectl describeper visualizzare il nome del secret di Kubernetes eApigeeRouteConfiga cui appartiene il problema:kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci
ISSUE_NAMEcon il nome del problema, ad esempiomcp-client-cert-expired-my-org-my-virtualhost.In questo esempio,
my-org-my-virtualhostApigeeRouteConfigfa riferimento al secretmy-org-my-virtualhost-mcp. -
Determina il nome
virtualhostdaApigeeRouteConfig.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. -
Trova l'host virtuale corrispondente nel tuo
overrides.yamle controlla quale forma utilizza il suo bloccomcpMtls(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
...-
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.sslCertPathemcpMtls.sslKeyPath. -
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
...-
Ottieni un certificato client mTLS MCP rinnovato e la relativa chiave privata dalla tua autorità di certificazione.
-
Aggiorna il secret in loco con il certificato e la relativa chiave privata, dove MCP_CLIENT_SECRET_NAME è il secret denominato in
Spec.Detailse 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:
- L'ID progetto Google Cloud .
- Il nome dell'organizzazione Apigee hybrid.
- Il campo
Spec.DetailsdiApigeeIssue. -
(Facoltativo) Il certificato nel file a cui fa riferimento
mcpMtls.sslCertPatho nella vocecertdel secret per l'host virtuale interessato.