Mengaktifkan Model Context Protocol (MCP) di Apigee hybrid

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara mengaktifkan Model Context Protocol (MCP) di cluster hybrid Apigee yang sudah ada dan menjalankan versi 1.17.0 atau yang lebih baru. Setelah Anda menyelesaikan prosedur ini, cluster Anda akan menjalankan bidang data MCP dalam cluster baru dan Message Processor Anda siap merutekan panggilan alat MCP ke bidang data tersebut. Kemudian, Anda dapat men-deploy MCP Discovery Proxy pertama dengan mengikuti MCP quickstart yang dibagikan.

Untuk konsep, arsitektur, dan detail fitur MCP yang digunakan bersama antara Apigee dan Apigee hybrid, lihat Ringkasan MCP di Apigee.

Fungsi prosedur ini

Mengaktifkan MCP di cluster Apigee hybrid akan membuat perubahan berikut:

  1. Memberikan akses identitas apigee-watcher ke konfigurasi MCP di bidang kontrol Apigee. Anda menambahkan akun layanan apigee-watcher ke daftar watcher_identities di resource controlPlaneAccess organisasi Apigee Anda sehingga sidecar MCP dapat menarik paket konfigurasi MCP dari bidang kontrol Apigee. Ini adalah perubahan bidang kontrol, yang dicakup ke organisasi Apigee, dan merupakan langkah satu kali per organisasi terlepas dari jumlah cluster yang melayani organisasi tersebut.
  2. Menambahkan data plane MCP dalam cluster baru. Kumpulan pod MCP baru dibuat di namespace Kubernetes yang sama tempat Apigee Hybrid diinstal (default apigee), bersama dengan resource Kubernetes pendukung (Service, Horizontal Pod Autoscaler, dan RBAC) yang diperlukan untuk menjalankannya. Panggilan alat MCP ditangani oleh pod ini.
  3. Mengonfigurasi Pemroses Pesan Anda untuk menjangkau bidang data MCP. Operator Apigee memperbarui spesifikasi pod Message Processor sehingga MP merutekan panggilan alat MCP ke data plane MCP dalam cluster yang baru. Menerapkan perubahan ini akan memicu rilis canary bertahap Message Processor (dikelola oleh pengontrol ApigeeDeployment ); pod sebelumnya akan terus melayani traffic hingga pod baru Ready. Pelepasan hanya terjadi pada transisi aktif dan nonaktif, bukan pada aktivitas MCP yang sedang berlangsung atau traffic MCP dalam kondisi stabil. Jalankan prosedur ini di masa pemeliharaan yang disetujui dan tunggu hingga rilis selesai sebelum melanjutkan.

Langkah 1: Edit overrides.yaml

Buka file overrides.yaml yang Anda gunakan untuk chart Helm Apigee hybrid. Di tingkat teratas file, tambahkan:

enableMcpServer: true

Ini adalah konfigurasi minimum yang diperlukan untuk mengaktifkan MCP. Hal ini menggunakan default bawaan dari diagram apigee-org: dua replika bidang data MCP yang menskalakan otomatis hingga sepuluh pada penggunaan CPU 70%, dengan permintaan resource 500m CPU dan memori 512 Mi, serta batas 2000m CPU dan memori 1 Gi pada container bidang data MCP. Untuk menyesuaikan jumlah replika, permintaan resource, atau akun layanan MCP, lihat Referensi: Kolom MCP di overrides.yaml di halaman ini.

Contoh lengkap overrides.yaml gabungan berikut, satu untuk setiap gaya autentikasi. Gunakan contoh yang cocok dengan cara konfigurasi penginstalan dasar Anda yang ada; baris khusus MCP ditandai dengan komentar dan sama dalam ketiga varian.

Pilih tab yang sesuai dengan cara penginstalan dasar Anda mengautentikasi komponen Apigee ke Google Cloud. Pilihan ini berlaku untuk setiap blok kode yang tercakup dalam varian di halaman ini.

Workload Identity (GKE)

Gunakan varian ini jika penginstalan dasar Anda mengautentikasi komponen Apigee ke Google Cloud melalui GKE Workload Identity (tidak ada file kunci akun layanan di disk).

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
  workloadIdentity:
    enabled: true
    gsa: apigee-non-prod@my-hybrid-project.iam.
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

Kunci akun layanan berbasis file

Gunakan varian ini jika penginstalan dasar Anda mengautentikasi komponen Apigee ke Google Cloud melalui file kunci akun layanan yang Anda distribusikan ke setiap cluster.

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env
  serviceAccountPaths:
    synchronizer: ./service-accounts/apigee-non-prod.json
    runtime:      ./service-accounts/apigee-non-prod.json

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

Workload Identity Federation (AKS/EKS)

Gunakan varian ini jika penginstalan dasar Anda ada di AKS atau EKS dan melakukan autentikasi ke Google Cloud melalui Workload Identity Federation. MCP mewarisi identitas yang didukung WIF yang sudah digunakan apigee-watcher di cluster Anda — Anda tidak perlu menambahkan konfigurasi identitas khusus MCP.

Tambahkan kunci tingkat teratas MCP ke overrides.yaml WIF yang ada:

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

