Model Context Protocol (MCP) in Apigee Hybrid aktivieren

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie das Model Context Protocol (MCP) in einem vorhandenen Apigee Hybrid-Cluster mit Version 1.17.0 oder höher aktivieren. Nachdem Sie diese Schritte ausgeführt haben, wird in Ihrem Cluster eine neue MCP-Datenebene ausgeführt und Ihr Message Processor ist bereit, MCP-Toolaufrufe dorthin weiterzuleiten. Anschließend können Sie Ihren ersten MCP-Discovery-Proxy bereitstellen. Folgen Sie dazu der MCP-Kurzanleitung.

Informationen zu MCP-Konzepten, -Architektur und -Funktionen, die zwischen Apigee und Apigee Hybrid gemeinsam genutzt werden, finden Sie unter MCP in Apigee – Übersicht.

Was bewirkt dieses Verfahren?

Wenn Sie MCP in einem Apigee Hybrid-Cluster aktivieren, werden die folgenden Änderungen vorgenommen:

  1. Gewährt der Identität apigee-watcher Zugriff auf die MCP-Konfiguration auf der Apigee-Steuerungsebene. Fügen Sie das Dienstkonto apigee-watcher der Liste watcher_identities in der controlPlaneAccess-Ressource Ihrer Apigee-Organisation hinzu, damit der MCP-Sidecar MCP-Konfigurationspakete von der Apigee-Steuerungsebene abrufen kann. Dies ist eine Änderung der Steuerungsebene, die auf die Apigee-Organisation beschränkt ist. Sie ist ein einmaliger Schritt pro Organisation, unabhängig davon, wie viele Cluster für diese Organisation bereitgestellt werden.
  2. Fügt eine neue In-Cluster-Datenebene für MCP hinzu. Ein neuer Satz von MCP-Pods wird im selben Kubernetes-Namespace erstellt, in dem Apigee Hybrid installiert ist (Standard: apigee), zusammen mit den unterstützenden Kubernetes-Ressourcen (Service, Horizontal Pod Autoscaler und RBAC), die für die Ausführung erforderlich sind. MCP-Toolaufrufe werden von diesen Pods verarbeitet.
  3. Konfiguriert Ihren Message Processor so, dass er die MCP-Datenebene erreichen kann. Der Apigee-Operator aktualisiert die Spezifikation Ihres Message Processor-Pods, sodass MP-Routen MCP-Toolaufrufe an die neue In-Cluster-MCP-Datenebene weiterleiten. Durch die Anwendung dieser Änderung wird ein stufenweiser Canary-Release von Message Processor (verwaltet vom ApigeeDeployment-Controller) ausgelöst. Der vorherige Pod verarbeitet weiterhin Traffic, bis der neue Pod Ready ist. Der Release wird nur bei den Übergängen „Aktivieren“ und „Deaktivieren“ ausgelöst, nicht bei laufenden MCP-Aktivitäten oder MCP-Traffic im Steady State. Führen Sie diesen Vorgang in einem genehmigten Wartungszeitraum aus und warten Sie, bis die Veröffentlichung abgeschlossen ist, bevor Sie fortfahren.

Schritt 1: overrides.yaml bearbeiten

Öffnen Sie die Datei overrides.yaml, die Sie für Ihre Apigee Hybrid-Helm-Diagramme verwenden. Fügen Sie auf oberster Ebene der Datei Folgendes hinzu:

enableMcpServer: true

Dies ist die Mindestkonfiguration, die zum Aktivieren von MCP erforderlich ist. Es werden die integrierten Standardwerte aus dem apigee-org-Diagramm verwendet: zwei MCP-Datenebenenreplikate, die bei einer CPU-Auslastung von 70% automatisch auf zehn skaliert werden, mit Ressourcenanforderungen von 500 m CPU und 512 Mi Arbeitsspeicher und Limits von 2.000 m CPU und 1 Gi Arbeitsspeicher für den MCP-Datenebenencontainer. Informationen zum Anpassen der Anzahl der Replikate, der Ressourcenanforderungen oder des MCP-Dienstkontos finden Sie weiter unten auf dieser Seite unter Referenz: MCP-Felder in „overrides.yaml“.

Es folgen vollständige Beispiele für ein zusammengeführtes overrides.yaml, eines für jeden Authentifizierungsstil. Verwenden Sie das Beispiel, das der Konfiguration Ihrer vorhandenen Basisinstallation entspricht. Die MCP-spezifischen Zeilen sind mit Kommentaren hervorgehoben und in allen drei Varianten identisch.

Wählen Sie den Tab aus, der der Authentifizierung von Apigee-Komponenten bei Google Cloud in Ihrer Basisinstallation entspricht. Die Auswahl gilt für jeden variantenbezogenen Codeblock auf dieser Seite.

Workload Identity (GKE)

Verwenden Sie diese Variante, wenn Ihre Basisinstallation Apigee-Komponenten über GKE Workload Identity bei Google Cloud authentifiziert (keine Dienstkonto-Schlüsseldateien auf der Festplatte).

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

Dateibasierte Dienstkontoschlüssel

Verwenden Sie diese Variante, wenn Ihre Basisinstallation Apigee-Komponenten bei Google Cloud über Dienstkontoschlüsseldateien authentifiziert, die Sie an jeden Cluster verteilen.

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

Identitätsföderation von Arbeitslasten (AKS/EKS)

Verwenden Sie diese Variante, wenn Ihre Basisinstallation auf AKS oder EKS erfolgt und die Authentifizierung bei Google Cloud über die Identitätsföderation von Arbeitslasten erfolgt. MCP übernimmt die WIF-basierte Identität, die apigee-watcher bereits in Ihrem Cluster verwendet. Sie müssen keine MCP-spezifische Identitätskonfiguration hinzufügen.

Fügen Sie Ihrer vorhandenen WIF-Datei overrides.yaml den MCP-Schlüssel auf oberster Ebene hinzu:

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

