MCP mTLS CA 인증서가 잘못됨

이 페이지는 Apigee Hybrid에 적용되지만 Apigee에는 적용되지 않습니다.

이 주제에 해당하는 Apigee Edge 문서가 없습니다.

증상

apigee 네임스페이스의 리소스를 보면 Reason이 AIS_MCP_MTLS_CA_CERT_INVALID인 ApigeeIssue가 표시됩니다.

이 문제는 mcpMtls 블록에 체인 검증이 사용 설정된(기본값) 환경 그룹에만 발생합니다. mcpMtls.disableChainValidation: true가 있는 그룹의 경우 MCP 데이터 영역은 CA 인증서를 사용하지 않으며 -cacert 보안 비밀은 스캔되지 않습니다.

오류 메시지

kubectl -n apigee get apigeeissues를 실행하면 다음과 같은 오류가 표시됩니다.

NAME                                        SEVERITY   REASON                         DOCUMENTATION                                                                              AGE
mcp-ca-cert-invalid-my-org-my-virtualhost   ERROR      AIS_MCP_MTLS_CA_CERT_INVALID   https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID   5h18m

가능한 원인

다음 표에는 이 문제의 가능한 원인이 나와 있습니다.

원인 설명
MCP mTLS CA 인증서 보안 비밀 또는 항목이 누락됨 -cacert 보안 비밀이 없거나 사용 가능한 cacert 항목이 없습니다.
MCP mTLS CA 인증서가 PEM으로 인코딩되지 않음 cacert 항목에 PEM 인증서 블록이 없거나 PEM 블록 외부에 바이트가 있습니다.
MCP mTLS CA 인증서의 형식이 잘못되었거나 CA 인증서가 아님 cacert 항목의 블록이 인증서가 아니거나, 파싱되지 않거나, CA 인증서가 아닙니다.

원인: MCP mTLS CA 인증서 보안 비밀 또는 항목이 누락됨

MCP 데이터 영역이 인그레스 게이트웨이를 검증하는 CA 인증서를 보유해야 하는 Kubernetes 보안 비밀이 apigee 네임스페이스에 없거나 비어 있지 않은 cacert 항목 없이 존재합니다. 이름은 클라이언트 인증서 보안 비밀 이름에 -cacert가 추가된 것입니다. 차트는 인증서 파일을 사용할 때만 이 보안 비밀을 만듭니다. sslSecret를 사용하면 직접 만들어야 하며, 이를 잊어버리는 것이 이 문제의 가장 일반적인 원인입니다.

진단

다음 명령어를 실행합니다.

kubectl -n apigee describe apigeeissue ISSUE_NAME

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

출력은 다음과 비슷하게 표시됩니다.

Name:         mcp-ca-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" not found
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CA_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp-cacert" not found

Spec.Details의 콘텐츠는 보안 비밀, ApigeeRouteConfig, 잘못된 항목의 이름을 지정합니다. 예를 들면 다음과 같습니다.

  • secret not found
  • secret has no usable "cacert" entry

해결 방법

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

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

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

  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. 보안 비밀이 있고 cacert 항목이 있는지 확인합니다. 여기서 MCP_CA_SECRET_NAME은 Spec.Details에 이름이 지정된 보안 비밀입니다.

    kubectl -n apigee describe secret MCP_CA_SECRET_NAME

    보안 비밀이 누락되었거나 항목이 없는 경우 mcpMtls.caCertPath에서 참조하는 파일이 있고 비어 있지 않은지 확인합니다. 다음 단계에서는 이 백업에서 보안 비밀을 복원합니다. 체인 검증 없이 실행하려면 mcpMtls.disableChainValidation: true를 설정하고 mcpMtls.caCertPath를 삭제합니다(차트에서 두 가지를 함께 거부함). 이렇게 하면 MCP 데이터 영역에서 인그레스 게이트웨이 인증서 확인이 사용 중지됩니다.

  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. cacert 항목을 사용하여 정확히 해당 이름으로 보안 비밀이 있는지 확인합니다. 여기서 MCP_CLIENT_SECRET_NAME은 mcpMtls.sslSecret로 이름이 지정된 클라이언트 인증서 보안 비밀입니다.

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template는 보안 비밀이 있는지 확인하지 않습니다. helm install 및 helm upgrade만 확인하므로 helm template 실행이 완료되었다고 해서 이 보안 비밀이 있다는 증거는 아닙니다. 체인 검증 없이 실행하려는 경우 보안 비밀을 생략하는 것만으로는 충분하지 않습니다. overrides.yaml에서 mcpMtls.disableChainValidation: true를 설정하고 가상 호스트를 업그레이드합니다. 이렇게 하면 MCP 데이터 영역에서 인그레스 게이트웨이 인증서 확인이 사용 중지됩니다.

  2. CA 인증서 보안 비밀을 만들거나 업데이트합니다. 여기서 MCP_CLIENT_SECRET_NAME은 mcpMtls.sslSecret의 값이고 CA 인증서 보안 비밀은 -cacert가 추가된 이름이며 MCP_TRUST_CA_FILE은 CA 인증서 파일입니다.

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \
      --from-file=cacert=MCP_TRUST_CA_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

