Esta página se aplica à Apigee híbrida, mas não à Apigee.
Não há documentação equivalente da Apigee Edge para esse tópico.
Sintoma
Um ApigeeIssue com Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID é exibido ao visualizar recursos no namespace apigee.
Mensagens de erro
Depois de executar kubectl -n apigee get apigeeissues, um erro como este é exibido:
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 possíveis
A tabela a seguir lista as possíveis causas desse problema:
| Causa | Descrição |
|---|---|
| A entrada ou o secret do certificado do cliente mTLS do MCP está ausente |
O secret nomeado por mcpMtls não existe ou não tem uma entrada cert ou key utilizável.
|
| O certificado do cliente ou a chave mTLS do MCP está incorreto |
A entrada cert não está codificada em PEM ou a entrada key não é
a chave privada correspondente.
|
| O certificado do cliente mTLS do MCP omite o uso de chave estendido clientAuth |
O certificado é analisado, mas o uso de chave estendido não inclui
clientAuth.
|
Causa: o secret ou a entrada do certificado do cliente mTLS do MCP está ausente
O secret do Kubernetes que deveria conter o certificado do cliente mTLS do MCP não existe no namespace apigee ou existe sem uma entrada cert não vazia ou sem uma entrada key. O plano de dados do MCP não tem um certificado do cliente para apresentar a
esse grupo de ambientes. Portanto, as chamadas de ferramenta do MCP para o grupo falham no handshake de TLS.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
Resolução
-
Use
kubectl describepara exibir o nome do secret do Kubernetes e oApigeeRouteConfigao qual o problema pertence:kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua
ISSUE_NAMEpelo nome do problema, por exemplo,mcp-client-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp. -
Determine o nome do
virtualhostnoApigeeRouteConfig.O nome do
ApigeeRouteConfigestá no formato:<Apigee organization>-<virtualhost name>.Neste exemplo,
my-orgé a organização da Apigee, e o nome do virtualhost émy-virtualhost. -
Encontre o host virtual correspondente no
overrides.yamle verifique qual formulário o blocomcpMtlsusa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.
Arquivos de certificado
Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath,
caCertPath), o gráfico do host virtual cria e gerencia as secrets do
conteúdo do arquivo.
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
...-
Verifique se o secret existe e tem as duas entradas, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em
Spec.Details. A seçãoDataprecisa listarcertekey:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Se o secret estiver ausente ou não tiver uma entrada, verifique se os arquivos referenciados por
mcpMtls.sslCertPathemcpMtls.sslKeyPathexistem e não estão vazios. A próxima etapa restaura o secret usando esses dados. -
Faça upgrade do host virtual para que o gráfico reescreva o secret:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets do Kubernetes
Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP
lê os valores do certificado diretamente dos secrets que você criou, e as atualizações
são aplicadas automaticamente. Não é necessário usar helm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Confirme se o secret existe e tem as duas entradas, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em
Spec.Details. A seçãoDataprecisa listarcertekey. Verifique se o nome emmcpMtls.sslSecretcorresponde ao secret que você criou e se o secret está no namespaceapigee: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 templatenão verifica se os secrets existem. Somentehelm installehelm upgradefazem isso. Portanto, uma execução limpa dehelm templatenão é evidência de que esse secret está presente. -
Crie ou atualize o secret com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em
Spec.Detailse MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele: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 -
O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns
minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima
verificação.
Causa: o certificado do cliente ou a chave mTLS do MCP está incorreto
A entrada cert não contém um certificado X.509 codificado em PEM ou a entrada key não está codificada em PEM ou não é a chave privada desse certificado. O
plano de dados do MCP não pode carregar o par.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:
-
entry holds no PEM encoded certificate: a entradacertnão é PEM. -
tls: failed to find any PEM data in key input: a entradakeynão é PEM. -
tls: private key does not match public key: as entradascertekeynão estão pareadas. -
tls: failed to parse private key: não é possível analisar a chave, geralmente porque ela está criptografada. A entradakeyprecisa ser uma chave privada PEM não criptografada.
Resolução
-
Use
kubectl describepara exibir o nome do secret do Kubernetes e oApigeeRouteConfigao qual o problema pertence:kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua
ISSUE_NAMEpelo nome do problema, por exemplo,mcp-client-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp. -
Determine o nome do
virtualhostnoApigeeRouteConfig.O nome do
ApigeeRouteConfigestá no formato:<Apigee organization>-<virtualhost name>.Neste exemplo,
my-orgé a organização da Apigee, e o nome do virtualhost émy-virtualhost. -
Encontre o host virtual correspondente no
overrides.yamle verifique qual formulário o blocomcpMtlsusa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.
Arquivos de certificado
Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath,
caCertPath), o gráfico do host virtual cria e gerencia as secrets do
conteúdo do arquivo.
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
...-
Valide o arquivo de certificado e o arquivo de chave referenciados por
mcpMtls.sslCertPathemcpMtls.sslKeyPathe corrija-os, se necessário. O certificado precisa conter as linhas de início e fim, e a chave precisa ser a chave privada dele. Exemplo:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Faça upgrade do host virtual para que o gráfico reescreva o secret:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets do Kubernetes
Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP
lê os valores do certificado diretamente dos secrets que você criou, e as atualizações
são aplicadas automaticamente. Não é necessário usar helm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Valide o arquivo de certificado (MCP_CLIENT_CERT_FILE) e o arquivo de chave (MCP_CLIENT_KEY_FILE) que você armazena nas entradas
certekeydo secret e corrija-os, se necessário. O certificado precisa conter as linhas de início e fim, e a chave precisa ser a chave privada dele. Exemplo:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Atualize o secret no local com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em
Spec.Details, e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele: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 -
O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns
minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima
verificação.
Causa: o certificado do cliente mTLS do MCP omite o uso de chave estendido clientAuth
O certificado está bem formado e é pareado com a chave, mas o uso de chave estendido (EKU, na sigla em inglês) não
inclui clientAuth. Portanto, ele não pode ser usado para autenticação de cliente, e o plano de dados do MCP
não o apresenta. Isso é comum quando um certificado de servidor ou um certificado de um perfil de CA público que não emite mais clientAuth é reutilizado.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-client-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret e o ApigeeRouteConfig e lista os usos de chave estendidos que o certificado carrega.
Resolução
-
Use
kubectl describepara exibir o nome do secret do Kubernetes e oApigeeRouteConfigao qual o problema pertence:kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua
ISSUE_NAMEpelo nome do problema, por exemplo,mcp-client-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp. -
Determine o nome do
virtualhostnoApigeeRouteConfig.O nome do
ApigeeRouteConfigestá no formato:<Apigee organization>-<virtualhost name>.Neste exemplo,
my-orgé a organização da Apigee, e o nome do virtualhost émy-virtualhost. -
Encontre o host virtual correspondente no
overrides.yamle verifique qual formulário o blocomcpMtlsusa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.
Arquivos de certificado
Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath,
caCertPath), o gráfico do host virtual cria e gerencia as secrets do
conteúdo do arquivo.
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
...-
Emita novamente o certificado do cliente da sua CA particular com um perfil que inclua o uso de chave estendido
clientAuth. Confirme, em que MCP_CLIENT_CERT_FILE é o certificado reemitido, e substitua os arquivos referenciados pormcpMtls.sslCertPathemcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Faça upgrade do host virtual para que o gráfico reescreva o secret:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace apigee \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Secrets do Kubernetes
Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP
lê os valores do certificado diretamente dos secrets que você criou, e as atualizações
são aplicadas automaticamente. Não é necessário usar helm upgrade.
virtualhosts:
...
- name: my-virtualhost
selector:
app: apigee-ingressgateway
tlsMode: MUTUAL
sslSecret: my-ingress-secret
mcpMtls:
sslSecret: my-mcp-client-secret
...-
Emita novamente o certificado do cliente da sua CA particular com um perfil que inclua o uso de chave estendido
clientAuth. Confirme isso antes de atualizar o secret, em que MCP_CLIENT_CERT_FILE é o certificado reemitido:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Atualize o secret no local com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em
Spec.Details, e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele: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 -
O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns
minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima
verificação.
É necessário coletar informações de diagnóstico
Se o problema persistir mesmo depois de seguir as instruções acima, colete as seguintes informações de diagnóstico e entre em contato com o Google Cloud Customer Care:
- O ID do projeto do Google Cloud .
- O nome da organização da Apigee híbrida.
- O campo
Spec.DetailsdoApigeeIssue. -
(Opcional) O certificado no arquivo referenciado por
mcpMtls.sslCertPathou na entradacertdo secret para o host virtual afetado.