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_CLIENT_CERT_INVALID
ditampilkan saat melihat resource di namespace apigee.
Pesan error
Setelah menjalankan kubectl -n apigee get apigeeissues, error seperti berikut akan ditampilkan:
NAME SEVERITY REASON DOCUMENTATION AGE mcp-client-cert-invalid-my-org-my-virtualhost ERROR AIS_MCP_MTLS_CLIENT_CERT_INVALID https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID 5h18m
Kemungkinan penyebab
Tabel berikut mencantumkan kemungkinan penyebab masalah ini:
| Penyebab | Deskripsi |
|---|---|
| Rahasia atau entri sertifikat klien mTLS MCP tidak ada |
Secret yang diberi nama oleh mcpMtls tidak ada, atau tidak memiliki entri cert atau key yang dapat digunakan.
|
| Sertifikat atau kunci klien mTLS MCP salah format |
Entri cert tidak dienkode PEM, atau entri key bukan kunci pribadi yang cocok.
|
| Sertifikat klien mTLS MCP menghilangkan penggunaan kunci yang diperluas clientAuth |
Sertifikat diuraikan, tetapi penggunaan kunci yang diperpanjang tidak menyertakan
clientAuth.
|
Penyebab: Rahasia atau entri sertifikat klien mTLS MCP tidak ada
Secret Kubernetes yang seharusnya menyimpan sertifikat klien mTLS MCP tidak ada di namespace apigee, atau ada tanpa entri cert yang tidak kosong atau tanpa entri key. Bidang data MCP tidak memiliki sertifikat klien yang dapat ditampilkan untuk
grup lingkungan ini, sehingga panggilan alat MCP ke grup tersebut gagal pada TLS handshake.
Diagnosis
Jalankan perintah berikut:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti ISSUE_NAME dengan nama masalah, misalnya
mcp-client-cert-invalid-my-org-my-virtualhost.
Output-nya akan terlihat seperti berikut:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found
Konten Spec.Details memberi nama secret,
ApigeeRouteConfig, dan apa yang salah. Contoh:
secret not foundsecret has no usable "cert" entrysecret has no "key" 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-client-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp. -
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 kedua entri, dengan MCP_CLIENT_SECRET_NAME adalah secret yang diberi nama di
Spec.Details. BagianDataharus mencantumkancertdankey:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
Jika secret tidak ada atau tidak memiliki entri, pastikan file yang direferensikan oleh
mcpMtls.sslCertPathdanmcpMtls.sslKeyPathada dan tidak kosong. Langkah berikutnya akan memulihkan secret dari file tersebut. -
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
...-
Pastikan secret ada dan memiliki kedua entri, dengan MCP_CLIENT_SECRET_NAME adalah secret yang diberi nama di
Spec.Details. BagianDataharus mencantumkancertdankey. Pastikan nama dimcpMtls.sslSecretcocok dengan secret yang Anda buat dan secret tersebut berada di namespaceapigee:kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME kubectl get secret -A --field-selector metadata.name=MCP_CLIENT_SECRET_NAME # if the first command finds nothing
helm templatetidak memeriksa apakah secret ada; hanyahelm installdanhelm upgradeyang melakukannya, sehingga eksekusihelm templateyang bersih bukan bukti bahwa secret ini ada. -
Buat atau perbarui secret dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di
Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya: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 -
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 atau kunci klien mTLS MCP salah format
Entri cert tidak berisi sertifikat X.509 berenkode PEM, atau entri key tidak berenkode PEM atau bukan kunci pribadi untuk sertifikat tersebut. Data plane MCP tidak dapat memuat pasangan.
Diagnosis
Jalankan perintah berikut:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti ISSUE_NAME dengan nama masalah, misalnya
mcp-client-cert-invalid-my-org-my-virtualhost.
Output-nya akan terlihat seperti berikut:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key
Konten Spec.Details memberi nama secret,
ApigeeRouteConfig, dan apa yang salah. Contoh:
-
entry holds no PEM encoded certificate: entricertbukan PEM. -
tls: failed to find any PEM data in key input: entrikeybukan PEM. -
tls: private key does not match public key: entricertdankeytidak berpasangan. -
tls: failed to parse private key: kunci tidak dapat diurai, biasanya karena dienkripsi. Entrikeyharus berupa kunci pribadi PEM yang tidak dienkripsi.
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-client-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp. -
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 file sertifikat dan file kunci yang direferensikan oleh
mcpMtls.sslCertPathdanmcpMtls.sslKeyPath, dan perbaiki jika diperlukan. Sertifikat harus berisi baris sertifikat awal dan akhir, dan kuncinya harus berupa kunci pribadi untuk sertifikat tersebut. 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 file sertifikat (MCP_CLIENT_CERT_FILE) dan file kunci (MCP_CLIENT_KEY_FILE) yang Anda simpan di entri
certdankeysecret, dan perbaiki jika diperlukan. Sertifikat harus berisi baris sertifikat awal dan akhir, dan kunci harus berupa kunci pribadi untuk sertifikat tersebut. Contoh:-----BEGIN CERTIFICATE----- MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL ... <contents omitted> ... QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM MMM= -----END CERTIFICATE-----
-
Perbarui secret di tempat dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di
Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya: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 -
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 klien mTLS MCP menghilangkan penggunaan kunci yang diperluas clientAuth
Sertifikat terbentuk dengan baik dan dipasangkan dengan kuncinya, tetapi penggunaan kunci yang diperpanjang (EKU) tidak
mencakup clientAuth, sehingga tidak dapat digunakan untuk autentikasi klien dan bidang data MCP
tidak menampilkannya. Hal ini umum terjadi saat sertifikat server, atau sertifikat dari profil CA publik yang tidak lagi menerbitkan clientAuth, digunakan kembali.
Diagnosis
Jalankan perintah berikut:
kubectl -n apigee describe apigeeissue ISSUE_NAME
Ganti ISSUE_NAME dengan nama masalah, misalnya
mcp-client-cert-invalid-my-org-my-virtualhost.
Output-nya akan terlihat seperti berikut:
Name: mcp-client-cert-invalid-my-org-my-virtualhost Namespace: apigee Labels: ais-reason=AIS_MCP_MTLS_CLIENT_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 client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth Documentation: https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID Reason: AIS_MCP_MTLS_CLIENT_CERT_INVALID Severity: ERROR Events: <none>
Spec: Details: MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth
Konten Spec.Details memberi nama secret dan
ApigeeRouteConfig, serta mencantumkan penggunaan kunci yang diperpanjang yang dibawa oleh sertifikat.
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-client-cert-invalid-my-org-my-virtualhost.Dalam contoh ini,
ApigeeRouteConfigmy-org-my-virtualhostmerujuk ke secretmy-org-my-virtualhost-mcp. -
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
...-
Terbitkan ulang sertifikat klien dari CA pribadi Anda dengan profil yang menyertakan penggunaan kunci yang diperluas
clientAuth. Konfirmasi, dengan MCP_CLIENT_CERT_FILE adalah sertifikat yang diterbitkan ulang, lalu ganti file yang direferensikan olehmcpMtls.sslCertPathdanmcpMtls.sslKeyPath:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
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
...-
Terbitkan ulang sertifikat klien dari CA pribadi Anda dengan profil yang menyertakan penggunaan kunci yang diperluas
clientAuth. Konfirmasi sebelum Anda memperbarui secret, dengan MCP_CLIENT_CERT_FILE sebagai sertifikat yang diterbitkan ulang:openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage # must list: TLS Web Client Authentication
-
Perbarui secret di tempat dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di
Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya: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 -
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.sslCertPath, atau dalam entricertsecret, untuk virtualhost yang terpengaruh.