Activer le protocole MCP (Model Context Protocol) dans Apigee hybrid

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment activer le protocole MCP (Model Context Protocol) dans un cluster Apigee hybrid existant exécutant la version 1.17.0 ou ultérieure. Une fois cette procédure terminée, votre cluster exécute un nouveau plan de données MCP dans le cluster, et votre processeur de messages est prêt à y acheminer les appels d'outils MCP. Vous pouvez ensuite déployer votre premier proxy de découverte MCP en suivant le guide de démarrage rapide MCP partagé.

Pour en savoir plus sur les concepts, l'architecture et les fonctionnalités MCP partagés entre Apigee et Apigee hybrid, consultez la présentation de MCP dans Apigee.

En quoi consiste cette procédure ?

L'activation de MCP sur un cluster Apigee hybrid entraîne les modifications suivantes :

  1. Accorde à l'identité apigee-watcher l'accès à la configuration MCP sur le plan de contrôle Apigee. Ajoutez le compte de service apigee-watcher à la liste watcher_identities de la ressource controlPlaneAccess de votre organisation Apigee afin que le side-car MCP puisse extraire les bundles de configuration MCP du plan de contrôle Apigee. Il s'agit d'une modification du plan de contrôle, limitée à l'organisation Apigee. Il s'agit d'une étape unique par organisation, quel que soit le nombre de clusters qui desservent cette organisation.
  2. Ajoute un nouveau plan de données MCP dans le cluster. Un nouvel ensemble de pods MCP est créé dans le même espace de noms Kubernetes où Apigee hybrid est installé (apigee par défaut), ainsi que les ressources Kubernetes associées (service, autoscaler horizontal de pods et RBAC) nécessaires à leur exécution. Les appels d'outils MCP sont gérés par ces pods.
  3. Configure votre processeur de messages pour accéder au plan de données MCP. L'opérateur Apigee met à jour la spécification du pod Processeur de messages afin que MP route les appels d'outils MCP vers le nouveau plan de données MCP dans le cluster. L'application de cette modification déclenche une version canary par étapes du processeur de messages (gérée par le contrôleur ApigeeDeployment). Le pod précédent continue de diffuser le trafic jusqu'à ce que le nouveau pod soit Ready. La version n'est déclenchée que lors des transitions d'activation et de désactivation, et non lors de l'activité MCP en cours ni du trafic MCP à l'état stable. Exécutez cette procédure dans une fenêtre de maintenance approuvée et attendez la fin de la mise à jour avant de continuer.

Étape 1 : Modifiez overrides.yaml

Ouvrez le fichier overrides.yaml que vous utilisez pour vos charts Helm Apigee hybrid. En haut du fichier, ajoutez :

enableMcpServer: true

Il s'agit de la configuration minimale requise pour activer MCP. Il utilise les valeurs par défaut intégrées du graphique apigee-org : deux répliques de plan de données MCP qui évoluent automatiquement jusqu'à dix à 70% d'utilisation du processeur, avec des demandes de ressources de 500 m de processeur et 512 Mi de mémoire, et des limites de 2 000 m de processeur et 1 Gi de mémoire sur le conteneur de plan de données MCP. Pour personnaliser le nombre de répliques, les demandes de ressources ou le compte de service MCP, consultez Référence : champs MCP dans overrides.yaml plus loin sur cette page.

Vous trouverez ci-dessous des exemples complets de overrides.yaml fusionnés, un pour chaque style d'authentification. Utilisez l'exemple qui correspond à la configuration de votre installation de base existante. Les lignes spécifiques à MCP sont mises en évidence par des commentaires et sont identiques dans les trois variantes.

Sélectionnez l'onglet qui correspond à la façon dont votre installation de base authentifie les composants Apigee auprès de Google Cloud. La sélection s'applique à tous les blocs de code de portée variable sur cette page.

Workload Identity (GKE)

Utilisez cette variante si votre installation de base authentifie les composants Apigee auprès de Google Cloud via GKE Workload Identity (aucun fichier de clé de compte de service sur le disque).

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: {}
# ----------------------------------------------------------------------------

Clés de compte de service basées sur des fichiers

Utilisez cette variante si votre installation de base authentifie les composants Apigee auprès de Google Cloud à l'aide de fichiers de clé de compte de service que vous distribuez à chaque 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: {}
# ----------------------------------------------------------------------------

Fédération d'identité de charge de travail (AKS/EKS)

Utilisez cette variante si votre installation de base se trouve sur AKS ou EKS et s'authentifie auprès de Google Cloud via la fédération d'identité de charge de travail. MCP hérite de l'identité basée sur WIF que apigee-watcher utilise déjà dans votre cluster. Vous n'avez pas besoin d'ajouter de configuration d'identité spécifique à MCP.

Ajoutez la clé de premier niveau MCP à votre fichier overrides.yaml WIF existant :

# ---- 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: {}
# ----------------------------------------------------------------------------

