このページの内容は Apigee ハイブリッドに適用されます。Apigee には適用されません。
このトピックに対応する Apigee Edge のドキュメントはありません。
症状
apigee Namespace のリソースを表示したときに、ApigeeIssue(Reason = AIS_MCP_MTLS_CLIENT_CERT_INVALID)が表示されます。
エラー メッセージ
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 で指定されたシークレットが存在しないか、使用可能な cert エントリまたは key エントリがありません。 |
| MCP mTLS クライアント証明書または鍵が不正な形式である |
cert エントリが PEM エンコードされていないか、key エントリが一致する秘密鍵ではありません。 |
| MCP mTLS クライアント証明書で clientAuth 拡張鍵の使用が省略されている |
証明書は解析されますが、拡張鍵の使用に clientAuth が含まれていません。 |
原因: MCP mTLS クライアント証明書の Secret またはエントリがない
MCP mTLS クライアント証明書を保持する Kubernetes Secret が apigee Namespace に存在しないか、空でない cert エントリまたは key エントリなしで存在しています。MCP データプレーンには、この環境グループに提示するクライアント証明書がないため、グループへの MCP ツール呼び出しは TLS handshake で失敗します。
診断
次のコマンドを実行します。
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>の形式になっています。この例では、Apigee 組織は
my-orgで、仮想ホスト名はmy-virtualhostです。 -
overrides.yamlで対応する仮想ホストを探し、mcpMtlsブロックで使用されている形式を確認します(MCP データプレーンと Ingress ゲートウェイ間の 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
Secret がないか、エントリがない場合は、
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
...-
Secret が存在し、両方のエントリがあることを確認します。ここで、MCP_CLIENT_SECRET_NAME は
Spec.Detailsで指定された Secret です。Dataセクションには、certとkeyを記述する必要があります。mcpMtls.sslSecretの名前が作成した Secret と一致し、Secret がapigeeNamespace にあることを確認します。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が正常に実行されたことは、このシークレットが存在することの証拠にはなりません。 -
証明書とその秘密鍵を一緒に使用して 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 を再起動することなく、次の定期的な更新で修正された Secret を取得します。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>の形式になっています。この例では、Apigee 組織は
my-orgで、仮想ホスト名はmy-virtualhostです。 -
overrides.yamlで対応する仮想ホストを探し、mcpMtlsブロックで使用されている形式を確認します(MCP データプレーンと Ingress ゲートウェイ間の 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 データプレーンは、通常数分以内に、Pod を再起動することなく、次の定期的な更新で修正された Secret を取得します。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>の形式になっています。この例では、Apigee 組織は
my-orgで、仮想ホスト名はmy-virtualhostです。 -
overrides.yamlで対応する仮想ホストを探し、mcpMtlsブロックで使用されている形式を確認します(MCP データプレーンと Ingress ゲートウェイ間の 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 からクライアント証明書を再発行します。シークレットを更新する前に確認します。ここで、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 を再起動することなく、次の定期的な更新で修正された Secret を取得します。ApigeeIssue は次のスキャンで取り消されます。
診断情報の収集が必要な場合
上記の手順でも問題が解決しない場合は、次の診断情報を収集して Google Cloud カスタマーケアに連絡してください。
- Google Cloud プロジェクト ID
- Apigee ハイブリッド組織の名前。
ApigeeIssueのSpec.Detailsフィールド。-
(省略可)影響を受ける仮想ホストの
mcpMtls.sslCertPathによって参照されているファイル内の証明書、またはシークレットのcertエントリ内の証明書。