MCP mTLS クライアント証明書が無効

このページの内容は 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 found
  • secret has no usable "cert" entry
  • secret has no "key" entry

解決策

  1. kubectl describe を使用して、Kubernetes Secret の名前と、問題が属する ApigeeRouteConfig を表示します。

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME は、問題の名前(mcp-client-cert-invalid-my-org-my-virtualhost など)に置き換えます。

    この例では、ApigeeRouteConfig my-org-my-virtualhost が Secret my-org-my-virtualhost-mcp を参照しています。

  2. ApigeeRouteConfig から virtualhost の名前を特定します。

    ApigeeRouteConfig の名前は <Apigee organization>-<virtualhost name> の形式になっています。

    この例では、Apigee 組織は my-org で、仮想ホスト名は my-virtualhost です。

  3. 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
...
  1. 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 で参照されているファイルが存在し、空でないことを確認します。次のステップでは、それらからシークレットを復元します。

  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 が存在し、両方のエントリがあることを確認します。ここで、MCP_CLIENT_SECRET_NAME は Spec.Details で指定された Secret です。Data セクションには、cert と key を記述する必要があります。mcpMtls.sslSecret の名前が作成した Secret と一致し、Secret が apigee Namespace にあることを確認します。

    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 が正常に実行されたことは、このシークレットが存在することの証拠にはなりません。

  2. 証明書とその秘密鍵を一緒に使用して 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 秘密鍵にする必要があります。

解決策

  1. kubectl describe を使用して、Kubernetes Secret の名前と、問題が属する ApigeeRouteConfig を表示します。

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME は、問題の名前(mcp-client-cert-invalid-my-org-my-virtualhost など)に置き換えます。

    この例では、ApigeeRouteConfig my-org-my-virtualhost が Secret my-org-my-virtualhost-mcp を参照しています。

  2. ApigeeRouteConfig から virtualhost の名前を特定します。

    ApigeeRouteConfig の名前は <Apigee organization>-<virtualhost name> の形式になっています。

    この例では、Apigee 組織は my-org で、仮想ホスト名は my-virtualhost です。

  3. 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
...
  1. mcpMtls.sslCertPath と mcpMtls.sslKeyPath で参照されている証明書ファイルと鍵ファイルを検証し、必要に応じて修正します。証明書には、証明書の開始行と終了行が含まれている必要があります。また、鍵は証明書の秘密鍵である必要があります。次に例を示します。

    -----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 の cert エントリと key エントリに保存されている証明書ファイル(MCP_CLIENT_CERT_FILE)と鍵ファイル(MCP_CLIENT_KEY_FILE)を検証し、必要に応じて修正します。証明書には開始証明書行と終了証明書行が含まれている必要があります。鍵は、その証明書の秘密鍵である必要があります。次に例を示します。

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. 証明書とその秘密鍵を一緒に使用して、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 の名前を指定し、証明書が持つ拡張鍵の使用方法を一覧表示します。

解決策

  1. kubectl describe を使用して、Kubernetes Secret の名前と、問題が属する ApigeeRouteConfig を表示します。

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME は、問題の名前(mcp-client-cert-invalid-my-org-my-virtualhost など)に置き換えます。

    この例では、ApigeeRouteConfig my-org-my-virtualhost が Secret my-org-my-virtualhost-mcp を参照しています。

  2. ApigeeRouteConfig から virtualhost の名前を特定します。

    ApigeeRouteConfig の名前は <Apigee organization>-<virtualhost name> の形式になっています。

    この例では、Apigee 組織は my-org で、仮想ホスト名は my-virtualhost です。

  3. 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
...
  1. 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
  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. clientAuth 拡張鍵用途を含むプロファイルを使用して、プライベート CA からクライアント証明書を再発行します。シークレットを更新する前に確認します。ここで、MCP_CLIENT_CERT_FILE は再発行された証明書です。

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. 証明書とその秘密鍵を一緒に使用して、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 カスタマーケアに連絡してください。

  1. Google Cloud プロジェクト ID
  2. Apigee ハイブリッド組織の名前。
  3. ApigeeIssue の Spec.Details フィールド。
  4. (省略可)影響を受ける仮想ホストの mcpMtls.sslCertPath によって参照されているファイル内の証明書、またはシークレットの cert エントリ内の証明書。