Ne définissez pas mcpServer.gsa et mcpServer.serviceAccountPath. Le side-car MCP récupère la même identité apigee-watcher et la résout via WIF.

Étape 2 : Accordez à l'identité de l'observateur l'accès à la configuration MCP sur le plan de contrôle

Le side-car MCP récupère son bundle de configuration à partir du plan de contrôle Apigee à l'aide du compte de service Google Cloud du composant apigee-watcher (l'identité que vous avez sélectionnée à l'étape 1). Avant le démarrage des pods MCP, ajoutez ce compte de service à la liste watcher_identities de la ressource controlPlaneAccess de votre organisation Apigee. Sans cette autorisation, les appels du side-car MCP à apigee.googleapis.com pour récupérer la référence de configuration MCP renvoient 404 Not Found et le plan de données MCP n'est jamais prêt à diffuser le trafic d'outils.

Il s'agit d'une étape unique par organisation (et non par cluster). Ignorez cette étape si vous avez déjà accordé l'accès pour un cluster précédent dans la même organisation Apigee.

  1. Définissez les variables shell que vous utilisez pour l'appel d'API. Réutilisez les valeurs de votre installation : 
    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)

    Où :

    • YOUR_ORG_NAME est le nom de votre organisation Apigee Hybrid.
    • YOUR_GCP_PROJECT_ID est le projet Google Cloud qui héberge votre organisation Apigee hybrid.
    • WATCHER_SA est l'adresse e-mail du compte de service apigee-watcher. Si vous avez remplacé watcher.gsa dans overrides.yaml, utilisez cette valeur au lieu de la valeur par défaut apigee-watcher@${PROJECT_ID}..
  2. Appelez l'API updateControlPlaneAccess pour ajouter le compte de service Watcher à la liste watcher_identities :

    Sans résidence des données

    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}\"]}"

    Résidence des données

    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}\"]}"

    Où CONTROL_PLANE_LOCATION correspond à l'emplacement de vos données de plan de contrôle si votre installation Apigee hybrid utilise la résidence des données. Pour obtenir la liste des emplacements disponibles, consultez Régions du plan de contrôle de l'API Apigee disponibles.

    L'appel renvoie une opération de longue durée. Attendez la fin de l'opération avant d'exécuter l'étape de validation ci-dessous.

  3. Vérifiez que la subvention a bien été accordée. Appelez getControlPlaneAccess et vérifiez que le compte de service du service d'observation s'affiche dans le champ watcherIdentities de la réponse :

    Sans résidence des données

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

    Résidence des données

    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 réponse doit inclure un tableau watcherIdentities contenant votre compte de service d'observateur. Exemple :

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

    Si watcherIdentities est absent de la réponse ou ne contient pas votre compte de service d'observateur, réexécutez la commande PATCH et vérifiez l'état de l'opération pour détecter les erreurs avant de continuer.

Étape 3 : Mettez à niveau le graphique apigee-operator

Mettez d'abord à niveau le graphique de l'opérateur. Le chart de l'opérateur possède le schéma des nouvelles ressources MCP, et le chart de l'organisation les référence. Si vous effectuez la mise à niveau dans le mauvais ordre, vous obtiendrez un helm upgrade réussi, mais aucun pod MCP ne sera créé.

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

L'exécution de la commande prend moins d'une minute. Vérifiez que le déploiement de l'opérateur est entièrement déployé avec la nouvelle image (apigee-controller-manager Deployment est une ressource Kubernetes standard, et non un ApigeeDeployment, donc kubectl rollout status deploy est la bonne commande ici) :

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

Résultat attendu :

deployment "apigee-controller-manager" successfully rolled out

Étape 4 : Mettez à niveau le chart apigee-org

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

Deux boucles de réconciliation s'exécutent désormais en parallèle :

  • L'opérateur Apigee crée le déploiement, le service, le AHP, le ServiceAccount, le rôle et le RoleBinding MCP. Les pods MCP sont lancés deux par deux (selon la planification Kubernetes). Le conteneur side-car de chaque pod effectue sa première récupération de configuration à partir du plan de contrôle Apigee peu après le démarrage.
  • L'opérateur Apigee insère l'entrée hostAliases dans la spécification du pod Message Processor, ce qui déclenche une version de apigee-runtime ApigeeDeployment.

Étape 5 : Vérifiez l'installation

Vérifier que le plan de données MCP est en cours d'exécution

Inspectez les quatre ressources liées à MCP créées par l'opérateur. Les noms de ressources incluent un suffixe dérivé de l'organisation. Les exemples suivants utilisent ORG_CR_SUFFIX comme espace réservé pour ce suffixe. Les suffixes de pod et le ClusterIP de service seront différents dans votre environnement.

