Sertifikat CA mTLS MCP tidak valid

Halaman ini berlaku untuk Apigee hybrid, tetapi tidak untuk Apigee.

Tidak ada dokumentasi Apigee Edge yang setara untuk topik ini.

Gejala

ApigeeIssue dengan Reason AIS_MCP_MTLS_CA_CERT_INVALID ditampilkan saat melihat resource di namespace apigee.

Masalah ini hanya muncul untuk grup lingkungan yang blok mcpMtls-nya mengaktifkan validasi rantai (default). Untuk grup dengan mcpMtls.disableChainValidation: true, bidang data MCP tidak menggunakan sertifikat CA dan secret -cacert tidak dipindai.

Pesan error

Setelah menjalankan kubectl -n apigee get apigeeissues, error seperti berikut akan ditampilkan:

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

Kemungkinan penyebab

Tabel berikut mencantumkan kemungkinan penyebab masalah ini:

Penyebab Deskripsi
Entri atau secret sertifikat CA mTLS MCP tidak ada Rahasia -cacert tidak ada, atau tidak memiliki entri cacert yang dapat digunakan.
Sertifikat CA mTLS MCP tidak dienkode PEM Entri cacert tidak memiliki blok sertifikat PEM, atau memiliki byte di luar blok PEM.
Sertifikat CA mTLS MCP salah format atau bukan sertifikat CA Blok dalam entri cacert bukan sertifikat, tidak diurai, atau bukan sertifikat CA.

Penyebab: Rahasia atau entri sertifikat CA mTLS MCP tidak ada

Secret Kubernetes yang seharusnya menyimpan sertifikat CA yang divalidasi oleh bidang data MCP terhadap gateway ingress tidak ada di namespace apigee, atau ada tanpa entri cacert yang tidak kosong. Namanya adalah nama rahasia sertifikat klien dengan -cacert ditambahkan. Diagram ini membuat secret ini hanya saat Anda menggunakan file sertifikat; dengan sslSecret, Anda harus membuatnya sendiri, dan melupakannya adalah penyebab paling umum dari masalah ini.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

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

Konten Spec.Details memberi nama secret, ApigeeRouteConfig, dan apa yang salah. Contoh:

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

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp-cacert.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

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. Periksa apakah secret ada dan memiliki entri cacert, dengan MCP_CA_SECRET_NAME adalah secret yang diberi nama di Spec.Details:

    kubectl -n apigee describe secret MCP_CA_SECRET_NAME

    Jika secret tidak ada atau tidak memiliki entri, pastikan file yang dirujuk oleh mcpMtls.caCertPath ada dan tidak kosong. Langkah berikutnya memulihkan secret dari secret tersebut. Jika Anda ingin menjalankan tanpa validasi rantai, tetapkan mcpMtls.disableChainValidation: true dan hapus mcpMtls.caCertPath (diagram menolak keduanya). Perlu diketahui bahwa tindakan ini akan menonaktifkan verifikasi sertifikat gateway ingress oleh bidang data MCP.

  2. Upgrade virtualhost agar diagram menulis ulang secret:

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

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Konfirmasi bahwa secret ada dengan nama yang sama persis dengan entri cacert, dengan MCP_CLIENT_SECRET_NAME adalah secret sertifikat klien yang diberi nama oleh mcpMtls.sslSecret:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert

    helm template tidak memeriksa apakah secret ada; hanya helm install dan helm upgrade yang melakukannya, sehingga eksekusi helm template yang bersih bukan bukti bahwa secret ini ada. Jika Anda ingin menjalankan tanpa validasi rantai, menghilangkan rahasia saja tidak cukup. Tetapkan mcpMtls.disableChainValidation: true di overrides.yaml dan upgrade virtualhost. Perlu diketahui bahwa tindakan ini akan menonaktifkan verifikasi sertifikat gateway ingress oleh bidang data MCP.

  2. Buat atau perbarui secret sertifikat CA, dengan MCP_CLIENT_SECRET_NAME adalah nilai mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan -cacert ditambahkan, dan MCP_TRUST_CA_FILE adalah file sertifikat 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 -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Penyebab: Sertifikat CA mTLS MCP tidak dienkode dengan PEM

