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 foundsecret has no usable "cacert" entry
Solución
-
Usa
kubectl describepara mostrar el nombre del Secret de Kubernetes yApigeeRouteConfigal que pertenece el problema:kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza
ISSUE_NAMEpor el nombre del problema, por ejemplo,mcp-ca-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp-cacert. -
Determina el nombre
virtualhostdeApigeeRouteConfig.El nombre de
ApigeeRouteConfigtiene el siguiente formato:<Apigee organization>-<virtualhost name>.En este ejemplo,
my-orges la organización de Apigee y el nombre del host virtual esmy-virtualhost. -
Busca el host virtual correspondiente en tu
overrides.yamly verifica qué formato usa su bloquemcpMtls(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
...-
Verifica si el Secret existe y tiene una entrada
cacert, en la que MCP_CA_SECRET_NAME es el Secret que se menciona enSpec.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.caCertPathexista 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, configuramcpMtls.disableChainValidation: truey quitamcpMtls.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. -
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
...-
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 pormcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
helm templateno verifica que los Secrets existan; solo lo hacenhelm installyhelm upgrade, por lo que una ejecución limpia dehelm templateno es evidencia de que este Secret esté presente. Si pretendes ejecutar sin validación de cadena, no basta con omitir el secreto. EstablecemcpMtls.disableChainValidation: trueenoverrides.yamly 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. -
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-cacertagregado 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 certificateholds N trailing bytes that are not PEM
Solución
-
Usa
kubectl describepara mostrar el nombre del Secret de Kubernetes yApigeeRouteConfigal que pertenece el problema:kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza
ISSUE_NAMEpor el nombre del problema, por ejemplo,mcp-ca-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp-cacert. -
Determina el nombre
virtualhostdeApigeeRouteConfig.El nombre de
ApigeeRouteConfigtiene el siguiente formato:<Apigee organization>-<virtualhost name>.En este ejemplo,
my-orges la organización de Apigee y el nombre del host virtual esmy-virtualhost. -
Busca el host virtual correspondiente en tu
overrides.yamly verifica qué formato usa su bloquemcpMtls(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
...-
Valida el contenido del archivo al que hace referencia
mcpMtls.caCertPathy 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-----
-
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
...-
Valida el contenido del archivo del certificado de la AC (MCP_TRUST_CA_FILE) que almacenas en la entrada
cacertdel 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-----
-
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-cacertadjunto 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
-
Usa
kubectl describepara mostrar el nombre del Secret de Kubernetes yApigeeRouteConfigal que pertenece el problema:kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza
ISSUE_NAMEpor el nombre del problema, por ejemplo,mcp-ca-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp-cacert. -
Determina el nombre
virtualhostdeApigeeRouteConfig.El nombre de
ApigeeRouteConfigtiene el siguiente formato:<Apigee organization>-<virtualhost name>.En este ejemplo,
my-orges la organización de Apigee y el nombre del host virtual esmy-virtualhost. -
Busca el host virtual correspondiente en tu
overrides.yamly verifica qué formato usa su bloquemcpMtls(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
...-
Vuelve a compilar el archivo al que hace referencia
mcpMtls.caCertPathpara 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
-
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
...-
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
-
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-cacertadjunto 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:
- Es el ID del proyecto de Google Cloud .
- El nombre de la organización de Apigee hybrid.
- El campo
Spec.DetailsdeApigeeIssue. -
(Opcional) El certificado en el archivo al que hace referencia
mcpMtls.caCertPatho en la entradacacertdel secreto para el host virtual afectado.