Pods MCP (deux par défaut, autoscaling jusqu'à dix en cas de charge) :

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

Chaque pod doit afficher 2/2 dans la colonne READY. Les deux conteneurs de chaque pod sont les suivants :

  • apigee-mcp-server : conteneur du plan de données MCP auquel se connectent les pods MP.
  • apigee-mcp-server-config : side-car de configuration (mode du binaire apigee-watcher) qui récupère les bundles de configuration depuis le plan de contrôle Apigee et les écrit dans un volume partagé que lit le conteneur du plan de données MCP.

MCP ApigeeDeployment (ressource personnalisée Kubernetes, et non 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

L'état attendu est running. Vérifiez également que le pod sous-jacent est 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

Service 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

MCP HorizontalPodAutoscaler :

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

Vérifiez que MINPODS correspond à mcpServer.replicaCountMin de votre overrides.yaml (2 par défaut) et que MAXPODS correspond à mcpServer.replicaCountMax (10 par défaut). Les colonnes TARGETS, REPLICAS et AGE dépendent des métriques en direct et de l'état du cluster.

Vérifiez que les pods Processeur de messages ont reçu l'entrée hostAliases.

Chaque pod MP doit afficher l'entrée injectée. Si un seul pod est manquant, il ne peut pas router les appels d'outils MCP. Listez tous les pods MP et leurs hostAliases :

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

Résultat attendu : chaque pod MP liste un tableau hostAliases contenant une entrée avec deux noms d'hôte pointant vers l'adresse ClusterIP du service MCP de l'étape précédente (le deuxième nom d'hôte utilise le nom de votre organisation en minuscules). Les noms des pods Processeur de messages suivent le modèle apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, où TRUNCATED_ORG est le nom de votre organisation (tronqué pour respecter la limite de 63 caractères de Kubernetes si le nom de votre organisation est long), ENV_GROUP_HASH est un hachage de groupe de déploiement par environnement, REV est le numéro de révision de la version actuelle (quatre chiffres, par exemple 1170) et POD_HASH est un suffixe aléatoire par pod. Exemple :

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]]

Si un pod affiche une valeur hostAliases vide, cela signifie que le processeur de messages ApigeeDeployment n'a pas entièrement récupéré la spécification de pod mise à jour. Forcez une nouvelle version Canary intermédiaire en supprimant les pods du processeur de messages actuel. Le contrôleur ApigeeDeployment les rendra à nouveau à partir de la spécification actuelle (qui inclut désormais l'entrée hostAliases) :

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

Le contrôleur ApigeeDeployment recréera les pods dans un délai d'une minute. Notez que kubectl rollout restart deploy (la commande Kubernetes standard) ne fonctionne pas sur le processeur de messages, car celui-ci est déployé en tant que ressource personnalisée ApigeeDeployment et non en tant que Deployment.

Installation terminée

Ensemble, les trois vérifications précédentes confirment que votre plan de données MCP est en cours d'exécution et que l'adresse MP est accessible :

  • Chaque pod MCP est 2/2 Running. Le conteneur du plan de données MCP échoue à sa vérification d'aptitude Kubernetes sur le port 15021 si le certificat TLS émis par l'opérateur n'est pas chargé et que le side-car n'a pas encore chargé sa configuration MCP initiale. Les pods Ready remplissent donc ces deux conditions préalables.
  • La spécification de chaque pod MP contient l'entrée hostAliases qui épingle mcp.apigee.internal et ORG_NAME.mcp.apigee.internal au ClusterIP du service MCP. Les pods MP peuvent donc résoudre les points de terminaison cibles du proxy MCP vers le plan de données MCP de votre cluster.
  • Un pod MP résout mcp.apigee.internal en ClusterIP du service MCP via l'entrée hostAliases injectée.

Vous validez le trafic d'outil MCP de bout en bout (un appel MCP initialize ou tools/list réel via votre entrée Apigee) dans le démarrage rapide MCP partagé, après avoir déployé votre premier proxy de découverte MCP.

Si l'une des trois vérifications précédentes échoue, consultez Dépannage des déploiements MCP avant de passer au guide de démarrage rapide.

Étape 6 : Activez MCP sur les clusters restants

Les requêtes MCP pour un nom d'hôte donné peuvent être acheminées vers n'importe quel cluster desservant le groupe d'environnements Apigee correspondant. Si MCP est activé sur certains clusters et pas sur d'autres dans le même groupe d'environnement, les requêtes MCP acheminées vers un cluster sans MCP activé échouent (généralement renvoyées au client sous la forme 503 Service Unavailable).

Activez MCP de manière uniforme sur chaque cluster qui dessert le même groupe d'environnements. Pour chaque cluster supplémentaire, répétez les étapes 1, 3, 4 et 5. Vous n'avez pas besoin de répéter l'étape 2 (accorder l'accès à l'identité de l'observateur) : cette autorisation est limitée à l'organisation Apigee et s'applique à tous les clusters de la même organisation.

Rollback

Pour désactiver MCP sur un cluster, définissez enableMcpServer: false (ou supprimez complètement le champ) dans overrides.yaml, puis mettez à niveau le graphique apigee-org :

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