Biarkan mcpServer.gsa dan mcpServer.serviceAccountPath tidak disetel. The MCP sidecar picks up the same identity apigee-watcher resolves through WIF.

Langkah 2: Beri identitas pengamat akses ke konfigurasi MCP di bidang kontrol

Sidecar MCP mengambil paket konfigurasinya dari bidang kontrol Apigee menggunakan akun layanan Google Cloud komponen apigee-watcher (identitas yang Anda pilih di Langkah 1). Sebelum pod MCP dimulai, tambahkan akun layanan tersebut ke daftar watcher_identities di resource controlPlaneAccess organisasi Apigee Anda. Tanpa pemberian ini, panggilan sidecar MCP ke apigee.googleapis.com untuk mengambil referensi konfigurasi MCP akan menampilkan 404 Not Found dan bidang data MCP tidak akan pernah siap untuk menayangkan traffic alat.

Langkah ini hanya perlu dilakukan satu kali per organisasi (bukan per cluster). Lewati langkah ini jika Anda telah memberikan akses untuk cluster sebelumnya di organisasi Apigee yang sama.

  1. Tetapkan variabel shell yang Anda gunakan untuk panggilan API. Gunakan kembali nilai dari penginstalan Anda: 
    export ORG_NAME=YOUR_ORG_NAME
export PROJECT_ID=YOUR_GCP_PROJECT_ID
export WATCHER_SA=apigee-watcher@${PROJECT_ID}.
export TOKEN=$(gcloud auth print-access-token)

    Dengan:

    • YOUR_ORG_NAME adalah nama organisasi Apigee hybrid Anda.
    • YOUR_GCP_PROJECT_ID adalah project Google Cloud yang menghosting organisasi hybrid Apigee Anda.
    • WATCHER_SA adalah alamat email akun layanan apigee-watcher. Jika Anda mengganti watcher.gsa di overrides.yaml, gunakan nilai tersebut, bukan apigee-watcher@${PROJECT_ID}. default.
  2. Panggil updateControlPlaneAccess API untuk menambahkan akun layanan watcher ke daftar watcher_identities:

    Tidak ada residensi data

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
  -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"

    Residensi data

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
  -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"

    Dengan CONTROL_PLANE_LOCATION adalah lokasi untuk data bidang kontrol jika penginstalan Apigee hybrid Anda menggunakan residensi data. Untuk daftar lokasi yang tersedia, lihat Region bidang kontrol Apigee API yang tersedia.

    Panggilan ini menampilkan operasi yang berjalan lama. Tunggu hingga selesai sebelum menjalankan langkah verifikasi di bawah.

  3. Verifikasi bahwa hibah telah diterima. Panggil getControlPlaneAccess dan konfirmasi bahwa akun layanan watcher muncul di kolom watcherIdentities respons:

    Tidak ada residensi data

    curl -X GET -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"

    Residensi data

    curl -X GET -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"

    Respons harus menyertakan array watcherIdentities yang berisi akun layanan watcher Anda. Contoh:

    {
  "synchronizerIdentities": [ ... ],
  "analyticsPublisherIdentities": [ ... ],
  "watcherIdentities": [
    "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID."
  ]
}

    Jika watcherIdentities tidak ada dalam respons atau tidak berisi akun layanan watcher Anda, jalankan kembali perintah PATCH dan periksa status operasi untuk mengetahui apakah ada error sebelum melanjutkan.

Langkah 3: Upgrade diagram apigee-operator

Upgrade diagram operator terlebih dahulu. Diagram operator memiliki skema untuk resource MCP baru; diagram organisasi mereferensikannya. Mengupgrade dengan urutan yang salah akan menghasilkan helm upgrade yang berhasil dan tidak membuat pod MCP.

helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

Perintah selesai dalam waktu kurang dari satu menit. Pastikan Deployment operator di-roll out sepenuhnya dengan image baru (apigee-controller-manager Deployment adalah resource Kubernetes standar, bukan ApigeeDeployment, jadi kubectl rollout status deploy adalah perintah yang benar di sini):

kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m

Output yang diharapkan:

deployment "apigee-controller-manager" successfully rolled out

Langkah 4: Tingkatkan kualitas diagram apigee-org

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

Dua loop rekonsiliasi kini berjalan secara paralel:

  • Operator Apigee membuat Deployment, Layanan, HPA, ServiceAccount, Role, dan RoleBinding MCP. Pod MCP muncul dua per dua (tunduk pada penjadwalan Kubernetes); penampung sidecar di setiap pod melakukan pengambilan konfigurasi pertamanya dari bidang kontrol Apigee segera setelah startup.
  • Operator Apigee menyuntikkan entri hostAliases ke dalam spesifikasi pod Message Processor, yang memicu rilis apigee-runtime ApigeeDeployment.

Langkah 5: Verifikasi penginstalan

Memverifikasi bahwa bidang data MCP sedang berjalan

Periksa empat resource terkait MCP yang dibuat operator. Nama resource mencakup sufiks yang berasal dari organisasi; contoh berikut menggunakan ORG_CR_SUFFIX sebagai placeholder untuk sufiks tersebut, dan sufiks pod serta ClusterIP Layanan akan berbeda di lingkungan Anda.

