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_INVALID quando visualizzi le risorse nello spazio dei nomi apigee.
Messaggi di errore
Dopo aver eseguito kubectl -n apigee get apigeeissues, viene visualizzato un errore simile al seguente:
NAME SEVERITY REASON DOCUMENTATION AGE mcp-client-cert-invalid-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CLIENT_CERT_INVALID https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID 5h18m
Cause possibili
La tabella seguente elenca le possibili cause di questo problema:
| Causa | Descrizione |
|---|---|
| Secret o voce del certificato client mTLS MCP mancante |
Il secret denominato da mcpMtls non esiste o non ha una voce cert o key utilizzabile.
|
| Il certificato o la chiave client mTLS MCP non sono nel formato corretto |
La voce cert non è codificata in PEM o la voce key non è la chiave privata corrispondente.
|
| Il certificato client mTLS MCP omette l'utilizzo della chiave estesa clientAuth |
Il certificato viene analizzato, ma l'utilizzo della chiave estesa non include clientAuth.
|
Causa: il secret o la voce del certificato client mTLS MCP non è presente
Il secret di Kubernetes che dovrebbe contenere il certificato client mTLS MCP non esiste nello spazio dei nomi apigee o esiste senza una voce cert non vuota o senza una voce key. Il piano dati MCP non ha un certificato client da presentare per questo gruppo di ambienti, pertanto le chiamate dello strumento MCP al gruppo non vanno a buon fine durante il TLS handshake.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found
I contenuti di Spec.Details indicano il nome del secret, il ApigeeRouteConfig e il problema. Ad esempio:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
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-invalid-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
...-
Controlla se il secret esiste e contiene entrambe le voci, dove MCP_CLIENT_SECRET_NAME è il secret denominato in
Spec.Details. La sezioneDatadeve elencarecertekey:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Se il secret non è presente o non contiene una voce, assicurati che i file a cui fanno riferimento
mcpMtls.sslCertPathemcpMtls.sslKeyPathesistano e non siano vuoti. Il passaggio successivo ripristina il secret da questi frammenti. -
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
...-
Verifica che il secret esista e contenga entrambe le voci, dove MCP_CLIENT_SECRET_NAME è il secret denominato in
Spec.Details. La sezioneDatadeve elencarecertekey. Verifica che il nome inmcpMtls.sslSecretcorrisponda al secret che hai creato e che il secret si trovi nello spazio dei nomiapigee:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME kubectl get secret -A --field-selector metadata.name=MCP_CLIENT_SECRET_NAME # if the first command finds nothing
helm templatenon verifica l'esistenza dei secret; solohelm installehelm upgradelo fanno, quindi un'esecuzione pulita dihelm templatenon è una prova della presenza di questo secret. -
Crea o aggiorna il secret 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 corretto 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 o la chiave client mTLS MCP non sono validi
La voce cert non contiene un certificato X.509 con codifica PEM oppure la voce key non ha la codifica PEM o non è la chiave privata per quel certificato. Il piano dati MCP non può caricare la coppia.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key
I contenuti di Spec.Details indicano il nome del secret, il ApigeeRouteConfig e il problema. Ad esempio:
-
entry holds no PEM encoded certificate: la vocecertnon è PEM. -
tls: failed to find any PEM data in key input: la vocekeynon è in formato PEM. -
tls: private key does not match public key: le vocicertekeynon sono accoppiate. -
tls: failed to parse private key: la chiave non può essere analizzata, di solito perché è criptata. La vocekeydeve essere una chiave privata PEM non criptata.
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-invalid-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
...-
Convalida il file del certificato e il file della chiave a cui fanno riferimento
mcpMtls.sslCertPathemcpMtls.sslKeyPathe correggili, se necessario. Il certificato deve contenere le righe di inizio e fine del certificato e la chiave deve essere la chiave privata corrispondente. Ad esempio:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
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
...-
Convalida il file del certificato (MCP_CLIENT_CERT_FILE) e il file della chiave (MCP_CLIENT_KEY_FILE) archiviati nelle voci
certekeydel secret e correggili, se necessario. Il certificato deve contenere le righe di inizio e di fine del certificato e la chiave deve essere la chiave privata corrispondente. Ad esempio:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
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 corretto 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 omette l'utilizzo della chiave estesa clientAuth
Il certificato è nel formato corretto e si accoppia con la relativa chiave, ma l'utilizzo della chiave estesa (EKU) non include clientAuth, pertanto non può essere utilizzato per l'autenticazione del client e il piano dati MCP non lo presenta. Questo accade spesso quando viene riutilizzato un certificato server o un certificato di un profilo CA pubblico che non emette più clientAuth.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-client-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth
I contenuti di Spec.Details indicano il nome del secret e di ApigeeRouteConfig ed elencano gli utilizzi estesi della chiave contenuti nel certificato.
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-invalid-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
...-
Riemetti il certificato client dalla tua CA privata con un profilo che include l'utilizzo esteso della chiave
clientAuth. Conferma, dove MCP_CLIENT_CERT_FILE è il certificato riemesso, quindi sostituisci i file a cui fanno riferimentomcpMtls.sslCertPathemcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
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
...-
Riemetti il certificato client dalla tua CA privata con un profilo che include l'utilizzo esteso della chiave
clientAuth. Confermalo prima di aggiornare il secret, dove MCP_CLIENT_CERT_FILE è il certificato riemesso:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
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 corretto 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.