Abilitare Model Context Protocol (MCP) in Apigee hybrid

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come attivare 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 data plane MCP in-cluster e il processore di messaggi è pronto a indirizzare le chiamate allo strumento MCP. Puoi quindi eseguire il deployment del primo proxy di rilevamento MCP seguendo la guida rapida MCP condivisa.

Per i concetti, l'architettura e i dettagli delle funzionalità di MCP condivisi tra Apigee e Apigee hybrid, consulta la sezione MCP nella panoramica di Apigee.

Cosa fa questa procedura

L'attivazione di MCP su un cluster Apigee hybrid comporta le seguenti modifiche:

  1. Concede all'identità apigee-watcher l'accesso alla configurazione MCP sul control plane Apigee. Aggiungi l'account di servizio apigee-watcher all'elenco watcher_identities nella risorsa controlPlaneAccess della tua organizzazione Apigee in modo che il sidecar MCP possa estrarre i bundle di configurazione MCP dal control plane 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 servono.
  2. Aggiunge un nuovo data plane MCP in-cluster. Viene creato un nuovo insieme di pod MCP nello stesso spazio dei nomi Kubernetes in cui è installato Apigee hybrid (apigee per impostazione predefinita), 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.
  3. Configura il processore di messaggi per raggiungere il data plane MCP. L'operatore Apigee aggiorna la specifica del pod processore di messaggi in modo che MP indirizzi le chiamate allo strumento MCP al nuovo piano dati MCP in-cluster. L'applicazione di questa modifica attiva una versione canary in più fasi del processore di messaggi (gestito dal controller ApigeeDeployment); il pod precedente continua a erogare traffico finché il nuovo pod non è Ready. Il rilascio viene attivato solo durante le transizioni di attivazione e disattivazione, non durante l'attività MCP in corso o il traffico MCP in stato stazionario. Esegui questa procedura in un periodo di manutenzione approvato e attendi il completamento del rilascio prima di procedere.

Passaggio 1: modifica overrides.yaml

Apri il file overrides.yaml che utilizzi per i grafici Helm di Apigee hybrid. Al livello superiore del file, aggiungi:

enableMcpServer: true

Questa è la configurazione minima richiesta per abilitare MCP. Utilizza i valori predefiniti integrati del grafico apigee-org: due repliche del piano dati MCP che vengono scalate automaticamente fino a dieci con un utilizzo della CPU del 70%, con richieste di risorse di 500 m di CPU e 512 Mi di memoria e limiti di 2000 m di CPU e 1 Gi di memoria nel container del piano dati MCP. Per personalizzare i conteggi delle repliche, le richieste di risorse o l'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 che corrisponde alla configurazione della tua installazione di base esistente. Le righe specifiche di MCP sono evidenziate con commenti e sono uguali in tutte e tre le varianti.

Seleziona la scheda che corrisponde 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 di chiavi del account di servizio su 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.iam.gserviceaccount.com
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 del account di servizio basate su file

Utilizza questa variante se l'installazione di base autentica i componenti Apigee su Google Cloud tramite i file delle chiavi del 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 si trova su AKS o EKS ed esegue l'autenticazione su Google Cloud 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 devi aggiungere alcuna configurazione dell'identità specifica per MCP. Se invece memorizzi la configurazione delle credenziali in un secret Kubernetes, consulta Altri meccanismi di identità.

Aggiungi la chiave di primo livello MCP al tuo 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à che hai selezionato nel passaggio 1). Prima dell'avvio dei pod MCP, aggiungi questo account di servizio all'elenco watcher_identities nella risorsa controlPlaneAccess dell'organizzazione Apigee. 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 data plane MCP non diventa mai pronto a gestire il traffico degli strumenti.

