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_CA_CERT_INVALID é exibido ao visualizar recursos no namespace apigee.
Esse problema é gerado apenas para grupos de ambiente em que o bloco mcpMtls tem a validação de cadeia
ativada (o padrão). Para um grupo com
mcpMtls.disableChainValidation: true, o plano de dados do MCP não usa um certificado
de CA, e o secret -cacert não é verificado.
Mensagens de erro
Depois de executar kubectl -n apigee get apigeeissues, um erro como este é exibido:
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 possíveis
A tabela a seguir lista as possíveis causas desse problema:
| Causa | Descrição |
|---|---|
| O secret ou a entrada do certificado de CA mTLS do MCP está ausente |
O secret -cacert não existe ou não tem uma entrada cacert
utilizável.
|
| O certificado de CA de mTLS do MCP não é codificado em PEM |
A entrada cacert não contém nenhum bloco de certificado PEM ou contém bytes fora
dos blocos PEM.
|
| O certificado de CA mTLS do MCP está incorreto ou não é um certificado de CA |
Um bloco na entrada cacert não é um certificado, não é analisado ou não é um certificado de CA.
|
Causa: o secret ou a entrada do certificado de CA de mTLS do MCP está ausente
O secret do Kubernetes que deve conter o certificado de CA que o plano de dados do MCP valida o gateway de entrada não existe no namespace apigee ou existe sem uma entrada cacert não vazia. O nome dele é o nome do secret do certificado do cliente
com -cacert anexado. O gráfico cria esse secret apenas quando você usa arquivos de certificado. Com sslSecret, você precisa criá-lo por conta própria, e esquecer de fazer isso é a causa mais comum desse problema.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-ca-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:
secret not foundsecret has no usable "cacert" 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-ca-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp-cacert. -
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 uma entrada
cacert, em que MCP_CA_SECRET_NAME é o secret nomeado emSpec.Details:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
Se o secret estiver ausente ou não tiver uma entrada, verifique se o arquivo referenciado por
mcpMtls.caCertPathexiste e não está vazio. A próxima etapa restaura o secret a partir dele. Se você pretende executar sem validação de cadeia, definamcpMtls.disableChainValidation: truee removamcpMtls.caCertPath(o gráfico rejeita os dois juntos). Esteja ciente de que isso desativa a verificação do certificado do gateway de entrada pelo plano de dados do MCP. -
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 exatamente com esse nome com uma entrada
cacert, em que MCP_CLIENT_SECRET_NAME é o secret do certificado do cliente nomeado pormcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
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. Se você pretende executar sem validação de cadeia, omitir o secret não é suficiente. DefinamcpMtls.disableChainValidation: trueemoverrides.yamle faça upgrade do host virtual. Isso desativa a verificação do certificado do gateway de entrada pelo plano de dados do MCP. -
Crie ou atualize o secret do certificado de CA, em que MCP_CLIENT_SECRET_NAME é o valor de
mcpMtls.sslSecret, o secret do certificado de CA é esse nome com-cacertanexado e MCP_TRUST_CA_FILE é o arquivo de certificado de CA: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 -
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 de CA de mTLS do MCP não é codificado em PEM
A entrada cacert não tem os blocos de texto de codificação PEM ou tem conteúdo após a última linha -----END CERTIFICATE----- que não é PEM. O plano de dados do MCP não o carrega.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-ca-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:
entry holds no PEM encoded certificateholds N trailing bytes that are not PEM
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-ca-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp-cacert. -
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 conteúdo do arquivo referenciado por
mcpMtls.caCertPathe corrija-o, se necessário. Verifique se o conteúdo tem apenas blocos de certificado completos, cada um com as linhas inicial e final. 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 conteúdo do arquivo de certificado de CA (MCP_TRUST_CA_FILE) armazenado na entrada
cacertdo secret e corrija-o, se necessário. Verifique se o conteúdo tem apenas blocos de certificado completos, cada um com as linhas inicial e final. Exemplo:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Atualize o secret do certificado de CA no local, em que MCP_CLIENT_SECRET_NAME é o valor de
mcpMtls.sslSecret, o secret do certificado de CA é esse nome com-cacertanexado e MCP_TRUST_CA_FILE é o arquivo de certificado de CA: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 -
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 de CA de mTLS do MCP está incorreto ou não é um certificado de CA
Cada bloco PEM na entrada cacert precisa ser um bloco CERTIFICATE que
analisa e tem a restrição básica de CA. Um bloco de chave privada, um certificado de folha (por exemplo, o
certificado do servidor do gateway de entrada) ou um bloco corrompido torna a entrada inutilizável, e
o plano de dados do MCP não a carrega.
Diagnóstico
Execute este comando:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Substitua ISSUE_NAME pelo nome do problema, por exemplo,
mcp-ca-cert-invalid-my-org-my-virtualhost.
A saída será parecida com esta:
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
O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:
-
no PEM block parsed as a certificate: ...: nenhum dos blocos de certificado pode ser analisado (por exemplo, o único certificado está corrompido). -
block N is a "..." block, want CERTIFICATE: o bloco N não é um certificado (por exemplo, uma chave privada). -
block N does not parse: o bloco N é um certificado corrompido. -
block N is not a CA certificate: o bloco N é um certificado, mas não uma CA (por exemplo, um certificado de folha).
Os blocos são numerados a partir de 0.
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-ca-cert-invalid-my-org-my-virtualhost.Neste exemplo, o
ApigeeRouteConfigmy-org-my-virtualhostreferencia o secretmy-org-my-virtualhost-mcp-cacert. -
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
...-
Recrie o arquivo referenciado por
mcpMtls.caCertPathpara que ele contenha apenas o certificado de CA (ou cadeia) que assinou o certificado do gateway de entrada. Em seguida, confirme se cada bloco é um certificado de CA, em que MCP_TRUST_CA_FILE é esse arquivo:openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
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
...-
Recrie o arquivo de certificado de CA (MCP_TRUST_CA_FILE) para que ele contenha apenas o certificado de CA (ou cadeia) que assinou o certificado do gateway de entrada. Em seguida, confirme se cada bloco é um certificado de CA:
openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
Atualize o secret do certificado de CA no local, em que MCP_CLIENT_SECRET_NAME é o valor de
mcpMtls.sslSecret, o secret do certificado de CA é esse nome com-cacertanexado e MCP_TRUST_CA_FILE é o arquivo de certificado de CA: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 -
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.caCertPathou na entradacacertdo secret para o host virtual afetado.