Lassen Sie mcpServer.gsa und mcpServer.serviceAccountPath leer. Der MCP-Sidecar übernimmt dieselbe Identität, die apigee-watcher über die Identitätsföderation von Arbeitslasten aufgelöst wird.

Schritt 2: Zugriff auf die MCP-Konfiguration auf der Steuerungsebene für die Beobachteridentität gewähren

Der MCP-Sidecar ruft sein Konfigurations-Bundle von der Apigee-Steuerungsebene ab. Dazu verwendet er das Google Cloud-Dienstkonto der apigee-watcher-Komponente (die Identität, die Sie in Schritt 1 ausgewählt haben). Bevor die MCP-Pods gestartet werden, fügen Sie dieses Dienstkonto der Liste watcher_identities in der controlPlaneAccess-Ressource Ihrer Apigee-Organisation hinzu. Ohne diese Berechtigung geben die Aufrufe des MCP-Sidecars an apigee.googleapis.com zum Abrufen der MCP-Konfigurationsreferenz 404 Not Found zurück und die MCP-Datenebene ist nie bereit, Tool-Traffic zu verarbeiten.

Dieser Schritt muss nur einmal pro Organisation durchgeführt werden (nicht pro Cluster). Überspringen Sie diesen Schritt, wenn Sie bereits Zugriff für einen vorherigen Cluster in derselben Apigee-Organisation gewährt haben.

  1. Legen Sie die Shell-Variablen fest, die Sie für den API-Aufruf verwenden. Werte aus Ihrer Installation wiederverwenden: 
    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)

    Wobei:

    • YOUR_ORG_NAME ist der Name Ihrer Apigee Hybrid-Organisation.
    • YOUR_GCP_PROJECT_ID ist das Google Cloud-Projekt, in dem Ihre Apigee Hybrid-Organisation gehostet wird.
    • WATCHER_SA ist die E-Mail-Adresse des apigee-watcher-Dienstkontos. Wenn Sie watcher.gsa in overrides.yaml überschrieben haben, verwenden Sie diesen Wert anstelle des Standardwerts apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com.
  2. Rufen Sie die API updateControlPlaneAccess auf, um das Watcher-Dienstkonto der Liste watcher_identities hinzuzufügen:

    Kein Datenstandort

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

    Datenstandort

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

    Dabei ist CONTROL_PLANE_LOCATION der Speicherort für Ihre Daten der Steuerungsebene, wenn für Ihre Apigee Hybrid-Installation der Datenstandort verwendet wird. Eine Liste der verfügbaren Standorte finden Sie unter Verfügbare Regionen der Apigee API-Steuerungsebene.

    Der Aufruf gibt einen Vorgang mit langer Ausführungszeit zurück. Warten Sie, bis der Vorgang abgeschlossen ist, bevor Sie den Bestätigungsschritt unten ausführen.

  3. Prüfen Sie, ob die Bewilligung eingegangen ist. Rufen Sie getControlPlaneAccess auf und prüfen Sie, ob das Dienstkonto des Watcher-Dienstes im Feld watcherIdentities der Antwort angezeigt wird:

    Kein Datenstandort

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

    Datenstandort

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

    Die Antwort sollte ein watcherIdentities-Array mit dem Dienstkonto des Watcher-Dienstes enthalten. Beispiel:

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

    Wenn watcherIdentities in der Antwort fehlt oder Ihr Dienstkonto für den Watcher nicht enthält, führen Sie den PATCH-Befehl noch einmal aus und prüfen Sie den Vorgangsstatus auf Fehler, bevor Sie fortfahren.

Schritt 3: apigee-operator-Diagramm aktualisieren

Aktualisieren Sie zuerst das Operator-Diagramm. Das Operatorschema enthält das Schema für die neuen MCP-Ressourcen. Im Organisationsschema wird darauf verwiesen. Wenn Sie in der falschen Reihenfolge upgraden, wird helm upgrade erfolgreich ausgeführt, es werden aber keine MCP-Pods erstellt.

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

Die Ausführung des Befehls dauert weniger als eine Minute. Prüfen Sie, ob das Operator-Deployment vollständig mit dem neuen Image bereitgestellt wurde. apigee-controller-manager Deployment ist eine Standard-Kubernetes-Ressource, keine ApigeeDeployment. Daher ist kubectl rollout status deploy der richtige Befehl:

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

Erwartete Ausgabe:

deployment "apigee-controller-manager" successfully rolled out

Schritt 4: apigee-org-Diagramm aktualisieren

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

Es werden jetzt zwei Abgleichsschleifen parallel ausgeführt:

  • Der Apigee-Operator erstellt die MCP-Bereitstellung, den Dienst, die HPA, das Dienstkonto, die Rolle und das RoleBinding. MCP-Pods werden jeweils zu zweit gestartet (abhängig von der Kubernetes-Planung). Der Sidecar-Container in jedem Pod ruft kurz nach dem Start die erste Konfiguration von der Apigee-Steuerungsebene ab.
  • Der Apigee-Operator fügt den Eintrag hostAliases in die Pod-Spezifikation des Message Processors ein, wodurch ein Release von apigee-runtime ApigeeDeployment ausgelöst wird.

Schritt 5: Installation überprüfen

Prüfen, ob die MCP-Datenebene ausgeführt wird

Sehen Sie sich die vier MCP-bezogenen Ressourcen an, die der Operator erstellt hat. Ressourcennamen enthalten ein organisationsbezogenes Suffix. In den folgenden Beispielen wird ORG_CR_SUFFIX als Platzhalter für dieses Suffix verwendet. Pod-Suffixe und die Service-ClusterIP unterscheiden sich in Ihrer Umgebung.

MCP-Pods (standardmäßig zwei; automatische Skalierung auf zehn bei Last):

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

