Certificato CA mTLS MCP non valido

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 found
  • secret has no usable "cacert" entry

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-ca-cert-invalid-my-org-my-virtualhost.

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

  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. Controlla se il secret esiste e ha una voce cacert, dove MCP_CA_SECRET_NAME è il secret denominato in Spec.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.caCertPath esista e non sia vuoto. Il passaggio successivo ripristina il secret da questa versione. Se intendi eseguire l'operazione senza la convalida della catena, imposta mcpMtls.disableChainValidation: true e rimuovi mcpMtls.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.

  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. Verifica che il secret esista esattamente con quel nome con una voce cacert, dove MCP_CLIENT_SECRET_NAME è il secret del certificato client denominato da mcpMtls.sslSecret:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template non verifica l'esistenza dei secret; solo helm install e helm upgrade lo fanno, quindi un'esecuzione pulita di helm template non è una prova della presenza di questo secret. Se intendi eseguire l'operazione senza la convalida della catena, non è sufficiente omettere il secret. Imposta mcpMtls.disableChainValidation: true in overrides.yaml ed 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.

  2. 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 -cacert aggiunto 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 certificate
  • holds N trailing bytes that are not PEM

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-ca-cert-invalid-my-org-my-virtualhost.

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

  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. Convalida i contenuti del file a cui fa riferimento mcpMtls.caCertPath 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-----
  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. Convalida i contenuti del file del certificato CA (MCP_TRUST_CA_FILE) che memorizzi nella voce cacert del 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-----
  2. 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 -cacert 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 è 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

  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-ca-cert-invalid-my-org-my-virtualhost.

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

  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. Ricrea il file a cui fa riferimento mcpMtls.caCertPath 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, 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
  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. 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
  2. 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 -cacert 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.

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.caCertPath o nella voce cacert del secret per l'host virtuale interessato.