Questo è un passaggio una tantum per organizzazione (non per cluster). Salta questo passaggio se hai già concesso l'accesso per un cluster precedente nella stessa organizzazione Apigee.

  1. 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}.iam.gserviceaccount.com
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 ibrida.
    • WATCHER_SA è l'indirizzo email del account di servizio apigee-watcher. Se hai eseguito l'override di watcher.gsa in overrides.yaml, utilizza quel valore anziché il valore predefinito apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com.
  2. 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 posizione 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 dell'API Apigee disponibili.

    La chiamata restituisce un'operazione a lunga esecuzione. Attendi il completamento prima di eseguire il passaggio di verifica riportato di seguito.

  3. Verifica che la concessione sia stata assegnata. Chiama getControlPlaneAccess e verifica che il account di servizio watcher venga visualizzato nel campo watcherIdentities della 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 watcherIdentities contenente il account di servizio del watcher. Ad esempio:

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

    Se watcherIdentities non è presente nella risposta o non contiene il 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 l'upgrade del grafico dell'operatore prima. 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 completamente implementato con la nuova immagine (apigee-controller-manager Deployment è una risorsa Kubernetes standard, non un ApigeeDeployment, quindi kubectl rollout status deploy è il comando corretto):

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 in parallelo due cicli di riconciliazione:

  • L'operatore Apigee crea il deployment, il servizio, l'HPA, il service account, il ruolo e il RoleBinding 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 hostAliases nella specifica del pod Message Processor, che attiva il rilascio di apigee-runtime ApigeeDeployment.

Passaggio 5: verifica l'installazione

Verifica che il data plane MCP sia in esecuzione

Esamina le quattro risorse correlate 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 e i suffissi dei pod e Service ClusterIP 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 contenitore del piano dati MCP a cui si connettono i pod MP.
  • apigee-mcp-server-config: il sidecar di configurazione (una modalità del apigee-watcher binario) che recupera i bundle di configurazione dal piano di controllo Apigee e li scrive in un volume condiviso che il container del piano dati MCP legge.