Le champ enableMcpServer n'est utilisé que par le graphique apigee-org. Le graphique de l'opérateur n'a donc pas besoin d'être mis à niveau lors d'une désactivation. L'opérateur Apigee (inchangé) récupère la modification de configuration à partir de la ressource personnalisée ApigeeOrganization, supprime les ressources MCP et supprime l'entrée hostAliases de la spécification du pod Processeur de messages, ce qui déclenche une version de apigee-runtime ApigeeDeployment. Effectuez un rollback pendant un intervalle de maintenance approuvé.

Après la restauration, les proxys de découverte MCP que vous avez déployés dans l'environnement Apigee sont toujours présents dans le plan de contrôle Apigee, mais aucun cluster de ce groupe d'environnements ne traite le trafic MCP. Annulez le déploiement des proxys de découverte MCP pour désactiver complètement la fonctionnalité, ou laissez-les déployés et réactivez MCP sur les clusters ultérieurement.

Référence : Champs MCP dans overrides.yaml

Le tableau suivant liste tous les champs overrides.yaml Apigee hybrid qui contrôlent le comportement du MCP dans la version 1.17.0. Seul enableMcpServer est obligatoire. Tous les autres champs ont des valeurs par défaut sécurisées qui conviennent à la plupart des installations.

Les définitions de champ correspondent aux valeurs par défaut du chart Helm apigee-org pour 1.17.0 hybride.

