이 페이지는 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 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는 보안 비밀my-org-my-virtualhost-mcp를 참조합니다. -
ApigeeRouteConfig에서virtualhost이름을 확인합니다.ApigeeRouteConfig의 이름은<Apigee organization>-<virtualhost name>형식입니다.이 예시에서
my-org는 Apigee 조직이고 virtualhost 이름은my-virtualhost입니다. -
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
...-
보안 비밀이 있고 두 항목이 모두 있는지 확인합니다. 여기서 MCP_CLIENT_SECRET_NAME는
Spec.Details에 이름이 지정된 보안 비밀입니다.Data섹션에는cert및key가 나열되어야 합니다.kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
보안 비밀이 누락되었거나 항목이 없는 경우
mcpMtls.sslCertPath및mcpMtls.sslKeyPath에서 참조하는 파일이 존재하고 비어 있지 않은지 확인합니다. 다음 단계에서는 이 백업에서 보안 비밀을 복원합니다. -
차트가 보안 비밀을 다시 작성하도록 가상 호스트를 업그레이드합니다.
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
...-
보안 비밀이 있고 두 항목이 모두 있는지 확인합니다. 여기서 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실행이 완료되었다고 해서 이 보안 비밀이 있다는 증거는 아닙니다. -
인증서와 비공개 키를 함께 사용하여 보안 비밀을 만들거나 업데이트합니다. 여기서 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 비공개 키여야 합니다.
해결 방법
-
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는 보안 비밀my-org-my-virtualhost-mcp를 참조합니다. -
ApigeeRouteConfig에서virtualhost이름을 확인합니다.ApigeeRouteConfig의 이름은<Apigee organization>-<virtualhost name>형식입니다.이 예시에서
my-org는 Apigee 조직이고 virtualhost 이름은my-virtualhost입니다. -
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
...-
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 보안 비밀
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
...-
보안 비밀의
cert및key항목에 저장하는 인증서 파일(MCP_CLIENT_CERT_FILE)과 키 파일(MCP_CLIENT_KEY_FILE)을 검증하고 필요한 경우 수정합니다. 인증서에는 시작 및 종료 인증서 줄이 포함되어야 하며 키는 인증서의 비공개 키여야 합니다. 예를 들면 다음과 같습니다.-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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의 이름을 지정하고 인증서가 전달하는 확장 키 사용을 나열합니다.
해결 방법
-
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는 보안 비밀my-org-my-virtualhost-mcp를 참조합니다. -
ApigeeRouteConfig에서virtualhost이름을 확인합니다.ApigeeRouteConfig의 이름은<Apigee organization>-<virtualhost name>형식입니다.이 예시에서
my-org는 Apigee 조직이고 virtualhost 이름은my-virtualhost입니다. -
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
...-
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 보안 비밀
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
...-
clientAuth확장 키 사용이 포함된 프로필을 사용하여 비공개 CA에서 클라이언트 인증서를 다시 발급합니다. 보안 비밀을 업데이트하기 전에 확인합니다. 여기서 MCP_CLIENT_CERT_FILE는 재발급된 인증서입니다.openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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에 문의하세요.
- Google Cloud 프로젝트 ID입니다.
- Apigee Hybrid 조직의 이름
ApigeeIssue의Spec.Details필드-
(선택사항) 영향을 받는 virtualhost에 대해
mcpMtls.sslCertPath에서 참조하는 파일의 인증서 또는 보안 비밀의cert항목에 있는 인증서