本頁面適用於 Apigee Hybrid,但不適用於 Apigee。
這個主題沒有對應的 Apigee Edge 說明文件。
問題
查看 apigee 命名空間中的資源時,會顯示含有 Reason AIS_MCP_MTLS_CA_CERT_INVALID 的 ApigeeIssue。
只有在環境群組的 mcpMtls 區塊啟用鏈結驗證 (預設) 時,才會發生這個問題。對於具有 mcpMtls.disableChainValidation: true 的群組,MCP 資料層不會使用 CA 憑證,也不會掃描 -cacert 密鑰。
錯誤訊息
執行 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 憑證密鑰或項目 |
-cacert 密鑰不存在,或沒有可用的 cacert 項目。 |
| MCP mTLS CA 憑證未採用 PEM 編碼 |
cacert 項目不含 PEM 憑證區塊,或包含 PEM 區塊以外的位元組。 |
| MCP mTLS CA 憑證格式錯誤或不是 CA 憑證 |
cacert 項目中的區塊不是憑證、無法剖析,或不是 CA 憑證。
|
原因:缺少 MCP mTLS CA 憑證密鑰或項目
Kubernetes 密鑰應包含 CA 憑證,MCP 資料層會根據該憑證驗證輸入閘道,但該密鑰不存在於 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 的內容會指出密鑰名稱、ApigeeRouteConfig 和錯誤。例如:
secret not foundsecret has no usable "cacert" entry
解析度
-
使用
kubectl describe顯示 Kubernetes 密鑰的名稱,並使用ApigeeRouteConfig顯示問題所屬的命名空間:kubectl -n apigee describe apigeeissue ISSUE_NAME
將
ISSUE_NAME替換為問題名稱,例如mcp-ca-cert-invalid-my-org-my-virtualhost。在本範例中,
ApigeeRouteConfigmy-org-my-virtualhost參照的是 Secretmy-org-my-virtualhost-mcp-cacert。 -
從
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
...-
檢查密鑰是否存在,且具有
cacert項目,其中 MCP_CA_SECRET_NAME 是Spec.Details中指定的密鑰:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
如果缺少密鑰或項目,請確認
mcpMtls.caCertPath參照的檔案存在且不為空白。下一步是從中還原密鑰。如要執行不含鏈結驗證的作業,請設定mcpMtls.disableChainValidation: true並移除mcpMtls.caCertPath(圖表會同時拒絕這兩項)。請注意,這會停用 MCP 資料層對 ingress 閘道憑證的驗證。 -
升級虛擬主機,讓圖表重寫密鑰:
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
...-
確認密鑰確實存在,且名稱與
cacert項目完全相同,其中 MCP_CLIENT_SECRET_NAME 是由mcpMtls.sslSecret命名的用戶端憑證密鑰: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 資料層對 ingress 閘道憑證的驗證。 -
建立或更新 CA 憑證密鑰,其中 MCP_CLIENT_SECRET_NAME 是
mcpMtls.sslSecret的值,CA 憑證密鑰是附加-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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 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 的內容會指出密鑰名稱、ApigeeRouteConfig 和錯誤。例如:
entry holds no PEM encoded certificateholds N trailing bytes that are not PEM
解析度
-
使用
kubectl describe顯示 Kubernetes 密鑰的名稱,並使用ApigeeRouteConfig顯示問題所屬的命名空間:kubectl -n apigee describe apigeeissue ISSUE_NAME
將
ISSUE_NAME替換為問題名稱,例如mcp-ca-cert-invalid-my-org-my-virtualhost。在本範例中,
ApigeeRouteConfigmy-org-my-virtualhost參照的是 Secretmy-org-my-virtualhost-mcp-cacert。 -
從
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.caCertPath參照的檔案內容,並視需要修正。請確認內容僅包含完整的憑證區塊,且每個區塊都有起始行和結束行。例如:-----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
...-
驗證儲存在 Secret
cacert項目中的 CA 憑證檔案 (MCP_TRUST_CA_FILE) 內容,並視需要修正。請確認內容僅包含完整的憑證區塊,且每個區塊都有起始行和結束行。例如:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
就地更新 CA 憑證密鑰,其中 MCP_CLIENT_SECRET_NAME 是
mcpMtls.sslSecret的值,CA 憑證密鑰是附加-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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 Pod,且 ApigeeIssue 會在下次掃描時撤回。
原因:MCP mTLS CA 憑證格式錯誤,或不是 CA 憑證
cacert 項目中的每個 PEM 區塊都必須是 CERTIFICATE 區塊,可剖析且具有 CA 基本限制。私密金鑰區塊、分葉憑證 (例如 ingress 閘道本身的伺服器憑證) 或損毀的區塊會導致項目無法使用,且 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 的內容會指出密鑰名稱、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 開始。
解析度
-
使用
kubectl describe顯示 Kubernetes 密鑰的名稱,並使用ApigeeRouteConfig顯示問題所屬的命名空間:kubectl -n apigee describe apigeeissue ISSUE_NAME
將
ISSUE_NAME替換為問題名稱,例如mcp-ca-cert-invalid-my-org-my-virtualhost。在本範例中,
ApigeeRouteConfigmy-org-my-virtualhost參照的是 Secretmy-org-my-virtualhost-mcp-cacert。 -
從
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.caCertPath參照的檔案,使其僅保留簽署 ingress 閘道憑證的 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
-
升級虛擬主機,讓圖表重寫密鑰:
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
...-
重建 CA 憑證檔案 (MCP_TRUST_CA_FILE),使其僅保留簽署 ingress 閘道憑證的 CA 憑證 (或鏈結)。接著,確認每個區塊都是 CA 憑證:
openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:' # every certificate must show CA:TRUE
-
就地更新 CA 憑證密鑰,其中 MCP_CLIENT_SECRET_NAME 是
mcpMtls.sslSecret的值,CA 憑證密鑰是附加-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 資料層會在下次定期重新整理時 (通常在幾分鐘內) 擷取修正後的密鑰,不需重新啟動 Pod,且 ApigeeIssue 會在下次掃描時撤回。
必須收集診斷資訊
如果按照上述操作說明操作後,問題仍未解決,請收集下列診斷資訊,然後與 Google Cloud Customer Care 聯絡:
- Google Cloud 專案 ID。
- Apigee Hybrid 組織的名稱。
ApigeeIssue的Spec.Details欄位。-
(選用) 受影響虛擬主機的憑證,位於
mcpMtls.caCertPath參照的檔案中,或密鑰的cacert項目中。