Champ Type Par défaut Réglage recommandé
enableMcpServer booléen false Obligatoire. Définissez la valeur sur true pour activer MCP sur ce cluster. Si vous activez ce champ, un déploiement de version Canary par étapes du Processeur de messages est déclenché. N'activez le bouton bascule que pendant un intervalle de maintenance et attendez la fin de la version avant de continuer.
mcpServer.replicaCountMin entier 2 Conservez 2 pour la haute disponibilité. Augmentez-le uniquement si vous avez une référence de trafic MCP élevé. L'AHP évolue automatiquement en cas de pression sur le CPU. Signal : AHP soutenue à replicaCountMax et CPU au-dessus de la cible.
mcpServer.replicaCountMax entier 10 Augmentez-la si vous constatez que l'AHP est plafonnée à 10 pendant les pics. Signal : kubectl top pods -l app=apigee-mcp-server affiche tous les pods proches de leur limite de processeur au pic. Si metrics-server n'est pas installé, utilisez kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server et vérifiez si la colonne REPLICAS est au plafond MAXPODS.
mcpServer.targetCPUUtilizationPercentage entier 70 50–60 pour les charges de travail sensibles à la latence (mise à l'échelle plus tôt). Augmentez la valeur à 80–85 pour réduire le nombre de répliques dans les clusters sensibles aux coûts. Signal : la latence des requêtes P95 est corrélée au processeur par pod.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi Augmentez les requêtes si les pods sont fréquemment arrêtés en raison d'une erreur Out of Memory ou si leur processeur est limité à l'état stable. Signal : kubectl describe pod indique les conditions OOMKilled ou de limitation.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Augmentez la limite de processeur avant d'augmenter le nombre de répliques lorsque la latence P95 est élevée, mais que le nombre total de requêtes par seconde est faible (requêtes peu nombreuses et coûteuses). N'augmentez la limite de mémoire que si vous constatez des erreurs OOMKill.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Il est rarement nécessaire de l'ajuster. Le side-car compose et écrit régulièrement des ensembles de configuration. L'utilisation du processeur en état stable est minimale.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Il est rarement nécessaire de l'ajuster. N'augmentez la mémoire que si vous déployez un nombre inhabituellement élevé d'outils MCP dans un seul proxy Discovery.
mcpServer.terminationGracePeriodSeconds entier 30 Il est rarement nécessaire de l'ajuster. Augmentez cette valeur si les requêtes MCP en cours de longue durée ont besoin de plus de temps pour se terminer lors d'une vidange de pod.
mcpServer.annotations carte {} Ajoutez des annotations de pod supplémentaires si votre cluster en a besoin.
mcpServer.serviceAccountPath string unset Laissez cette option non définie, sauf si vous avez besoin d'une séparation des identités par composant. Lorsqu'elle n'est pas définie, MCP revient à watcher.serviceAccountPath, puis à envs[].serviceAccountPaths.runtime. L'identité apigee-watcher dispose déjà des autorisations dont le side-car MCP a besoin. Chemin d'accès à un fichier JSON de clé de compte de service Google Cloud si vous effectuez un remplacement. S'exclut mutuellement avec mcpServer.gsa.

Privilégiez Workload Identity (GKE) ou la fédération d'identité de charge de travail (AKS/EKS) autant que possible. Les clés de compte de service basées sur des fichiers doivent être renouvelées, stockées de manière sécurisée et distribuées à chaque cluster. Elles sont la source la plus courante de fuites dans les artefacts d'assistance (voir Demandes d'assistance).
mcpServer.gsa string unset Laissez cette option non définie, sauf si vous avez besoin d'une séparation des identités par composant. Lorsqu'elle n'est pas définie, MCP revient à watcher.gsa, puis à gcp.workloadIdentity.gsa. L'identité apigee-watcher dispose déjà des autorisations dont le side-car MCP a besoin. Il est donc recommandé de la réutiliser. Remplacez-le par une adresse e-mail de compte de service Google Cloud dédiée uniquement si votre organisation exige une identité distincte pour le side-car MCP à des fins d'audit.
mcpServer.serviceAccountRef string unset Paramètres avancés. Nom d'un secret Kubernetes existant dans l'espace de noms Apigee qui contient une clé de compte de service Google Cloud pour le side-car MCP. N'utilisez cette option que si vous gérez les secrets de clé de compte de service en dehors des charts Helm Apigee. S'exclut mutuellement avec mcpServer.serviceAccountPath et mcpServer.gsa.
mcpServer.podDisruptionBudget carte unset PodDisruptionBudget facultatif pour les pods MCP. Accepte minAvailable ou maxUnavailable (chaîne de pourcentage ou entier). Définissez l'un ou l'autre, mais pas les deux. Ne définissez pas cette valeur, sauf si votre cluster applique des règles strictes de perturbation volontaire qui nécessitent un budget explicite.
mcpServer.tolerations list unset (reprend la valeur de tolerations au niveau supérieur) Tolérances Kubernetes standards pour les pods MCP. Ne définissez cette valeur que si les pods MCP doivent tolérer les taints que les autres composants Apigee ne tolèrent pas.
mcpServer.image.pullPolicy string IfNotPresent Stratégie d'extraction d'images pour le conteneur serveur MCP. Rarement modifié.
mcpServer.sidecar.image.pullPolicy string IfNotPresent Stratégie d'extraction d'images pour le conteneur side-car MCP. Rarement modifié.

Estimer la capacité des outils MCP

Apigee hybrid n'impose pas de nombre maximal fixe d'outils MCP par organisation. Au lieu de cela, la capacité de l'outil est limitée par quatre limites de taille strictes appliquées au moment du déploiement ou de la requête. Le nombre d'outils pouvant être utilisés dépend de la taille de chacun d'eux, qui est dérivée de la spécification OpenAPI définissant l'outil.

Capacité standard

Pour la plupart des spécifications OpenAPI (un mélange d'outils avec un nombre de paramètres, une taille de corps de requête et une longueur de description variables, la majorité des outils se situant dans la plage de taille petite à moyenne), vous pouvez généralement vous attendre à pouvoir intégrer 10 000 outils MCP par organisation avec la limite de taille de réponse tools/list par défaut.

La capacité réelle varie en fonction de la forme spécifique de votre spécification OpenAPI. Les organisations dont les spécifications sont dominées par des outils comportant de nombreux paramètres, des corps de requête volumineux ou de longues descriptions peuvent intégrer proportionnellement moins d'outils avant d'atteindre l'une des quatre limites strictes ci-dessous. Pour valider la capacité de vos spécifications spécifiques, suivez les instructions de la section Estimer la capacité de vos spécifications ci-dessous.

Limites strictes

Quatre limites de taille s'appliquent dans la version 1.17.0 d'Apigee hybrid. C'est la limite la plus basse qui s'applique. Augmenter l'une d'elles n'augmente pas les autres.

Limite Valeur Champ d'application Mode de défaillance
Taille du fichier de spécification OpenAPI 3 Mio par fichier .yaml 400 lors de la validation du proxy
Taille du bundle de proxy MCP (décompressé) 50 Mio par proxy de découverte MCP 400 lors de la validation du proxy
Taille de réponse tools/list 10 Mio (par défaut) par nom d'hôte 502 par TooBigBody
Noms d'hôte par groupe d'environnements 100 par groupe d'environnements 400 lors de la mise à jour d'un groupe d'environnements

Qu'est-ce qui détermine la taille de chaque outil ?

La taille par outil est presque entièrement composée du inputSchema de l'outil, qui est dérivé des parameters et requestBody de la spécification OpenAPI pour l'opération. Trois propriétés sont les plus importantes :

  • Nombre de paramètres. Chaque entrée de paramètre contribue à peu près 100 octets à la taille de l'outil dans la réponse tools/list.
  • Nombre de propriétés du corps de la requête. Chaque propriété du corps de la requête contribue à environ 100 octets. Les opérations avec un corps de requête (généralement POST et PUT) sont donc beaucoup plus volumineuses que celles sans corps de requête (généralement GET et DELETE).
  • Longueur de la description : Les descriptions des opérations sont copiées presque mot à mot dans l'outil. Par conséquent, une description plus longue augmente directement la taille de l'outil.

Les schémas de réponse ne sont pas pris en compte dans le budget de taille. Seuls parameters et requestBody atteignent la configuration MCP. Par conséquent, la capacité de dimensionnement basée uniquement sur la taille du fichier OpenAPI a tendance à surestimer les coûts, car la plupart des spécifications OpenAPI réelles incluent des définitions de schéma de réponse qui n'affectent pas la taille de l'outil.

Estimer la capacité pour votre spécification

La méthode la plus fiable pour estimer la capacité des outils pour vos spécifications OpenAPI consiste à mesurer un sous-ensemble représentatif :

  1. Déployez un proxy de découverte MCP qui fait référence à un petit sous-ensemble représentatif des outils que vous prévoyez de publier (par exemple, 50 à 100 outils qui reflètent le mélange de nombres de paramètres, de tailles de corps de requête et de longueurs de description dans votre spécification complète).
  2. Appelez tools/list sur le proxy déployé et enregistrez la taille de la réponse en octets et le nombre d'outils renvoyés.
  3. Divisez la taille de la réponse par le nombre d'outils pour obtenir la taille moyenne par outil pour votre spécification.
  4. Divisez la limite de taille de réponse tools/list applicable (10 Mio par défaut) par cette moyenne pour estimer le nombre maximal d'outils pouvant tenir sur un nom d'hôte pour une spécification de cette forme.

Augmenter la capacité

Deux mécanismes permettent d'augmenter la capacité des outils au-delà des valeurs par défaut :

  • Répartissez les outils sur les noms d'hôte. La limite de réponses tools/list est définie par nom d'hôte. La répartition des outils sur plusieurs noms d'hôte au sein d'un même groupe d'environnements multiplie la marge de manœuvre par nom d'hôte (dans la limite de 100 noms d'hôte par groupe d'environnements). Le partitionnement n'augmente pas la limite de bundle par proxy. La limite de 50 Mio continue de s'appliquer à tous les noms d'hôte sur un même proxy de découverte MCP.
  • Augmentez la limite de taille des réponses de tools/list. La limite par défaut est de 10 Mio par nom d'hôte. Vous pouvez l'augmenter jusqu'à 30 Mio. Au minimum, cela implique de définir envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory et envs.components.runtime.cwcAppend.bin_setenv_max_mem dans votre overrides.yaml, puis d'exécuter helm upgrade sur le graphique apigee-org. Pour connaître la procédure complète, y compris les variantes par environnement et par installation, les conseils sur le dimensionnement du tas de mémoire du processeur de messages et les exemples complets de overrides.yaml, consultez Configurer la prise en charge des charges utiles de messages volumineux dans Apigee hybrid. L'augmentation de la limite de réponse n'a aucune incidence sur la limite de taille de 50 Mio du bundle de proxy MCP. Si votre capacité est limitée par cette limite, ce changement ne vous aidera pas.

Sécurité

Limite de confiance

Le plan de données MCP s'exécute dans votre propre cluster Kubernetes. Google n'a aucun accès au plan de données lors de l'exécution. Le plan de contrôle Apigee vous fournit une configuration MCP dérivée de votre spécification OpenAPI. Il n'observe pas le trafic des requêtes MCP. Les données de configuration au repos sont stockées dans un bucket Cloud Storage géré par Apigee et limité au projet de locataire Apigee. Elles sont récupérées par le side-car MCP à l'aide de son compte de service Google Cloud ambiant.

L'opérateur Apigee provisionne un Role et un RoleBinding Kubernetes à portée MCP dans votre espace de noms Apigee (APIGEE_NAMESPACE) pour le compte de service du plan de données MCP. Ce rôle accorde un accès en lecture seule :

  • get, list et watch sur services dans le groupe d'API Core.
  • get, list, watch sur apigeeroutes dans le groupe d'API apigee.cloud.google.com.

Le rôle n'accorde aucun verbe d'écriture ni aucun accès à Secrets, ConfigMaps ou à l'état du pod. Votre auditeur peut vérifier les règles exactes directement à partir du cluster avec la commande suivante :

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

Les ressources apigee-mcp-server-APIGEE_ORG_CR Role et RoleBinding sont des ressources RBAC à portée MCP. Leur nom inclut le nom complet de votre ressource personnalisée ApigeeOrganization (qui est dérivé du nom de votre organisation Apigee et d'un hachage court). Elles ne comportent pas de libellé app=apigee-mcp-server au niveau de la ressource (seuls les pods en comportent un). Par conséquent, une recherche basée sur un libellé ne renvoie aucun résultat. Si la commande field-selector ci-dessus ne renvoie rien, listez toutes les ressources RBAC liées à MCP dans l'espace de noms avec :

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

TLS entre le processeur de messages et le plan de données MCP

Les pods du processeur de messages appellent le plan de données MCP à l'adresse https://mcp.apigee.internal/ ou https://ORG_NAME.mcp.apigee.internal/. Ces noms d'hôte sont résolus en ClusterIP du service MCP via l'entrée hostAliases injectée. Le conteneur du plan de données MCP présente un certificat TLS signé par l'émetteur provisionné par l'opérateur Apigee (ClusterIssuer nommé apigee-ca-issuer). Les autres noms de l'objet du certificat incluent les deux noms d'hôte.

Restreindre l'accès entrant au service MCP

Dans Apigee hybrid 1.17.0, le plan de données MCP n'authentifie pas ses appelants de manière indépendante. Il part du principe que les requêtes qui lui parviennent ont déjà été authentifiées par un proxy MCP Apigee exécuté dans le processeur de messages. Le seul appelant prévu du service MCP est le processeur de messages. Toute autre charge de travail du cluster pouvant atteindre l'adresse IP du cluster de service MCP sur le port TCP 443 peut appeler les outils MCP sans vérification de l'authentification.

Limitez l'accès entrant aux pods MCP aux pods Processeur de messages uniquement, à l'aide du moteur de règles d'entrée de cluster de votre plate-forme (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy ou équivalent). Restriction :

  • Autorise l'entrée dans les pods portant l'étiquette app=apigee-mcp-server dans l'espace de noms APIGEE_NAMESPACE sur le port TCP 443 depuis les pods portant l'étiquette app=apigee-runtime dans le même espace de noms uniquement.
  • Refuse tout autre trafic entrant sur le port TCP 443 vers les pods portant le libellé app=apigee-mcp-server.
  • Refuse tout le trafic entrant dans le cluster sur le port TCP 15021 vers les pods portant le libellé app=apigee-mcp-server. Le port 15021 dessert un point de terminaison /healthz/ready HTTP simple non authentifié utilisé par kubelet pour le probing de disponibilité. kubelet y accède directement sur l'adresse IP du pod. Aucune autre charge de travail du cluster ne doit donc accéder aux pods MCP sur 15021.

Appliquez cette restriction avant de suivre le guide de démarrage rapide MCP et de déployer votre premier proxy de découverte MCP dans un environnement autre que celui de développement.

Contrat de fraîcheur de la configuration

Lorsque le side-car MCP effectue une extraction de configuration réussie, le conteneur du plan de données MCP charge le bundle récupéré et continue de le diffuser jusqu'à la prochaine extraction réussie. Si les extractions suivantes échouent (plan de contrôle Apigee inaccessible, Cloud Storage inaccessible, autorisation IAM supprimée sur le compte de service du watcher ou erreur à une autre étape du pipeline d'extraction), le side-car continue de diffuser le dernier bundle correct indéfiniment. Il n'existe pas de plafond d'obsolescence intégré dans 1.17.0 : le pod reste Ready et le trafic de l'outil MCP continue d'être diffusé par rapport au bundle obsolète. Le signal indiquant que la configuration a cessé de s'actualiser est une ligne de journal side-car au niveau ERROR qui comporte un compteur consecutive_failures (consultez Résoudre les problèmes de déploiements MCP pour connaître les messages spécifiques émis par le side-car à chaque étape d'échec).

Pour les environnements de production réglementés, consultez la page sur les incréments répétés de ce compteur. Une alerte viable minimale est une page lorsqu'un conteneur side-car MCP émet une ligne de journal de niveau ERROR avec consecutive_failures atteignant un seuil que vous définissez en fonction de votre tolérance à la fraîcheur. Des valeurs en hausse indiquent que le side-car a cessé d'actualiser la configuration. En attendant, il continue de diffuser le dernier bundle réussi.

Si le side-car a cessé d'actualiser la configuration, examinez le mode d'échec à partir des journaux du side-car. Pour en savoir plus, consultez Résoudre les problèmes liés aux déploiements MCP. Le redémarrage des pods MCP ne résout pas le problème de récupération sous-jacent, car les pods nouvellement créés empruntent le même chemin de récupération.

Configuration réseau sortante requise

Le side-car MCP (le conteneur de configuration à l'intérieur de chaque pod MCP) a besoin d'un accès réseau sortant aux points de terminaison suivants sur le port TCP 443. Sélectionnez l'onglet correspondant à l'utilisation ou non de la résidence des données par votre organisation Apigee. Les points de terminaison requis sont différents.

Sans résidence des données

Point de terminaison Utilisation
apigee.googleapis.com Récupérez la référence de configuration MCP actuelle pour votre organisation à partir du plan de contrôle Apigee à chaque actualisation de la configuration.
storage.googleapis.com Téléchargez la configuration MCP de votre organisation depuis Google Cloud Storage.

Résidence des données

Si votre organisation Apigee utilise la résidence des données, le side-car MCP accède au point de terminaison régional du plan de contrôle Apigee (le même point de terminaison que celui utilisé par vos autres composants Apigee hybrid, configuré via la valeur du graphique contractProvider dans votre overrides.yaml). Remplacez CONTROL_PLANE_LOCATION par l'emplacement du plan de contrôle de votre organisation (par exemple, us, eu).

Point de terminaison Utilisation
CONTROL_PLANE_LOCATION-apigee.googleapis.com Récupérez la référence de configuration MCP actuelle pour votre organisation à partir de votre point de terminaison régional du plan de contrôle Apigee à chaque actualisation de la configuration.
storage.googleapis.com Téléchargez la configuration MCP de votre organisation depuis Google Cloud Storage. Le bucket se trouve dans la région de votre organisation. Cloud Storage y accède automatiquement.

De plus, le side-car doit pouvoir obtenir des jetons d'accès Google Cloud pour les identifiants ambiants sous lesquels le pod s'exécute (via Workload Identity ou une clé de compte de service basée sur un fichier). Les points de terminaison d'échange de jetons spécifiques dépendent de votre chemin d'authentification et sont les mêmes que ceux que les autres composants Apigee hybrid utilisent déjà dans votre cluster. Si le trafic hybride Apigee existant vers les API Google Cloud réussit à partir de cet espace de noms, l'échange de jetons du side-car MCP réussit également.

De plus, le side-car a besoin d'un accès au serveur d'API Kubernetes dans le cluster (via l'adresse de service standard dans le cluster) pour publier son état de disponibilité et de préparation. Ce trafic ne quitte jamais votre cluster.

Dépannage

Pour obtenir une checklist de diagnostic complète, consultez Résoudre les problèmes de déploiements MCP, qui inclut une checklist de diagnostic côté cluster pour Apigee hybrid.

Échecs d'installation courants

Problème constaté Cause et solution
helm upgrade se termine, mais aucune ressource MCP n'apparaît. L'organigramme a été mis à niveau avant le chart operator. Exécutez d'abord helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/, puis réexécutez helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/.
Pods MCP bloqués dans ContainerCreating ou 1/2 Ready. Deux causes courantes : le cert-manager Certificate pour MCP n'a pas encore été émis ou l'extraction de l'image de conteneur échoue. Exécutez kubectl describe pod sur le pod concerné pour connaître la raison exacte.
Les journaux Sidecar (apigee-mcp-server-config) sont signalésno MCP config from CP yet; skipping tick, pod stays Ready via seed à chaque interrogation. État stable attendu lorsqu'aucun proxy de découverte MCP n'a encore été déployé pour votre organisation. Le plan de contrôle Apigee renvoie une référence de configuration vide, et le plan de données MCP ne comporte que l'écouteur d'état prêt Kubernetes chargé sur le port 15021. Le port de requête MCP 8443 ne comporte pas encore d'écouteur, et les requêtes envoyées à https://mcp.apigee.internal/mcp reçoivent une connexion refusée. Pour passer à l'état de diffusion, suivez le guide de démarrage rapide MCP pour déployer un proxy de découverte MCP dans un environnement du groupe d'environnements desservi par ce cluster.
Les journaux Sidecar signalent CP fetch failed avec un 403 ou PermissionDenied HTTP intégré. Le compte de service Google Cloud de l'observateur Apigee a perdu le rôle roles/apigee.runtimeAgent (qui accorde l'autorisation apigee.runtimeconfigs.get dont le side-car a besoin) dans votre projet locataire Apigee. L'installation de base d'Apigee hybrid attribue automatiquement ce rôle. S'il a été supprimé par un balayage d'automatisation IAM, réappliquez-le au compte de service Google Cloud apigee-watcher.
Les journaux Sidecar signalent CP fetch failed avec context deadline exceeded, des erreurs DNS ou des erreurs TLS. Le side-car ne peut pas atteindre apigee.googleapis.com ni storage.googleapis.com depuis votre cluster. Vérifiez la sortie par rapport aux trois points de terminaison listés dans la section Exigences concernant le réseau sortant ci-dessus.
Les pods Processeur de messages n'ont pas redémarré après helm upgrade. Vérifiez que l'entrée hostAliases est présente sur chaque pod MP : kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. Si un pod est vide, forcez un nouveau rendu en le supprimant (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). Le contrôleur ApigeeDeployment le recréera à partir de la spécification actuelle, qui inclut l'entrée hostAliases. N'utilisez pas kubectl rollout restart deploy, car il ne s'applique pas à ApigeeDeployment.
Les journaux des pods MP affichent des erreurs de handshake TLS lors de l'établissement de la connexion à https://mcp.apigee.internal/ ou https://ORG_NAME.mcp.apigee.internal/ après le début du flux de trafic des outils MCP via le démarrage rapide. Le conteneur du plan de données MCP diffuse un certificat dont les noms d'objet de remplacement (SAN) n'incluent pas le nom d'hôte composé par le MP. Vérifiez le certificat : kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, puis kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. Le dnsNames du certificat doit inclure à la fois mcp.apigee.internal et ORG_NAME.mcp.apigee.internal en minuscules. Si ce n'est pas le cas, supprimez la ressource Certificate du MCP et laissez cert-manager la réémettre.

Étapes suivantes