本頁面適用於 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 用戶端憑證密鑰或項目 |
名為 mcpMtls 的密鑰不存在,或沒有可用的 cert 或 key 項目。 |
| MCP mTLS 用戶端憑證或金鑰格式不正確 |
cert 項目未採用 PEM 編碼,或 key 項目不是相符的私密金鑰。 |
| MCP mTLS 用戶端憑證省略 clientAuth 擴充金鑰用途 |
憑證剖析,但其擴充金鑰用途不包含 clientAuth。 |
原因:缺少 MCP mTLS 用戶端憑證密鑰或項目
apigee 命名空間中沒有應保存 MCP mTLS 用戶端憑證的 Kubernetes 密鑰,或該密鑰存在,但沒有非空白的 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 的內容會指出密鑰名稱、ApigeeRouteConfig 和錯誤。例如:
secret not foundsecret has no usable "cert" entrysecret has no "key" entry
解析度
-
使用
kubectl describe顯示 Kubernetes 密鑰的名稱,並使用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) 時,虛擬主機圖表會根據檔案內容建立及管理密鑰。
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
...-
請檢查密鑰是否存在且包含這兩個項目,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中指定的密鑰名稱。Data區段必須列出cert和key:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
如果缺少密鑰或項目,請確認
mcpMtls.sslCertPath和mcpMtls.sslKeyPath參照的檔案存在且不為空白。下一步是從中還原 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
...-
確認密鑰存在且包含這兩個項目,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中指定的密鑰名稱。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不會檢查密鑰是否存在,只有helm install和helm upgrade會檢查,因此helm template執行成功不代表密鑰存在。 -
使用憑證及其私密金鑰建立或更新密鑰,其中 MCP_CLIENT_SECRET_NAME 是
Spec.Details中指定的密鑰,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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 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 的內容會指出密鑰名稱、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 密鑰的名稱,並使用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) 時,虛擬主機圖表會根據檔案內容建立及管理密鑰。
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-----
-
升級虛擬主機,讓圖表重寫密鑰:
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
...-
驗證您儲存在密鑰
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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 Pod,且 ApigeeIssue 會在下次掃描時撤回。
原因:MCP mTLS 用戶端憑證省略 clientAuth 擴充金鑰用途
憑證格式正確,且與金鑰配對,但擴充金鑰用途 (EKU) 不包含 clientAuth,因此無法用於用戶端驗證,MCP 資料層也不會顯示該憑證。如果重複使用伺服器憑證,或公開 CA 設定檔中不再核發 clientAuth 的憑證,通常就會發生這種情況。
診斷
請執行下列指令:
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 密鑰的名稱,並使用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) 時,虛擬主機圖表會根據檔案內容建立及管理密鑰。
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
-
升級虛擬主機,讓圖表重寫密鑰:
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 重新核發用戶端憑證。請先確認這項資訊,再更新密鑰 (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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 Pod,且 ApigeeIssue 會在下次掃描時撤回。
必須收集診斷資訊
如果按照上述操作說明操作後,問題仍未解決,請收集下列診斷資訊,然後與 Google Cloud Customer Care 聯絡:
- Google Cloud 專案 ID。
- Apigee Hybrid 組織的名稱。
ApigeeIssue的Spec.Details欄位。-
(選用) 受影響虛擬主機的憑證,位於
mcpMtls.sslCertPath參照的檔案中,或密鑰的cert項目中。