Questa pagina si applica ad Apigee e ad Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Questa pagina descrive come attivare il protocollo Model Context Protocol (MCP) in un cluster Apigee hybrid esistente con versione 1.17.0 o successive. Una volta completata questa procedura, il cluster esegue un nuovo piano dati MCP in-cluster e il processore di messaggi è pronto per indirizzare le chiamate allo strumento MCP. Puoi quindi eseguire il deployment del tuo primo proxy di rilevamento MCP seguendo la guida rapida di MCP condivisa.
Per i concetti, l'architettura e i dettagli delle funzionalità di MCP condivisi tra Apigee e Apigee hybrid, consulta la panoramica di MCP in Apigee.
A cosa serve questa procedura
L'abilitazione di MCP su un cluster Apigee hybrid comporta le seguenti modifiche:
- Concede all'identità
apigee-watcherl'accesso alla configurazione MCP sul control plane di Apigee. Aggiungi il service accountapigee-watcherall'elencowatcher_identitiesdella risorsacontrolPlaneAccessdella tua organizzazione Apigee in modo che il sidecar MCP possa estrarre i bundle di configurazione MCP dal control plane di Apigee. Si tratta di una modifica del control plane, limitata all'organizzazione Apigee, ed è un passaggio una tantum per organizzazione, indipendentemente dal numero di cluster che la gestiscono. - Aggiunge un nuovo piano dati MCP in-cluster. Viene creato un nuovo set di pod MCP nello stesso spazio dei nomi Kubernetes in cui è installato Apigee hybrid (
apigeepredefinito), insieme alle risorse Kubernetes di supporto (Service, Horizontal Pod Autoscaler e RBAC) necessarie per eseguirli. Le chiamate allo strumento MCP vengono gestite da questi pod. - Configura il processore di messaggi per raggiungere il piano dati MCP. L'operatore Apigee aggiorna la specifica del pod del processore di messaggi in modo che il processore di messaggi indirizzi le chiamate allo strumento MCP al nuovo piano dati MCP nel cluster. L'applicazione di questa modifica attiva una release canary in più fasi del processore di messaggi (gestito dal controller
ApigeeDeployment); il pod precedente continua a gestire il traffico finché il nuovo pod non èReady. La release viene attivata solo durante le transizioni di attivazione e disattivazione, non durante l'attività MCP in corso o il traffico MCP in stato stabile. Esegui questa procedura in un periodo di manutenzione approvato e attendi il completamento della release prima di procedere.
Passaggio 1: modifica overrides.yaml
Apri il file overrides.yaml che utilizzi per i chart Helm di Apigee hybrid. Al livello superiore del file, aggiungi:
enableMcpServer: true
Questa è la configurazione minima richiesta per attivare MCP. Utilizza i valori predefiniti integrati del grafico apigee-org: due repliche del piano dati MCP con scalabilità automatica fino a dieci con un utilizzo della CPU del 70%, con richieste di risorse di 500m CPU e 512Mi di memoria e limiti di 2000m CPU e 1Gi di memoria sul container del piano dati MCP. Per personalizzare i conteggi delle repliche, le richieste di risorse o il account di servizio MCP, consulta Riferimento: campi MCP in overrides.yaml più avanti in questa pagina.
Di seguito sono riportati esempi completi di un overrides.yaml unito, uno per ogni stile di autenticazione. Utilizza l'esempio corrispondente alla configurazione dell'installazione di base esistente. Le righe specifiche per MCP sono evidenziate con commenti e sono le stesse in tutte e tre le varianti.
Scegli la scheda corrispondente al modo in cui l'installazione di base autentica i componenti Apigee su Google Cloud. La selezione si applica a ogni blocco di codice con ambito variante in questa pagina.
Workload Identity (GKE)
Utilizza questa variante se l'installazione di base autentica i componenti Apigee su Google Cloud tramite Workload Identity di GKE (nessun file della chiave account di servizio sul disco).
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. 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: {} # ----------------------------------------------------------------------------
Chiavi dei account di servizio basate su file
Utilizza questa variante se l'installazione di base autentica i componenti Apigee in Google Cloud tramite i file delle chiavi dei account di servizio che distribuisci a ogni 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 guardrails: serviceAccountPath: ./service-accounts/apigee-non-prod.json mart: serviceAccountPath: ./service-accounts/apigee-non-prod.json connectAgent: serviceAccountPath: ./service-accounts/apigee-non-prod.json watcher: serviceAccountPath: ./service-accounts/apigee-non-prod.json # MCP also uses this key file 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: {} # ----------------------------------------------------------------------------
Federazione delle identità per i workload (AKS/EKS)
Utilizza questa variante se l'installazione di base è su AKS o EKS e l'autenticazione su Google Cloud avviene tramite la federazione delle identità per i workload. MCP utilizza il file di configurazione delle credenziali già utilizzato da apigee-watcher, da watcher.serviceAccountPath, quindi non aggiungi alcuna configurazione dell'identità specifica per MCP. Se invece memorizzi la configurazione delle credenziali in un secret di Kubernetes, consulta Altri meccanismi di identità.
Aggiungi la chiave di primo livello MCP alla configurazione WIF esistente overrides.yaml:
# ---- 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: {} # ----------------------------------------------------------------------------
Lascia mcpServer.gsa e mcpServer.serviceAccountPath non impostati. Il sidecar MCP utilizza lo stesso file di configurazione delle credenziali di apigee-watcher, da watcher.serviceAccountPath.
Passaggio 2: concedi all'identità watcher l'accesso alla configurazione MCP sul control plane
Il sidecar MCP recupera il bundle di configurazione dal control plane Apigee utilizzando l'account di servizio Google Cloud del componente apigee-watcher (l'identità selezionata nel passaggio 1). Prima dell'avvio dei pod MCP, aggiungi quell'account di servizio alwatcher_identities elenco sulla tua organizzazione ApigeecontrolPlaneAccess risorsa. Senza questa concessione, le chiamate del sidecar MCP a apigee.googleapis.com per recuperare il riferimento alla configurazione MCP restituiscono 404 Not Found e il piano dati MCP non diventa mai pronto per gestire il traffico degli strumenti.
Questo passaggio viene eseguito una sola volta per organizzazione (non per cluster). Salta questo passaggio se hai già concesso l'accesso per un cluster precedente nella stessa organizzazione Apigee.
- Imposta le variabili della shell che utilizzi per la chiamata API. Riutilizza i valori dell'installazione:
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)
Dove:
YOUR_ORG_NAMEè il nome della tua organizzazione Apigee hybrid.YOUR_GCP_PROJECT_IDè il progetto Google Cloud che ospita la tua organizzazione Apigee Hybrid.WATCHER_SAè l'indirizzo email del account di servizioapigee-watcher. Se hai eseguito l'override diwatcher.gsainoverrides.yaml, utilizza questo valore anziché quello predefinitoapigee-watcher@${PROJECT_ID}..
- Chiama l'API updateControlPlaneAccess per aggiungere il account di servizio watcher all'elenco
watcher_identities:Nessuna residenza dei dati
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}\"]}"Residenza dei dati
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}\"]}"Dove
CONTROL_PLANE_LOCATIONè la località dei dati del control plane se l'installazione di Apigee Hybrid utilizza la residenza dei dati. Per l'elenco delle località disponibili, consulta Regioni del control plane delle API Apigee disponibili.La chiamata restituisce un'operazione a lunga esecuzione. Attendi il completamento prima di eseguire il passaggio di verifica riportato di seguito.
- Verifica che la concessione sia stata applicata. Chiama getControlPlaneAccess e verifica che il account di servizio watcher venga visualizzato nel campo
watcherIdentitiesdella risposta:Nessuna residenza dei dati
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"Residenza dei dati
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"La risposta deve includere un array
watcherIdentitiescontenente il tuo account di servizio watcher. Ad esempio:{ "synchronizerIdentities": [ ... ], "analyticsPublisherIdentities": [ ... ], "watcherIdentities": [ "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID." ] }
Se
watcherIdentitiesnon è presente nella risposta o non contiene il tuo account di servizio watcher, esegui nuovamente il comando PATCH e controlla lo stato dell'operazione per verificare la presenza di errori prima di procedere.
Passaggio 3: esegui l'upgrade del grafico apigee-operator
Esegui prima l'upgrade del grafico dell'operatore. Il grafico dell'operatore possiede lo schema per le nuove risorse MCP; il grafico dell'organizzazione fa riferimento a queste risorse. L'upgrade nell'ordine sbagliato comporta un helm upgrade riuscito che non crea pod MCP.
helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
Il comando viene completato in meno di un minuto. Verifica che il deployment dell'operatore sia stato completamente implementato con la nuova immagine (apigee-controller-manager Deployment è una risorsa Kubernetes standard, non un ApigeeDeployment, quindi il comando corretto è kubectl rollout status deploy):
kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m
Output previsto:
deployment "apigee-controller-manager" successfully rolled out
Passaggio 4: esegui l'upgrade del grafico apigee-org
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
Ora vengono eseguiti due loop di riconciliazione in parallelo:
- L'operatore Apigee crea il deployment, il servizio, l'HPA, il ServiceAccount, il ruolo e il RoleBinding di MCP. I pod MCP vengono visualizzati due alla volta (in base alla pianificazione di Kubernetes); il container sidecar in ogni pod esegue il primo recupero della configurazione dal control plane di Apigee poco dopo l'avvio.
- L'operatore Apigee inserisce la voce
hostAliasesnella specifica del pod del processore di messaggi, che attiva una release diapigee-runtimeApigeeDeployment.
Passaggio 5: verifica l'installazione
Verifica che il piano dati MCP sia in esecuzione
Esamina le quattro risorse relative a MCP create dall'operatore. I nomi delle risorse includono un suffisso derivato dall'organizzazione; gli esempi che seguono utilizzano ORG_CR_SUFFIX come segnaposto per questo suffisso, mentre i suffissi dei pod e il ClusterIP del servizio saranno diversi nel tuo ambiente.
Pod MCP (due per impostazione predefinita; scalabilità automatica fino a dieci in caso di carico):
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
Ogni pod deve mostrare 2/2 nella colonna READY. I due container in ogni pod sono:
apigee-mcp-server: il container del piano dati MCP a cui si connettono i pod MP.apigee-mcp-server-config: il sidecar di configurazione (una modalità del file binarioapigee-watcher) che recupera i bundle di configurazione dal control plane Apigee e li scrive in un volume condiviso letto dal container del piano dati MCP.
MCP ApigeeDeployment (una risorsa personalizzata Kubernetes, non una Deployment standard):
kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME STATE NESTEDSTATE AGE apigee-mcp-server-default-ORG_CR_SUFFIX running 2m
Lo stato previsto è running. Verifica anche che il pod sottostante sia 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
Servizio 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
Verifica che MINPODS corrisponda a mcpServer.replicaCountMin
del tuo overrides.yaml (valore predefinito 2) e che MAXPODS
corrisponda a mcpServer.replicaCountMax (valore predefinito 10). Le
colonne TARGETS, REPLICAS e AGE dipendono dalle
metriche live e dallo stato del cluster.
Verifica che i pod del processore di messaggi abbiano ricevuto la voce hostAliases
Ogni pod MP deve mostrare la voce inserita. Se anche un solo pod non la contiene, non può instradare le chiamate allo strumento MCP. Elenca tutti i pod MP e i relativi hostAliases:
kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
Output previsto: ogni pod MP elenca un array hostAliases contenente una voce con due nomi host che puntano al ClusterIP del servizio MCP del passaggio precedente (il secondo nome host utilizza il nome dell'organizzazione in minuscolo). I nomi dei pod del processore di messaggi seguono il modello apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, dove TRUNCATED_ORG è il nome della tua organizzazione (troncato per rientrare nel limite di 63 caratteri di Kubernetes se il nome della tua organizzazione è lungo), ENV_GROUP_HASH è un hash del gruppo di deployment per ambiente, REV è il numero di revisione della release corrente (quattro cifre, ad esempio 1170) e POD_HASH è un suffisso casuale per pod. Ad esempio:
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]]
Se un pod mostra un valore hostAliases vuoto, il processore di messaggi
ApigeeDeployment non ha acquisito completamente la specifica del pod aggiornata. Forza una
nuova versione canary temporanea eliminando i pod del processore di messaggi attuali; il
controller ApigeeDeployment li eseguirà nuovamente dalla specifica attuale
(che ora include la voce hostAliases):
kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime
Il controller ApigeeDeployment ricreerà i pod entro un minuto. Tieni presente che kubectl rollout restart deploy (il comando Kubernetes standard) non funziona sul processore di messaggi perché quest'ultimo viene distribuito come risorsa personalizzata ApigeeDeployment, non come Deployment.
Installazione completata
Insieme, i tre controlli precedenti confermano che il piano dati MCP è in esecuzione e indirizzabile tramite MP:
- Ogni pod MCP è
2/2 Running. Il container del piano dati MCP non supera il probe di idoneità di Kubernetes sulla porta15021se il certificato TLS emesso dall'operatore non è caricato e il sidecar non ha ancora caricato la configurazione MCP iniziale, quindi i podReadyhanno entrambe le precondizioni. - La specifica di ogni pod MP contiene la voce
hostAliasesche fissamcp.apigee.internaleORG_NAME.mcp.apigee.internalal ClusterIP del servizio MCP. I pod MP possono quindi risolvere gli endpoint target del proxy MCP nel piano dati MCP nel cluster. - Un pod MP risolve
mcp.apigee.internalnel ClusterIP del servizio MCP tramite la vocehostAliasesinserita.
Verifichi il traffico dello strumento MCP end-to-end (una chiamata MCP initialize o tools/list effettiva tramite l'ingresso Apigee) nell'ambito della guida rapida MCP condivisa, dopo aver eseguito il deployment del primo proxy di rilevamento MCP.
Se uno dei tre controlli precedenti non va a buon fine, consulta Risolvi i problemi relativi ai deployment MCP prima di procedere con la guida rapida.
Passaggio 6: abilita MCP sui cluster rimanenti
Le richieste MCP per un determinato nome host possono essere indirizzate a qualsiasi cluster che gestisce il gruppo di ambienti Apigee corrispondente. Se MCP è abilitato su alcuni cluster e non su altri nello stesso gruppo di ambienti, le richieste MCP che vengono indirizzate a un cluster senza MCP abilitato non vanno a buon fine (in genere vengono restituite al client come 503 Service Unavailable).
Abilita MCP in modo uniforme su ogni cluster che gestisce lo stesso gruppo di ambienti. Per ogni cluster aggiuntivo, ripeti i passaggi 1, 3, 4 e 5. Non è necessario ripetere il passaggio 2 (concedi l'accesso all'identità del watcher): questa concessione ha come ambito l'organizzazione Apigee e si applica a tutti i cluster della stessa organizzazione.
Verifica il protocollo MCP stateless (versione 1.17.4 e successive)
Le versioni 1.17.4 e successive di Apigee hybrid gestiscono il protocollo MCP stateless (versione 2026-07-28) per impostazione predefinita. Per verificare che la tua installazione lo supporti, chiama il metodo server/discover, che esiste solo nel protocollo stateless. Questo controllo richiede un proxy di rilevamento MCP di cui è stato eseguito il deployment, quindi eseguilo dopo aver completato la guida rapida di MCP.
Nelle versioni da 1.17.0 a 1.17.3, che gestiscono solo le versioni del protocollo MCP stateful, salta questo controllo.
La richiesta viene inviata a un nome host nel tuo gruppo di ambienti Apigee, in modo che qualsiasi cluster che gestisce il gruppo di ambienti possa rispondere. Il controllo verifica quindi il gruppo di ambienti, non un cluster specifico, e devi eseguirlo una sola volta per gruppo di ambienti. Per verificare che ogni cluster sia integro, utilizza i controlli per cluster nel Passaggio 5: verifica l'installazione.
curl -X POST "https://MCP_ENDPOINT_URL/mcp" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2026-07-28" \ -H "Mcp-Method: server/discover" \ -H "Authorization: Bearer TOKEN" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } }'
Sostituisci quanto segue:
MCP_ENDPOINT_URL: il nome host dell'endpoint MCP, ovvero un nome host registrato nel gruppo di ambienti Apigee e gestito dal gateway in entrata Apigee. Ad esempio,api.example.com.TOKEN: un token di accesso OAuth 2.0, obbligatorio se il proxy MCP verifica i token con una policy OAuthV2. Se il proxy utilizza una policy VerifyAPIKey, sostituisci la riga-H "Authorization: Bearer TOKEN"con la chiave API nell'intestazione o nel parametro di query letto dalla policy. Se il proxy accetta richieste non autenticate, rimuovi la riga.
Il gruppo di ambiente gestisce il protocollo MCP stateless se la risposta è HTTP
200 e l'array result.supportedVersions contiene
2026-07-28. Una risposta corretta è simile alla seguente:
{ "id": 1, "jsonrpc": "2.0", "result": { "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "SERVICE_NAME", "version": "1.0.0" } }, "cacheScope": "public", "capabilities": { "tools": { "listChanged": false } }, "resultType": "complete", "supportedVersions": [ "2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" ], "ttlMs": 0 } }
Nella risposta, SERVICE_NAME è il nome del servizio MCP che ha risposto. I campi cacheScope e ttlMs sono suggerimenti per la cache;
"ttlMs": 0 è il valore predefinito e non indica un errore.
Se la risposta è un errore, utilizzala per trovare la causa:
- HTTP
400conerror.code-32602eerror.messageUnsupported protocol version: i cluster eseguono le versioni di Apigee Hybrid dalla1.17.0alla1.17.3, che non gestiscono il protocollo stateless. Esegui l'upgrade alla versione1.17.4o successive. - Qualsiasi altro errore, ad esempio HTTP
401o403(autenticazione), HTTP404(nessun proxy MCP di cui è stato eseguito il deployment in/mcpsu questo gruppo di ambienti), HTTP503(piano dati MCP non integro) o un altro valoreerror.codeda una richiesta in formato non corretto: la causa non è la versione di Apigee hybrid. Consulta Risolvi i problemi dei deployment MCP.
Per l'insieme completo di requisiti ed errori delle richieste stateless, consulta Versioni del protocollo MCP supportate.
Esegui il rollback
Per disabilitare MCP su un cluster, imposta enableMcpServer: false (o rimuovi completamente il campo) in overrides.yaml, quindi esegui l'upgrade del grafico apigee-org:
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml
Il campo enableMcpServer viene utilizzato solo dal grafico apigee-org, pertanto non è necessario eseguire l'upgrade del grafico dell'operatore durante una disattivazione. L'operatore Apigee (invariato) rileva la modifica della configurazione dalla risorsa personalizzata ApigeeOrganization, elimina le risorse MCP e rimuove la voce hostAliases dalla specifica del pod del processore di messaggi, il che attiva un rilascio di apigee-runtime ApigeeDeployment. Esegui il rollback in un periodo di manutenzione approvato.
Dopo il rollback, i proxy di rilevamento MCP di cui hai eseguito il deployment nell'ambiente Apigee sono ancora presenti nel control plane di Apigee, ma nessun cluster in quel gruppo di ambienti gestisce il traffico MCP. Annulla il deployment dei proxy di rilevamento MCP per disattivare completamente la funzionalità o lasciali disponibili ed esegui nuovamente il deployment di MCP sui cluster in un secondo momento.
Configura mTLS tra il piano dati MCP e il gateway in entrata
Le chiamate allo strumento MCP escono dal piano dati MCP e rientrano nel cluster tramite il gateway in entrata Apigee, utilizzando gli stessi alias host e la stessa voce virtualhosts[] di qualsiasi altra chiamata API a quel gruppo di ambiente. Per impostazione predefinita, il piano dati MCP si connette al gateway in entrata tramite TLS unidirezionale: la connessione è criptata, ma il piano dati MCP non presenta alcun certificato client e non verifica il certificato del gateway in entrata.
A partire da Apigee hybrid 1.17.4, puoi attivare mutual TLS (mTLS) su questa connessione, per gruppo di ambienti, con il blocco virtualhosts[].mcpMtls. Con mTLS abilitato:
- Il piano dati MCP presenta un certificato client emesso da te, quindi il gateway in entrata autentica il piano dati MCP nello stesso modo in cui autentica qualsiasi altro client mTLS di quel gruppo di ambienti.
- Il piano dati MCP verifica che il certificato del gateway in entrata sia concatenato a una CA che hai nominato e che copra l'alias host chiamato. Entrambi i controlli sono attivi per impostazione predefinita e possono essere disattivati per gruppo di ambienti.
Configuri mTLS un gruppo di ambienti alla volta. I gruppi di ambienti senza mcpMtls continuano a utilizzare TLS unidirezionale, inclusi i gruppi di ambienti gestiti dallo stesso gateway in entrata, in modo da poter eseguire la migrazione in modo incrementale. Anche il certificato client e la CA di attendibilità sono per gruppo di ambiente: non esiste un certificato client MCP a livello di cluster e due gruppi di ambiente sullo stesso gateway in entrata possono presentare certificati client diversi emessi da CA diverse.
I campi mcpMtls riutilizzano deliberatamente i nomi dei campi TLS in entrata un livello più in alto, ma i ruoli sono invertiti, perché su questa connessione il piano dati MCP è il client e il gateway in entrata è il server:
| Campo | Meno di virtualhosts[].mcpMtls |
Direttamente sotto virtualhosts[] |
|---|---|---|
sslCertPath, sslKeyPath |
Il certificato client e la chiave che il piano dati MCP presenta al gateway in entrata.
Deve contenere l'utilizzo esteso della chiave clientAuth. |
Il certificato e la chiave del server del gateway in entrata. |
sslSecret |
Secret contenente il certificato e la chiave client (chiavi cert,
key). |
Secret contenente il certificato e la chiave del server del gateway in entrata. |
caCertPath o il nome sslSecret con l'aggiunta di -cacert |
La CA considerata attendibile dal piano dati MCP per il certificato del server del gateway in entrata. | La CA considerata attendibile dal gateway in entrata per i certificati client in entrata, inclusi quelli del piano dati MCP. |
Prima di iniziare
- Il cluster esegue Apigee hybrid
1.17.4o versioni successive, con i graficiapigee-operator,apigee-orgeapigee-virtualhostdi cui è stato eseguito l'upgrade a quella versione e MCP abilitato completando i passaggi che iniziano con Passaggio 1: modificaoverrides.yaml. Assicurati che l'upgrade includa il passaggio Installa le CRD Apigee aggiornate (kubectl apply -k apigee-operator/etc/crds/default/ ...). L'upgrade del grafico dell'operatore da solo non aggiorna le CRD. Sulle CRD precedenti alla versione1.17.4, il server API elimina silenziosamente il bloccomcpMtlsdalla risorsaApigeeRouteConfig, quindi il blocco non ha alcun effetto e il cluster non può segnalare i problemi relativi ai certificati descritti in Verifica. - Un certificato client e una chiave privata per il piano dati MCP, emessi da una CA considerata attendibile dal gateway in entrata per questo gruppo di ambienti: la CA in
virtualhosts[].caCertPatho il secretINGRESS_SECRET_NAME-cacertdella stessa vocevirtualhosts[]. Se il certificato ha un'estensione Extended Key Usage, deve includereclientAuth; il piano dati MCP rifiuta un certificato il cui Extended Key Usage lo omette (un certificato senza estensione Extended Key Usage viene accettato). Utilizza una CA privata: le CA pubbliche in genere non emettono certificati con l'utilizzo della chiave estesaclientAuth. - Il certificato CA che ha firmato il certificato TLS del gateway in entrata per questo gruppo di ambienti (il certificato in
virtualhosts[].sslCertPathoINGRESS_SECRET_NAME). Il piano dati MCP convalida il gateway in entrata rispetto a questa CA. Omettilo solo se impostidisableChainValidation: true. - A meno che non imposti
disableSanValidation: true, il certificato del gateway in entrata deve elencare gli alias host del gruppo di ambienti nei relativi nomi alternativi del soggetto. In genere sì, perché i client esterni eseguono lo stesso controllo.
Scegli uno dei due modi per fornire i certificati. Rispecchiano le due opzioni per la configurazione mTLS del gateway in entrata.
Opzione 1: file dei certificati
Aggiungi mcpMtls con i percorsi dei file alla voce virtualhosts[] del gruppo di ambienti. Helm può leggere solo i file all'interno della directory del grafico, quindi i file devono trovarsi in $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ (ad esempio nella directory certs/, accanto ai certificati di ingresso) e i percorsi sono relativi a quella directory, esattamente come i campi sslCertPath, sslKeyPath e caCertPath esistenti. Consulta Crea certificati TLS.
virtualhosts: - name: ENV_GROUP_NAME tlsMode: MUTUAL caCertPath: certs/INGRESS_CA_FILE # CA the ingress gateway trusts for client certificates sslCertPath: certs/INGRESS_CERT_FILE sslKeyPath: certs/INGRESS_KEY_FILE mcpMtls: sslCertPath: certs/MCP_CLIENT_CERT_FILE # client certificate the MCP data plane presents sslKeyPath: certs/MCP_CLIENT_KEY_FILE caCertPath: certs/MCP_TRUST_CA_FILE # CA that signed INGRESS_CERT_FILE
Opzione 2: secret di Kubernetes
- Crea un secret contenente il certificato e la chiave client. Le chiavi dei dati devono essere
certekey:kubectl create secret generic MCP_CLIENT_SECRET_NAME -n APIGEE_NAMESPACE \ --from-file=cert=MCP_CLIENT_CERT_FILE \ --from-file=key=MCP_CLIENT_KEY_FILE
- Crea un secondo secret contenente la CA che ha firmato il certificato del gateway in entrata.
Il suo nome deve essere il nome del primo secret con l'aggiunta di
-cacerte la chiave dei dati deve esserecacert. Salta questo passaggio solo se impostidisableChainValidation: true:kubectl create secret generic MCP_CLIENT_SECRET_NAME-cacert -n APIGEE_NAMESPACE \ --from-file=cacert=MCP_TRUST_CA_FILE
- Fai riferimento al primo secret dalla voce
virtualhosts[]del gruppo di ambienti:virtualhosts: - name: ENV_GROUP_NAME tlsMode: MUTUAL sslSecret: INGRESS_SECRET_NAME mcpMtls: sslSecret: MCP_CLIENT_SECRET_NAME
Non combinare le due opzioni in un unico blocco mcpMtls. helm upgrade
fail-fast con una diagnostica che indica la voce per le configurazioni errate comuni, tra cui:
sslSecret combinato con un campo del percorso; sslCertPath senza
sslKeyPath o sslKeyPath senza sslCertPath;
nessun modulo fornito; o un secret di riferimento mancante o privo delle chiavi di dati
previste. Altre incoerenze (ad esempio, caCertPath impostato insieme a disableChainValidation: true) sono descritte nel riferimento della proprietà virtualhosts[].mcpMtls.
Applica la modifica
Esegui l'upgrade della release apigee-virtualhost per il gruppo di ambienti:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace APIGEE_NAMESPACE \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Nessun pod MCP viene riavviato e nessun altro gruppo di ambienti è interessato. Il piano dati MCP rileva la nuova configurazione al successivo aggiornamento periodico, in genere entro pochi minuti.
Se stai passando dalla voce tlsMode: SIMPLE a MUTUAL
nello stesso upgrade, le chiamate dello strumento MCP a questo gruppo di ambienti possono non riuscire durante questo periodo di tempo,
perché il gateway in entrata inizia a richiedere un certificato client prima che il piano dati MCP
inizi a presentarne uno. Apporta la modifica in un periodo di manutenzione per quel gruppo di ambienti.
Verifica
- Verifica che la configurazione abbia raggiunto la risorsa di routing del piano dati MCP per il gruppo di ambienti. L'output deve mostrare il nome del secret e i due flag di convalida
che hai configurato (i flag non impostati vengono omessi):
Se la colonnakubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
mcpMtlsè ancora vuota diversi minuti dopo l'upgrade, la causa più comune è che i CRD Apigee nel cluster sono precedenti alla versione1.17.4e hanno eliminato il campo: applica i CRD aggiornati (consulta Prima di iniziare) ed esegui nuovamente l'upgrade diapigee-virtualhost. Meno spesso, il graficoapigee-org(che fornisce l'immagine del watcher) non è stato aggiornato a1.17.4. - Verifica che il piano dati MCP abbia accettato i certificati. Il sidecar registra una riga
errore mantiene la configurazione precedente per quel gruppo di ambienti ogni volta che un secret è mancante, illeggibile o contiene materiale inutilizzabile. Subito dopo l'attivazione, non dovrebbero essercene: Cerca nell'intero log anziché in una finestra recente: un secret difettoso viene segnalato quando il sidecar lo rileva per la prima volta, non a ogni aggiornamento.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
- Controlla se sono presenti report sui problemi relativi ai certificati segnalati come risorse
ApigeeIssue(consulta Problemi mTLS MCP):kubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)'
- Invia una richiesta MCP tramite un proxy di rilevamento MCP di cui è stato eseguito il deployment nel gruppo di ambienti, come nella guida rapida di MCP. Una chiamata allo strumento riuscita conferma il percorso completo, incluso l'handshake mTLS con il gateway in entrata.
Ruota i certificati
- Opzione 2 (Secret): aggiorna i secret in loco, ad esempio con
kubectl create secret generic ... --dry-run=client -o yaml | kubectl apply -f -. Il piano dati MCP controlla entrambi i secret e carica il nuovo materiale al successivo aggiornamento. Non è necessario riavviare il pod néhelm upgradee le chiamate MCP in corso non vengono interrotte. Mantieni invariate le chiavi dei daticert,keyecacert. - Opzione 1 (file): sostituisci i file ed esegui lo stesso
helm upgradecome in Applica la modifica. Il grafico aggiorna i secret che gestisce e il piano dati MCP li acquisisce come descritto per l'opzione 2.
Quattordici giorni prima della scadenza del certificato client o della CA di attendibilità, il cluster genera un ApigeeIssue con gravità WARNING; dopo la scadenza, la gravità è ERROR. Un certificato scaduto viene comunque presentato finché non lo sostituisci; è il gateway in entrata che rifiuta l'handshake.
Disabilita mTLS per un gruppo di ambienti
Rimuovi il blocco mcpMtls, imposta nuovamente tlsMode della voce su SIMPLE (o rimuovi tlsMode) nella stessa modifica ed esegui lo stesso helm upgrade. Il piano dati MCP riporta il gruppo di ambienti a TLS unidirezionale al successivo aggiornamento e rimuove il materiale del certificato che aveva scritto per il gruppo.
I secret creati manualmente per l'Opzione 2 non vengono eliminati. Rimuovili quando non sono più necessari.
Comportamento quando i certificati non sono disponibili
Se il piano dati MCP non riesce a leggere o non può utilizzare i certificati configurati per un gruppo di ambienti (manca un secret, manca una chiave dati, il certificato non contiene clientAuth o il secret della CA non è una CA), registra una riga error, continua a gestire il gruppo di ambienti con gli ultimi certificati caricati correttamente e riprova nei successivi aggiornamenti. Se non sono mai stati caricati certificati per il gruppo, le chiamate dello strumento MCP a quel gruppo non vanno a buon fine (il client in genere riceve 503 Service Unavailable), mentre tutti gli altri gruppi di ambiente continuano a essere gestiti. Correggi il secret o la voce overrides.yaml. Non è necessario riavviare. Per i messaggi specifici, consulta Risolvi i problemi relativi ai deployment MCP.
Riferimento: campi MCP in overrides.yaml
La tabella seguente elenca tutti i campi overrides.yaml di Apigee hybrid che controllano il comportamento di MCP nella versione 1.17.0. Solo enableMcpServer è obbligatorio; tutti gli altri campi hanno valori predefiniti sicuri adatti alla maggior parte delle installazioni.
Le definizioni dei campi corrispondono ai valori predefiniti del chart Helm apigee-org per Apigee hybrid 1.17.0. Le impostazioni mTLS per la connessione dal piano dati MCP al gateway in entrata non sono presenti in questa tabella: sono per gruppo di ambiente, in virtualhosts[].mcpMtls nel grafico apigee-virtualhost (1.17.4 e versioni successive).
| Campo | Tipo | Predefinito | Ottimizzazione consigliata |
|---|---|---|---|
enableMcpServer |
boolean | false |
Obbligatorio. Imposta su true per abilitare MCP su questo cluster. L'attivazione/disattivazione di questo campo attiva una versione canary in più fasi del processore di messaggi. Attiva/disattiva solo in un periodo di manutenzione e attendi il completamento della release prima di procedere. |
mcpServer.replicaCountMin |
integer | 2 |
Mantieni 2 per l'alta affidabilità. Aumenta questo valore solo se hai una base di riferimento di traffico MCP elevato; l'HPA esegue lo scale up automaticamente in caso di pressione della CPU. Segnale: HPA sostenuto
a replicaCountMax e CPU superiore al target. |
mcpServer.replicaCountMax |
integer | 10 |
Aumenta se noti che l'HPA è limitato a 10 durante i picchi. Indicatore:
kubectl top pods -l app=apigee-mcp-server mostra tutti i pod vicini al limite di CPU
al picco. Se metrics-server non è installato, utilizza kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server e controlla se la colonna REPLICAS ha raggiunto il limite massimo di MAXPODS. |
mcpServer.targetCPUUtilizationPercentage |
integer | 70 |
Riduci a 50-60 per i workload sensibili alla latenza (scalabilità anticipata). Aumenta il valore a 80-85 per ridurre il numero di repliche nei cluster sensibili ai costi. Indicatore: la latenza delle richieste p95 è correlata alla CPU per pod. |
mcpServer.resources.requests |
ResourceList | cpu: 500m, memory: 512Mi |
Aumenta le richieste se i pod vengono spesso terminati per memoria insufficiente (OOMKilled) o se la CPU viene limitata in stato stabile. Indicatore: kubectl describe pod mostra condizioni OOMKilled o limitate. |
mcpServer.resources.limits |
ResourceList | cpu: 2000m, memory: 1Gi |
Aumenta il limite di CPU prima di aumentare il numero di repliche quando la latenza p95 è elevata, ma le QPS complessive sono basse (poche richieste costose). Aumenta il limite di memoria solo se vedi terminazioni OOM. |
mcpServer.sidecar.resources.requests |
ResourceList | cpu: 200m, memory: 128Mi |
Raramente richiede l'ottimizzazione. Il sidecar compone e scrive periodicamente i bundle di configurazione; la CPU in stato stabile è minima. |
mcpServer.sidecar.resources.limits |
ResourceList | cpu: 500m, memory: 512Mi |
Raramente richiede l'ottimizzazione. Aumenta la memoria solo se esegui il deployment di un numero insolitamente elevato di strumenti MCP in un singolo proxy di rilevamento. |
mcpServer.terminationGracePeriodSeconds |
integer | 30 |
Raramente richiede l'ottimizzazione. Aumenta questo valore se le richieste MCP in corso di lunga durata richiedono più tempo per essere completate durante lo svuotamento di un pod. |
mcpServer.annotations |
mappa | {} |
Aggiungi annotazioni pod aggiuntive se il cluster le richiede. |
mcpServer.serviceAccountPath |
string | unset | Lascia il campo non impostato, a meno che non sia necessaria la separazione delle identità per componente. Se non è impostato, MCP utilizza watcher.serviceAccountPath. MCP non utilizza
envs[].serviceAccountPaths.runtime. L'identità apigee-watcher dispone già delle autorizzazioni necessarie per il sidecar MCP. Se esegui l'override di questo campo, specifica il percorso di un file JSON della chiave dell'account di servizio Google Cloud . Si escludono a vicenda con mcpServer.gsa.
Se Workload Identity non è abilitato e non imposti né mcpServer.serviceAccountRef né
serviceAccountSecretProviderClass, devi impostare
mcpServer.serviceAccountPath o
watcher.serviceAccountPath. Se non imposti nessuno dei due, helm upgrade non va a buon fine e viene visualizzato l'errore mcpServer.serviceAccountPath or watcher.serviceAccountPath is
required!!.
Se possibile, preferisci Workload Identity (GKE) o la federazione delle identità per i workload (AKS/EKS). Le chiavi dei service account basate su file devono essere ruotate, archiviate in modo sicuro, distribuite a ogni cluster e sono la fonte più comune di fughe di dati negli artefatti di assistenza (vedi Richieste di assistenza). |
mcpServer.gsa |
string | unset | Lascia il campo non impostato, a meno che non sia necessaria la separazione delle identità per componente. Se non è impostato, MCP torna a watcher.gsa, poi a gcp.workloadIdentity.gsa. L'identità apigee-watcher dispone già delle autorizzazioni necessarie per il sidecar MCP, quindi il riutilizzo è il percorso consigliato. Esegui l'override con un indirizzo email dell'account di servizio Google Cloud dedicato solo se la tua organizzazione richiede un'identità distinta per il sidecar MCP per motivi di controllo. |
mcpServer.serviceAccountRef |
string | unset | Avanzate. Nome di un secret Kubernetes esistente nello spazio dei nomi Apigee che contiene una chiave del account di servizio Google Cloud per il sidecar MCP. Utilizza questa opzione solo se gestisci i secret delle chiavi dei account di servizio al di fuori dei chart Helm di Apigee. Si esclude a vicenda con mcpServer.serviceAccountPath e mcpServer.gsa.
MCP non utilizza watcher.serviceAccountRef. Se l'installazione di base archivia la chiave apigee-watcher in un secret Kubernetes con watcher.serviceAccountRef, imposta questa proprietà sullo stesso nome del secret. |
mcpServer.podDisruptionBudget |
mappa | unset | PodDisruptionBudget facoltativo per i pod MCP. Accetta minAvailable o maxUnavailable (numero intero o stringa di percentuale). Imposta uno, non entrambi. Non impostare questo valore, a meno che il cluster non abbia policy di interruzione volontaria rigorose che richiedono un budget esplicito. |
mcpServer.tolerations |
list | unset (viene utilizzato il valore di primo livello tolerations) |
Tolleranze Kubernetes standard per i pod MCP. Imposta solo se i pod MCP devono tollerare taints che altri componenti Apigee non tollerano. |
mcpServer.image.pullPolicy |
string | IfNotPresent |
Policy di pull delle immagini per il contenitore del server MCP. Raramente modificato. |
mcpServer.sidecar.image.pullPolicy |
string | IfNotPresent |
Policy di pull delle immagini per il container sidecar MCP. Raramente modificato. |
Stima la capacità degli strumenti MCP
Apigee hybrid non impone un numero massimo fisso di strumenti MCP per organizzazione. La capacità degli strumenti è invece limitata da quattro limiti di dimensioni rigidi applicati al momento del deployment o della richiesta. La possibilità di inserire un numero specifico di strumenti dipende dalle dimensioni di ciascuno strumento, che derivano dalla specifica OpenAPI che lo definisce.
Capacità tipica
Per la maggior parte delle specifiche OpenAPI, un mix di strumenti con un numero di parametri, dimensioni del corpo della richiesta e lunghezze delle descrizioni variabili, con la maggior parte degli strumenti che rientra nell'intervallo di dimensioni da piccole a medie,in genere puoi aspettarti di inserire 10.000 strumenti MCP per organizzazione con il limite di dimensioni della risposta tools/list predefinito.
La capacità effettiva varia in base alla forma specifica della specifica OpenAPI. Le organizzazioni le cui specifiche sono dominate da strumenti con molti parametri, corpi delle richieste di grandi dimensioni o descrizioni lunghe possono inserire proporzionalmente meno strumenti prima di raggiungere uno dei quattro limiti massimi riportati di seguito. Per convalidare la capacità per le tue specifiche, segui le istruzioni riportate di seguito in Stima la capacità per la tua specifica.
Limiti rigidi
Nella versione 1.17.0 di Apigee hybrid si applicano quattro limiti di dimensioni. Il limite applicabile più basso è quello vincolante; l'aumento di un limite non comporta l'aumento degli altri.
| Limite | Valore | Ambito | Modalità di errore |
|---|---|---|---|
| Dimensioni del file di specifica OpenAPI | 3 MiB | per .yaml file |
400 alla convalida del proxy |
| Dimensioni del bundle del proxy MCP (decompresso) | 50 MiB | per proxy di rilevamento MCP | 400 alla convalida del proxy |
Dimensioni risposta tools/list |
10 MiB (predefinito) | per nome host | 502 con TooBigBody |
| Nomi host per gruppo di ambienti | 100 | per gruppo di ambienti | 400 all'aggiornamento del gruppo di ambienti |
Cosa determina le dimensioni per strumento
La dimensione per strumento è composta quasi interamente dal inputSchema dello strumento, che deriva da parameters e requestBody della specifica OpenAPI per l'operazione.
Le tre proprietà più importanti sono:
- Numero di parametri. Ogni voce di parametro contribuisce per circa 100 byte alle dimensioni dello strumento nella risposta
tools/list. - Numero di proprietà del corpo della richiesta. Ogni proprietà del corpo della richiesta contribuisce per circa 100 byte. Le operazioni con un corpo della richiesta (in genere
POSTePUT) sono quindi sostanzialmente più grandi delle operazioni senza un corpo della richiesta (in genereGETeDELETE). - Lunghezza della descrizione. Le descrizioni delle operazioni vengono copiate quasi letteralmente nello strumento, quindi una descrizione più lunga aumenta direttamente le dimensioni dello strumento.
Gli schemi di risposta non vengono conteggiati nel budget delle dimensioni. Solo parameters e requestBody raggiungono la configurazione MCP. Il dimensionamento della capacità basato solo sulle dimensioni del file OpenAPI tende quindi a sovrastimare il costo, perché la maggior parte delle specifiche OpenAPI reali include definizioni di schema di risposta che non influiscono sulle dimensioni dello strumento.
Stima la capacità per la tua specifica
Il modo più affidabile per stimare la capacità degli strumenti per le tue specifiche OpenAPI è misurare un sottoinsieme rappresentativo:
- Esegui il deployment di un proxy di rilevamento MCP che faccia riferimento a un piccolo sottoinsieme rappresentativo degli strumenti che prevedi di pubblicare (ad esempio, da 50 a 100 strumenti che riflettano la combinazione di conteggi dei parametri, dimensioni del corpo della richiesta e lunghezze delle descrizioni nella specifica completa).
- Chiama
tools/listsul proxy di cui è stato eseguito il deployment e registra le dimensioni della risposta in byte e il numero di strumenti restituiti. - Dividi le dimensioni della risposta per il numero di strumenti per ottenere le dimensioni medie per strumento per la tua specifica.
- Dividi il limite di dimensioni della risposta
tools/listapplicabile (10 MiB per impostazione predefinita) per questa media per stimare il numero massimo di strumenti che possono essere inseriti in un nome host per una specifica di questa forma.
Aumento della capacità
Esistono due meccanismi per aumentare la capacità degli strumenti oltre i valori predefiniti:
- Distribuisci gli strumenti tra i nomi host. Il limite di risposte
tools/listè per nome host. La suddivisione degli strumenti su più nomi host all'interno dello stesso gruppo di ambienti moltiplica l'headroom per nome host (soggetto al limite di 100 nomi host per gruppo di ambienti). Lo sharding non aumenta il limite di bundle per proxy; il limite di 50 MiB per bundle continua a essere applicato a tutti i nomi host su un singolo proxy di rilevamento MCP. - Aumenta il limite di dimensioni della risposta
tools/list. Il limite predefinito è 10 MiB per nome host. Puoi aumentarlo fino a 30 MiB. Come minimo, devi impostareenvs.components.runtime.resources.limits.memory,envs.components.runtime.resources.requests.memoryeenvs.components.runtime.cwcAppend.bin_setenv_max_memnel tuooverrides.yaml, quindi eseguirehelm upgradesul graficoapigee-org. Per la procedura completa, consulta Configura il supporto dei payload dei messaggi di grandi dimensioni in Apigee hybrid, incluse le varianti per ambiente e per l'intera installazione, le indicazioni per il dimensionamento dell'heap del processore di messaggi ed esempi completi dioverrides.yaml. L'aumento del limite di risposta non influisce sul limite di 50 MiB per le dimensioni del bundle del proxy MCP. Se la tua capacità è limitata da questo limite, questa modifica non sarà utile.
Sicurezza
Confine di attendibilità
Il piano dati MCP viene eseguito all'interno del tuo cluster Kubernetes. Google non ha accesso in fase di runtime al piano dati. Il control plane di Apigee ti fornisce la configurazione MCP derivata dalla tua specifica OpenAPI; non osserva il traffico delle richieste MCP. I dati di configurazione at-rest vengono archiviati in un bucket Cloud Storage gestito da Apigee, con ambito nel progetto tenant Apigee, recuperato dal sidecar MCP utilizzando il relativo account di servizio Google Cloud ambientale.
L'operatore Apigee esegue il provisioning di un Role e un RoleBinding Kubernetes con ambito MCP nello spazio dei nomi Apigee (APIGEE_NAMESPACE) per il ServiceAccount del piano dati MCP. Il ruolo concede l'accesso di sola lettura:
get,list,watchsuservicesnel gruppo API di base.get,list,watchsuapigeeroutesnel gruppo di APIapigee.cloud.google.com.- In
1.17.4e versioni successive:get,list,watchsusecretsnel gruppo API di base. Il piano dati MCP lo utilizza per leggere il certificato client e i secret della CA di attendibilità denominati davirtualhosts[].mcpMtlse per rilevare la loro rotazione (consulta Configura mTLS tra il piano dati MCP e il gateway in entrata). La concessione è di sola lettura, ma copre ogni secret nello spazio dei nomi Apigee: RBAC di Kubernetes non può limitarelistewatchai secret con nome. È presente indipendentemente dal fatto che un gruppo di ambienti abbia o menomcpMtlsconfigurato.
Il ruolo non concede verbi di scrittura e nessun accesso a ConfigMaps o allo stato del pod.
Il revisore può verificare le regole esatte direttamente dal cluster con:
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
Il ruolo e il RoleBinding apigee-mcp-server-APIGEE_ORG_CR sono le risorse RBAC con ambito MCP; i loro nomi includono il nome completo della tua risorsa personalizzata ApigeeOrganization (che deriva dal nome della tua organizzazione Apigee e da un breve hash). Non hanno un'etichetta app=apigee-mcp-server a livello di risorsa (solo i pod ce l'hanno), quindi una ricerca basata su etichette non restituisce risultati. Se il comando field-selector riportato sopra non restituisce alcun risultato, elenca tutte le risorse RBAC correlate a MCP nello spazio dei nomi con:
kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server
TLS tra il processore di messaggi e il piano dati MCP
I pod del processore di messaggi compongono il piano dati MCP all'indirizzo https://mcp.apigee.internal/ o https://ORG_NAME.mcp.apigee.internal/. Questi nomi host vengono risolti nel ClusterIP del servizio MCP tramite la voce hostAliases inserita. Il container del piano dati MCP presenta un certificato TLS firmato dall'emittente di cui è stato eseguito il provisioning dall'operatore Apigee (il ClusterIssuer denominato apigee-ca-issuer). I nomi alternativi del soggetto del certificato includono entrambi i nomi host.
TLS tra il piano dati MCP e il gateway in entrata
Il piano dati MCP inoltra ogni chiamata allo strumento al gateway in entrata Apigee sulla porta 443, utilizzando l'alias host del gruppo di ambienti. Per impostazione predefinita, questa connessione è TLS unidirezionale e il piano dati MCP non verifica il certificato del gateway in entrata. In 1.17.4 e versioni successive, puoi richiedere l'autenticazione reciproca su questa connessione per gruppo di ambienti; consulta Configura mTLS tra il piano dati MCP e il gateway in entrata.
Limita l'accesso in entrata al servizio MCP
In Apigee hybrid 1.17.0, il piano dati MCP non autentica in modo indipendente i chiamanti. Si fida del fatto che le richieste che riceve siano già state autenticate da un proxy MCP Apigee in esecuzione nel processore di messaggi. L'unico chiamante previsto del servizio MCP è il processore di messaggi. Qualsiasi altro workload nel cluster che può raggiungere l'IP del cluster del servizio MCP su TCP 443 può richiamare gli strumenti MCP senza un controllo di autenticazione.
Limita l'accesso in entrata ai pod MCP solo ai pod processore di messaggi Processor, utilizzando il motore delle policy di ingresso del cluster della tua piattaforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy o equivalente). La limitazione:
- Consente il traffico in entrata verso i pod con l'etichetta
app=apigee-mcp-servernello spazio dei nomiAPIGEE_NAMESPACEsu TCP443dai pod con l'etichettaapp=apigee-runtimesolo nello stesso spazio dei nomi. - Nega tutto il traffico in entrata su TCP
443ai pod con etichettaapp=apigee-mcp-server. - Nega tutto il traffico in entrata nel cluster su TCP
15021ai pod con etichettaapp=apigee-mcp-server. La porta15021gestisce un endpoint/healthz/readyHTTP semplice non autenticato utilizzato da kubelet per il probe di idoneità; kubelet lo raggiunge direttamente sull'IP del pod, quindi nessun altro workload nel cluster deve raggiungere i pod MCP su15021.
Applica questa limitazione prima di completare la guida rapida di MCP ed eseguire il deployment del tuo primo proxy di rilevamento MCP in un ambiente non di sviluppo.
Contratto di aggiornamento della configurazione
Quando il sidecar MCP completa un pull di configurazione riuscito, il container del piano dati MCP carica il bundle recuperato e continua a gestirlo fino al pull successivo riuscito. Se i pull successivi non vanno a buon fine (control plane Apigee non raggiungibile, Cloud Storage non raggiungibile, autorizzazione IAM rimossa nel account di servizio watcher o un errore in qualsiasi altra fase della pipeline di pull), il sidecar continua a pubblicare il bundle valido più recente per un periodo di tempo indefinito. Non esiste un limite di inattività integrato in 1.17.0: il pod rimane Ready e il traffico dello strumento MCP continua a essere gestito in base al bundle inattivo. Il segnale che l'aggiornamento della configurazione è stato interrotto è una riga di log del sidecar a livello ERROR che contiene un contatore consecutive_failures (consulta Risolvi i problemi relativi ai deployment MCP per i messaggi specifici emessi dal sidecar per ogni fase di errore).
Per gli ambienti di produzione regolamentati, invia un avviso in caso di incrementi ripetuti di questo contatore. Un avviso minimo valido è: invia un avviso quando un container sidecar MCP genera una riga di log di livello ERROR con consecutive_failures che raggiunge una soglia impostata in base alla tua tolleranza di inattività. I valori in aumento indicano che il sidecar ha interrotto l'aggiornamento della configurazione. Nel frattempo, il sidecar continua a gestire l'ultimo bundle riuscito.
Se il sidecar ha smesso di aggiornare la configurazione, esamina la modalità di errore dai log del sidecar; consulta Risolvi i problemi dei deployment MCP. Il riavvio dei pod MCP non risolve il problema di recupero sottostante, perché i pod appena creati raggiungono lo stesso percorso di recupero.
Requisiti di rete in uscita
Il sidecar MCP (il container di configurazione all'interno di ogni pod MCP) deve avere accesso alla rete in uscita ai seguenti endpoint su TCP 443. Seleziona la scheda corrispondente all'utilizzo o meno della residenza dei dati da parte della tua organizzazione Apigee. Gli endpoint richiesti sono diversi.
Nessuna residenza dei dati
| Endpoint | Utilizzato per |
|---|---|
apigee.googleapis.com |
Recupera il riferimento alla configurazione MCP corrente per la tua organizzazione dal control plane Apigee a ogni aggiornamento della configurazione. |
storage.googleapis.com |
Scarica la configurazione MCP della tua organizzazione da Google Cloud Storage. |
Residenza dei dati
Se la tua organizzazione Apigee utilizza la residenza dei dati, il sidecar MCP raggiunge l'endpoint del control plane Apigee regionale (lo stesso endpoint utilizzato dagli altri componenti Apigee hybrid, configurato tramite il valore del grafico contractProvider in overrides.yaml). Sostituisci CONTROL_PLANE_LOCATION con la località del control plane della tua organizzazione (ad esempio us, eu).
| Endpoint | Utilizzato per |
|---|---|
CONTROL_PLANE_LOCATION-apigee.googleapis.com |
Recupera il riferimento alla configurazione MCP corrente per la tua organizzazione dall'endpoint del control plane Apigee regionale a ogni aggiornamento della configurazione. |
storage.googleapis.com |
Scarica la configurazione MCP della tua organizzazione da Google Cloud Storage. Il bucket si trova nella regione della tua organizzazione; Cloud Storage lo indirizza automaticamente. |
Inoltre, il sidecar deve essere in grado di ottenere i token di accesso di Google Cloud per le credenziali ambientali con cui viene eseguito il pod (tramite Workload Identity o una chiave del service account basata su file). Gli endpoint di scambio di token specifici dipendono dal percorso di autenticazione e sono gli stessi già utilizzati da altri componenti di Apigee hybrid nel tuo cluster. Se il traffico Apigee hybrid esistente verso le API Cloud di Google Cloud ha esito positivo da questo spazio dei nomi, anche lo scambio di token del sidecar MCP ha esito positivo.
Inoltre, il sidecar deve avere accesso in-cluster al server API Kubernetes (tramite l'indirizzo del servizio in-cluster standard) per pubblicare lo stato di liveness e readiness. Questo traffico non lascia mai il cluster.
Risoluzione dei problemi
Per un elenco di controllo diagnostico completo, consulta Risolvi i problemi relativi ai deployment MCP, che include un elenco di controllo diagnostico lato cluster per Apigee hybrid.
Errori di installazione comuni
| Sintomo | Causa e correzione |
|---|---|
helm upgrade viene completato, ma non vengono visualizzate risorse MCP. |
Il grafico dell'organizzazione è stato aggiornato prima del grafico dell'operatore. Esegui prima helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/, poi esegui di nuovo helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/. |
Pod MCP bloccati in ContainerCreating o 1/2 Ready. |
Due cause comuni: il cert-manager Certificate per MCP non è ancora stato emesso o il pull dell'immagine container non va a buon fine. Esegui kubectl describe pod sul pod interessato per conoscere il motivo esatto. |
I log di Sidecar (apigee-mcp-server-config) segnalano no MCP config from CP yet; skipping tick, pod stays Ready via seed a ogni polling. |
Stato stabile previsto quando non è stato ancora eseguito il deployment di un proxy di rilevamento MCP per la tua organizzazione. Il control plane Apigee restituisce un riferimento di configurazione vuoto e il piano dati MCP ha solo il listener di idoneità Kubernetes caricato sulla porta 15021; la porta di richiesta MCP 8443 non ha ancora un listener e le richieste a https://mcp.apigee.internal/mcp ricevono una connessione rifiutata. Per passare allo stato di pubblicazione, segui la
guida rapida di MCP
per eseguire il deployment di un proxy di rilevamento MCP in un ambiente del gruppo di ambienti gestito
da questo cluster. |
I log sidecar segnalano CP fetch failed con un 403 o PermissionDenied HTTP incorporato. |
Il account di servizio Google Cloud del watcher Apigee ha perso il ruolo roles/apigee.runtimeAgent (che concede l'autorizzazione apigee.runtimeconfigs.get necessaria per il sidecar) nel tuo progetto tenant Apigee. L'installazione di base di Apigee hybrid concede questo ruolo automaticamente. Se è stato rimosso da un'analisi di automazione IAM, applicalo di nuovo al account di servizio Google Cloud apigee-watcher. |
I log sidecar segnalano CP fetch failed con
context deadline exceeded, errori DNS o errori TLS. |
Il sidecar non può raggiungere apigee.googleapis.com o
storage.googleapis.com dall'interno del cluster. Verifica il traffico in uscita rispetto ai tre endpoint elencati in Requisiti di rete in uscita sopra. |
I pod del processore di messaggi non sono stati riavviati dopo helm upgrade. |
Verifica che la voce hostAliases sia presente in ogni pod MP:
kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o
jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'.
Se un pod è vuoto, forza un nuovo rendering eliminando il pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). Il controller ApigeeDeployment lo ricreerà dalla specifica attuale, che include la voce hostAliases. Non utilizzare kubectl rollout restart deploy, non si applica a ApigeeDeployment. |
I log dei pod MP mostrano errori di TLS handshake durante la connessione a https://mcp.apigee.internal/ o https://ORG_NAME.mcp.apigee.internal/ dopo che il traffico dello strumento MCP inizia a fluire attraverso la guida rapida. |
Il container del piano dati MCP fornisce un certificato i cui nomi alternativi del soggetto (SAN) non includono il nome host composto dall'MP. Verifica il certificato:
kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, poi
kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. Il dnsNames del certificato deve includere sia mcp.apigee.internal sia ORG_NAME.mcp.apigee.internal in minuscolo. In caso contrario, elimina la risorsa MCP Certificate e lascia che cert-manager la riemetta. |
Passaggi successivi
- Segui la guida rapida di MCP per eseguire il deployment del tuo primo proxy di rilevamento MCP e chiamare uno strumento MCP da un client MCP.
- Scopri come gestire l'accesso agli strumenti MCP con i prodotti API.
- Scopri come monitorare e analizzare il traffico MCP.
- Per la diagnostica avanzata, consulta la guida alla risoluzione dei problemi di MCP.