Pod MCP (dua secara default; penskalaan otomatis hingga sepuluh saat ada beban):

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                                                READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-abc12   2/2     Running   0          2m
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-def34   2/2     Running   0          2m

Setiap pod harus menampilkan 2/2 di kolom READY. Dua container di setiap pod adalah:

  • apigee-mcp-server — container bidang data MCP yang terhubung ke pod MP.
  • apigee-mcp-server-config — sidecar konfigurasi (mode biner apigee-watcher) yang mengambil paket konfigurasi dari bidang kontrol Apigee dan menuliskannya ke volume bersama yang dibaca oleh penampung bidang data MCP.

MCP ApigeeDeployment (resource kustom Kubernetes, bukan Deployment):

kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                              STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   running                 2m

Status yang diharapkan adalah running. Selain itu, pastikan pod yang mendasarinya adalah 2/2 Running:

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                                    READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH   2/2     Running   0          2m

Layanan MCP:

kubectl get svc -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                              TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                              AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   ClusterIP   10.96.42.17   <none>        80/TCP,443/TCP,15021/TCP,15000/TCP   2m

HorizontalPodAutoscaler MCP:

kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server

Pastikan MINPODS cocok dengan mcpServer.replicaCountMin dari overrides.yaml (default 2) dan MAXPODS cocok dengan mcpServer.replicaCountMax (default 10). Kolom TARGETS, REPLICAS, dan AGE bergantung pada metrik aktif dan status cluster.

Verifikasi bahwa pod Message Processor menerima entri hostAliases

Setiap pod MP harus menampilkan entri yang disisipkan — jika satu pod saja tidak memilikinya, pod tersebut tidak dapat merutekan panggilan alat MCP. Mencantumkan semua pod MP dan hostAliases-nya:

kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

Output yang diharapkan: setiap pod MP mencantumkan array hostAliases yang berisi satu entri dengan dua nama host yang mengarah ke ClusterIP Layanan MCP dari langkah sebelumnya (nama host kedua menggunakan nama org Anda dalam huruf kecil). Nama pod Message Processor mengikuti template apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, dengan TRUNCATED_ORG adalah nama organisasi Anda (dipangkas agar sesuai dengan batas nama Kubernetes 63 karakter jika nama organisasi Anda panjang), ENV_GROUP_HASH adalah hash grup deployment per lingkungan, REV adalah nomor revisi rilis saat ini (empat digit, misalnya 1170), dan POD_HASH adalah akhiran acak per pod. Contoh:

apigee-runtime-myorg-env1-abc12-1170-def34   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
apigee-runtime-myorg-env1-abc12-1170-ghi56   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]

Jika ada pod yang menampilkan nilai hostAliases kosong, ApigeeDeployment Message Processor tidak sepenuhnya mengambil spesifikasi pod yang diperbarui. Lakukan rilis canary bertahap baru dengan menghapus pod Message Processor saat ini; pengontrol ApigeeDeployment akan merender ulang pod tersebut dari spesifikasi saat ini (yang kini menyertakan entri hostAliases):

kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime

Pengontrol ApigeeDeployment akan membuat ulang pod dalam satu menit. Perhatikan bahwa kubectl rollout restart deploy (perintah Kubernetes standar) tidak berfungsi di Message Processor karena Message Processor di-deploy sebagai resource kustom ApigeeDeployment, bukan Deployment.

Penginstalan selesai

Ketiga pemeriksaan sebelumnya bersama-sama mengonfirmasi bahwa bidang data MCP Anda berjalan dan dapat dialamatkan MP:

  • Setiap pod MCP adalah 2/2 Running. Kontainer data plane MCP gagal dalam pemeriksaan kesiapan Kubernetes di port 15021 jika sertifikat TLS yang dikeluarkan operator tidak dimuat dan sidecar belum memuat konfigurasi MCP awalnya, sehingga pod Ready memiliki kedua prasyarat tersebut.
  • Spesifikasi setiap pod MP berisi entri hostAliases yang menyematkan mcp.apigee.internal dan ORG_NAME.mcp.apigee.internal ke ClusterIP Layanan MCP. Oleh karena itu, pod MP dapat me-resolve endpoint target proxy MCP ke bidang data MCP dalam cluster Anda.
  • Pod MP menyelesaikan mcp.apigee.internal ke ClusterIP Layanan MCP melalui entri hostAliases yang disuntikkan.

Anda memverifikasi traffic alat MCP end-to-end (panggilan initialize atau tools/list MCP yang sebenarnya melalui ingress Apigee) sebagai bagian dari MCP quickstart bersama, setelah Anda men-deploy Proxy Penemuan MCP pertama.

Jika salah satu dari tiga pemeriksaan sebelumnya gagal, lihat Memecahkan masalah deployment MCP sebelum melanjutkan ke panduan memulai.

Langkah 6: Aktifkan MCP di cluster yang tersisa

Permintaan MCP untuk nama host tertentu dapat dirutekan ke cluster mana pun yang melayani grup lingkungan Apigee yang sesuai. Jika MCP diaktifkan di beberapa cluster dan tidak diaktifkan di cluster lain dalam grup lingkungan yang sama, permintaan MCP yang dirutekan ke cluster tanpa MCP yang diaktifkan akan gagal (biasanya ditampilkan ke klien sebagai 503 Service Unavailable).

