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 ibrido esistente che esegue la 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 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 panoramica di MCP in Apigee.

A cosa serve 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 piano dati MCP nel cluster. Un nuovo insieme di pod MCP viene creato 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 piano dati MCP. L'operatore Apigee aggiorna la specifica del pod del processore di messaggi in modo che MP indirizzi le chiamate allo strumento MCP al nuovo data plane MCP in-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 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 principale 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 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 sul 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 overrides.yaml unito, uno per ogni stile di autenticazione. Utilizza l'esempio che corrisponde alla configurazione dell'installazione di base esistente. Le righe specifiche di MCP sono evidenziate con commenti e sono le stesse 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 viene applicata 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 GKE Workload Identity (nessun file di chiavi dell'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.
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 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
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 carichi di lavoro. MCP eredita l'identità basata su WIF che apigee-watcher utilizza già nel tuo cluster. Non devi aggiungere alcuna configurazione dell'identità specifica di MCP.

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 rileva la stessa identità apigee-watcher risolta tramite WIF.

Passaggio 2: concedi all'identità del watcher l'accesso alla configurazione MCP sul control plane

Il sidecar MCP recupera il bundle di configurazione dal control plane Apigee utilizzando ilaccount di serviziot 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 della tua 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.

Si tratta di un passaggio da eseguire 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.

  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}.
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 sostituito watcher.gsa in overrides.yaml, utilizza questo valore anziché il valore predefinito apigee-watcher@${PROJECT_ID}..
  2. Chiama l'API updateControlPlaneAccess per aggiungere il account di servizio di monitoraggio 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 piano di controllo 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 l'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 serviziot del watcher. Ad esempio:

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

    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 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 errato 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, HPA, ServiceAccount, il ruolo e 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 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, 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 contenitore del data plane MCP a cui si connettono i pod MP.
  • apigee-mcp-server-config: il sidecar di configurazione (una modalità del file binario apigee-watcher) che recupera i bundle di configurazione dal control plane 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 per impostazione predefinita) e che MAXPODS corrisponda a mcpServer.replicaCountMax (10 per impostazione predefinita). Le colonne TARGETS, REPLICAS e AGE dipendono dalle metriche in tempo reale 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 Service ClusterIP di 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 di base) 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 di controllo MCP è in esecuzione e che può essere indirizzato da MP:

  • Ogni pod MCP è 2/2 Running. Il container del piano dati MCP non supera il probe di disponibilità di Kubernetes sulla porta 15021 se il certificato TLS emesso dall'operatore non è caricato e il sidecar non ha ancora caricato la configurazione MCP iniziale, quindi i pod Ready soddisfano entrambi i prerequisiti.
  • La specifica di ogni pod MP contiene la voce hostAliases che blocca mcp.apigee.internal e ORG_NAME.mcp.apigee.internal a ClusterIP del servizio MCP. Pertanto, i pod MP possono 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.

Verifichi il traffico end-to-end dello strumento MCP (una chiamata MCP initialize o tools/list 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: attiva 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 Mantieni 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 questo valore se noti che l'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 si trova 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 di memoria o la CPU viene limitata in modo costante. Signal: 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 torna a watcher.serviceAccountPath, poi a envs[].serviceAccountPaths.runtime. L'identità apigee-watcher dispone già delle autorizzazioni necessarie per il file collaterale MCP. Percorso di un file JSON con le chiavi per il account di servizio Google Cloud se esegui l'override. Si esclude a vicenda con mcpServer.gsa.

Se possibile, preferisci Workload Identity (GKE) o la federazione delle identità per i carichi di lavoro (AKS/EKS). Le chiavi dell'account di servizio 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 sidecar 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 del account di servizio 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.
mcpServer.podDisruptionBudget mappa unset PodDisruptionBudget facoltativo per i pod MCP. Accetta minAvailable o maxUnavailable (stringa di numeri interi o percentuali). Imposta uno dei due, non entrambi. Lascia questo campo vuoto a meno che il cluster non abbia norme di interruzione volontaria rigorose che richiedono un budget esplicito.
mcpServer.tolerations list unset (viene ripristinato il valore 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 Criterio 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 della capacità dello strumento MCP

Apigee Hybrid non impone un numero massimo fisso di strumenti MCP per organizzazione. La capacità dello strumento è invece limitata da quattro limiti di dimensioni rigidi applicati al momento del deployment o della richiesta. Il numero specifico di strumenti che possono essere inseriti 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 adattano 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 inferiore applicabile è quello 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 durante l'aggiornamento del gruppo di ambienti

Cosa determina le dimensioni per strumento

Le dimensioni per strumento sono composte quasi interamente dallo inputSchema dello strumento, che deriva da parameters e requestBody dell'operazione della specifica OpenAPI. Le tre proprietà più importanti sono:

  • 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 alla lettera nello strumento, quindi una descrizione più lunga aumenta direttamente le dimensioni dello strumento.

Gli schemi di risposta non vengono conteggiati ai fini del budget delle dimensioni. Solo parameters e requestBody raggiungono la configurazione MCP. Pertanto, il dimensionamento della capacità in base alle 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 tua 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 della descrizione nella specifica completa).
  2. Chiama tools/list sul 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 dimensione 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:

  • 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 (soggetta al limite di 100 nomi host per gruppo di ambienti). Lo sharding non aumenta il limite per pacchetto per proxy; il limite di 50 MiB per pacchetto 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 pagina Configurare il supporto di 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à è limitata 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 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 per il tuo progetto tenant Apigee, recuperati dal sidecar MCP utilizzando il relativo account di servizio Google Cloud ambiente.

L'operatore Apigee esegue il provisioning di un Kubernetes Role e RoleBinding 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 principale.
  • 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 tuo 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 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 fornita da 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 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 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'accesso in entrata 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 della configurazione, 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 Risolvere i 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 vitale è: pagina quando un contenitore sidecar 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. Consulta la sezione Risoluzione dei problemi delle implementazioni 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 alla 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 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 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 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 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 ibrido Apigee esistente verso le API 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 in-cluster al server API Kubernetes (tramite l'indirizzo di servizio in-cluster standard) per pubblicare il proprio stato di attività e preparazione. Questo traffico non esce mai dal 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 a ogni sondaggio. Stato stazionario previsto quando non è ancora stato implementato 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 solo il listener di disponibilità 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 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 HTTP incorporato 403 o PermissionDenied. 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 progetto tenant Apigee. L'installazione di base di Apigee Hybrid concede automaticamente questo ruolo. Se è stato rimosso da una pulizia dell'automazione IAM, riapplicalo all'account di servizio Google Cloud apigee-watcher.
I log del 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 il giorno 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 data plane MCP sta pubblicando un certificato i cui nomi alternativi del soggetto (SAN) non includono il nome host a cui si è connesso il 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 Certificate e lascia che cert-manager la riemetta.

Passaggi successivi