MCP mTLS CA 证书无效

本页面适用于 Apigee Hybrid,但不适用于 Apigee。

此主题没有等效的 Apigee Edge 文档。

症状

查看 apigee 命名空间中的资源时,系统会显示 Reason 为 AIS_MCP_MTLS_CA_CERT_INVALID 的 ApigeeIssue。

只有在环境组的 mcpMtls 块启用了链验证(默认)时,才会出现此问题。对于具有 mcpMtls.disableChainValidation: true 的组,MCP 数据平面不使用 CA 证书,并且不会扫描 -cacert Secret。

错误消息

运行 kubectl -n apigee get apigeeissues 后,系统会显示如下错误:

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

可能的原因

下表列出了此问题的可能原因:

原因 说明
MCP mTLS CA 证书 Secret 或条目缺失 -cacert 密钥不存在,或者没有可用的 cacert 条目。
MCP mTLS CA 证书未采用 PEM 编码 cacert 条目不包含 PEM 证书块,或包含 PEM 块之外的字节。
MCP mTLS CA 证书格式不正确或不是 CA 证书 cacert 条目中的块不是证书、无法解析或不是 CA 证书。

原因:MCP mTLS CA 证书 Secret 或条目缺失

MCP 数据平面用于验证入站网关的 CA 证书应存储在 Kubernetes Secret 中,但该 Secret 在 apigee 命名空间中不存在,或者存在但没有非空的 cacert 条目。其名称是客户端证书 Secret 的名称,后跟 -cacert。仅当您使用证书文件时,该图表才会创建此 Secret;使用 sslSecret 时,您必须自行创建,而忘记创建是导致此问题的最常见原因。

诊断

运行以下命令:

kubectl -n apigee describe apigeeissue ISSUE_NAME

将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

输出应类似如下所示:

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

Spec.Details 的内容会指明 Secret、ApigeeRouteConfig 以及错误。例如:

  • secret not found
  • secret has no usable "cacert" entry

解决方法

  1. 使用 kubectl describe 显示问题所属的 Kubernetes Secret 和 ApigeeRouteConfig 的名称:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

    在此示例中,ApigeeRouteConfig my-org-my-virtualhost 引用了 Secret my-org-my-virtualhost-mcp-cacert。

  2. 根据 ApigeeRouteConfig 确定 virtualhost 名称。

    ApigeeRouteConfig 的名称采用以下格式:<Apigee organization>-<virtualhost name>。

    在此示例中,my-org 是 Apigee 组织,虚拟主机名为 my-virtualhost。

  3. 在 overrides.yaml 中找到相应的虚拟主机,并检查其 mcpMtls 块使用的形式(请参阅在 MCP 数据平面和入站流量网关之间配置 mTLS)。选择匹配的标签页,然后按照该标签页中的步骤操作。

证书文件

当您使用文件路径(sslCertPath、sslKeyPath、caCertPath)时,virtualhost 图表会根据文件内容创建和管理 Secret。

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. 检查该 Secret 是否存在且具有 cacert 条目,其中 MCP_CA_SECRET_NAME 是 Spec.Details 中命名的 Secret:

    kubectl -n apigee describe secret MCP_CA_SECRET_NAME

    如果密钥缺失或缺少条目,请确保 mcpMtls.caCertPath 引用的文件存在且不为空。下一步将从中恢复 Secret。如果您打算在不进行链验证的情况下运行,请设置 mcpMtls.disableChainValidation: true 并移除 mcpMtls.caCertPath(图表会同时拒绝这两者)。请注意,这会关闭 MCP 数据平面验证入站流量网关证书的功能。

  2. 升级虚拟主机,以便图表重写 Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes Secret

当您使用 Kubernetes Secret 引用 (sslSecret) 时,MCP 数据平面会直接从您创建的 Secret 中读取证书值,并自动应用更新。无需 helm upgrade。

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. 确认该 Secret 确实存在,且名称与 cacert 条目完全一致,其中 MCP_CLIENT_SECRET_NAME 是由 mcpMtls.sslSecret 命名的客户端证书 Secret:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template 不会检查 Secret 是否存在;只有 helm install 和 helm upgrade 会检查,因此 helm template 运行成功并不能证明此 Secret 存在。如果您打算在不进行链验证的情况下运行,仅省略密钥是不够的。 在 overrides.yaml 中设置 mcpMtls.disableChainValidation: true,并升级虚拟主机。请注意,这会关闭 MCP 数据平面验证入站流量网关证书的功能。

  2. 创建或更新 CA 证书 Secret,其中 MCP_CLIENT_SECRET_NAME 是 mcpMtls.sslSecret 的值,CA 证书 Secret 是该名称附加 -cacert,MCP_TRUST_CA_FILE 是 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 -

MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。

原因:MCP mTLS CA 证书未采用 PEM 编码

cacert 条目缺少 PEM 编码文本块,或者在最后一个 -----END CERTIFICATE----- 行之后有非 PEM 内容。MCP 数据平面不会加载它。

诊断

运行以下命令:

kubectl -n apigee describe apigeeissue ISSUE_NAME

将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

输出应类似如下所示:

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

Spec.Details 的内容会指明 Secret、ApigeeRouteConfig 以及错误。例如:

  • entry holds no PEM encoded certificate
  • holds N trailing bytes that are not PEM