Aktifkan MCP secara seragam di setiap cluster yang melayani grup lingkungan yang sama. Untuk setiap cluster tambahan, ulangi Langkah 1, 3, 4, dan 5. Anda tidak perlu mengulangi Langkah 2 (memberikan akses identitas pengamat): pemberian ini dicakup ke organisasi Apigee dan berlaku untuk semua cluster dalam organisasi yang sama.

Rollback

Untuk menonaktifkan MCP di cluster, tetapkan enableMcpServer: false (atau hapus kolom seluruhnya) di overrides.yaml, lalu upgrade diagram apigee-org:

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml

Kolom enableMcpServer hanya digunakan oleh diagram apigee-org, sehingga diagram operator tidak perlu diupgrade selama penonaktifan. Operator Apigee (tidak berubah) mengambil perubahan konfigurasi dari resource kustom ApigeeOrganization, menghapus resource MCP, dan menghapus entri hostAliases dari spesifikasi pod Message Processor, yang memicu rilis apigee-runtime ApigeeDeployment. Lakukan pembatalan dalam masa pemeliharaan yang disetujui.

Setelah rollback, Proxy Penemuan MCP yang Anda deploy ke lingkungan Apigee masih ada di bidang kontrol Apigee, tetapi tidak ada cluster dalam grup lingkungan tersebut yang melayani traffic MCP. Batalkan deployment MCP Discovery Proxy untuk membatalkan fitur sepenuhnya, atau biarkan fitur tersebut di-deploy dan aktifkan kembali MCP di cluster nanti.

Referensi: Kolom MCP di overrides.yaml

Tabel berikut mencantumkan setiap kolom overrides.yaml Apigee hybrid yang mengontrol perilaku MCP dalam versi 1.17.0. Hanya enableMcpServer yang wajib diisi; semua kolom lainnya memiliki nilai default aman yang sesuai untuk sebagian besar penginstalan.

Definisi kolom cocok dengan default diagram Helm apigee-org untuk 1.17.0 hybrid.

Kolom Jenis Default Penyesuaian yang direkomendasikan
enableMcpServer boolean false Wajib. Tetapkan ke true untuk mengaktifkan MCP di cluster ini. Mengaktifkan/menonaktifkan kolom ini akan memicu rilis terbatas bertahap Message Processor. Aktifkan hanya dalam masa pemeliharaan dan tunggu hingga rilis selesai sebelum melanjutkan.
mcpServer.replicaCountMin integer 2 Tetap di 2 untuk HA. Tingkatkan hanya jika Anda memiliki traffic MCP tinggi sebagai dasar ; HPA akan melakukan penskalaan otomatis saat CPU tertekan. Sinyal: HPA berkelanjutan di replicaCountMax dan CPU di atas target.
mcpServer.replicaCountMax integer 10 Tingkatkan jika Anda mengamati HPA dibatasi pada 10 selama puncak. Sinyal: kubectl top pods -l app=apigee-mcp-server menunjukkan semua pod yang mendekati batas CPU pada puncak penggunaan. Jika metrics-server tidak diinstal, gunakan kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server dan periksa apakah kolom REPLICAS berada di batas MAXPODS.
mcpServer.targetCPUUtilizationPercentage integer 70 Lebih rendah ke 50–60 untuk beban kerja yang sensitif terhadap latensi (menskalakan lebih awal). Naikkan menjadi 80–85 untuk mengurangi jumlah replika di cluster yang sensitif terhadap biaya. Sinyal: Latensi permintaan p95 berkorelasi dengan CPU per pod.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi Tingkatkan permintaan jika pod sering dihentikan karena kehabisan memori atau CPU dibatasi pada kondisi stabil. Sinyal: kubectl describe pod menunjukkan kondisi OOMKilled atau pembatasan.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Tingkatkan batas CPU sebelum meningkatkan jumlah replika saat latensi p95 tinggi, tetapi QPS keseluruhan rendah (beberapa permintaan mahal). Naikkan batas memori hanya jika Anda melihat OOMKills.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Jarang memerlukan penyesuaian. Sidecar secara berkala menyusun dan menulis paket konfigurasi; CPU dalam kondisi stabil sangat minimal.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Jarang memerlukan penyesuaian. Tingkatkan memori hanya jika Anda men-deploy sejumlah besar alat MCP yang tidak biasa dalam satu Discovery Proxy.
mcpServer.terminationGracePeriodSeconds integer 30 Jarang memerlukan penyesuaian. Tingkatkan jika permintaan MCP dalam proses yang berjalan lama memerlukan lebih banyak waktu untuk diselesaikan selama pengurasan pod.
mcpServer.annotations map {} Tambahkan anotasi pod tambahan jika cluster Anda memerlukannya.
mcpServer.serviceAccountPath string unset Biarkan tidak disetel kecuali jika Anda memerlukan pemisahan identitas per komponen. Jika tidak disetel, MCP akan kembali ke watcher.serviceAccountPath, lalu ke envs[].serviceAccountPaths.runtime. Identitas apigee-watcher sudah memiliki izin yang diperlukan sidecar MCP. Jalur ke file JSON kunci akun layanan Google Cloud jika Anda mengganti. Tidak dapat muncul bersamaan dengan mcpServer.gsa.

