本页面适用于 Apigee Hybrid,但不适用于 Apigee。
此主题没有等效的 Apigee Edge 文档。
症状
查看 apigee 命名空间中的资源时,系统会显示 Reason 为 AIS_MCP_MTLS_CLIENT_CERT_INVALID 的 ApigeeIssue。
错误消息
运行 kubectl -n apigee get apigeeissues 后,系统会显示如下错误:
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
可能的原因
下表列出了此问题的可能原因:
| 原因 | 说明 |
|---|---|
| MCP mTLS 客户端证书 Secret 或条目缺失 |
mcpMtls 命名的 Secret 不存在,或者没有可用的 cert 或 key 条目。
|
| MCP mTLS 客户端证书或密钥格式不正确 |
cert 条目未采用 PEM 编码,或 key 条目不是匹配的私钥。
|
| MCP mTLS 客户端证书省略了 clientAuth 扩展密钥用途 |
证书已解析,但其扩展密钥用途不包含 clientAuth。
|
原因:缺少 MCP mTLS 客户端证书 Secret 或条目
应包含 MCP mTLS 客户端证书的 Kubernetes Secret 不存在于 apigee 命名空间中,或者存在但没有非空 cert 条目或没有 key 条目。MCP 数据平面没有可为此环境组提供的客户端证书,因此对该组的 MCP 工具调用会在 TLS 握手时失败。
诊断
运行以下命令:
kubectl -n apigee describe apigeeissue ISSUE_NAME
将 ISSUE_NAME 替换为问题的名称,例如 mcp-client-cert-invalid-my-org-my-virtualhost。
输出应类似如下所示:
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
Spec.Details 的内容会指明 Secret、ApigeeRouteConfig 以及错误。例如:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
解决方法
-
使用
kubectl describe显示问题所属的 Kubernetes Secret 和ApigeeRouteConfig的名称:kubectl -n apigee describe apigeeissue ISSUE_NAME
将
ISSUE_NAME替换为问题的名称,例如mcp-client-cert-invalid-my-org-my-virtualhost。在此示例中,
ApigeeRouteConfigmy-org-my-virtualhost引用了 Secretmy-org-my-virtualhost-mcp。 -
根据
ApigeeRouteConfig确定virtualhost名称。ApigeeRouteConfig的名称采用以下格式:<Apigee organization>-<virtualhost name>。在此示例中,
my-org是 Apigee 组织,虚拟主机名为my-virtualhost。 -
在
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
...-
检查该 Secret 是否存在且包含两个条目,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中命名的 Secret。Data部分必须列出cert和key:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
如果密钥缺失或缺少条目,请确保
mcpMtls.sslCertPath和mcpMtls.sslKeyPath引用的文件存在且不为空。下一步会从中恢复 Secret。 -
升级虚拟主机,以便图表重写 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
...-
确认该 Secret 存在且包含这两个条目,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中命名的 Secret。Data部分必须列出cert和key。检查mcpMtls.sslSecret中的名称是否与您创建的 Secret 匹配,以及该 Secret 是否位于apigee命名空间中: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 template不会检查 Secret 是否存在;只有helm install和helm upgrade会检查,因此helm template运行成功并不能证明此 Secret 存在。 -
使用证书及其私钥一起创建或更新 Secret,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中命名的 Secret,MCP_CLIENT_CERT_FILE 和 MCP_CLIENT_KEY_FILE 是证书及其私钥: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 -
MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。
原因:MCP mTLS 客户端证书或密钥格式不正确
cert 条目不包含 PEM 编码的 X.509 证书,或者 key 条目未采用 PEM 编码,或者不是该证书的私钥。MCP 数据平面无法加载该对。
诊断
运行以下命令:
kubectl -n apigee describe apigeeissue ISSUE_NAME
将 ISSUE_NAME 替换为问题的名称,例如 mcp-client-cert-invalid-my-org-my-virtualhost。
输出应类似如下所示:
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
Spec.Details 的内容会指明 Secret、ApigeeRouteConfig 以及错误。例如:
-
entry holds no PEM encoded certificate:cert条目不是 PEM。 -
tls: failed to find any PEM data in key input:key条目不是 PEM。 -
tls: private key does not match public key:cert和key条目不配对。 -
tls: failed to parse private key:密钥无法解析,通常是因为它已加密。key条目必须是未加密的 PEM 私钥。
解决方法
-
使用
kubectl describe显示问题所属的 Kubernetes Secret 和ApigeeRouteConfig的名称:kubectl -n apigee describe apigeeissue ISSUE_NAME
将
ISSUE_NAME替换为问题的名称,例如mcp-client-cert-invalid-my-org-my-virtualhost。在此示例中,
ApigeeRouteConfigmy-org-my-virtualhost引用了 Secretmy-org-my-virtualhost-mcp。 -
根据
ApigeeRouteConfig确定virtualhost名称。ApigeeRouteConfig的名称采用以下格式:<Apigee organization>-<virtualhost name>。在此示例中,
my-org是 Apigee 组织,虚拟主机名为my-virtualhost。 -
在
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
...-
验证
mcpMtls.sslCertPath和mcpMtls.sslKeyPath引用的证书文件和密钥文件,并根据需要进行更正。证书必须包含起始和结束证书行,并且密钥必须是其私钥。例如:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
升级虚拟主机,以便图表重写 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
...-
验证您存储在 Secret 的
cert和key条目中的证书文件 (MCP_CLIENT_CERT_FILE) 和密钥文件 (MCP_CLIENT_KEY_FILE),并根据需要进行更正。证书必须包含起始和结束证书行,并且密钥必须是其私钥。例如:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
将证书及其私钥一起就地更新 Secret,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中命名的 Secret,MCP_CLIENT_CERT_FILE 和 MCP_CLIENT_KEY_FILE 是证书及其私钥: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 -
MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。
原因:MCP mTLS 客户端证书省略了 clientAuth 扩展密钥用途
证书格式正确且与其密钥配对,但其扩展密钥用途 (EKU) 不包含 clientAuth,因此无法用于客户端身份验证,并且 MCP 数据平面不会显示该证书。当重复使用服务器证书或不再颁发 clientAuth 的公共 CA 配置文件中的证书时,通常会出现这种情况。
诊断
运行以下命令:
kubectl -n apigee describe apigeeissue ISSUE_NAME
将 ISSUE_NAME 替换为问题的名称,例如 mcp-client-cert-invalid-my-org-my-virtualhost。
输出应类似如下所示:
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
Spec.Details 的内容会命名 Secret 和 ApigeeRouteConfig,并列出证书确实具有的扩展密钥用途。
解决方法
-
使用
kubectl describe显示问题所属的 Kubernetes Secret 和ApigeeRouteConfig的名称:kubectl -n apigee describe apigeeissue ISSUE_NAME
将
ISSUE_NAME替换为问题的名称,例如mcp-client-cert-invalid-my-org-my-virtualhost。在此示例中,
ApigeeRouteConfigmy-org-my-virtualhost引用了 Secretmy-org-my-virtualhost-mcp。 -
根据
ApigeeRouteConfig确定virtualhost名称。ApigeeRouteConfig的名称采用以下格式:<Apigee organization>-<virtualhost name>。在此示例中,
my-org是 Apigee 组织,虚拟主机名为my-virtualhost。 -
在
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
...-
使用包含
clientAuth扩展密钥用途的配置文件,从您的私有 CA 重新颁发客户端证书。确认该证书(其中 MCP_CLIENT_CERT_FILE 是重新签发的证书),然后替换mcpMtls.sslCertPath和mcpMtls.sslKeyPath引用的文件:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
升级虚拟主机,以便图表重写 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
...-
使用包含
clientAuth扩展密钥用途的配置文件,从您的私有 CA 重新颁发客户端证书。在更新 Secret 之前,请确认该 Secret,其中 MCP_CLIENT_CERT_FILE 是重新颁发的证书:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
将证书及其私钥一起就地更新 Secret,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中命名的 Secret,MCP_CLIENT_CERT_FILE 和 MCP_CLIENT_KEY_FILE 是证书及其私钥: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 -
MCP 数据平面会在下次定期刷新时(通常在几分钟内)获取更正后的 Secret,而无需重启 Pod,并且 ApigeeIssue 会在下次扫描时撤消。
必须收集的诊断信息
如果按照上述说明操作后问题仍然存在,请收集以下诊断信息,然后与 Google Cloud Customer Care 联系:
- Google Cloud 项目 ID。
- Apigee Hybrid 组织的名称。
ApigeeIssue的Spec.Details字段。-
(可选)受影响虚拟主机的证书,位于
mcpMtls.sslCertPath引用的文件中,或位于 Secret 的cert条目中。