MCP mTLS 클라이언트 인증서가 잘못됨

이 페이지는 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 클라이언트 인증서 보안 비밀 또는 항목이 누락됨

MCP mTLS 클라이언트 인증서를 보유해야 하는 Kubernetes 보안 비밀이 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의 콘텐츠는 보안 비밀, ApigeeRouteConfig, 잘못된 항목의 이름을 지정합니다. 예를 들면 다음과 같습니다.

  • secret not found
  • secret has no usable "cert" entry
  • secret has no "key" entry

해결 방법

  1. kubectl describe를 사용하여 Kubernetes 보안 비밀의 이름과 문제가 속한 ApigeeRouteConfig를 표시합니다.

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME을 문제 이름(예: mcp-client-cert-invalid-my-org-my-virtualhost)으로 바꿉니다.

    이 예시에서 ApigeeRouteConfig my-org-my-virtualhost는 보안 비밀 my-org-my-virtualhost-mcp를 참조합니다.

  2. ApigeeRouteConfig에서 virtualhost 이름을 확인합니다.

    ApigeeRouteConfig의 이름은 <Apigee organization>-<virtualhost name> 형식입니다.

    이 예시에서 my-org는 Apigee 조직이고 virtualhost 이름은 my-virtualhost입니다.

  3. overrides.yaml에서 해당 virtualhost를 찾고 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
...
  1. 보안 비밀이 있고 두 항목이 모두 있는지 확인합니다. 여기서 MCP_CLIENT_SECRET_NAME는 Spec.Details에 이름이 지정된 보안 비밀입니다. Data 섹션에는 cert 및 key가 나열되어야 합니다.

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    보안 비밀이 누락되었거나 항목이 없는 경우 mcpMtls.sslCertPath 및 mcpMtls.sslKeyPath에서 참조하는 파일이 존재하고 비어 있지 않은지 확인합니다. 다음 단계에서는 이 백업에서 보안 비밀을 복원합니다.

  2. 차트가 보안 비밀을 다시 작성하도록 가상 호스트를 업그레이드합니다.

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes 보안 비밀

Kubernetes 보안 비밀 참조(sslSecret)를 사용하면 MCP 데이터 영역이 사용자가 만든 보안 비밀에서 인증서 값을 직접 읽고 업데이트가 자동으로 적용됩니다. helm upgrade는 필요하지 않습니다.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. 보안 비밀이 있고 두 항목이 모두 있는지 확인합니다. 여기서 MCP_CLIENT_SECRET_NAME은 Spec.Details에 이름이 지정된 보안 비밀입니다. Data 섹션에는 cert 및 key가 나열되어야 합니다. mcpMtls.sslSecret의 이름이 만든 보안 비밀과 일치하고 보안 비밀이 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 실행이 완료되었다고 해서 이 보안 비밀이 있다는 증거는 아닙니다.

  2. 인증서와 비공개 키를 함께 사용하여 보안 비밀을 만들거나 업데이트합니다. 여기서 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 데이터 영역은 포드를 다시 시작하지 않고도 다음 주기적 새로고침(일반적으로 몇 분 이내)에서 수정된 보안 비밀을 선택하고 다음 스캔에서 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 비공개 키여야 합니다.

해결 방법

  1. kubectl describe를 사용하여 Kubernetes 보안 비밀의 이름과 문제가 속한 ApigeeRouteConfig를 표시합니다.

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME을 문제 이름(예: mcp-client-cert-invalid-my-org-my-virtualhost)으로 바꿉니다.

    이 예시에서 ApigeeRouteConfig my-org-my-virtualhost는 보안 비밀 my-org-my-virtualhost-mcp를 참조합니다.

  2. ApigeeRouteConfig에서 virtualhost 이름을 확인합니다.

    ApigeeRouteConfig의 이름은 <Apigee organization>-<virtualhost name> 형식입니다.

    이 예시에서 my-org는 Apigee 조직이고 virtualhost 이름은 my-virtualhost입니다.

  3. overrides.yaml에서 해당 virtualhost를 찾고 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
...
  1. mcpMtls.sslCertPath 및 mcpMtls.sslKeyPath에서 참조하는 인증서 파일과 키 파일을 검증하고 필요한 경우 수정합니다. 인증서에는 시작 및 종료 인증서 줄이 포함되어야 하며 키는 이에 대한 비공개 키여야 합니다. 예를 들면 다음과 같습니다.

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. 차트가 보안 비밀을 다시 작성하도록 가상 호스트를 업그레이드합니다.

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes 보안 비밀

Kubernetes 보안 비밀 참조(sslSecret)를 사용하면 MCP 데이터 영역이 사용자가 만든 보안 비밀에서 인증서 값을 직접 읽고 업데이트가 자동으로 적용됩니다. helm upgrade는 필요하지 않습니다.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. 보안 비밀의 cert 및 key 항목에 저장하는 인증서 파일(MCP_CLIENT_CERT_FILE)과 키 파일(MCP_CLIENT_KEY_FILE)을 검증하고 필요한 경우 수정합니다. 인증서에는 시작 및 종료 인증서 줄이 포함되어야 하며 키는 인증서의 비공개 키여야 합니다. 예를 들면 다음과 같습니다.

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. 인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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 데이터 영역은 포드를 다시 시작하지 않고도 다음 주기적 새로고침(일반적으로 몇 분 이내)에서 수정된 보안 비밀을 선택하고 다음 스캔에서 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 콘텐츠는 보안 비밀과 ApigeeRouteConfig의 이름을 지정하고 인증서가 전달하는 확장 키 사용을 나열합니다.

해결 방법

  1. kubectl describe를 사용하여 Kubernetes 보안 비밀의 이름과 문제가 속한 ApigeeRouteConfig를 표시합니다.

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME을 문제 이름(예: mcp-client-cert-invalid-my-org-my-virtualhost)으로 바꿉니다.

    이 예시에서 ApigeeRouteConfig my-org-my-virtualhost는 보안 비밀 my-org-my-virtualhost-mcp를 참조합니다.

  2. ApigeeRouteConfig에서 virtualhost 이름을 확인합니다.

    ApigeeRouteConfig의 이름은 <Apigee organization>-<virtualhost name> 형식입니다.

    이 예시에서 my-org는 Apigee 조직이고 virtualhost 이름은 my-virtualhost입니다.

  3. overrides.yaml에서 해당 virtualhost를 찾고 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
...
  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. 차트가 보안 비밀을 다시 작성하도록 가상 호스트를 업그레이드합니다.

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Kubernetes 보안 비밀

Kubernetes 보안 비밀 참조(sslSecret)를 사용하면 MCP 데이터 영역이 사용자가 만든 보안 비밀에서 인증서 값을 직접 읽고 업데이트가 자동으로 적용됩니다. 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. 인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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 데이터 영역은 포드를 다시 시작하지 않고도 다음 주기적 새로고침(일반적으로 몇 분 이내)에서 수정된 보안 비밀을 선택하고 다음 스캔에서 ApigeeIssue이 철회됩니다.

진단 정보 수집 필요

안내를 따른 후에도 문제가 지속되면 다음 진단 정보를 수집한 후 Google Cloud Customer Care에 문의하세요.

  1. Google Cloud 프로젝트 ID입니다.
  2. Apigee Hybrid 조직의 이름
  3. ApigeeIssue의 Spec.Details 필드
  4. (선택사항) 영향을 받는 virtualhost에 대해 mcpMtls.sslCertPath에서 참조하는 파일의 인증서 또는 보안 비밀의 cert 항목에 있는 인증서