Sebaiknya gunakan Workload Identity (GKE) atau Workload Identity Federation (AKS/EKS) jika memungkinkan. Kunci akun layanan berbasis file harus diubah, disimpan dengan aman, didistribusikan ke setiap cluster, dan merupakan sumber kebocoran yang paling umum ke dalam artefak dukungan (lihat Kasus dukungan).
mcpServer.gsa string unset Biarkan tidak disetel kecuali jika Anda memerlukan pemisahan identitas per komponen. Jika tidak disetel, MCP akan kembali ke watcher.gsa, lalu ke gcp.workloadIdentity.gsa. Identitas apigee-watcher sudah memiliki izin yang diperlukan sidecar MCP, sehingga menggunakan kembali identitas tersebut adalah cara yang direkomendasikan. Ganti dengan email akun layanan Google Cloud khusus hanya jika organisasi Anda memerlukan identitas yang berbeda untuk sidecar MCP karena alasan audit.
mcpServer.serviceAccountRef string unset Lanjutan. Nama Secret Kubernetes yang ada di namespace Apigee yang menyimpan kunci akun layanan Google Cloud untuk sidecar MCP. Gunakan ini hanya jika Anda mengelola Secret kunci akun layanan di luar diagram Helm Apigee. Tidak dapat muncul bersamaan dengan mcpServer.serviceAccountPath dan mcpServer.gsa.
mcpServer.podDisruptionBudget map unset PodDisruptionBudget opsional untuk pod MCP. Menerima minAvailable atau maxUnavailable (string bilangan bulat atau persentase). Tetapkan salah satu, bukan keduanya. Biarkan tidak disetel kecuali jika cluster Anda memiliki kebijakan gangguan sukarela yang ketat yang memerlukan anggaran eksplisit.
mcpServer.tolerations list unset (kembali ke tolerations tingkat teratas) Toleransi Kubernetes standar untuk pod MCP. Ditetapkan hanya jika pod MCP harus mentoleransi taint yang tidak ditoleransi oleh komponen Apigee lainnya.
mcpServer.image.pullPolicy string IfNotPresent Kebijakan pull image untuk penampung server MCP. Jarang berubah.
mcpServer.sidecar.image.pullPolicy string IfNotPresent Kebijakan pull image untuk container sidecar MCP. Jarang berubah.

Memperkirakan kapasitas alat MCP

Apigee Hybrid tidak menerapkan jumlah maksimum tetap alat MCP per organisasi. Sebagai gantinya, kapasitas alat dibatasi oleh empat batas ukuran tetap yang diterapkan pada waktu deployment atau permintaan. Apakah sejumlah alat tertentu cocok atau tidak bergantung pada ukuran setiap alat, yang berasal dari spesifikasi OpenAPI yang menentukan alat tersebut.

Kapasitas standar

Untuk sebagian besar spesifikasi OpenAPI — campuran alat dengan jumlah parameter, ukuran isi permintaan, dan panjang deskripsi yang bervariasi, dengan sebagian besar alat termasuk dalam rentang ukuran kecil hingga sedang — Anda biasanya dapat menyesuaikan 10.000 alat MCP per organisasi pada batas ukuran respons tools/list default.

Kapasitas sebenarnya bervariasi dengan bentuk spesifik spesifikasi OpenAPI Anda. Organisasi yang spesifikasinya didominasi oleh alat dengan banyak parameter, isi permintaan yang besar, atau deskripsi yang panjang akan memiliki proporsi alat yang lebih sedikit sebelum mencapai salah satu dari empat batas keras di bawah. Untuk memvalidasi kapasitas untuk spesifikasi tertentu, ikuti Perkirakan kapasitas untuk spesifikasi Anda di bawah.

Batas ketat

Empat batas ukuran berlaku di Apigee Hybrid versi 1.17.0. Batas terendah yang berlaku adalah batas yang mengikat; menaikkan satu batas tidak akan menaikkan batas lainnya.

Batas Nilai Cakupan Mode kegagalan
Ukuran file spesifikasi OpenAPI 3 MiB per .yaml file 400 saat validasi proxy
Ukuran paket proxy MCP (didekompresi) 50 MiB per MCP Discovery Proxy 400 saat validasi proxy
Ukuran respons tools/list 10 MiB (default) per nama host 502 dengan TooBigBody
Nama host per grup lingkungan 100 per grup lingkungan 400 saat pembaruan environment group

Yang memengaruhi ukuran per alat

Ukuran per alat hampir seluruhnya terdiri dari inputSchema alat, yang berasal dari spesifikasi OpenAPI parameters dan requestBody untuk operasi. Tiga properti yang paling penting:

  • Jumlah parameter. Setiap entri parameter berkontribusi sekitar 100 byte terhadap ukuran alat dalam respons tools/list.
  • Jumlah properti isi permintaan. Setiap properti isi permintaan berkontribusi sekitar 100 byte. Oleh karena itu, operasi dengan isi permintaan (biasanya POST dan PUT) jauh lebih besar daripada operasi tanpa isi permintaan (biasanya GET dan DELETE).
  • Panjang deskripsi. Deskripsi operasi disalin hampir kata demi kata ke dalam alat, sehingga deskripsi yang lebih panjang akan langsung meningkatkan ukuran alat.