MCP ApigeeDeployment (una risorsa personalizzata di Kubernetes, non una 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

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 di overrides.yaml (2 predefinito) e che MAXPODS corrisponda a mcpServer.replicaCountMax (10 predefinito). 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 mostra, 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 dell'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 rilevato completamente la specifica del pod aggiornata. Forza una nuova versione canary in staging eliminando i pod del processore di messaggi corrente; il controller ApigeeDeployment li eseguirà nuovamente dal rendering dalla specifica corrente (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 su processore di messaggi perché processore di messaggi viene implementato come risorsa personalizzata ApigeeDeployment, non come Deployment.

Installazione completata

I tre controlli precedenti confermano che il piano dati MCP è in esecuzione e che è indirizzabile tramite MP:

  • Ogni pod MCP è 2/2 Running. Il container del piano di controllo MCP non supera il probe di prontezza di Kubernetes sulla porta 15021 se il certificato TLS emesso dall'operatore non viene caricato e il sidecar non ha ancora caricato la configurazione MCP iniziale, pertanto i pod Ready soddisfano entrambe le precondizioni.
  • La specifica di ogni pod MP contiene la voce hostAliases che blocca mcp.apigee.internal e ORG_NAME.mcp.apigee.internal al ClusterIP del servizio MCP. I pod MP possono quindi risolvere gli endpoint di destinazione del proxy MCP nel piano dati MCP in-cluster.
  • Un pod MP risolve mcp.apigee.internal nel ClusterIP del servizio MCP tramite la voce hostAliases inserita.

Verifica il traffico end-to-end dello strumento MCP (una chiamata initialize o tools/list effettiva di MCP tramite l'ingresso Apigee) nell'ambito della guida rapida di MCP, dopo aver eseguito il deployment del primo proxy di rilevamento MCP.

Se uno dei tre controlli precedenti non va a buon fine, consulta la sezione Risoluzione dei 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 visualizzatore): questa concessione è limitata all'organizzazione Apigee e si applica a tutti i cluster della stessa organizzazione.

Esegui il rollback

Per disattivare MCP su un cluster, imposta enableMcpServer: false (o rimuovi completamente il campo) in overrides.yaml, poi 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, quindi 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 processore di messaggi, il che attiva il 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 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à oppure lasciali di cui è stato eseguito il deployment e riattiva MCP sui cluster in un secondo momento.

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 grafico Helm apigee-org per 1.17.0 ibrido.

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 del rilascio prima di procedere.
mcpServer.replicaCountMin integer 2 Continua a 2 per HA. Aumenta solo se hai una baseline di traffico MCP elevato; HPA aumenta automaticamente in base alla pressione della CPU. Segnale: HPA sostenuta a replicaCountMax e CPU superiore al target.
mcpServer.replicaCountMax integer 10 Aumenta se noti che HPA è limitato a 10 durante il picco. Segnale: 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 è al limite di MAXPODS.
mcpServer.targetCPUUtilizationPercentage integer 70 Riduzione a 50-60 per i carichi di lavoro sensibili alla latenza (scalabilità anticipata). Aumenta il valore a 80-85 per ridurre il numero di repliche nei cluster sensibili ai costi. Segnale: 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 errore OOM o se la CPU viene limitata in modo costante. Segnale: kubectl describe pod mostra le condizioni OOMKilled o di limitazione.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Aumenta il limite della CPU prima di aumentare il numero di repliche quando la latenza p95 è elevata, ma il QPS complessivo è basso (poche richieste costose). Aumenta il limite di memoria solo se visualizzi terminazioni OOM.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Raramente necessita di regolazioni. Il sidecar compone e scrive periodicamente i bundle di configurazione; la CPU in stato stazionario è minima.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Raramente necessita di regolazioni. Aumenta la memoria solo se implementi un numero insolitamente elevato di strumenti MCP in un unico proxy di scoperta.
mcpServer.terminationGracePeriodSeconds integer 30 Raramente necessita di regolazioni. Aumenta se le richieste MCP in corso di lunga durata hanno bisogno di 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 questo campo vuoto, a meno che tu non abbia bisogno di una 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 . Esclusivo 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 riesce 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 del service account basate su file devono essere ruotate, archiviate in modo sicuro, distribuite a ogni cluster e sono la fonte più comune di perdite negli artefatti di assistenza (vedi Richieste di assistenza).
mcpServer.gsa string unset Lascia questo campo vuoto, a meno che tu non abbia bisogno di una 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 file collaterale MCP, quindi il riutilizzo è il percorso consigliato. Esegui l'override con un indirizzo email del account di servizio Google Cloud dedicato solo se la tua organizzazione richiede un'identità distinta per il file collaterale MCP per motivi di audit.
mcpServer.serviceAccountRef string unset Avanzate. Nome di un Secret Kubernetes esistente nello spazio dei nomi Apigee che contiene una chiave delaccount di serviziot Google Cloud per il sidecar MCP. Utilizza questa opzione solo se gestisci i secret delle chiavi delaccount di serviziot al di fuori dei grafici Helm di Apigee. Si esclude a vicenda con mcpServer.serviceAccountPath e mcpServer.gsa.

MCP non utilizza watcher.serviceAccountRef. Se l'installazione di base memorizza 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 (stringa di numeri interi o percentuali). Impostane uno, non entrambi. Lascia questo campo vuoto a meno che il cluster non abbia norme di interruzione volontaria rigide che richiedono un budget esplicito.
mcpServer.tolerations list unset (viene ripristinato il valore predefinito di tolerations di primo livello) Tolleranze Kubernetes standard per i pod MCP. Imposta solo se i pod MCP devono tollerare i taint 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.

Stimare la capacità dello strumento MCP

Apigee Hybrid non impone un numero massimo fisso di strumenti MCP per organizzazione. Al contrario, la capacità dello strumento è limitata da quattro limiti di dimensioni rigidi applicati al momento del deployment o della richiesta. Se un numero specifico di strumenti è adatto dipende dalle dimensioni di ciascuno strumento, che derivano dalla specifica OpenAPI che definisce lo strumento.

Capacità tipica

Per la maggior parte delle specifiche OpenAPI, un mix di strumenti con conteggi dei parametri, dimensioni del corpo della richiesta e lunghezze della descrizione variabili, con la maggior parte degli strumenti che rientrano nell'intervallo di dimensioni da piccole a medie,in genere puoi prevedere di inserire 10.000 strumenti MCP per organizzazione al 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 inseriscono un numero proporzionalmente inferiore di strumenti prima di raggiungere uno dei quattro limiti rigidi riportati di seguito. Per convalidare la capacità per le tue specifiche, segui Stima della capacità per le tue specifiche di seguito.

Limiti rigidi

Nella versione ibrida di Apigee 1.17.0 si applicano quattro limiti di dimensione. Il limite applicabile più basso è vincolante; l'aumento di uno non comporta l'aumento degli altri.

Limite Valore Ambito Modalità di errore
Dimensioni del file di specifica OpenAPI 3 MiB per .yaml file 400 in proxy validate
Dimensioni del bundle del proxy MCP (decompresso) 50 MiB per il proxy di rilevamento MCP 400 in proxy validate
tools/list dimensioni risposta 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 dallo inputSchema dello strumento, che deriva da parameters e requestBody dell'operazione nella specifica OpenAPI. Tre proprietà sono le più importanti:

  • Numero di parametri. Ogni voce di parametro contribuisce con 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 con circa 100 byte. Le operazioni con un corpo della richiesta (in genere POST e PUT) sono quindi notevolmente più grandi rispetto a quelle senza (in genere GET e DELETE).
  • Lunghezza della descrizione. Le descrizioni delle operazioni vengono copiate quasi testualmente 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. Pertanto, il dimensionamento della capacità in base alle sole dimensioni del file OpenAPI tende a sovrastimare i costi, perché la maggior parte delle specifiche OpenAPI reali include definizioni di schemi di risposta che non influiscono sulle dimensioni dello strumento.

Stima della capacità per la specifica

Il modo più affidabile per stimare la capacità dello strumento per le specifiche OpenAPI è misurare un sottoinsieme rappresentativo:

  1. Esegui il deployment di un proxy di rilevamento MCP che fa riferimento a un piccolo sottoinsieme rappresentativo degli strumenti che prevedi di pubblicare (ad esempio, da 50 a 100 strumenti che riflettono il mix di conteggi dei parametri, dimensioni del corpo della richiesta e lunghezze delle descrizioni nella specifica completa).
  2. Chiama tools/list rispetto al proxy di cui è stato eseguito il deployment e registra le dimensioni della risposta in byte e il numero di strumenti restituiti.
  3. Dividi la dimensione della risposta per il numero di strumenti per ottenere la dimensione media per strumento per la tua specifica.
  4. Dividi il limite di dimensioni della risposta tools/list applicabile (10 MiB per impostazione predefinita) per la media per stimare il numero massimo di strumenti che rientrano in un nome host per una specifica di questa forma.

Aumento della capacità

Due meccanismi aumentano la capacità dello strumento oltre i valori predefiniti:

  • Dividi 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 (nel rispetto del limite di 100 nomi host per gruppo di ambienti). Lo sharding non aumenta il limite per 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, ciò comporta l'impostazione di envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory e envs.components.runtime.cwcAppend.bin_setenv_max_mem in overrides.yaml, quindi l'esecuzione di helm upgrade sul grafico apigee-org. Consulta la sezione Configurare il supporto del payload di messaggi di grandi dimensioni in Apigee hybrid per la procedura completa, incluse le varianti per ambiente e per installazione, le indicazioni per il dimensionamento dell'heap del processore di messaggi e gli esempi completi di overrides.yaml. L'aumento del limite di risposte non influisce sul limite di dimensioni del bundle proxy MCP di 50 MiB; se la tua capacità è vincolata da questo limite, questa modifica non ti aiuterà.

Sicurezza

Confine di attendibilità

Il data plane 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 fornisce la configurazione MCP derivata dalla 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 limitato al progetto tenant Apigee, recuperati dal sidecar MCP utilizzando il relativo account di servizio Google Cloud ambiente.

L'operatore Apigee esegue il provisioning di un Role e di un RoleBinding Kubernetes con ambito MCP nello spazio dei nomi Apigee (APIGEE_NAMESPACE) per il service account del data plane MCP. Il ruolo concede l'accesso di sola lettura:

  • get, list, watch su services nel gruppo di API di base.
  • get, list, watch su apigeeroutes nel gruppo di API apigee.cloud.google.com.

Il ruolo non concede verbi di scrittura e nessun accesso a Secrets, 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 risorsa personalizzata ApigeeOrganization (che deriva dal nome dell'organizzazione Apigee e da un hash breve). 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 nulla, elenca ogni risorsa RBAC correlata a MCP nello spazio dei nomi con:

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

TLS tra processore di messaggi e il piano dati MCP

I pod del processore di messaggi chiamano 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 contenitore del piano dati MCP presenta un certificato TLS firmato dall'emittente di cui è stato eseguito il provisioning di Apigee Operator (ClusterIssuer denominato apigee-ca-issuer). I nomi alternativi del soggetto del certificato includono entrambi i nomi host.

Limitare l'accesso in entrata al servizio MCP

In Apigee hybrid 1.17.0, il piano dati MCP non autentica in modo indipendente i suoi chiamanti. Confida che le richieste che lo raggiungono siano già state autenticate da un proxy Apigee MCP in esecuzione in un processore di messaggi. L'unico chiamante previsto del servizio MCP è il processore di messaggi. Qualsiasi altro carico di lavoro nel cluster che può raggiungere il ClusterIP del servizio MCP su TCP 443 può richiamare gli strumenti MCP senza un controllo dell'autenticazione.

Limita l'accesso in entrata ai pod MCP solo ai pod processore di messaggi utilizzando il motore di policy di ingresso del cluster della tua piattaforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy o equivalente). La limitazione:

  • Consente l'accesso in entrata ai pod con l'etichetta app=apigee-mcp-server nello spazio dei nomi APIGEE_NAMESPACE su TCP 443 dai pod con l'etichetta app=apigee-runtime solo nello stesso spazio dei nomi.
  • Nega tutto il traffico in entrata su TCP 443 ai pod con l'etichetta app=apigee-mcp-server.
  • Nega tutto l'ingresso nel cluster su TCP 15021 ai pod con l'etichetta app=apigee-mcp-server. La porta 15021 gestisce un endpoint HTTP semplice /healthz/ready non autenticato utilizzato da kubelet per il probing di disponibilità; kubelet lo raggiunge direttamente sull'IP del pod, quindi nessun altro workload nel cluster deve raggiungere i pod MCP su 15021.

Applica questa limitazione prima di completare la guida rapida di MCP e di eseguire il deployment del 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 data plane MCP carica il bundle recuperato e continua a gestirlo fino al successivo pull riuscito. Se i pull successivi non vanno a buon fine (il control plane Apigee non è raggiungibile, Cloud Storage non è raggiungibile, l'autorizzazione IAM è stata rimossa dal account di servizio watcher o si è verificato un errore in qualsiasi altra fase della pipeline di pull), il sidecar continua a pubblicare il bundle valido noto più recente a tempo indeterminato. Non esiste un limite di obsolescenza integrato in 1.17.0: il pod rimane Ready e il traffico dello strumento MCP continua a essere gestito in base al bundle obsoleto. Il segnale che la configurazione ha smesso di aggiornarsi è una riga di log sidecar a livello ERROR che contiene un contatore consecutive_failures (vedi Risoluzione dei problemi delle implementazioni MCP per i messaggi specifici emessi dal sidecar per ogni fase di errore).

Per gli ambienti di produzione regolamentati, pagina sugli incrementi ripetuti di questo contatore. Un avviso minimo praticabile è: pagina quando un contenitore secondario MCP emette una riga di log di livello ERROR con consecutive_failures che raggiunge una soglia impostata in base alla tolleranza all'obsolescenza. I valori in aumento indicano che il sidecar ha smesso di aggiornare la 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. Vedi Risolvere i problemi relativi ai deployment MCP. Il riavvio dei pod MCP non risolve il problema di recupero sottostante perché i pod appena creati seguono lo stesso percorso di recupero.

Requisiti di rete in uscita

Il sidecar MCP (il contenitore di configurazione all'interno di ogni pod MCP) ha bisogno dell'accesso di rete in uscita ai seguenti endpoint su TCP 443. Scegli la scheda che corrisponde all'utilizzo 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 attuale 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 posizione 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 attuale 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 raggiunge automaticamente.

Inoltre, il sidecar deve essere in grado di ottenere token di accesso Google Cloud per le credenziali ambientali con cui viene eseguito il pod (tramite Workload Identity o una chiave dell'account di servizio basata su file). Gli endpoint di scambio di token specifici dipendono dal percorso di autenticazione e sono gli stessi che gli altri componenti di Apigee Hybrid utilizzano già 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 accedere al server API Kubernetes all'interno del cluster (tramite l'indirizzo di servizio standard all'interno del cluster) per pubblicare il proprio stato di attività e preparazione. Questo traffico non esce mai dal tuo cluster.

Risoluzione dei problemi

Per un elenco di controllo diagnostico completo, consulta Risolvere i problemi relativi ai deployment di 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. L'organigramma è stato aggiornato prima del grafico dell'operatore. Esegui helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ prima, 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 riesce. Esegui kubectl describe pod sul pod interessato per il motivo esatto.
Report dei log di Sidecar (apigee-mcp-server-config) no MCP config from CP yet; skipping tick, pod stays Ready via seed in ogni sondaggio. Stato stazionario previsto quando non è ancora stato eseguito il deployment di alcun proxy di rilevamento MCP per la tua organizzazione. Il control plane Apigee restituisce un riferimento di configurazione vuoto e il data plane MCP ha caricato solo il listener di preparazione Kubernetes sulla porta 15021; la porta di richiesta MCP 8443 non ha ancora un listener e le richieste a https://mcp.apigee.internal/mcp ricevono un rifiuto di connessione. 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 di Apigee Watcher ha perso il ruolo roles/apigee.runtimeAgent (che concede l'autorizzazione apigee.runtimeconfigs.get necessaria al sidecar) nel tuo progetto tenant Apigee. L'installazione di base di Apigee Hybrid concede automaticamente questo ruolo. Se è stato rimosso da una pulizia dell'automazione IAM, riapplicalo al account di servizio Google Cloud apigee-watcher.
I log di Sidecar segnalano CP fetch failed con context deadline exceeded, errori DNS o TLS. Il sidecar non può raggiungere apigee.googleapis.com o storage.googleapis.com dall'interno del cluster. Verifica l'uscita rispetto ai tre endpoint elencati nei 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 eliminandolo (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). Il controller ApigeeDeployment lo ricreerà dalla specifica corrente, che include la voce hostAliases. Non utilizzare kubectl rollout restart deploy, in quanto non si applica a ApigeeDeployment.
I log dei pod MP mostrano errori di handshake TLS durante la composizione di 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 di controllo MCP sta pubblicando un certificato i cui nomi alternativi del soggetto (SAN) non includono il nome host composto dal 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