El certificado de la AC de mTLS de MCP no es válido

Esta página se aplica a Apigee Hybrid, pero no a Apigee.

No hay documentación de Apigee Edge equivalente para este tema.

Síntoma

Se muestra un ApigeeIssue con Reason AIS_MCP_MTLS_CA_CERT_INVALID cuando se visualizan los recursos en el espacio de nombres apigee.

Este problema solo se genera para los grupos de entornos cuyo bloque mcpMtls tiene habilitada la validación de cadena (la opción predeterminada). Para un grupo con mcpMtls.disableChainValidation: true, el plano de datos de MCP no usa un certificado de la AC y no se analiza el secreto -cacert.

Mensajes de error

Después de ejecutar kubectl -n apigee get apigeeissues, se muestra un error como el siguiente:

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

Causas posibles

En la siguiente tabla, se enumeran las posibles causas de este problema:

Causa Descripción
Falta el secreto o la entrada del certificado de la AC de mTLS de MCP El secreto -cacert no existe o no tiene una entrada cacert utilizable.
El certificado de la AC de mTLS de MCP no está codificado con PEM La entrada cacert no contiene ningún bloque de certificado PEM o contiene bytes fuera de los bloques PEM.
El certificado de la AC de mTLS de MCP tiene un formato incorrecto o no es un certificado de la AC Un bloque en la entrada cacert no es un certificado, no se analiza o no es un certificado de la AC.

Causa: Falta el secreto o la entrada del certificado de la AC de mTLS de MCP

El Secret de Kubernetes que debería contener el certificado de la AC con el que el plano de datos de MCP valida la puerta de enlace de entrada no existe en el espacio de nombres apigee o existe sin una entrada cacert no vacía. Su nombre es el nombre del Secret del certificado de cliente con -cacert agregado. El gráfico crea este Secret solo cuando usas archivos de certificado; con sslSecret, debes crearlo tú mismo, y olvidarlo es la causa más común de este problema.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

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

El contenido de Spec.Details nombra el Secret, el ApigeeRouteConfig y lo que está mal. Por ejemplo:

  • secret not found
  • secret has no usable "cacert" entry

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp-cacert.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

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. Verifica si el Secret existe y tiene una entrada cacert, en la que MCP_CA_SECRET_NAME es el Secret que se menciona en Spec.Details:

    kubectl -n apigee describe secret MCP_CA_SECRET_NAME

    Si falta el secreto o no tiene una entrada, asegúrate de que el archivo al que hace referencia mcpMtls.caCertPath exista y no esté vacío. En el siguiente paso, se restablece el secreto a partir de ella. Si quieres ejecutar sin validación de cadena, configura mcpMtls.disableChainValidation: true y quita mcpMtls.caCertPath (el gráfico rechaza los dos juntos). Ten en cuenta que esto desactiva la verificación del certificado de la puerta de enlace de entrada por parte del plano de datos de MCP.

  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Confirma que el Secret exista exactamente con ese nombre con una entrada cacert, en la que MCP_CLIENT_SECRET_NAME es el Secret del certificado de cliente nombrado por mcpMtls.sslSecret:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template no verifica que los Secrets existan; solo lo hacen helm install y helm upgrade, por lo que una ejecución limpia de helm template no es evidencia de que este Secret esté presente. Si pretendes ejecutar sin validación de cadena, no basta con omitir el secreto. Establece mcpMtls.disableChainValidation: true en overrides.yaml y actualiza el host virtual. Ten en cuenta que esto desactiva la verificación del certificado de la puerta de enlace de entrada por parte del plano de datos de MCP.

  2. Crea o actualiza el Secret del certificado de la AC, en el que MCP_CLIENT_SECRET_NAME es el valor de mcpMtls.sslSecret, el Secret del certificado de la AC es ese nombre con -cacert agregado y MCP_TRUST_CA_FILE es el archivo del certificado de la AC:

    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 -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Causa: El certificado de la AC de mTLS de MCP no está codificado con PEM