Skema respons tidak diperhitungkan dalam anggaran ukuran. Hanya parameters dan requestBody yang mencapai konfigurasi MCP. Oleh karena itu, penentuan ukuran kapasitas hanya berdasarkan ukuran file OpenAPI cenderung melebih-lebihkan biaya, karena sebagian besar spesifikasi OpenAPI yang sebenarnya menyertakan definisi skema respons yang tidak memengaruhi ukuran alat.

Memperkirakan kapasitas untuk spesifikasi Anda

Cara paling andal untuk memperkirakan kapasitas alat untuk spesifikasi OpenAPI Anda adalah dengan mengukur subset representatif:

  1. Deploy MCP Discovery Proxy yang mereferensikan subset kecil representatif dari alat yang akan Anda publikasikan (misalnya, 50 hingga 100 alat yang mencerminkan campuran jumlah parameter, ukuran isi permintaan, dan panjang deskripsi dalam spesifikasi lengkap Anda).
  2. Panggil tools/list terhadap proxy yang di-deploy dan catat ukuran respons dalam byte dan jumlah alat yang ditampilkan.
  3. Bagi ukuran respons dengan jumlah alat untuk mendapatkan ukuran rata-rata per alat untuk spesifikasi Anda.
  4. Bagi batas ukuran respons tools/list yang berlaku (10 MiB secara default) dengan rata-rata tersebut untuk memperkirakan jumlah maksimum alat yang sesuai dengan satu nama host untuk spesifikasi bentuk ini.

Meningkatkan kapasitas

Dua mekanisme meningkatkan kapasitas alat di luar default:

  • Bagikan alat di seluruh nama host. Batas respons tools/list adalah per nama host. Membagi alat di beberapa nama host dalam grup lingkungan yang sama akan melipatgandakan ruang kosong per nama host (tunduk pada batas 100 nama host per grup lingkungan). Sharding tidak menaikkan batas paket per-proxy; batas paket 50 MiB terus berlaku di semua nama host pada satu Proxy Penemuan MCP.
  • Naikkan batas ukuran respons tools/list. Batas defaultnya adalah 10 MiB per nama host. Anda dapat menaikkannya hingga 30 MiB. Setidaknya, hal ini melibatkan penetapan envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory, dan envs.components.runtime.cwcAppend.bin_setenv_max_mem di overrides.yaml, lalu menjalankan helm upgrade pada diagram apigee-org. Lihat Mengonfigurasi dukungan payload pesan besar di Apigee Hybrid untuk mengetahui prosedur lengkap, termasuk varian per lingkungan versus seluruh penginstalan, panduan penetapan ukuran heap Message Processor, dan contoh overrides.yaml lengkap. Menaikkan batas respons tidak akan memengaruhi batas ukuran paket proxy MCP 50 MiB; jika kapasitas Anda dibatasi oleh batas tersebut, perubahan ini tidak akan membantu.

Keamanan

Batas kepercayaan

Bidang data MCP berjalan di dalam cluster Kubernetes Anda sendiri. Google tidak memiliki akses runtime ke data plane. Bidang kontrol Apigee menyajikan konfigurasi MCP yang berasal dari Spesifikasi OpenAPI Anda; bidang ini tidak mengamati traffic permintaan MCP. Data konfigurasi saat istirahat disimpan dalam bucket Cloud Storage yang dikelola Apigee dan dicakup ke project tenant Apigee Anda, diambil oleh sidecar MCP menggunakan akun layanan Google Cloud ambient-nya.

Operator Apigee menyediakan Role dan RoleBinding Kubernetes yang tercakup dalam MCP di namespace Apigee Anda (APIGEE_NAMESPACE) untuk ServiceAccount bidang data MCP. Peran memberikan akses hanya baca:

  • get, list, watch di services dalam grup API inti.
  • get, list, watch di apigeeroutes dalam grup API apigee.cloud.google.com.

Peran tidak memberikan izin penulisan dan tidak memberikan akses ke Secrets, ConfigMaps, atau status pod. Auditor Anda dapat memverifikasi aturan yang tepat langsung dari cluster dengan:

APIGEE_ORG_CR=$(kubectl get apigeeorganization -n APIGEE_NAMESPACE \
  -o jsonpath='{.items[0].metadata.name}')
kubectl get role,rolebinding -n APIGEE_NAMESPACE \
  --field-selector metadata.name=apigee-mcp-server-$APIGEE_ORG_CR -o yaml

Role dan RoleBinding apigee-mcp-server-APIGEE_ORG_CR adalah resource RBAC yang tercakup dalam MCP; namanya mencakup nama lengkap resource kustom ApigeeOrganization Anda (yang berasal dari nama organisasi Apigee dan hash singkat). Resource ini tidak memiliki label app=apigee-mcp-server di tingkat resource (hanya pod yang memilikinya), sehingga penelusuran berbasis label tidak akan menampilkan hasil. Jika perintah field-selector di atas tidak menampilkan apa pun, cantumkan setiap resource RBAC terkait MCP di namespace dengan:

kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server

TLS antara Message Processor dan bidang data MCP

Pod Message Processor memanggil bidang data MCP di https://mcp.apigee.internal/ atau https://ORG_NAME.mcp.apigee.internal/. Nama host ini di-resolve ke ClusterIP Layanan MCP melalui entri hostAliases yang disuntikkan. Penampung bidang data MCP menyajikan sertifikat TLS yang ditandatangani oleh penerbit yang disediakan Apigee-operator (ClusterIssuer bernama apigee-ca-issuer). Nama Alternatif Subjek sertifikat mencakup kedua nama host.

Membatasi akses masuk ke Layanan MCP

Di Apigee hybrid 1.17.0, bidang data MCP tidak mengautentikasi pemanggilnya secara independen. Proxy ini memercayai bahwa permintaan yang sampai kepadanya telah diautentikasi oleh proxy MCP Apigee yang berjalan di Message Processor. Satu-satunya pemanggil yang dimaksudkan untuk Layanan MCP adalah Message Processor. Workload dalam cluster lainnya yang dapat menjangkau ClusterIP Layanan MCP di TCP 443 dapat memanggil alat MCP tanpa pemeriksaan autentikasi.

Batasi akses masuk ke pod MCP hanya untuk pod Message Processor, menggunakan mesin kebijakan ingress cluster platform Anda (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy, atau yang setara). Batasan:

  • Mengizinkan ingress ke pod dengan label app=apigee-mcp-server di namespace APIGEE_NAMESPACE pada TCP 443 dari pod dengan label app=apigee-runtime di namespace yang sama saja.
  • Menolak semua ingress lainnya pada TCP 443 ke pod dengan label app=apigee-mcp-server.
  • Menolak semua ingress dalam cluster pada TCP 15021 ke pod dengan label app=apigee-mcp-server. Port 15021 menyediakan endpoint HTTP biasa /healthz/ready yang tidak diautentikasi dan digunakan oleh kubelet untuk probing kesiapan; kubelet mencapainya secara langsung di IP pod, sehingga tidak ada workload dalam cluster lain yang dapat mencapai pod MCP di 15021.

Terapkan batasan ini sebelum Anda menyelesaikan panduan memulai MCP dan men-deploy Proxy Penemuan MCP pertama Anda di lingkungan non-pengembangan.

Kontrak keaktualan konfigurasi

Saat sidecar MCP berhasil menarik konfigurasi, penampung bidang data MCP memuat paket yang diambil dan terus menayangkannya hingga penarikan berikutnya berhasil. Jika penarikan berikutnya gagal (bidang kontrol Apigee tidak dapat dijangkau, Cloud Storage tidak dapat dijangkau, izin IAM dihapus di akun layanan watcher, atau terjadi error di tahap lain dalam pipeline penarikan), sidecar akan terus menayangkan paket terakhir yang diketahui berfungsi dengan baik tanpa batas waktu. Tidak ada batas kedaluwarsa bawaan di 1.17.0: pod tetap Ready dan traffic alat MCP terus ditayangkan terhadap bundle yang sudah kedaluwarsa. Sinyal bahwa konfigurasi telah berhenti diperbarui adalah baris log sidecar di tingkat ERROR yang membawa penghitung consecutive_failures (lihat Memecahkan masalah deployment MCP untuk mengetahui pesan spesifik yang dikeluarkan sidecar per tahap kegagalan).

Untuk lingkungan produksi yang diatur, lakukan penomoran pada peningkatan berulang penghitung ini. Pemberitahuan yang layak minimum adalah: halaman saat container sidecar MCP memancarkan baris log tingkat ERROR dengan consecutive_failures mencapai batas yang Anda tetapkan berdasarkan toleransi keterlambatan. Nilai yang meningkat menunjukkan bahwa sidecar telah berhenti memperbarui konfigurasi; sidecar terus menayangkan paket yang terakhir berhasil untuk sementara.

Jika sidecar telah berhenti memperbarui konfigurasi, selidiki mode kegagalan dari log sidecar; lihat Memecahkan masalah deployment MCP. Menghentikan dan memulai kembali pod MCP tidak menyelesaikan masalah pengambilan data yang mendasarinya karena pod yang baru dibuat menggunakan jalur pengambilan data yang sama.

Persyaratan jaringan keluar

Sidecar MCP (penampung konfigurasi di dalam setiap pod MCP) memerlukan akses jaringan keluar ke endpoint berikut di TCP 443. Pilih tab yang sesuai dengan apakah organisasi Apigee Anda menggunakan residensi data; endpoint yang diperlukan berbeda.

Tidak ada residensi data

Endpoint Digunakan untuk
apigee.googleapis.com Mengambil referensi konfigurasi MCP saat ini untuk organisasi Anda dari bidang kontrol Apigee pada setiap refresh konfigurasi.
storage.googleapis.com Download konfigurasi MCP organisasi Anda dari Google Cloud Storage.

Residensi data

