Certificado de CA de mTLS do MCP inválido

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 found
  • secret has no usable "cacert" entry

Resolução

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp-cacert.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (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
...
  1. Verifique se o secret existe e tem uma entrada cacert, em que MCP_CA_SECRET_NAME é o secret nomeado em Spec.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.caCertPath existe e não está vazio. A próxima etapa restaura o secret a partir dele. Se você pretende executar sem validação de cadeia, defina mcpMtls.disableChainValidation: true e remova mcpMtls.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.

  2. 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
...
  1. 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 por mcpMtls.sslSecret:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template não verifica se os secrets existem. Somente helm install e helm upgrade fazem isso. Portanto, uma execução limpa de helm template não é evidência de que esse secret está presente. Se você pretende executar sem validação de cadeia, omitir o secret não é suficiente. Defina mcpMtls.disableChainValidation: true em overrides.yaml e faça upgrade do host virtual. Isso desativa a verificação do certificado do gateway de entrada pelo plano de dados do MCP.

  2. 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 -cacert anexado 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 certificate
  • holds N trailing bytes that are not PEM

Resolução

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp-cacert.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (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
...
  1. Valide o conteúdo do arquivo referenciado por mcpMtls.caCertPath 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-----
  2. 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
...
  1. Valide o conteúdo do arquivo de certificado de CA (MCP_TRUST_CA_FILE) armazenado na entrada cacert do 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-----
  2. 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 -cacert anexado 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

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-ca-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp-cacert.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (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
...
  1. Recrie o arquivo referenciado por mcpMtls.caCertPath 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, 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
  2. 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
...
  1. 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
  2. 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 -cacert anexado 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:

  1. O ID do projeto do Google Cloud .
  2. O nome da organização da Apigee híbrida.
  3. O campo Spec.Details do ApigeeIssue.
  4. (Opcional) O certificado no arquivo referenciado por mcpMtls.caCertPath ou na entrada cacert do secret para o host virtual afetado.