MCP mTLS 클라이언트 인증서 만료

이 페이지는 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의 이름을 설명합니다.

해결 방법

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME을 문제 이름(예: mcp-client-cert-expiring-soon-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 mTLS 클라이언트 인증서를 가져오고 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 mTLS 클라이언트 인증서와 비공개 키를 가져옵니다.

  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 클라이언트 인증서가 만료됨

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의 이름을 설명합니다.

해결 방법

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    ISSUE_NAME을 문제 이름(예: mcp-client-cert-expired-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 mTLS 클라이언트 인증서를 가져오고 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 mTLS 클라이언트 인증서와 비공개 키를 가져옵니다.

  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 항목에 있는 인증서