Certificato client 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_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 found
  • secret has no usable "cert" entry
  • secret has no "key" 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-client-cert-invalid-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. Controlla se il secret esiste e contiene entrambe le voci, dove MCP_CLIENT_SECRET_NAME è il secret denominato in Spec.Details. La sezione Data deve elencare cert e key:

    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.sslCertPath e mcpMtls.sslKeyPath esistano e non siano vuoti. Il passaggio successivo ripristina il secret da questi frammenti.

  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 e contenga entrambe le voci, dove MCP_CLIENT_SECRET_NAME è il secret denominato in Spec.Details. La sezione Data deve elencare cert e key. Verifica che il nome in mcpMtls.sslSecret corrisponda al secret che hai creato e che il secret si trovi nello spazio dei nomi apigee:

    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 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.

  2. Crea o aggiorna il secret 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 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 voce cert non è PEM.
  • tls: failed to find any PEM data in key input: la voce key non è in formato PEM.
  • tls: private key does not match public key: le voci cert e key non sono accoppiate.
  • tls: failed to parse private key: la chiave non può essere analizzata, di solito perché è criptata. La voce key deve essere una chiave privata PEM non criptata.

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-invalid-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. Convalida il file del certificato e il file della chiave a cui fanno riferimento mcpMtls.sslCertPath e mcpMtls.sslKeyPath e 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-----
  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 il file del certificato (MCP_CLIENT_CERT_FILE) e il file della chiave (MCP_CLIENT_KEY_FILE) archiviati nelle voci cert e key del 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-----
  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 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

  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-invalid-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. 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 riferimento mcpMtls.sslCertPath e mcpMtls.sslKeyPath:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  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. 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
  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 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.sslCertPath o nella voce cert del secret per l'host virtuale interessato.