A la entrada cacert le faltan los bloques de texto con codificación PEM o tiene contenido después de la última línea -----END CERTIFICATE----- que no es PEM. El plano de datos de MCP no lo carga.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

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

El contenido de Spec.Details nombra el Secret, el ApigeeRouteConfig y lo que está mal. Por ejemplo:

  • entry holds no PEM encoded certificate
  • holds N trailing bytes that are not PEM

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp-cacert.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

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. Valida el contenido del archivo al que hace referencia mcpMtls.caCertPath y corrígelo si es necesario. Asegúrate de que el contenido solo tenga bloques de certificado completos, cada uno con sus líneas iniciales y finales. Por ejemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Valida el contenido del archivo del certificado de la AC (MCP_TRUST_CA_FILE) que almacenas en la entrada cacert del secreto y corrígelo si es necesario. Asegúrate de que el contenido solo tenga bloques de certificados completos, cada uno con sus líneas iniciales y finales. Por ejemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Actualiza el secreto del certificado de la AC en su lugar, donde MCP_CLIENT_SECRET_NAME es el valor de mcpMtls.sslSecret, el secreto del certificado de la AC es ese nombre con -cacert adjunto y MCP_TRUST_CA_FILE es el archivo del certificado de la AC:

    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 -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Causa: El certificado de la AC de mTLS de MCP tiene un formato incorrecto o no es un certificado de la AC

Cada bloque PEM en la entrada cacert debe ser un bloque CERTIFICATE que analice y tenga la restricción básica de la AC. Un bloque de clave privada, un certificado de hoja (por ejemplo, el certificado de servidor de la puerta de enlace de entrada) o un bloque dañado hacen que la entrada no se pueda usar, y el plano de datos de MCP no la carga.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

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

El contenido de Spec.Details nombra el Secret, el ApigeeRouteConfig y lo que está mal. Por ejemplo:

  • no PEM block parsed as a certificate: ...: No se puede analizar ninguno de los bloques de certificados (por ejemplo, el único certificado está dañado).
  • block N is a "..." block, want CERTIFICATE: El bloque N no es un certificado (por ejemplo, una clave privada).
  • block N does not parse: El bloque N es un certificado dañado.
  • block N is not a CA certificate: El bloque N es un certificado, pero no una AC (por ejemplo, un certificado de hoja).

Los bloques se numeran a partir de 0.

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp-cacert.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

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. Vuelve a compilar el archivo al que hace referencia mcpMtls.caCertPath para que solo contenga el certificado de la AC (o la cadena) que firmó el certificado de la puerta de enlace de entrada. Luego, confirma que cada bloque sea un certificado de la AC, en el que MCP_TRUST_CA_FILE sea ese archivo:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Vuelve a compilar el archivo de certificado de la AC (MCP_TRUST_CA_FILE) para que solo contenga el certificado de la AC (o la cadena) que firmó el certificado de la puerta de enlace de entrada. Luego, confirma que cada bloque sea un certificado de la AC:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. Actualiza el secreto del certificado de la AC en su lugar, donde MCP_CLIENT_SECRET_NAME es el valor de mcpMtls.sslSecret, el secreto del certificado de la AC es ese nombre con -cacert adjunto y MCP_TRUST_CA_FILE es el archivo del certificado de la AC:

    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 -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Se debe recopilar información de diagnóstico

Si el problema persiste incluso después de seguir las instrucciones anteriores, recopila la siguiente información de diagnóstico y, luego, comunícate con la Atención al cliente de Google Cloud:

  1. Es el ID del proyecto de Google Cloud .
  2. El nombre de la organización de Apigee hybrid.
  3. El campo Spec.Details de ApigeeIssue.
  4. (Opcional) El certificado en el archivo al que hace referencia mcpMtls.caCertPath o en la entrada cacert del secreto para el host virtual afectado.