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_CA_CERT_INVALID quando visualizzi le risorse nello spazio dei nomi apigee.
Questo problema viene segnalato solo per i gruppi di ambienti il cui blocco mcpMtls ha la convalida della catena abilitata (impostazione predefinita). Per un gruppo con mcpMtls.disableChainValidation: true, il piano dati MCP non utilizza un certificato CA e il secret -cacert non viene scansionato.
Messaggi di errore
Dopo aver eseguito kubectl -n apigee get apigeeissues, viene visualizzato un errore simile al seguente:
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
Cause possibili
La tabella seguente elenca le possibili cause di questo problema:
| Causa | Descrizione |
|---|---|
| Secret o voce del certificato CA mTLS MCP mancante |
Il secret -cacert non esiste o non ha una voce cacert utilizzabile.
|
| Il certificato CA mTLS MCP non è codificato in PEM |
La voce cacert non contiene un blocco di certificati PEM o contiene byte al di fuori dei blocchi PEM.
|
| Il certificato CA mTLS MCP non è valido o non è un certificato CA |
Un blocco nella voce cacert non è un certificato, non viene analizzato o non è un certificato CA.
|
Causa: manca la voce o il secret del certificato CA mTLS MCP
Il secret di Kubernetes che deve contenere il certificato CA rispetto al quale il piano dati MCP convalida il gateway in entrata non esiste nello spazio dei nomi apigee o esiste senza una voce cacert non vuota. Il suo nome è il nome del secret del certificato client con l'aggiunta di -cacert. Il grafico crea questo secret solo quando utilizzi i file dei certificati; con sslSecret devi crearlo tu e dimenticarlo è la causa più comune di questo problema.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-ca-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
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
I contenuti di Spec.Details indicano il nome del secret, il ApigeeRouteConfig e il problema. Ad esempio:
secret not foundsecret has no usable "cacert" 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-ca-cert-invalid-my-org-my-virtualhost.In questo esempio,
my-org-my-virtualhostApigeeRouteConfigfa riferimento al secretmy-org-my-virtualhost-mcp-cacert. -
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 ha una voce
cacert, dove MCP_CA_SECRET_NAME è il secret denominato inSpec.Details:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
Se il secret non è presente o non contiene una voce, assicurati che il file a cui fa riferimento
mcpMtls.caCertPathesista e non sia vuoto. Il passaggio successivo ripristina il secret da questa versione. Se intendi eseguire l'operazione senza la convalida della catena, impostamcpMtls.disableChainValidation: truee rimuovimcpMtls.caCertPath(il grafico rifiuta i due elementi insieme). Tieni presente che questa operazione disattiva la verifica del certificato del gateway in entrata da parte del piano dati MCP. -
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 esattamente con quel nome con una voce
cacert, dove MCP_CLIENT_SECRET_NAME è il secret del certificato client denominato damcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
helm templatenon verifica l'esistenza dei secret; solohelm installehelm upgradelo fanno, quindi un'esecuzione pulita dihelm templatenon è una prova della presenza di questo secret. Se intendi eseguire l'operazione senza la convalida della catena, non è sufficiente omettere il secret. ImpostamcpMtls.disableChainValidation: trueinoverrides.yamled esegui l'upgrade dell'host virtuale. Tieni presente che in questo modo viene disattivata la verifica del certificato del gateway in entrata da parte del piano dati MCP. -
Crea o aggiorna il secret del certificato CA, dove MCP_CLIENT_SECRET_NAME è il valore di
mcpMtls.sslSecret, il secret del certificato CA è quel nome con-cacertaggiunto e MCP_TRUST_CA_FILE è il file del certificato 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 -
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 CA mTLS MCP non è codificato in PEM
Nella voce cacert mancano i blocchi di testo con codifica PEM o sono presenti contenuti dopo l'ultima riga -----END CERTIFICATE----- che non sono PEM. Il piano dati MCP non lo carica.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-ca-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
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
I contenuti di Spec.Details indicano il nome del secret, il ApigeeRouteConfig e il problema. Ad esempio:
entry holds no PEM encoded certificateholds N trailing bytes that are not PEM
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-ca-cert-invalid-my-org-my-virtualhost.In questo esempio,
my-org-my-virtualhostApigeeRouteConfigfa riferimento al secretmy-org-my-virtualhost-mcp-cacert. -
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 i contenuti del file a cui fa riferimento
mcpMtls.caCertPathe correggili, se necessario. Assicurati che i contenuti includano solo blocchi di certificati completi, ciascuno con le righe di inizio e di fine. 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 i contenuti del file del certificato CA (MCP_TRUST_CA_FILE) che memorizzi nella voce
cacertdel secret e correggili, se necessario. Assicurati che i contenuti includano solo blocchi di certificati completi, ciascuno con le righe di inizio e di fine. Ad esempio:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Aggiorna il secret del certificato CA in loco, dove MCP_CLIENT_SECRET_NAME è il valore di
mcpMtls.sslSecret, il secret del certificato CA è quel nome con l'aggiunta di-cacerte MCP_TRUST_CA_FILE è il file del certificato 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 -
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 CA mTLS MCP non è nel formato corretto o non è un certificato CA
Ogni blocco PEM nella voce cacert deve essere un blocco CERTIFICATE che viene analizzato e ha il vincolo di base CA. Un blocco di chiavi private, un certificato foglia (ad esempio il certificato del server del gateway in entrata) o un blocco danneggiato rende la voce inutilizzabile e il piano dati MCP non la carica.
Diagnosi
Esegui questo comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Sostituisci ISSUE_NAME con il nome del problema, ad esempio mcp-ca-cert-invalid-my-org-my-virtualhost.
L'output dovrebbe essere simile al seguente:
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
I contenuti di Spec.Details indicano il nome del secret, il ApigeeRouteConfig e il problema. Ad esempio:
-
no PEM block parsed as a certificate: ...: non è possibile analizzare nessuno dei blocchi di certificati (ad esempio, l'unico certificato è danneggiato). -
block N is a "..." block, want CERTIFICATE: il blocco N non è un certificato (ad esempio, una chiave privata). -
block N does not parse: il blocco N è un certificato danneggiato. -
block N is not a CA certificate: il blocco N è un certificato, ma non una CA (ad esempio, un certificato foglia).
I blocchi sono numerati a partire da 0.
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-ca-cert-invalid-my-org-my-virtualhost.In questo esempio,
my-org-my-virtualhostApigeeRouteConfigfa riferimento al secretmy-org-my-virtualhost-mcp-cacert. -
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
...-
Ricrea il file a cui fa riferimento
mcpMtls.caCertPathin modo che contenga solo il certificato CA (o la catena) che ha firmato il certificato del gateway in entrata. Poi verifica che ogni blocco sia un certificato CA, dove MCP_TRUST_CA_FILE è il file:openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
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
...-
Ricrea il file del certificato CA (MCP_TRUST_CA_FILE) in modo che contenga solo il certificato CA (o la catena) che ha firmato il certificato del gateway in entrata. Poi verifica che ogni blocco sia un certificato CA:
openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
Aggiorna il secret del certificato CA in loco, dove MCP_CLIENT_SECRET_NAME è il valore di
mcpMtls.sslSecret, il secret del certificato CA è quel nome con l'aggiunta di-cacerte MCP_TRUST_CA_FILE è il file del certificato 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 -
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.caCertPatho nella vocecacertdel secret per l'host virtuale interessato.