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_CLIENT_CERT_INVALID cuando se visualizan los recursos en el espacio de nombres apigee.
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-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
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 cliente de mTLS de MCP |
El secreto que se indica en mcpMtls no existe o no tiene una entrada
cert o key que se pueda usar.
|
| El certificado de cliente o la clave de mTLS de MCP tiene un formato incorrecto |
La entrada cert no está codificada con PEM o la entrada key no es
la clave privada coincidente.
|
| El certificado de cliente de mTLS de MCP omite el uso de clave extendido clientAuth |
El certificado se analiza, pero su uso de clave extendido no incluye
clientAuth.
|
Causa: Falta el secreto o la entrada del certificado de cliente de mTLS de MCP
El Secret de Kubernetes que debería contener el certificado de cliente de mTLS de MCP no existe en el
espacio de nombres apigee, o existe sin una entrada cert no vacía o
sin una entrada key. El plano de datos de MCP no tiene un certificado de cliente para presentar en
este grupo de entornos, por lo que las llamadas a la herramienta de MCP al grupo fallan en el protocolo de enlace TLS.
Diagnóstico
Ejecuta el comando siguiente:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
El resultado debería ser similar al siguiente:
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
El contenido de Spec.Details nombra el Secret, el
ApigeeRouteConfig y lo que está mal. Por ejemplo:
secret not foundsecret has no usable "cert" entrysecret has no "key" 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-client-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp. -
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 ambas entradas, en las que MCP_CLIENT_SECRET_NAME es el Secret que se menciona en
Spec.Details. La secciónDatadebe enumerarcertykey:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Si falta el secreto o no tiene una entrada, asegúrate de que los archivos a los que hacen referencia
mcpMtls.sslCertPathymcpMtls.sslKeyPathexistan y no estén vacíos. En el siguiente paso, se restablece el secreto a partir de ellos. -
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 y tenga ambas entradas, en las que MCP_CLIENT_SECRET_NAME es el Secret que se menciona en
Spec.Details. La secciónDatadebe incluircertykey. Verifica que el nombre enmcpMtls.sslSecretcoincida con el Secret que creaste y que el Secret esté en el espacio de nombresapigee: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 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. -
Crea o actualiza el Secret con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se nombra en
Spec.Detailsy MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada: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 -
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 o la clave de cliente de mTLS de MCP tiene un formato incorrecto
La entrada cert no contiene un certificado X.509 codificado con PEM, o la
entrada key no está codificada con PEM o no es la clave privada de ese certificado. El plano de datos de MCP no puede cargar el par.
Diagnóstico
Ejecuta el comando siguiente:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
El resultado debería ser similar al siguiente:
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
El contenido de Spec.Details nombra el Secret, el
ApigeeRouteConfig y lo que está mal. Por ejemplo:
-
entry holds no PEM encoded certificate: La entradacertno es PEM. -
tls: failed to find any PEM data in key input: La entradakeyno es PEM. -
tls: private key does not match public key: Las entradascertykeyno se vinculan. -
tls: failed to parse private key: No se puede analizar la clave, por lo general, porque está encriptada. La entradakeydebe ser una clave privada PEM sin encriptar.
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-client-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp. -
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 archivo de certificado y el archivo de clave a los que hacen referencia
mcpMtls.sslCertPathymcpMtls.sslKeyPath, y corrígelos si es necesario. El certificado debe contener las líneas de certificado iniciales y finales, y la clave debe ser la clave privada para él. 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 archivo de certificado (MCP_CLIENT_CERT_FILE) y el archivo de clave (MCP_CLIENT_KEY_FILE) que almacenas en las entradas
certykeydel Secret, y corrígelos si es necesario. El certificado debe contener las líneas de certificado iniciales y finales, y la clave debe ser la clave privada para él. Por ejemplo:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Actualiza el Secret en su lugar con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se indica en
Spec.Detailsy MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada: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 -
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 cliente de mTLS de MCP omite el uso de clave extendido clientAuth
El certificado tiene un formato correcto y se vincula con su clave, pero su uso extendido de la clave (EKU) no
incluye clientAuth, por lo que no se puede usar para la autenticación del cliente y el plano de datos de MCP no lo
presenta. Esto es común cuando se reutiliza un certificado de servidor o un certificado de un
perfil de CA público que ya no emite clientAuth.
Diagnóstico
Ejecuta el comando siguiente:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
El resultado debería ser similar al siguiente:
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
El contenido de Spec.Details nombra el secreto y el
ApigeeRouteConfig, y enumera los usos de claves extendidos que lleva el certificado.
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-client-cert-invalid-my-org-my-virtualhost.En este ejemplo,
ApigeeRouteConfigmy-org-my-virtualhosthace referencia al Secretmy-org-my-virtualhost-mcp. -
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 emitir el certificado de cliente desde tu CA privada con un perfil que incluya el uso de clave extendido
clientAuth. Confírmalo, donde MCP_CLIENT_CERT_FILE es el certificado que se volvió a emitir y, luego, reemplaza los archivos a los que hacen referenciamcpMtls.sslCertPathymcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
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 emitir el certificado de cliente desde tu CA privada con un perfil que incluya el uso de clave extendido
clientAuth. Confírmalo antes de actualizar el secreto, donde MCP_CLIENT_CERT_FILE es el certificado que se volvió a emitir:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Actualiza el Secret en su lugar con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se indica en
Spec.Detailsy MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada: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 -
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.sslCertPatho en la entradacertdel secreto para el host virtual afectado.