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 foundsecret has no usable "cacert" entry
Resolusi
-
Gunakan
kubectl describeuntuk menampilkan nama secret Kubernetes danApigeeRouteConfigyang terkait dengan masalah tersebut:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti
ISSUE_NAMEdengan nama masalah, misalnyamcp-ca-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp-cacert. -
Tentukan nama
virtualhostdariApigeeRouteConfig.Nama
ApigeeRouteConfigmenggunakan format:<Apigee organization>-<virtualhost name>.Dalam contoh ini,
my-orgadalah organisasi Apigee dan nama virtualhost-nya adalahmy-virtualhost. -
Temukan virtualhost yang sesuai di
overrides.yamlAnda dan periksa bentuk blokmcpMtlsyang 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
...-
Periksa apakah secret ada dan memiliki entri
cacert, dengan MCP_CA_SECRET_NAME adalah secret yang diberi nama diSpec.Details:kubectl -n apigee describe secret MCP_CA_SECRET_NAME
Jika secret tidak ada atau tidak memiliki entri, pastikan file yang dirujuk oleh
mcpMtls.caCertPathada dan tidak kosong. Langkah berikutnya memulihkan secret dari secret tersebut. Jika Anda ingin menjalankan tanpa validasi rantai, tetapkanmcpMtls.disableChainValidation: truedan hapusmcpMtls.caCertPath(diagram menolak keduanya). Perlu diketahui bahwa tindakan ini akan menonaktifkan verifikasi sertifikat gateway ingress oleh bidang data MCP. -
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
...-
Konfirmasi bahwa secret ada dengan nama yang sama persis dengan entri
cacert, dengan MCP_CLIENT_SECRET_NAME adalah secret sertifikat klien yang diberi nama olehmcpMtls.sslSecret:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME-cacert
helm templatetidak memeriksa apakah secret ada; hanyahelm installdanhelm upgradeyang melakukannya, sehingga eksekusihelm templateyang bersih bukan bukti bahwa secret ini ada. Jika Anda ingin menjalankan tanpa validasi rantai, menghilangkan rahasia saja tidak cukup. TetapkanmcpMtls.disableChainValidation: truedioverrides.yamldan upgrade virtualhost. Perlu diketahui bahwa tindakan ini akan menonaktifkan verifikasi sertifikat gateway ingress oleh bidang data MCP. -
Buat atau perbarui secret sertifikat CA, dengan MCP_CLIENT_SECRET_NAME adalah nilai
mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan-cacertditambahkan, 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 certificateholds N trailing bytes that are not PEM
Resolusi
-
Gunakan
kubectl describeuntuk menampilkan nama secret Kubernetes danApigeeRouteConfigyang terkait dengan masalah tersebut:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti
ISSUE_NAMEdengan nama masalah, misalnyamcp-ca-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp-cacert. -
Tentukan nama
virtualhostdariApigeeRouteConfig.Nama
ApigeeRouteConfigmenggunakan format:<Apigee organization>-<virtualhost name>.Dalam contoh ini,
my-orgadalah organisasi Apigee dan nama virtualhost-nya adalahmy-virtualhost. -
Temukan virtualhost yang sesuai di
overrides.yamlAnda dan periksa bentuk blokmcpMtlsyang 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
...-
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-----
-
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
...-
Validasi konten file sertifikat CA (MCP_TRUST_CA_FILE) yang Anda simpan di entri
cacertsecret, 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-----
-
Perbarui secret sertifikat CA di tempat, dengan MCP_CLIENT_SECRET_NAME adalah nilai
mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan-cacertditambahkan, 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
-
Gunakan
kubectl describeuntuk menampilkan nama secret Kubernetes danApigeeRouteConfigyang terkait dengan masalah tersebut:kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti
ISSUE_NAMEdengan nama masalah, misalnyamcp-ca-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp-cacert. -
Tentukan nama
virtualhostdariApigeeRouteConfig.Nama
ApigeeRouteConfigmenggunakan format:<Apigee organization>-<virtualhost name>.Dalam contoh ini,
my-orgadalah organisasi Apigee dan nama virtualhost-nya adalahmy-virtualhost. -
Temukan virtualhost yang sesuai di
overrides.yamlAnda dan periksa bentuk blokmcpMtlsyang 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
...-
Bangun ulang file yang direferensikan oleh
mcpMtls.caCertPathsehingga 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
-
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
...-
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
-
Perbarui secret sertifikat CA di tempat, dengan MCP_CLIENT_SECRET_NAME adalah nilai
mcpMtls.sslSecret, secret sertifikat CA adalah nama tersebut dengan-cacertditambahkan, 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:
- Project ID Google Cloud .
- Nama organisasi Apigee hybrid.
- Kolom
Spec.DetailsdariApigeeIssue. -
(opsional) Sertifikat dalam file yang dirujuk oleh
mcpMtls.caCertPath, atau dalam entricacertsecret, untuk virtualhost yang terpengaruh.