解决方法

  1. 使用 kubectl describe 显示问题所属的 Kubernetes Secret 和 ApigeeRouteConfig 的名称:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

    在此示例中,ApigeeRouteConfig my-org-my-virtualhost 引用了 Secret my-org-my-virtualhost-mcp-cacert。

  2. 根据 ApigeeRouteConfig 确定 virtualhost 名称。

    ApigeeRouteConfig 的名称采用以下格式:<Apigee organization>-<virtualhost name>。

    在此示例中,my-org 是 Apigee 组织,虚拟主机名为 my-virtualhost。

  3. 在 overrides.yaml 中找到相应的虚拟主机,并检查其 mcpMtls 块使用的形式(请参阅在 MCP 数据平面和入站流量网关之间配置 mTLS)。选择匹配的标签页,然后按照该标签页中的步骤操作。

证书文件

当您使用文件路径(sslCertPath、sslKeyPath、caCertPath)时,virtualhost 图表会根据文件内容创建和管理 Secret。

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. 验证 mcpMtls.caCertPath 引用的文件的内容,并根据需要进行更正。确保内容仅包含完整的证书块,每个证书块都有起始行和结束行。例如:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. 升级虚拟主机,以便图表重写 Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes Secret

当您使用 Kubernetes Secret 引用 (sslSecret) 时,MCP 数据平面会直接从您创建的 Secret 中读取证书值,并自动应用更新。无需 helm upgrade。

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. 验证您存储在 Secret 的 cacert 条目中的 CA 证书文件 (MCP_TRUST_CA_FILE) 的内容,并根据需要进行更正。确保内容仅包含完整的证书块,每个证书块都有起始行和结束行。例如:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. 就地更新 CA 证书 Secret,其中 MCP_CLIENT_SECRET_NAME 是 mcpMtls.sslSecret 的值,CA 证书 Secret 是该名称附加 -cacert,MCP_TRUST_CA_FILE 是 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 -

MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。

原因:MCP mTLS CA 证书格式不正确或不是 CA 证书

cacert 条目中的每个 PEM 块都必须是可解析且具有 CA 基本限制条件的 CERTIFICATE 块。私钥块、叶证书(例如入站流量网关自己的服务器证书)或损坏的块会使条目无法使用,并且 MCP 数据平面不会加载该条目。

诊断

运行以下命令:

kubectl -n apigee describe apigeeissue ISSUE_NAME

将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

输出应类似如下所示:

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

Spec.Details 的内容会指明 Secret、ApigeeRouteConfig 以及错误。例如:

  • no PEM block parsed as a certificate: ...:无法解析任何证书块(例如,唯一的证书已损坏)。
  • block N is a "..." block, want CERTIFICATE:块 N 不是证书(例如,私钥)。
  • block N does not parse:块 N 是损坏的证书。
  • block N is not a CA certificate:块 N 是证书,但不是 CA(例如,叶证书)。

块从 0 开始编号。

解决方法

  1. 使用 kubectl describe 显示问题所属的 Kubernetes Secret 和 ApigeeRouteConfig 的名称:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    将 ISSUE_NAME 替换为问题的名称,例如 mcp-ca-cert-invalid-my-org-my-virtualhost。

    在此示例中,ApigeeRouteConfig my-org-my-virtualhost 引用了 Secret my-org-my-virtualhost-mcp-cacert。

  2. 根据 ApigeeRouteConfig 确定 virtualhost 名称。

    ApigeeRouteConfig 的名称采用以下格式:<Apigee organization>-<virtualhost name>。

    在此示例中,my-org 是 Apigee 组织,虚拟主机名为 my-virtualhost。

  3. 在 overrides.yaml 中找到相应的虚拟主机,并检查其 mcpMtls 块使用的形式(请参阅在 MCP 数据平面和入站流量网关之间配置 mTLS)。选择匹配的标签页,然后按照该标签页中的步骤操作。

证书文件

当您使用文件路径(sslCertPath、sslKeyPath、caCertPath)时,virtualhost 图表会根据文件内容创建和管理 Secret。

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. 重新构建 mcpMtls.caCertPath 引用的文件,使其仅包含对入站网关证书进行签名的 CA 证书(或链)。然后确认每个块都是 CA 证书,其中 MCP_TRUST_CA_FILE 是该文件:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. 升级虚拟主机,以便图表重写 Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes Secret

当您使用 Kubernetes Secret 引用 (sslSecret) 时,MCP 数据平面会直接从您创建的 Secret 中读取证书值,并自动应用更新。无需 helm upgrade。

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. 重新构建 CA 证书文件 (MCP_TRUST_CA_FILE),使其仅包含对入站流量网关证书进行签名的 CA 证书(或链)。然后确认每个块都是 CA 证书:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. 就地更新 CA 证书 Secret,其中 MCP_CLIENT_SECRET_NAME 是 mcpMtls.sslSecret 的值,CA 证书 Secret 是该名称附加 -cacert,MCP_TRUST_CA_FILE 是 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 -

MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。

必须收集的诊断信息

如果按照上述说明操作后问题仍然存在,请收集以下诊断信息,然后与 Google Cloud Customer Care 联系:

  1. Google Cloud 项目 ID。
  2. Apigee Hybrid 组织的名称。
  3. ApigeeIssue 的 Spec.Details 字段。
  4. (可选)受影响虚拟主机的证书,位于 mcpMtls.caCertPath 引用的文件中,或位于 Secret 的 cacert 条目中。