MCP 데이터 영역은 포드를 다시 시작하지 않고도 다음 주기적 새로고침(일반적으로 몇 분 이내)에서 수정된 보안 비밀을 선택하고 다음 스캔에서 ApigeeIssue이 철회됩니다.

원인: MCP mTLS CA 인증서가 PEM으로 인코딩되지 않음

cacert 항목에 PEM 인코딩 텍스트 블록이 없거나 마지막 -----END CERTIFICATE----- 줄 뒤에 PEM이 아닌 콘텐츠가 있습니다. MCP 데이터 영역은 이를 로드하지 않습니다.

진단

다음 명령어를 실행합니다.

kubectl -n apigee describe apigeeissue ISSUE_NAME

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

출력은 다음과 비슷하게 표시됩니다.

Name:         mcp-ca-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CA_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: holds 1289 trailing bytes that are not PEM

Spec.Details의 콘텐츠는 보안 비밀, ApigeeRouteConfig, 잘못된 항목의 이름을 지정합니다. 예를 들면 다음과 같습니다.

  • entry holds no PEM encoded certificate
  • holds N trailing bytes that are not PEM

해결 방법

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

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

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

  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.caCertPath에서 참조하는 파일의 콘텐츠를 검증하고 필요한 경우 수정합니다. 콘텐츠에 각각 시작 및 종료 줄이 있는 완전한 인증서 블록만 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

    -----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. 보안 비밀의 cacert 항목에 저장하는 CA 인증서 파일(MCP_TRUST_CA_FILE)의 콘텐츠를 검증하고 필요한 경우 수정합니다. 콘텐츠에 시작 및 종료 줄이 있는 완전한 인증서 블록만 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. CA 인증서 보안 비밀을 제자리에서 업데이트합니다. 여기서 MCP_CLIENT_SECRET_NAME은 mcpMtls.sslSecret의 값이고 CA 인증서 보안 비밀은 -cacert가 추가된 이름이며 MCP_TRUST_CA_FILE은 CA 인증서 파일입니다.

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \
      --from-file=cacert=MCP_TRUST_CA_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

MCP 데이터 영역은 포드를 다시 시작하지 않고도 다음 주기적 새로고침(일반적으로 몇 분 이내)에서 수정된 보안 비밀을 선택하고 다음 스캔에서 ApigeeIssue이 철회됩니다.

원인: MCP mTLS CA 인증서의 형식이 잘못되었거나 CA 인증서가 아님

cacert 항목의 모든 PEM 블록은 파싱되고 CA 기본 제약조건이 있는 CERTIFICATE 블록이어야 합니다. 비공개 키 블록, 리프 인증서(예: 인그레스 게이트웨이의 자체 서버 인증서) 또는 손상된 블록은 항목을 사용할 수 없게 만들고 MCP 데이터 영역은 이를 로드하지 않습니다.

진단

다음 명령어를 실행합니다.

kubectl -n apigee describe apigeeissue ISSUE_NAME

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

출력은 다음과 비슷하게 표시됩니다.

Name:         mcp-ca-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CA_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 CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CA_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CA_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS CA certificate in secret "my-org-my-virtualhost-mcp-cacert" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: block 1 is not a CA certificate

Spec.Details의 콘텐츠는 보안 비밀, ApigeeRouteConfig, 잘못된 항목의 이름을 지정합니다. 예를 들면 다음과 같습니다.

  • no PEM block parsed as a certificate: ...: 인증서 블록을 파싱할 수 없습니다(예: 유일한 인증서가 손상됨).
  • block N is a "..." block, want CERTIFICATE: N 블록이 인증서가 아닙니다(예: 비공개 키).
  • block N does not parse: : 블록 N은 손상된 인증서입니다.
  • block N is not a CA certificate: N 블록은 인증서이지만 CA가 아닙니다(예: 리프 인증서).

블록은 0부터 번호가 매겨집니다.

해결 방법

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

    kubectl -n apigee describe apigeeissue ISSUE_NAME

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

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

  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. 인그레스 게이트웨이의 인증서에 서명한 CA 인증서(또는 체인)만 보유하도록 mcpMtls.caCertPath에서 참조하는 파일을 다시 빌드합니다. 그런 다음 모든 블록이 CA 인증서인지 확인합니다. 여기서 MCP_TRUST_CA_FILE는 해당 파일입니다.

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  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. 인그레스 게이트웨이의 인증서에 서명한 CA 인증서(또는 체인)만 포함하도록 CA 인증서 파일(MCP_TRUST_CA_FILE)을 다시 빌드합니다. 그런 다음 모든 블록이 CA 인증서인지 확인합니다.

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. CA 인증서 보안 비밀을 제자리에서 업데이트합니다. 여기서 MCP_CLIENT_SECRET_NAME은 mcpMtls.sslSecret의 값이고 CA 인증서 보안 비밀은 -cacert가 추가된 이름이며 MCP_TRUST_CA_FILE은 CA 인증서 파일입니다.

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME-cacert \
      --from-file=cacert=MCP_TRUST_CA_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.caCertPath에서 참조하는 파일의 인증서 또는 보안 비밀의 cacert 항목에 있는 인증서