이 페이지는 Apigee Hybrid에 적용되지만 Apigee에는 적용되지 않습니다.
이 주제에 해당하는 Apigee Edge 문서가 없습니다.
증상
apigee 네임스페이스의 리소스를 보면 Reason이 AIS_MCP_MTLS_CLIENT_CERT_EXPIRY인 ApigeeIssue가 표시됩니다.
오류 메시지
kubectl -n apigee get apigeeissues를 실행하면 다음과 같은 문제가 표시됩니다.
NAME SEVERITY REASON DOCUMENTATION AGE mcp-client-cert-expired-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CLIENT_CERT_EXPIRY https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY 5h18m
가능한 원인
다음 표에는 이 문제의 가능한 원인이 나와 있습니다.
| 원인 | 설명 |
|---|---|
| MCP mTLS 클라이언트 인증서가 곧 만료됨 | 구성된 MCP mTLS 클라이언트 인증서가 14일 이내에 만료됩니다. |
| MCP mTLS 클라이언트 인증서가 만료됨 | 구성된 MCP mTLS 클라이언트 인증서가 만료되었습니다. |
원인: MCP mTLS 클라이언트 인증서가 곧 만료됨
ApigeeRouteConfig에서 참조하는 Kubernetes 보안 비밀에 저장된 MCP mTLS 클라이언트 인증서가 14일 이내에 만료됩니다.
진단
다음 명령어를 실행합니다.
kubectl -n apigee describe apigeeissue ISSUE_NAME
ISSUE_NAME을 문제 이름(예: mcp-client-cert-expiring-soon-my-org-my-virtualhost)으로 바꿉니다.
출력은 다음과 비슷하게 표시됩니다.
Name: mcp-client-cert-expiring-soon-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_CERT_EXPIRY 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 expiring in 335h12m4s at 2026-11-26 16:15:47 +0000 UTC Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY Reason: AIS_MCP_MTLS_CLIENT_CERT_EXPIRY Severity: WARNING Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is expiring in 335h12m4s at 2026-11-26 16:15:47 +0000 UTC
Spec.Details의 콘텐츠는 곧 만료되는 MCP mTLS 클라이언트 인증서가 포함된 Kubernetes 보안 비밀을 참조하는 ApigeeRouteConfig의 이름을 설명합니다.
해결 방법
-
kubectl describe를 사용하여 Kubernetes 보안 비밀의 이름과 문제가 속한ApigeeRouteConfig를 표시합니다.kubectl -n apigee describe apigeeissue ISSUE_NAME
ISSUE_NAME을 문제 이름(예:mcp-client-cert-expiring-soon-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 mTLS 클라이언트 인증서를 가져오고
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 mTLS 클라이언트 인증서와 비공개 키를 가져옵니다.
-
인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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 클라이언트 인증서가 만료됨
ApigeeRouteConfig에서 참조하는 Kubernetes 보안 비밀에 저장된 MCP mTLS 클라이언트 인증서가 만료되었습니다.
진단
다음 명령어를 실행합니다.
kubectl -n apigee describe apigeeissue ISSUE_NAME
ISSUE_NAME을 문제 이름(예: mcp-client-cert-expired-my-org-my-virtualhost)으로 바꿉니다.
출력은 다음과 비슷하게 표시됩니다.
Name: mcp-client-cert-expired-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_CERT_EXPIRY 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" expired at: 2026-11-10 17:03:43 +0000 UTC Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_EXPIRY Reason: AIS_MCP_MTLS_CLIENT_CERT_EXPIRY Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" expired at: 2026-11-10 17:03:43 +0000 UTC
Spec.Details의 콘텐츠는 만료된 MCP mTLS 클라이언트 인증서가 포함된 Kubernetes 보안 비밀을 참조하는 ApigeeRouteConfig의 이름을 설명합니다.
해결 방법
-
kubectl describe를 사용하여 Kubernetes 보안 비밀의 이름과 문제가 속한ApigeeRouteConfig를 표시합니다.kubectl -n apigee describe apigeeissue ISSUE_NAME
ISSUE_NAME을 문제 이름(예:mcp-client-cert-expired-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 mTLS 클라이언트 인증서를 가져오고
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 mTLS 클라이언트 인증서와 비공개 키를 가져옵니다.
-
인증서와 비공개 키를 함께 사용하여 보안 비밀을 업데이트합니다. 여기서 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항목에 있는 인증서