Jika organisasi Apigee Anda menggunakan residensi data, sidecar MCP akan mengakses endpoint bidang kontrol Apigee regional Anda (endpoint yang sama dengan yang digunakan oleh komponen Apigee hybrid lainnya, yang dikonfigurasi melalui nilai chart contractProvider di overrides.yaml Anda). Ganti CONTROL_PLANE_LOCATION dengan lokasi bidang kontrol organisasi Anda (misalnya, us, eu).

Endpoint Digunakan untuk
CONTROL_PLANE_LOCATION-apigee.googleapis.com Ambil referensi konfigurasi MCP saat ini untuk organisasi Anda dari endpoint bidang kontrol Apigee regional pada setiap refresh konfigurasi.
storage.googleapis.com Download konfigurasi MCP organisasi Anda dari Google Cloud Storage. Bucket berada di region organisasi Anda; Cloud Storage akan merutekan ke bucket tersebut secara otomatis.

Selain itu, sidecar harus dapat memperoleh token akses Google Cloud untuk kredensial sekitar yang dijalankan pod (melalui Workload Identity atau kunci akun layanan berbasis file). Endpoint pertukaran token tertentu bergantung pada jalur autentikasi Anda dan merupakan endpoint yang sama dengan yang sudah digunakan oleh komponen Apigee hybrid lainnya di cluster Anda. Jika traffic hybrid Apigee yang ada ke Google Cloud API berhasil dari namespace ini, pertukaran token MCP sidecar juga akan berhasil.

Selain itu, sidecar memerlukan akses dalam cluster ke server API Kubernetes (melalui alamat layanan dalam cluster standar) untuk memublikasikan status keaktifan dan kesiapannya. Traffic ini tidak pernah keluar dari cluster Anda.

Pemecahan masalah

Untuk mengetahui checklist diagnostik lengkap, lihat Memecahkan masalah deployment MCP, yang mencakup checklist diagnostik sisi cluster untuk Apigee Hybrid.

Kegagalan penginstalan umum

Gejala Penyebab dan perbaikan
helm upgrade selesai, tetapi tidak ada referensi MCP yang muncul. Diagram organisasi diupgrade sebelum diagram operator. Jalankan helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ terlebih dahulu, lalu jalankan kembali helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/.
Pod MCP macet di ContainerCreating atau 1/2 Ready. Dua penyebab umum: cert-manager Certificate untuk MCP belum dikeluarkan, atau penarikan image penampung gagal. Jalankan kubectl describe pod di pod yang terpengaruh untuk mengetahui alasan yang tepat.
Laporan log Sidecar (apigee-mcp-server-config) no MCP config from CP yet; skipping tick, pod stays Ready via seed di setiap polling. Status stabil yang diharapkan saat tidak ada MCP Discovery Proxy yang di-deploy untuk organisasi Anda. Bidang kontrol Apigee menampilkan referensi konfigurasi kosong dan bidang data MCP hanya memuat pendengar kesiapan Kubernetes di port 15021; port permintaan MCP 8443 belum memiliki pendengar, dan permintaan ke https://mcp.apigee.internal/mcp menerima koneksi ditolak. Untuk bertransisi ke status penayangan, ikuti panduan memulai MCP untuk men-deploy Proxy Penemuan MCP ke lingkungan dalam grup lingkungan yang ditayangkan oleh cluster ini.
Log sidecar melaporkan CP fetch failed dengan HTTP 403 atau PermissionDenied yang disematkan. Akun layanan Google Cloud watcher Apigee telah kehilangan peran roles/apigee.runtimeAgent (yang memberikan izin apigee.runtimeconfigs.get yang diperlukan sidecar) di project tenant Apigee Anda. Penginstalan hybrid Apigee dasar memberikan peran ini secara otomatis; jika peran ini telah dihapus oleh pembersihan otomatis IAM, terapkan kembali di akun layanan Google Cloud apigee-watcher.
Log sidecar melaporkan CP fetch failed dengan context deadline exceeded, error DNS, atau error TLS. Sidecar tidak dapat menjangkau apigee.googleapis.com atau storage.googleapis.com dari dalam cluster Anda. Verifikasi keluar terhadap tiga endpoint yang tercantum di Persyaratan jaringan keluar di atas.
Pod Message Processor tidak dimulai ulang setelah helm upgrade. Pastikan entri hostAliases ada di setiap pod MP: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. Jika ada pod yang kosong, paksa rendering baru dengan menghapus pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). Pengontrol ApigeeDeployment akan membuatnya ulang dari spesifikasi saat ini, yang mencakup entri hostAliases. Jangan gunakan kubectl rollout restart deploy; karena tidak berlaku untuk ApigeeDeployment.
Log pod MP menampilkan error handshake TLS saat memanggil https://mcp.apigee.internal/ atau https://ORG_NAME.mcp.apigee.internal/ setelah traffic alat MCP mulai mengalir melalui quickstart. Penampung data plane MCP menayangkan sertifikat yang Nama Alternatif Subjek (SAN) tidak menyertakan nama host yang dihubungi MP. Verifikasi sertifikat: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, lalu kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. dnsNames sertifikat harus menyertakan mcp.apigee.internal dan ORG_NAME.mcp.apigee.internal huruf kecil. Jika tidak, hapus resource MCP Certificate dan biarkan cert-manager menerbitkan ulang.

Langkah berikutnya