Entri cacert tidak memiliki blok teks berenkode PEM, atau memiliki konten setelah baris -----END CERTIFICATE----- terakhir yang bukan PEM. Data plane MCP tidak memuatnya.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

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

Konten Spec.Details memberi nama secret, ApigeeRouteConfig, dan apa yang salah. Contoh:

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

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp-cacert.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

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. Validasi konten file yang direferensikan oleh mcpMtls.caCertPath, dan perbaiki jika diperlukan. Pastikan konten hanya berisi blok sertifikat lengkap, masing-masing dengan baris awal dan akhir. Contoh:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Upgrade virtualhost agar diagram menulis ulang secret:

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

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Validasi konten file sertifikat CA (MCP_TRUST_CA_FILE) yang Anda simpan di entri cacert secret, dan perbaiki jika diperlukan. Pastikan konten hanya berisi blok sertifikat lengkap, masing-masing dengan baris awal dan akhir. Contoh:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Perbarui secret sertifikat CA di tempat, dengan MCP_CLIENT_SECRET_NAME adalah nilai mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan -cacert ditambahkan, dan MCP_TRUST_CA_FILE adalah file sertifikat 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 -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Penyebab: Sertifikat CA mTLS MCP salah format atau bukan sertifikat CA

Setiap blok PEM dalam entri cacert harus berupa blok CERTIFICATE yang mengurai dan memiliki batasan dasar CA. Blok kunci pribadi, sertifikat entitas akhir (misalnya, sertifikat server gateway ingress itu sendiri), atau blok yang rusak membuat entri tidak dapat digunakan, dan bidang data MCP tidak akan memuatnya.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

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

Konten Spec.Details memberi nama secret, ApigeeRouteConfig, dan apa yang salah. Contoh:

  • no PEM block parsed as a certificate: ...: tidak ada blok sertifikat yang dapat diuraikan (misalnya, satu-satunya sertifikat rusak).
  • block N is a "..." block, want CERTIFICATE: blok N bukan sertifikat (misalnya, kunci pribadi).
  • block N does not parse: blok N adalah sertifikat yang rusak.
  • block N is not a CA certificate: blok N adalah sertifikat, tetapi bukan CA (misalnya, sertifikat entitas akhir).

Blok diberi nomor mulai dari 0.

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-ca-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp-cacert.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

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. Bangun ulang file yang direferensikan oleh mcpMtls.caCertPath sehingga hanya menyimpan sertifikat (atau rantai) CA yang menandatangani sertifikat gateway masuk. Kemudian, konfirmasi bahwa setiap blok adalah sertifikat CA, dengan MCP_TRUST_CA_FILE adalah file tersebut:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. Upgrade virtualhost agar diagram menulis ulang secret:

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

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Bangun ulang file sertifikat CA (MCP_TRUST_CA_FILE) agar hanya menyimpan sertifikat (atau rantai) CA yang menandatangani sertifikat gateway masuk. Kemudian, pastikan bahwa setiap blok adalah sertifikat CA:

    openssl storeutl -noout -text -certs MCP_TRUST_CA_FILE | grep -E 'Subject:|CA:'
    # every certificate must show CA:TRUE
  2. Perbarui secret sertifikat CA di tempat, dengan MCP_CLIENT_SECRET_NAME adalah nilai mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan -cacert ditambahkan, dan MCP_TRUST_CA_FILE adalah file sertifikat 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 -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Harus mengumpulkan informasi diagnostik

Jika masalah berlanjut bahkan setelah mengikuti petunjuk sebelumnya, kumpulkan informasi diagnostik berikut, lalu hubungi Google Cloud Customer Care:

  1. Project ID Google Cloud .
  2. Nama organisasi Apigee hybrid.
  3. Kolom Spec.Details dari ApigeeIssue.
  4. (opsional) Sertifikat dalam file yang dirujuk oleh mcpMtls.caCertPath, atau dalam entri cacert secret, untuk virtualhost yang terpengaruh.