In jedem Pod muss in der Spalte READY der Wert 2/2 angezeigt werden. Die beiden Container in jedem Pod sind:

  • apigee-mcp-server: Der MCP-Datenebenencontainer, mit dem MP-Pods eine Verbindung herstellen.
  • apigee-mcp-server-config: Der Konfigurations-Sidecar (ein Modus des Binärprogramms apigee-watcher), der Konfigurations-Bundles von der Apigee-Steuerungsebene abruft und in ein freigegebenes Volume schreibt, das vom MCP-Datenebenencontainer gelesen wird.

MCP ApigeeDeployment (eine benutzerdefinierte Kubernetes-Ressource, keine Standard-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

Der erwartete Status ist running. Prüfen Sie auch, ob der zugrunde liegende Pod 2/2 Running ist:

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

MCP-Dienst:

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

Prüfen Sie, ob MINPODS mit mcpServer.replicaCountMin aus Ihrem overrides.yaml (Standard: 2) übereinstimmt und MAXPODS mit mcpServer.replicaCountMax (Standard: 10). Die Spalten TARGETS, REPLICAS und AGE hängen von Live-Messwerten und dem Clusterstatus ab.

Prüfen, ob die Message Processor-Pods den hostAliases-Eintrag erhalten haben

In jedem MP-Pod muss der eingefügte Eintrag angezeigt werden. Wenn er in einem Pod fehlt, können in diesem Pod keine MCP-Tool-Aufrufe weitergeleitet werden. Listen Sie alle MP-Pods und ihre hostAliases auf:

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

Erwartete Ausgabe: Jeder MP-Pod enthält ein hostAliases-Array mit einem Eintrag mit zwei Hostnamen, die auf die MCP-Service-ClusterIP aus dem vorherigen Schritt verweisen. Der zweite Hostname verwendet den Namen Ihrer Organisation in Kleinbuchstaben. Die Namen von Message Processor-Pods folgen der Vorlage apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, wobei TRUNCATED_ORG Ihr Organisationsname ist (der gekürzt wird, wenn er zu lang ist, um das Kubernetes-Namenslimit von 63 Zeichen einzuhalten), ENV_GROUP_HASH ein Hash der Bereitstellungsgruppe pro Umgebung, REV die aktuelle Revisionsnummer der Version (vier Ziffern, z. B. 1170) und POD_HASH ein zufälliges Suffix pro Pod ist. Beispiel:

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

Wenn für einen Pod ein leerer hostAliases-Wert angezeigt wird, hat der Message Processor ApigeeDeployment die aktualisierte Pod-Spezifikation nicht vollständig übernommen. Erzwingen Sie eine neue gestaffelte Canary-Version, indem Sie die aktuellen Message Processor-Pods löschen. Der ApigeeDeployment-Controller rendert sie dann neu anhand der aktuellen Spezifikation (die jetzt den hostAliases-Eintrag enthält):

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

Der ApigeeDeployment-Controller erstellt die Pods innerhalb einer Minute neu. Beachten Sie, dass kubectl rollout restart deploy (der Standard-Kubernetes-Befehl) im Message Processor nicht funktioniert, da der Message Processor als benutzerdefinierte ApigeeDeployment-Ressource und nicht als Deployment bereitgestellt wird.

Installation abgeschlossen

Die drei vorherigen Prüfungen bestätigen, dass Ihre MCP-Datenebene ausgeführt wird und MP-adressierbar ist:

  • Jeder MCP-Pod ist 2/2 Running. Der MCP-Datenebenencontainer besteht die Kubernetes-Bereitschaftsprüfung auf Port 15021 nicht, wenn das vom Operator ausgestellte TLS-Zertifikat nicht geladen wurde und der Sidecar seine erste MCP-Konfiguration noch nicht geladen hat. Bei Ready-Pods sind beide Voraussetzungen erfüllt.
  • Die Spezifikation jedes MP-Pods enthält den Eintrag hostAliases, der mcp.apigee.internal und ORG_NAME.mcp.apigee.internal an die ClusterIP des MCP-Dienstes anbindet. MP-Pods können daher MCP-Proxy-Zielendpunkte in die MCP-Datenebene in Ihrem Cluster auflösen.
  • Ein MP-Pod löst mcp.apigee.internal über den eingefügten hostAliases-Eintrag in die MCP-Service-ClusterIP auf.

Sie überprüfen den End-to-End-MCP-Tool-Traffic (einen tatsächlichen MCP-Aufruf von initialize oder tools/list über Ihren Apigee-Ingress) im Rahmen des gemeinsamen MCP-Schnellstarts, nachdem Sie Ihren ersten MCP-Discovery-Proxy bereitgestellt haben.

Wenn eine der drei vorherigen Prüfungen fehlschlägt, lesen Sie den Abschnitt Fehlerbehebung bei MCP-Bereitstellungen, bevor Sie mit der Kurzanleitung fortfahren.

Schritt 6: MCP für die verbleibenden Cluster aktivieren

MCP-Anfragen für einen bestimmten Hostnamen können an einen beliebigen Cluster weitergeleitet werden, der die entsprechende Apigee-Umgebungsgruppe bereitstellt. Wenn MCP in einigen Clustern und nicht in anderen in derselben Umgebungsgruppe aktiviert ist, schlagen MCP-Anfragen fehl, die an einen Cluster ohne aktiviertes MCP weitergeleitet werden (in der Regel wird 503 Service Unavailable an den Client zurückgegeben).

Aktivieren Sie MCP einheitlich für jeden Cluster, der dieselbe Umgebungsgruppe bereitstellt. Wiederholen Sie die Schritte 1, 3, 4 und 5 für jeden weiteren Cluster. Sie müssen Schritt 2 (Zugriff auf die Identität des Watchers gewähren) nicht wiederholen. Diese Berechtigung ist auf die Apigee-Organisation beschränkt und gilt für alle Cluster in derselben Organisation.

Rollback

Wenn Sie MCP für einen Cluster deaktivieren möchten, legen Sie enableMcpServer: false in overrides.yaml fest (oder entfernen Sie das Feld vollständig) und führen Sie dann ein Upgrade des apigee-org-Diagramms durch:

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

Das Feld enableMcpServer wird nur vom Diagramm apigee-org verwendet. Das Operator-Diagramm muss daher bei einer Deaktivierung nicht aktualisiert werden. Der Apigee-Operator (unverändert) übernimmt die Konfigurationsänderung aus der benutzerdefinierten Ressource ApigeeOrganization, löscht die MCP-Ressourcen und entfernt den Eintrag hostAliases aus der Pod-Spezifikation des Message Processor, wodurch eine Version von apigee-runtime ApigeeDeployment ausgelöst wird. Führen Sie den Rollback in einem genehmigten Wartungsfenster durch.

Nach dem Rollback sind die MCP Discovery-Proxys, die Sie in der Apigee-Umgebung bereitgestellt haben, weiterhin in der Apigee-Steuerungsebene vorhanden. In dieser Umgebungsgruppe wird jedoch kein Cluster für MCP-Traffic verwendet. Heben Sie die Bereitstellung der MCP-Discovery-Proxys auf, um die Funktion vollständig zu deaktivieren. Alternativ können Sie sie auch bereitgestellt lassen und MCP später wieder in den Clustern aktivieren.

Referenz: MCP-Felder in overrides.yaml

In der folgenden Tabelle sind alle overrides.yaml-Felder von Apigee Hybrid aufgeführt, mit denen das MCP-Verhalten in Version 1.17.0 gesteuert wird. Nur enableMcpServer ist erforderlich. Alle anderen Felder haben sichere Standardwerte, die für die meisten Installationen geeignet sind.

Die Felddefinitionen entsprechen den apigee-org-Helm-Diagramm-Standardeinstellungen für Hybrid 1.17.0.

Feld Typ Standard Empfohlene Optimierung
enableMcpServer boolean false Erforderlich. Legen Sie true fest, um MCP für diesen Cluster zu aktivieren. Durch das Umschalten dieses Felds wird ein stufenweiser Canary-Release von Message Processor ausgelöst. Aktivieren Sie die Option nur während eines Wartungsfensters und warten Sie, bis die Veröffentlichung abgeschlossen ist, bevor Sie fortfahren.
mcpServer.replicaCountMin integer 2 HA bei 2 beibehalten. Erhöhen Sie die Anzahl nur, wenn Sie einen hohen MCP-Basistraffic haben. Das HPA wird bei hoher CPU-Auslastung automatisch skaliert. Signal: Anhaltende HPA bei replicaCountMax und CPU über dem Zielwert.
mcpServer.replicaCountMax integer 10 Erhöhen Sie den Wert, wenn der HPA während der Spitzenzeiten auf 10 begrenzt ist. Signal: kubectl top pods -l app=apigee-mcp-server zeigt alle Pods an, die sich in Spitzenzeiten in der Nähe ihres CPU-Limits befinden. Wenn metrics-server nicht installiert ist, verwenden Sie kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server und prüfen Sie, ob die Spalte REPLICAS am MAXPODS-Maximum liegt.
mcpServer.targetCPUUtilizationPercentage integer 70 Niedriger auf 50–60 für latenzempfindliche Arbeitslasten (wird früher skaliert). Erhöhen Sie den Wert auf 80–85, um die Anzahl der Replikate in kostensensiblen Clustern zu verringern. Signal: Die P95-Anfragelatenz korreliert mit der CPU pro Pod.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi Erhöhen Sie die Anforderungen, wenn Pods im stabilen Zustand häufig OOMKilled oder CPU-gedrosselt werden. Signal: kubectl describe pod zeigt an, dass der Prozess aufgrund von OOMKilled oder Throttling beendet wurde.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Erhöhen Sie das CPU-Limit, bevor Sie die Anzahl der Replikate erhöhen, wenn die Latenz des 95. Perzentils hoch, die Gesamt-QPS jedoch niedrig ist (wenige, teure Anfragen). Erhöhen Sie das Speicherlimit nur, wenn Beendigungen aufgrund von Arbeitsspeichermangel auftreten.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Muss nur selten angepasst werden. Der Sidecar erstellt und schreibt regelmäßig Konfigurationspakete. Die CPU-Auslastung im stabilen Zustand ist minimal.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Muss nur selten angepasst werden. Erhöhen Sie den Arbeitsspeicher nur, wenn Sie eine ungewöhnlich große Anzahl von MCP-Tools in einem einzelnen Discovery-Proxy bereitstellen.
mcpServer.terminationGracePeriodSeconds integer 30 Muss nur selten angepasst werden. Erhöhen Sie den Wert, wenn lang andauernde MCP-Anfragen während eines Pod-Drainings mehr Zeit für den Abschluss benötigen.
mcpServer.annotations Karte {} Fügen Sie zusätzliche Pod-Annotationen hinzu, wenn Ihr Cluster dies erfordert.
mcpServer.serviceAccountPath String unset Lassen Sie diese Option unverändert, sofern Sie keine Identitätstrennung pro Komponente benötigen. Wenn der Wert nicht festgelegt ist, greift MCP auf watcher.serviceAccountPath und dann auf envs[].serviceAccountPaths.runtime zurück. Die Identität apigee-watcher hat bereits die Berechtigungen, die für den MCP-Sidecar erforderlich sind. Pfad zu einer JSON-Datei des Google Cloud-Dienstkontoschlüssels, wenn Sie eine Überschreibung vornehmen. Schließt sich mit mcpServer.gsa gegenseitig aus.

Nach Möglichkeit Workload Identity (GKE) oder Workload Identity Federation (AKS/EKS) verwenden. Dateibasierte Dienstkontoschlüssel müssen rotiert, sicher gespeichert und an jeden Cluster verteilt werden. Sie sind die häufigste Quelle für Lecks in Supportartefakten (siehe Supportanfragen).
mcpServer.gsa String unset Lassen Sie diese Option unverändert, sofern Sie keine Identitätstrennung pro Komponente benötigen. Wenn der Wert nicht festgelegt ist, greift MCP auf watcher.gsa und dann auf gcp.workloadIdentity.gsa zurück. Die apigee-watcher-Identität hat bereits die Berechtigungen, die der MCP-Sidecar benötigt. Daher wird empfohlen, sie wiederzuverwenden. Überschreiben Sie die E-Mail-Adresse nur dann mit einer dedizierten Google Cloud-Dienstkonto-E-Mail-Adresse, wenn Ihre Organisation aus Auditgründen eine separate Identität für den MCP-Sidecar benötigt.
mcpServer.serviceAccountRef String unset Erweitert. Name eines vorhandenen Kubernetes-Secrets im Apigee-Namespace, das einen Google Cloud-Dienstkontoschlüssel für den MCP-Sidecar enthält. Verwenden Sie diese Option nur, wenn Sie Dienstkontoschlüssel-Secrets außerhalb der Apigee-Helm-Charts verwalten. Schließt sich mit mcpServer.serviceAccountPath und mcpServer.gsa gegenseitig aus.
mcpServer.podDisruptionBudget Karte unset Optionales PodDisruptionBudget für die MCP-Pods. Akzeptiert minAvailable oder maxUnavailable (Ganzzahl oder Prozentstring). Legen Sie nur einen Wert fest, nicht beide. Lassen Sie diese Option leer, sofern für Ihren Cluster keine strengen Richtlinien für freiwillige Unterbrechungen gelten, die ein explizites Budget erfordern.
mcpServer.tolerations list unset (Fallback auf tolerations auf oberster Ebene) Standardmäßige Kubernetes-Toleranzen für MCP-Pods. Wird nur festgelegt, wenn MCP-Pods Taints tolerieren müssen, die andere Apigee-Komponenten nicht tolerieren.
mcpServer.image.pullPolicy String IfNotPresent Image-Pull-Richtlinie für den MCP-Servercontainer. Wird selten geändert.
mcpServer.sidecar.image.pullPolicy String IfNotPresent Image-Pull-Richtlinie für den MCP-Sidecar-Container. Wird selten geändert.

Kapazität von MCP-Tools schätzen

In Apigee Hybrid wird keine feste maximale Anzahl von MCP-Tools pro Organisation erzwungen. Stattdessen wird die Toolkapazität durch vier feste Größenbeschränkungen begrenzt, die bei der Bereitstellung oder Anfrage durchgesetzt werden. Ob eine bestimmte Anzahl von Tools passt, hängt von der Größe der einzelnen Tools ab, die aus der OpenAPI-Spezifikation abgeleitet wird, in der das Tool definiert ist.

Durchschnittliche Kapazität

Bei den meisten OpenAPI-Spezifikationen – einer Mischung aus Tools mit unterschiedlicher Anzahl von Parametern, Anfragetextgrößen und Beschreibungslängen, wobei die meisten Tools in den Größenbereich „klein bis mittel“ fallen – können Sie in der Regel mit dem standardmäßigen Größenlimit für tools/list-Antworten von 10.000 MCP-Tools pro Organisation rechnen.

Die tatsächliche Kapazität variiert je nach der spezifischen Form Ihrer OpenAPI-Spezifikation. Bei Organisationen, deren Spezifikationen von Tools mit vielen Parametern, großen Anfragetexten oder langen Beschreibungen dominiert werden, passen proportional weniger Tools, bevor eines der vier harten Limits unten erreicht wird. Wenn Sie die Kapazität für Ihre spezifischen Spezifikationen prüfen möchten, folgen Sie der Anleitung unter Kapazität für Ihre Spezifikation schätzen unten.

Harte Limits

In Apigee Hybrid-Version 1.17.0 gelten vier Größenlimits. Das niedrigste anwendbare Limit ist das, was bindet. Wenn Sie eines erhöhen, werden die anderen nicht erhöht.

Limit Wert Umfang Fehlermodus
Dateigröße der OpenAPI-Spezifikation 3 MiB pro .yaml-Datei 400 bei der Proxy-Validierung
Größe des MCP-Proxy-Bundles (entpackt) 50 MiB über den MCP Discovery-Proxy 400 bei der Proxy-Validierung
tools/list-Antwortgröße 10 MiB (Standard) pro Hostname 502 mit TooBigBody
Hostnamen pro Umgebungsgruppe 100 pro Umgebungsgruppe 400 bei der Aktualisierung von Umgebungsgruppen

Faktoren für die Größe von Tools

Die Größe pro Tool besteht fast ausschließlich aus dem inputSchema des Tools, das aus dem parameters und requestBody des Vorgangs in der OpenAPI-Spezifikation abgeleitet wird. Drei Attribute sind am wichtigsten:

  • Anzahl der Parameter: Jeder Parametereintrag trägt ungefähr 100 Byte zur Größe des Tools in der tools/list-Antwort bei.
  • Anzahl der Attribute im Anfragetext. Jede Eigenschaft im Anfragetext trägt etwa 100 Byte bei. Vorgänge mit einem Anfragetext (in der Regel POST und PUT) sind daher wesentlich größer als Vorgänge ohne Anfragetext (in der Regel GET und DELETE).
  • Länge der Beschreibung: Vorgangsbeschreibungen werden fast wörtlich in das Tool kopiert. Eine längere Beschreibung erhöht also direkt die Größe des Tools.

Antwortschemas werden nicht auf das Größenbudget angerechnet. Nur parameters und requestBody erreichen die MCP-Konfiguration. Wenn die Kapazität nur anhand der OpenAPI-Dateigröße berechnet wird, werden die Kosten in der Regel überschätzt, da die meisten echten OpenAPI-Spezifikationen Definitionen für Antwortschemata enthalten, die sich nicht auf die Toolgröße auswirken.

Kapazität für Ihre Spezifikation schätzen

Die zuverlässigste Methode, die Toolkapazität für Ihre OpenAPI-Spezifikationen zu schätzen, besteht darin, eine repräsentative Teilmenge zu messen:

  1. Stellen Sie einen MCP Discovery-Proxy bereit, der auf eine kleine repräsentative Teilmenge der Tools verweist, die Sie veröffentlichen möchten (z. B. 50 bis 100 Tools, die die Mischung aus Parameteranzahl, Größe des Anfragetexts und Länge der Beschreibung in Ihrer vollständigen Spezifikation widerspiegeln).
  2. Rufen Sie tools/list für den bereitgestellten Proxy auf und notieren Sie die Antwortgröße in Byte und die Anzahl der zurückgegebenen Tools.
  3. Teilen Sie die Antwortgröße durch die Anzahl der Tools, um die durchschnittliche Größe pro Tool für Ihre Spezifikation zu erhalten.
  4. Teilen Sie das anwendbare tools/list-Antwortgrößenlimit (standardmäßig 10 MiB) durch diesen Durchschnitt, um die maximale Anzahl von Tools zu schätzen, die für eine Spezifikation dieser Form auf einen Hostnamen passen.

Kapazität erhöhen

Es gibt zwei Mechanismen, mit denen die Tool-Kapazität über die Standardwerte hinaus erhöht werden kann:

  • Tools auf Hostnamen aufteilen: Die Obergrenze für tools/list-Antworten gilt pro Hostname. Wenn Sie Tools auf mehrere Hostnamen innerhalb derselben Umgebungsgruppe aufteilen, wird der Spielraum pro Hostname vervielfacht (vorbehaltlich des Limits von 100 Hostnamen pro Umgebungsgruppe). Durch Sharding wird das Limit für Proxy-Bundles nicht erhöht. Das Limit von 50 MiB gilt weiterhin für alle Hostnamen in einem einzelnen MCP Discovery Proxy.
  • Erhöhen Sie die Größenbeschränkung für tools/list-Antworten. Das Standardlimit beträgt 10 MiB pro Hostname. Sie können sie auf bis zu 30 MiB erhöhen. Dazu müssen Sie mindestens envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory und envs.components.runtime.cwcAppend.bin_setenv_max_mem in Ihrem overrides.yaml festlegen und dann helm upgrade für das apigee-org-Diagramm ausführen. Eine vollständige Anleitung, einschließlich der Varianten für die Umgebung und die gesamte Installation, der Anleitung zur Heap-Größenanpassung für Message Processor und vollständiger overrides.yaml-Beispiele, finden Sie unter Unterstützung für große Nachrichtennutzlast in Apigee Hybrid konfigurieren. Das Erhöhen des Antwortlimits hat keine Auswirkungen auf das Größenlimit von 50 MiB für MCP-Proxy-Bundles. Wenn Ihre Kapazität durch dieses Limit eingeschränkt wird, hilft diese Änderung nicht.

Sicherheit

Vertrauensgrenze

Die MCP-Datenebene wird in Ihrem eigenen Kubernetes-Cluster ausgeführt. Google hat keinen Laufzeitzugriff auf die Datenebene. Die Apigee-Steuerungsebene stellt Ihnen die MCP-Konfiguration bereit, die aus Ihrer OpenAPI-Spezifikation abgeleitet wird. Sie beobachtet keinen MCP-Anfrageverkehr. Konfigurationsdaten im Ruhezustand werden in einem von Apigee verwalteten Cloud Storage-Bucket gespeichert, der auf Ihr Apigee-Mandantenprojekt beschränkt ist. Der MCP-Sidecar ruft die Daten mit seinem Ambient-Google Cloud-Dienstkonto ab.

Der Apigee-Operator stellt ein Kubernetes-Role und RoleBinding mit MCP-Bereich in Ihrem Apigee-Namespace (APIGEE_NAMESPACE) für das MCP-Datenebenen-ServiceAccount bereit. Die Rolle gewährt nur Lesezugriff:

  • get, list, watch auf services in der Core API-Gruppe.
  • get, list, watch auf apigeeroutes in der API-Gruppe apigee.cloud.google.com.

Die Rolle gewährt keine Schreibvorgänge und keinen Zugriff auf Secrets, ConfigMaps oder den Pod-Status. Ihr Auditor kann die genauen Regeln direkt im Cluster mit folgendem Befehl prüfen:

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

Die apigee-mcp-server-APIGEE_ORG_CR-Rolle und RoleBinding sind die MCP-bezogenen RBAC-Ressourcen. Ihre Namen enthalten den vollständigen Namen Ihrer benutzerdefinierten ApigeeOrganization-Ressource, die aus dem Namen Ihrer Apigee-Organisation und einem kurzen Hash abgeleitet wird. Sie haben kein app=apigee-mcp-server-Label auf Ressourcenebene (nur die Pods), sodass eine labelbasierte Suche keine Ergebnisse zurückgibt. Wenn der obige Befehl für die Feldauswahl nichts zurückgibt, listen Sie alle MCP-bezogenen RBAC-Ressourcen im Namespace mit folgendem Befehl auf:

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

TLS zwischen Message Processor und MCP-Datenebene

Message Processor-Pods stellen eine Verbindung zur MCP-Datenebene unter https://mcp.apigee.internal/ oder https://ORG_NAME.mcp.apigee.internal/ her. Diese Hostnamen werden über den eingefügten hostAliases-Eintrag in die ClusterIP des MCP-Dienstes aufgelöst. Der MCP-Datenebenencontainer präsentiert ein TLS-Zertifikat, das vom Apigee-Operator bereitgestellten Aussteller (dem ClusterIssuer mit dem Namen apigee-ca-issuer) signiert wurde. Die alternativen Antragstellernamen des Zertifikats enthalten beide Hostnamen.

Eingehenden Zugriff auf den MCP-Dienst einschränken

In Apigee Hybrid 1.17.0 authentifiziert die MCP-Datenebene ihre Aufrufer nicht unabhängig. Es wird davon ausgegangen, dass Anfragen, die es erreichen, bereits von einem Apigee-MCP-Proxy authentifiziert wurden, der im Message Processor ausgeführt wird. Der einzige vorgesehene Aufrufer des MCP-Dienstes ist der Message Processor. Jede andere Arbeitslast im Cluster, die die MCP-ClusterIP auf TCP 443 erreichen kann, kann MCP-Tools ohne Authentifizierungsprüfung aufrufen.

Eingehenden Zugriff auf die MCP-Pods auf Message Processor-Pods beschränken. Verwenden Sie dazu die Richtlinien-Engine für den Cluster-Ingress Ihrer Plattform (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy oder eine entsprechende Engine). Die Einschränkung:

  • Ermöglicht eingehenden Traffic zu Pods mit dem Label app=apigee-mcp-server im Namespace APIGEE_NAMESPACE über TCP 443 nur von Pods mit dem Label app=apigee-runtime im selben Namespace.
  • Lehnt den gesamten anderen eingehenden Traffic auf TCP 443 zu Pods mit dem Label app=apigee-mcp-server ab.
  • Verweigert den gesamten In-Cluster-Eingang auf TCP 15021 zu Pods mit dem Label app=apigee-mcp-server. Über Port 15021 wird ein nicht authentifizierter /healthz/ready-Endpunkt für einfaches HTTP bereitgestellt, der von kubelet für Bereitschaftsprüfungen verwendet wird. Kubelet erreicht ihn direkt über die Pod-IP-Adresse. Daher sollte keine andere In-Cluster-Arbeitslast die MCP-Pods über 15021 erreichen.

Wenden Sie diese Einschränkung an, bevor Sie die MCP-Kurzanleitung durchlaufen und Ihren ersten MCP Discovery-Proxy in einer Nicht-Entwicklungsumgebung bereitstellen.

Vertrag zur Konfigurationsaktualität

Wenn der MCP-Sidecar einen erfolgreichen Konfigurations-Pull abgeschlossen hat, lädt der MCP-Datenebenencontainer das abgerufene Bundle und stellt es bis zum nächsten erfolgreichen Pull bereit. Wenn nachfolgende Pulls fehlschlagen (Apigee-Steuerungsebene nicht erreichbar, Cloud Storage nicht erreichbar, IAM-Berechtigung für das Watcher-Dienstkonto entfernt oder ein Fehler in einer anderen Phase der Pull-Pipeline), stellt der Sidecar das zuletzt bekannte funktionierende Bundle auf unbestimmte Zeit bereit. In 1.17.0 gibt es keine integrierte Obergrenze für die Veralterung: Der Pod bleibt Ready und der MCP-Tool-Traffic wird weiterhin mit dem alten Bundle bereitgestellt. Das Signal dafür, dass die Konfiguration nicht mehr aktualisiert wird, ist eine Sidecar-Logzeile auf der Ebene ERROR, die einen consecutive_failures-Zähler enthält. Unter Fehlerbehebung bei MCP-Bereitstellungen finden Sie die spezifischen Meldungen, die der Sidecar pro Fehlerphase ausgibt.

Bei regulierten Produktionsumgebungen wird die Seite bei wiederholten Erhöhungen dieses Zählers aufgerufen. Ein minimal funktionsfähiger Hinweis ist eine Seite, wenn ein beliebiger MCP-Sidecar-Container eine Logzeile auf ERROR-Ebene mit consecutive_failures ausgibt, die einen Schwellenwert erreicht, den Sie basierend auf Ihrer Toleranz für veraltete Daten festlegen. Steigende Werte deuten darauf hin, dass die Sidecar-Konfiguration nicht mehr aktualisiert wird. In der Zwischenzeit wird weiterhin das letzte erfolgreiche Bundle bereitgestellt.

Wenn der Sidecar die Konfiguration nicht mehr aktualisiert, untersuchen Sie den Fehlermodus anhand der Sidecar-Logs. Weitere Informationen finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen. Durch das Neustarten der MCP-Pods wird das zugrunde liegende Abrufproblem nicht behoben, da neu erstellte Pods denselben Abrufpfad verwenden.

Anforderungen an ausgehende Netzwerke

Der MCP-Sidecar (der Konfigurationscontainer in jedem MCP-Pod) benötigt ausgehenden Netzwerkzugriff auf die folgenden Endpunkte über TCP 443. Wählen Sie den Tab aus, der dem Datenstandort Ihrer Apigee-Organisation entspricht. Die erforderlichen Endpunkte sind unterschiedlich.

Kein Datenstandort

Endpunkt Verwendet für
apigee.googleapis.com Rufen Sie bei jeder Konfigurationsaktualisierung die aktuelle MCP-Konfigurationsreferenz für Ihre Organisation von der Apigee-Steuerungsebene ab.
storage.googleapis.com Laden Sie die MCP-Konfiguration Ihrer Organisation aus Google Cloud Storage herunter.

Datenstandort

Wenn Ihre Apigee-Organisation den Datenstandort verwendet, greift der MCP-Sidecar auf den regionalen Apigee-Steuerungsebenenendpunkt zu. Das ist derselbe Endpunkt, den auch Ihre anderen Apigee Hybrid-Komponenten verwenden. Er wird über den contractProvider-Diagrammwert in Ihrer overrides.yaml konfiguriert. Ersetzen Sie CONTROL_PLANE_LOCATION durch den Speicherort der Steuerungsebene Ihrer Organisation, z. B. us oder eu.

Endpunkt Verwendet für
CONTROL_PLANE_LOCATION-apigee.googleapis.com Rufen Sie bei jeder Konfigurationsaktualisierung die aktuelle MCP-Konfigurationsreferenz für Ihre Organisation von Ihrem regionalen Apigee-Steuerungsebenenendpunkt ab.
storage.googleapis.com Laden Sie die MCP-Konfiguration Ihrer Organisation aus Google Cloud Storage herunter. Der Bucket befindet sich in der Region Ihrer Organisation. Cloud Storage leitet automatisch dorthin weiter.

Außerdem muss der Sidecar Google Cloud-Zugriffstokens für die Umgebungsvariablen Anmeldedaten abrufen können, mit denen der Pod ausgeführt wird (über Workload Identity oder einen dateibasierten Dienstkontoschlüssel). Die spezifischen Token-Exchange-Endpunkte hängen von Ihrem Authentifizierungspfad ab und sind dieselben, die andere Apigee Hybrid-Komponenten bereits in Ihrem Cluster verwenden. Wenn vorhandener Apigee Hybrid-Traffic zu Google Cloud APIs über diesen Namespace erfolgreich ist, ist auch der Token-Austausch des MCP-Sidecars erfolgreich.

Außerdem benötigt der Sidecar-Container den Zugriff auf den Kubernetes API-Server im Cluster (über die standardmäßige Dienstadresse im Cluster), um seinen Liveness- und Readiness-Status zu veröffentlichen. Dieser Traffic verlässt Ihren Cluster nie.

Fehlerbehebung

Eine vollständige Checkliste für die Diagnose finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen. Dort finden Sie auch eine Checkliste für die Diagnose auf Clusterseite für Apigee Hybrid.

Häufige Installationsfehler

Symptom Ursache und Lösung
helm upgrade wird abgeschlossen, es werden aber keine MCP-Ressourcen angezeigt. Das Organisationsdiagramm wurde vor dem Operator-Diagramm aktualisiert. Führen Sie zuerst helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ aus und dann helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ noch einmal.
MCP-Pods bleiben in ContainerCreating oder 1/2 Ready hängen. Zwei häufige Ursachen: Das cert-manager-Certificate für MCP wurde noch nicht ausgestellt oder das Abrufen des Container-Images schlägt fehl. Führen Sie kubectl describe pod auf dem betroffenen Pod aus, um den genauen Grund zu ermitteln.
Sidecar-Logs (apigee-mcp-server-config) werden bei jeder Abfrage gemeldet.no MCP config from CP yet; skipping tick, pod stays Ready via seed Erwarteter Steady State, wenn noch kein MCP Discovery-Proxy für Ihre Organisation bereitgestellt wurde. Die Apigee-Steuerungsebene gibt eine leere Konfigurationsreferenz zurück und auf der MCP-Datenebene ist nur der Kubernetes-Readiness-Listener auf Port 15021 geladen. Der MCP-Anfrageport 8443 hat noch keinen Listener und Anfragen an https://mcp.apigee.internal/mcp werden mit „Verbindung abgelehnt“ beantwortet. Um in den Serving-Status zu wechseln, folgen Sie der MCP-Kurzanleitung, um einen MCP-Discovery-Proxy in einer Umgebung in der Umgebungsgruppe bereitzustellen, die von diesem Cluster bereitgestellt wird.
In den Sidecar-Logs wird CP fetch failed mit einem eingebetteten HTTP-403 oder PermissionDenied gemeldet. Das Google Cloud-Dienstkonto des Apigee-Watchers hat die Rolle roles/apigee.runtimeAgent (die die Berechtigung apigee.runtimeconfigs.get gewährt, die der Sidecar benötigt) in Ihrem Apigee-Mandantenprojekt verloren. Bei der Basisinstallation von Apigee Hybrid wird diese Rolle automatisch gewährt. Wenn sie durch eine automatische IAM-Bereinigung entfernt wurde, wenden Sie sie noch einmal auf das Google Cloud-Dienstkonto apigee-watcher an.
In den Sidecar-Logs wird CP fetch failed mit context deadline exceeded, DNS-Fehlern oder TLS-Fehlern gemeldet. Der Sidecar kann apigee.googleapis.com oder storage.googleapis.com nicht aus Ihrem Cluster heraus erreichen. Prüfen Sie den ausgehenden Traffic anhand der drei Endpunkte, die oben unter Anforderungen an ausgehenden Netzwerkverkehr aufgeführt sind.
Message Processor-Pods wurden nach helm upgrade nicht neu gestartet. Prüfen Sie, ob der Eintrag hostAliases in jedem MP-Pod vorhanden ist: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. Wenn ein Pod leer ist, erzwingen Sie ein neues Rendern, indem Sie den Pod löschen (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). Der ApigeeDeployment-Controller erstellt ihn anhand der aktuellen Spezifikation neu, die den Eintrag hostAliases enthält. Verwenden Sie kubectl rollout restart deploy nicht, da sie nicht für ApigeeDeployment gilt.
In den MP-Pod-Logs werden TLS-Handshake-Fehler beim Wählen von https://mcp.apigee.internal/ oder https://ORG_NAME.mcp.apigee.internal/ angezeigt, nachdem der MCP-Tool-Traffic über den Schnellstart erfolgt ist. Der MCP-Datenebenencontainer stellt ein Zertifikat bereit, dessen alternative Antragstellernamen (Subject Alternative Names, SANs) nicht den Hostnamen enthalten, den der MP gewählt hat. Prüfen Sie das Zertifikat: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, dann kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. Der dnsNames des Zertifikats muss sowohl mcp.apigee.internal als auch ORG_NAME.mcp.apigee.internal in Kleinbuchstaben enthalten. Wenn nicht, löschen Sie die MCP-Ressource Certificate und lassen Sie cert-manager sie neu ausstellen.

Nächste Schritte