Habilita el Protocolo de contexto del modelo (MCP) en Apigee hybrid

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo habilitar el Protocolo de contexto del modelo (MCP) en un clúster existente de Apigee hybrid que ejecuta la versión 1.17.0 o posterior. Después de completar este procedimiento, tu clúster ejecutará un nuevo plano de datos de MCP en el clúster, y tu procesador de mensajes estará listo para enrutar las llamadas a herramientas de MCP hacia él. Luego, puedes implementar tu primer proxy de descubrimiento de MCP siguiendo la guía de inicio rápido de MCP compartida.

Para obtener detalles sobre los conceptos, la arquitectura y las funciones de MCP que se comparten entre Apigee y Apigee Hybrid, consulta la Descripción general de MCP en Apigee.

Qué hace este procedimiento

Habilitar el MCP en un clúster de Apigee Hybrid genera los siguientes cambios:

  1. Otorga a la identidad apigee-watcher acceso a la configuración de MCP en el plano de control de Apigee. Agrega la cuenta de servicio apigee-watcher a la lista watcher_identities en el recurso controlPlaneAccess de tu organización de Apigee para que el sidecar de MCP pueda extraer paquetes de configuración de MCP del plano de control de Apigee. Este es un cambio en el plano de control, que se limita a la organización de Apigee y es un paso único por organización, independientemente de la cantidad de clústeres que la atienden.
  2. Agrega un nuevo plano de datos de MCP en el clúster. Se crea un nuevo conjunto de Pods de MCP en el mismo espacio de nombres de Kubernetes en el que se instaló Apigee Hybrid (apigee predeterminado), junto con los recursos de Kubernetes de asistencia (servicio, Horizontal Pod Autoscaler y RBAC) necesarios para ejecutarlos. Estos pods controlan las llamadas a herramientas de MCP.
  3. Configura tu Message Processor para que llegue al plano de datos del MCP. El operador de Apigee actualiza la especificación del Pod de Message Processor para que MP enrute las llamadas a la herramienta de MCP al nuevo plano de datos de MCP en el clúster. La aplicación de este cambio activa un lanzamiento Canary por etapas del Message Processor (administrado por el controlador ApigeeDeployment); el Pod anterior sigue entregando tráfico hasta que el Pod nuevo se encuentre en estado Ready. La versión se lanza solo en las transiciones de habilitación y deshabilitación, no en la actividad en curso del MCP ni en el tráfico estable del MCP. Ejecuta este procedimiento en un período de mantenimiento aprobado y espera a que se complete la versión antes de continuar.

Paso 1: Edita overrides.yaml

Abre el archivo overrides.yaml que usas para tus gráficos de Helm de Apigee Hybrid. En el nivel superior del archivo, agrega lo siguiente:

enableMcpServer: true

Esta es la configuración mínima necesaria para habilitar el MCP. Utiliza los valores predeterminados integrados del gráfico apigee-org: dos réplicas del plano de datos de MCP que se ajustan automáticamente a diez con un 70% de uso de CPU, con solicitudes de recursos de 500 mCPU y 512 Mi de memoria, y límites de 2,000 mCPU y 1 Gi de memoria en el contenedor del plano de datos de MCP. Para personalizar los recuentos de réplicas, las solicitudes de recursos o la cuenta de servicio de MCP, consulta Referencia: Campos de MCP en overrides.yaml más adelante en esta página.

A continuación, se incluyen ejemplos completos de un overrides.yaml combinado, uno para cada estilo de autenticación. Usa el ejemplo que coincida con la configuración de tu instalación base existente. Las líneas específicas de MCP se destacan con comentarios y son las mismas en las tres variantes.

Elige la pestaña que coincida con la forma en que tu instalación base autentica los componentes de Apigee en Google Cloud. La selección se aplica a todos los bloques de código con alcance de variantes de esta página.

Workload Identity (GKE)

Usa esta variante si tu instalación base autentica los componentes de Apigee en Google Cloud a través de Workload Identity de GKE (no hay archivos de claves de cuentas de servicio en el disco).

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
  workloadIdentity:
    enabled: true
    gsa: apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

Claves de cuentas de servicio basadas en archivos

Usa esta variante si tu instalación base autentica los componentes de Apigee en Google Cloud a través de archivos de claves de cuentas de servicio que distribuyes a cada clúster.

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
guardrails:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
mart:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
connectAgent:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
watcher:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json  # MCP also uses this key file
envs:
- name: my-env
  serviceAccountPaths:
    synchronizer: ./service-accounts/apigee-non-prod.json
    runtime:      ./service-accounts/apigee-non-prod.json

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

Federación de identidades para cargas de trabajo (AKS/EKS)

Usa esta variante si tu instalación base se encuentra en AKS o EKS y se autentica en Google Cloud a través de la federación de identidades para cargas de trabajo. MCP usa el archivo de configuración de credenciales que apigee-watcher ya usa, desde watcher.serviceAccountPath, por lo que no debes agregar ninguna configuración de identidad específica de MCP. Si, en cambio, almacenas la configuración de credenciales en un Secret de Kubernetes, consulta Otros mecanismos de identidad.

Agrega la clave de nivel superior del MCP a tu overrides.yaml de WIF existente:

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

Deja mcpServer.gsa y mcpServer.serviceAccountPath sin configurar. El sidecar de MCP usa el mismo archivo de configuración de credenciales que apigee-watcher, desde watcher.serviceAccountPath.

Paso 2: Otorga a la identidad del observador acceso a la configuración de MCP en el plano de control

El sidecar de MCP recupera su paquete de configuración del plano de control de Apigee con la cuenta de servicio de Google Cloud del componente apigee-watcher (la identidad que seleccionaste en el paso 1). Antes de que se inicien los Pods de MCP, agrega esa cuenta de servicio a la lista de watcher_identities en el recurso controlPlaneAccess de la organización de Apigee. Sin este permiso, las llamadas del sidecar de MCP a apigee.googleapis.com para recuperar la referencia de configuración de MCP devuelven 404 Not Found, y el plano de datos de MCP nunca está listo para entregar tráfico de herramientas.

Este es un paso que se debe realizar una sola vez por organización (no por clúster). Omite este paso si ya otorgaste acceso para un clúster anterior en la misma organización de Apigee.

  1. Establece las variables de shell que usas para la llamada a la API. Reutiliza los valores de tu instalación: 
    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)

    Aquí:

    • YOUR_ORG_NAME es el nombre de tu organización de Apigee hybrid.
    • YOUR_GCP_PROJECT_ID es el proyecto de Google Cloud que aloja tu organización de Apigee Hybrid.
    • WATCHER_SA es la dirección de correo electrónico de la cuenta de servicio apigee-watcher. Si anulaste watcher.gsa en overrides.yaml, usa ese valor en lugar del apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com predeterminado.
  2. Llama a la API de updateControlPlaneAccess para agregar la cuenta de servicio del observador a la lista de watcher_identities:

    Sin residencia de datos

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

    Residencia de los datos

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

    Aquí, CONTROL_PLANE_LOCATION es la ubicación de los datos del plano de control si tu instalación de Apigee Hybrid usa la residencia de datos. Para obtener la lista de ubicaciones disponibles, consulta Regiones del plano de control de la API de Apigee disponibles.

    La llamada devuelve una operación de larga duración. Espera a que se complete antes de ejecutar el paso de verificación que se indica a continuación.

  3. Verifica que se haya aplicado el permiso. Llama a getControlPlaneAccess y confirma que la cuenta de servicio del observador aparezca en el campo watcherIdentities de la respuesta:

    Sin residencia de datos

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

    Residencia de los datos

    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 respuesta debe incluir un array watcherIdentities que contenga tu cuenta de servicio de observador. Por ejemplo:

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

    Si watcherIdentities no está presente en la respuesta o no contiene tu cuenta de servicio de observador, vuelve a ejecutar el comando PATCH y verifica el estado de la operación para detectar errores antes de continuar.

Paso 3: Actualiza el gráfico apigee-operator

Primero, actualiza el gráfico del operador. El gráfico del operador posee el esquema para los nuevos recursos de MCP, y el gráfico de la organización los referencia. Si se realiza la actualización en el orden incorrecto, se genera un helm upgrade exitoso que no crea pods de MCP.

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

El comando se completa en menos de un minuto. Confirma que la Deployment del operador se haya completado con la nueva imagen (apigee-controller-manager Deployment es un recurso de Kubernetes estándar, no un ApigeeDeployment, por lo que kubectl rollout status deploy es el comando correcto aquí):

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

Resultado esperado:

deployment "apigee-controller-manager" successfully rolled out

Paso 4: Actualiza el gráfico apigee-org

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

Ahora se ejecutan dos bucles de conciliación en paralelo:

  • El operador de Apigee crea la implementación, el servicio, el HPA, la cuenta de servicio, el rol y el RoleBinding de MCP. Los Pods de MCP se inician de a dos por vez (sujeto a la programación de Kubernetes); el contenedor secundario de cada Pod realiza su primera recuperación de configuración del plano de control de Apigee poco después del inicio.
  • El operador de Apigee inserta la entrada hostAliases en la especificación del pod del procesador de mensajes, lo que activa una versión de apigee-runtime ApigeeDeployment.

Paso 5: Verifica la instalación

Verifica que el plano de datos de MCP esté en ejecución

Inspecciona los cuatro recursos relacionados con MCP que creó el operador. Los nombres de recursos incluyen un sufijo derivado de la organización. En los siguientes ejemplos, se usa ORG_CR_SUFFIX como marcador de posición para ese sufijo, y los sufijos de Pod y el ClusterIP del Service diferirán en tu entorno.

Pods de MCP (dos de forma predeterminada; se ajustan automáticamente a diez bajo carga):

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

Cada cápsula debe mostrar 2/2 en la columna READY. Los dos contenedores de cada Pod son los siguientes:

  • apigee-mcp-server: Es el contenedor del plano de datos del MCP al que se conectan los Pods de MP.
  • apigee-mcp-server-config: Es el sidecar de configuración (un modo del objeto binario apigee-watcher) que recupera paquetes de configuración del plano de control de Apigee y los escribe en un volumen compartido que lee el contenedor del plano de datos de MCP.

MCP ApigeeDeployment (un recurso personalizado de Kubernetes, no un Deployment estándar):

kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
 
NAME                              STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   running                 2m

El estado esperado es running. También verifica que el pod subyacente sea 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

Servicio de 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 de MCP:

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

Confirma que MINPODS coincida con mcpServer.replicaCountMin de tu overrides.yaml (2 predeterminado) y que MAXPODS coincida con mcpServer.replicaCountMax (10 predeterminado). Las columnas TARGETS, REPLICAS y AGE dependen de las métricas en tiempo real y del estado del clúster.

Verifica que los Pods de Message Processor hayan recibido la entrada hostAliases

Todos los pods de MP deben mostrar la entrada insertada. Si falta incluso un pod, este no podrá enrutar las llamadas a las herramientas de MCP. Enumera todos los Pods de MP y sus hostAliases:

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

Resultado esperado: Cada Pod de MP muestra un array hostAliases que contiene una entrada con dos nombres de host que apuntan a la ClusterIP del Service de MCP del paso anterior (el segundo nombre de host usa el nombre de tu organización en minúsculas). Los nombres de los pods de Message Processor siguen la plantilla apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, en la que TRUNCATED_ORG es el nombre de tu organización (truncado para ajustarse al límite de 63 caracteres de Kubernetes si el nombre de tu organización es largo), ENV_GROUP_HASH es un hash de grupo de implementación por entorno, REV es el número de revisión de la versión actual (cuatro dígitos, por ejemplo, 1170) y POD_HASH es un sufijo aleatorio por pod. Por ejemplo:

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 algún Pod muestra un valor hostAliases vacío, el Message Processor ApigeeDeployment no captó por completo la especificación del Pod actualizada. Para forzar una lanzamiento Canary nueva y provisional, borra los Pods del Message Processor actuales. El controlador ApigeeDeployment los volverá a renderizar a partir de la especificación actual (que ahora incluye la entrada hostAliases):

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

El controlador ApigeeDeployment volverá a crear los Pods en un minuto. Ten en cuenta que kubectl rollout restart deploy (el comando de Kubernetes estándar) no funciona en Message Processor porque este se implementa como un recurso personalizado ApigeeDeployment, no como un Deployment.

Se completó la instalación

En conjunto, las tres verificaciones anteriores confirman que tu plano de datos de MCP se está ejecutando y que se puede direccionar con MP:

  • Todos los pods de MCP son 2/2 Running. El contenedor del plano de datos de MCP falla en su sondeo de preparación de Kubernetes en el puerto 15021 si no se carga el certificado TLS emitido por el operador y el proceso secundario aún no cargó su configuración inicial de MCP, por lo que los Pods de Ready tienen esas dos condiciones previas.
  • La especificación de cada pod de MP contiene la entrada hostAliases que fija mcp.apigee.internal y ORG_NAME.mcp.apigee.internal en el ClusterIP del servicio de MCP. Por lo tanto, los pods de MP pueden resolver los extremos de destino del proxy de MCP en tu plano de datos de MCP dentro del clúster.
  • Un pod de MP resuelve mcp.apigee.internal en el ClusterIP del servicio de MCP a través de la entrada hostAliases insertada.

Verificas el tráfico de la herramienta de MCP de extremo a extremo (una llamada real de initialize o tools/list de MCP a través de tu entrada de Apigee) como parte de la guía de inicio rápido de MCP compartida, después de implementar tu primer proxy de descubrimiento de MCP.

Si falla alguna de las tres verificaciones anteriores, consulta Soluciona problemas de implementaciones de MCP antes de continuar con la guía de inicio rápido.

Paso 6: Habilita el MCP en los clústeres restantes

Las solicitudes de MCP para un nombre de host determinado se pueden enrutar a cualquier clúster que publique el grupo de entornos de Apigee correspondiente. Si el MCP está habilitado en algunos clústeres y no en otros del mismo grupo de entornos, fallarán las solicitudes de MCP que se enruten a un clúster sin el MCP habilitado (por lo general, se devuelven al cliente como 503 Service Unavailable).

Habilita el MCP de manera uniforme en cada clúster que publique el mismo grupo de entornos. Para cada clúster adicional, repite los pasos 1, 3, 4 y 5. No es necesario que repitas el paso 2 (otorga acceso de identidad de observador): ese otorgamiento se limita a la organización de Apigee y se aplica a todos los clústeres de la misma organización.

Revertir

Para inhabilitar el MCP en un clúster, establece enableMcpServer: false (o quita el campo por completo) en overrides.yaml y, luego, actualiza el gráfico de apigee-org:

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

El campo enableMcpServer solo lo usa el gráfico apigee-org, por lo que no es necesario actualizar el gráfico del operador durante una inhabilitación. El operador de Apigee (sin cambios) detecta el cambio de configuración del recurso personalizado ApigeeOrganization, borra los recursos de MCP y quita la entrada hostAliases de la especificación del Pod de Message Processor, lo que activa una versión de apigee-runtime ApigeeDeployment. Realiza la reversión en un período de mantenimiento aprobado.

Después de la reversión, los proxies de descubrimiento de MCP que implementaste en el entorno de Apigee seguirán presentes en el plano de control de Apigee, pero ningún clúster de ese grupo de entornos atenderá el tráfico de MCP. Anula la implementación de los proxies de descubrimiento de MCP para deshacer por completo la función, o bien déjalos implementados y vuelve a habilitar MCP en los clústeres más adelante.

Referencia: Campos de MCP en overrides.yaml

En la siguiente tabla, se enumeran todos los campos de overrides.yaml de Apigee Hybrid que controlan el comportamiento de MCP en la versión 1.17.0. Solo se requiere enableMcpServer; todos los demás campos tienen valores predeterminados seguros que se adaptan a la mayoría de las instalaciones.

Las definiciones de los campos coinciden con los valores predeterminados del gráfico de Helm apigee-org para 1.17.0 híbrido.

Campo Tipo Predeterminado Ajustes recomendados
enableMcpServer booleano false Obligatorio. Establece el valor en true para habilitar el MCP en este clúster. Activar o desactivar este campo activa un lanzamiento Canary por etapas del Message Processor. Activa el botón de activación solo en un período de mantenimiento y espera a que se complete la versión antes de continuar.
mcpServer.replicaCountMin integer 2 Mantén la configuración en 2 para la HA. Aumenta solo si tienes un valor de referencia de tráfico de MCP alto. El HPA se ajusta automáticamente bajo presión de la CPU. Señal: HPA sostenido en replicaCountMax y CPU por encima del objetivo.
mcpServer.replicaCountMax integer 10 Aumenta si observas que el HPA alcanza su límite máximo en 10 durante los períodos de mayor actividad. Indicador: kubectl top pods -l app=apigee-mcp-server muestra todos los Pods cerca de su límite de CPU en el punto máximo. Si metrics-server no está instalado, usa kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server y verifica si la columna REPLICAS está en el límite de MAXPODS.
mcpServer.targetCPUUtilizationPercentage integer 70 Disminuye a 50–60 para cargas de trabajo sensibles a la latencia (se ajusta antes). Aumenta el valor a 80–85 para reducir el recuento de réplicas en clústeres sensibles a los costos. Indicador: La latencia de solicitud del percentil 95 se correlaciona con la CPU por Pod.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi Aumenta las solicitudes si los Pods suelen ser OOMKilled o se limitan por CPU en estado estable. Indicador: kubectl describe pod muestra condiciones de OOMKilled o de limitación.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Aumenta el límite de CPU antes de aumentar el recuento de réplicas cuando la latencia del percentil 95 es alta, pero la cantidad general de QPS es baja (pocas solicitudes costosas). Aumenta el límite de memoria solo si ves OOMKills.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Casi nunca necesita ajustes. El proceso secundario compone y escribe paquetes de configuración de forma periódica, y el uso de CPU en estado estable es mínimo.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Casi nunca requiere ajustes. Aumenta la memoria solo si implementas una cantidad inusualmente grande de herramientas de MCP en un solo Discovery Proxy.
mcpServer.terminationGracePeriodSeconds integer 30 Casi nunca necesita ajustes. Aumenta si las solicitudes de MCP en curso de larga duración necesitan más tiempo para completarse durante el vaciado de un pod.
mcpServer.annotations mapa {} Agrega anotaciones de Pod adicionales si tu clúster las requiere.
mcpServer.serviceAccountPath cadena unset Déjalo sin configurar, a menos que necesites una separación de identidad por componente. Cuando no se configura, el MCP usa watcher.serviceAccountPath. El MCP no usa envs[].serviceAccountPaths.runtime. La identidad de apigee-watcher ya tiene los permisos que necesita el sidecar del MCP. Si anulas este campo, especifica la ruta de acceso a un archivo JSON de clave de cuenta de servicio Google Cloud . Este campo y mcpServer.gsa son mutuamente excluyentes.

Si Workload Identity no está habilitado y no configuras mcpServer.serviceAccountRef ni serviceAccountSecretProviderClass, debes configurar mcpServer.serviceAccountPath o watcher.serviceAccountPath. Si no configuras ninguno de los dos, helm upgrade fallará con el error mcpServer.serviceAccountPath or watcher.serviceAccountPath is required!!.

Prefiere Workload Identity (GKE) o la federación de identidades para cargas de trabajo (AKS/EKS) siempre que sea posible. Las claves de cuentas de servicio basadas en archivos deben rotarse, almacenarse de forma segura, distribuirse a cada clúster y son la fuente más común de filtraciones en los artefactos de asistencia (consulta Casos de asistencia).
mcpServer.gsa cadena unset Déjalo sin configurar, a menos que necesites una separación de identidad por componente. Cuando no se establece, el MCP recurre a watcher.gsa y, luego, a gcp.workloadIdentity.gsa. La identidad apigee-watcher ya tiene los permisos que necesita el sidecar de MCP, por lo que se recomienda reutilizarla. Anula con una dirección de correo electrónico de cuenta de servicio de Google Cloud dedicada solo si tu organización requiere una identidad distinta para el sidecar de MCP por motivos de auditoría.
mcpServer.serviceAccountRef cadena unset Avanzado Nombre de un Secret de Kubernetes existente en el espacio de nombres de Apigee que contiene una clave de cuenta de servicio de Google Cloud para el proceso secundario de MCP. Úsalo solo si administras los Secrets de las claves de la cuenta de servicio fuera de los gráficos de Helm de Apigee. Es mutuamente excluyente con mcpServer.serviceAccountPath y mcpServer.gsa.

El MCP no usa watcher.serviceAccountRef. Si tu instalación base almacena la clave apigee-watcher en un Secret de Kubernetes con watcher.serviceAccountRef, establece esta propiedad en el mismo nombre del Secret.
mcpServer.podDisruptionBudget mapa unset Es un PodDisruptionBudget opcional para los Pods del MCP. Acepta minAvailable o maxUnavailable (cadena de porcentaje o número entero). Configura uno, no ambos. No se debe configurar, a menos que el clúster tenga políticas de interrupción voluntaria estrictas que requieran un presupuesto explícito.
mcpServer.tolerations list unset (se revierte al tolerations de nivel superior) Son tolerancias estándares de Kubernetes para los Pods de MCP. Se configura solo si los pods de MCP deben tolerar contaminaciones que otros componentes de Apigee no toleran.
mcpServer.image.pullPolicy cadena IfNotPresent Es la política de extracción de imágenes para el contenedor del servidor de MCP. Casi nunca se cambia.
mcpServer.sidecar.image.pullPolicy cadena IfNotPresent Es la política de extracción de imágenes para el contenedor secundario del MCP. Casi nunca se cambia.

Cómo estimar la capacidad de la herramienta de MCP

Apigee Hybrid no aplica una cantidad máxima fija de herramientas de MCP por organización. En cambio, la capacidad de la herramienta está limitada por cuatro límites de tamaño fijos que se aplican en el momento de la implementación o la solicitud. La cantidad de herramientas que caben depende del tamaño de cada una, que se deriva de la especificación de OpenAPI que define la herramienta.

Capacidad típica

Para la mayoría de las especificaciones de OpenAPI (una combinación de herramientas con diferentes cantidades de parámetros, tamaños de cuerpo de solicitud y longitudes de descripción, en la que la mayoría de las herramientas se encuentran en el rango de tamaño pequeño a mediano), por lo general, puedes esperar que quepan 10,000 herramientas de MCP por organización con el límite de tamaño de respuesta tools/list predeterminado.

La capacidad real varía según la forma específica de tu especificación de OpenAPI. Las organizaciones cuyas especificaciones se basan principalmente en herramientas con muchos parámetros, cuerpos de solicitud grandes o descripciones largas pueden ajustar proporcionalmente menos herramientas antes de alcanzar uno de los cuatro límites estrictos que se indican a continuación. Para validar la capacidad de tus especificaciones, sigue los pasos que se indican en Cómo estimar la capacidad de tus especificaciones a continuación.

Límites estrictos

En la versión 1.17.0 de Apigee Hybrid, se aplican cuatro límites de tamaño. El límite más bajo aplicable es el que vincula; aumentar uno no aumenta los demás.

Límite Valor Alcance Modo de falla
Tamaño del archivo de especificaciones de OpenAPI 3 MiB por archivo .yaml 400 en la validación del proxy
Tamaño del paquete del proxy de MCP (descomprimido) 50 MiB por proxy de descubrimiento de MCP 400 en la validación del proxy
Tamaño de la respuesta de tools/list 10 MiB (predeterminado) por nombre de host 502 con TooBigBody
Nombres de host por grupo de entornos 100 por grupo de entornos 400 en la actualización del grupo de entornos

Qué determina el tamaño de cada herramienta

El tamaño por herramienta se compone casi por completo del inputSchema de la herramienta, que se deriva del parameters y el requestBody de la operación de la especificación de OpenAPI. Las tres propiedades más importantes son las siguientes:

  • Cantidad de parámetros. Cada entrada de parámetro contribuye con aproximadamente 100 bytes al tamaño de la herramienta en la respuesta de tools/list.
  • Cantidad de propiedades del cuerpo de la solicitud. Cada propiedad del cuerpo de la solicitud aporta aproximadamente 100 bytes. Por lo tanto, las operaciones con un cuerpo de solicitud (por lo general, POST y PUT) son mucho más grandes que las operaciones sin uno (por lo general, GET y DELETE).
  • Longitud de la descripción: Las descripciones de las operaciones se copian casi textualmente en la herramienta, por lo que una descripción más larga aumenta directamente el tamaño de la herramienta.

Los esquemas de respuesta no se consideran para el presupuesto de tamaño. Solo parameters y requestBody alcanzan la configuración del MCP. Por lo tanto, dimensionar la capacidad solo según el tamaño del archivo de OpenAPI tiende a sobreestimar el costo, ya que la mayoría de las especificaciones de OpenAPI reales incluyen definiciones de esquemas de respuesta que no afectan el tamaño de la herramienta.

Estima la capacidad para tu especificación

La forma más confiable de estimar la capacidad de las herramientas para tus especificaciones de OpenAPI es medir un subconjunto representativo:

  1. Implementa un proxy de descubrimiento de MCP que haga referencia a un pequeño subconjunto representativo de las herramientas que planeas publicar (por ejemplo, de 50 a 100 herramientas que reflejen la combinación de recuentos de parámetros, tamaños del cuerpo de la solicitud y longitudes de la descripción en tu especificación completa).
  2. Llama a tools/list en el proxy implementado y registra el tamaño de la respuesta en bytes y la cantidad de herramientas devueltas.
  3. Divide el tamaño de la respuesta por la cantidad de herramientas para obtener el tamaño promedio por herramienta de tu especificación.
  4. Divide el límite de tamaño de respuesta tools/list aplicable (10 MiB de forma predeterminada) por ese promedio para estimar la cantidad máxima de herramientas que caben en un nombre de host para una especificación de esta forma.

Aumento de la capacidad

Hay dos mecanismos que aumentan la capacidad de las herramientas más allá de los valores predeterminados:

  • Fragmenta las herramientas en varios nombres de host. El límite de respuestas tools/list se aplica por nombre de host. Dividir las herramientas en varios nombres de host dentro del mismo grupo de entornos multiplica el espacio disponible por nombre de host (sujeto al límite de 100 nombres de host por grupo de entornos). El sharding no aumenta el límite por paquete de proxy; el límite de 50 MiB por paquete se sigue aplicando a todos los nombres de host en un solo proxy de detección de MCP.
  • Aumenta el límite de tamaño de la respuesta de tools/list. El límite predeterminado es de 10 MiB por nombre de host. Puedes aumentarlo hasta 30 MiB. Como mínimo, esto implica establecer envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory y envs.components.runtime.cwcAppend.bin_setenv_max_mem en tu overrides.yaml y, luego, ejecutar helm upgrade en el gráfico apigee-org. Consulta Configura la compatibilidad con cargas útiles de mensajes grandes en Apigee Hybrid para conocer el procedimiento completo, incluidas las variantes por entorno y por instalación, la orientación sobre el tamaño del montón del Message Processor y ejemplos completos de overrides.yaml. Aumentar el límite de respuesta no afecta el límite de tamaño del paquete del proxy de MCP de 50 MiB. Si tu capacidad está limitada por ese límite, este cambio no te ayudará.

Seguridad

Límite de confianza

El plano de datos del MCP se ejecuta dentro de tu propio clúster de Kubernetes. Google no tiene acceso en el tiempo de ejecución al plano de datos. El plano de control de Apigee te proporciona la configuración de MCP derivada de tu especificación de OpenAPI, pero no observa el tráfico de solicitudes de MCP. Los datos de configuración en reposo se almacenan en un bucket de Cloud Storage administrado por Apigee y con alcance en tu proyecto de usuario de Apigee, y el sidecar de MCP los recupera con su cuenta de servicio de Google Cloud ambiental.

El operador de Apigee aprovisiona un Role y un RoleBinding de Kubernetes con alcance de MCP en tu espacio de nombres de Apigee (APIGEE_NAMESPACE) para la ServiceAccount del plano de datos de MCP. El rol otorga acceso de solo lectura:

  • get, list y watch en services en el grupo de APIs principales
  • get, list, watch en apigeeroutes en el grupo de APIs de apigee.cloud.google.com

El Role no otorga verbos de escritura ni acceso a Secrets, ConfigMaps ni al estado del pod. Tu auditor puede verificar las reglas exactas directamente desde el clúster con el siguiente comando:

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

Los objetos apigee-mcp-server-APIGEE_ORG_CR Role y RoleBinding son los recursos de RBAC con alcance de MCP. Sus nombres incluyen el nombre completo de tu recurso personalizado ApigeeOrganization (que se deriva del nombre de tu organización de Apigee y un hash corto). No tienen una etiqueta app=apigee-mcp-server a nivel del recurso (solo los pods la tienen), por lo que una búsqueda basada en etiquetas no devuelve resultados. Si el comando de selector de campos anterior no devuelve nada, enumera todos los recursos de RBAC relacionados con MCP en el espacio de nombres con el siguiente comando:

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

TLS entre el Message Processor y el plano de datos de MCP

Los Pods de Message Processor marcan el plano de datos de MCP en https://mcp.apigee.internal/ o https://ORG_NAME.mcp.apigee.internal/. Estos nombres de host se resuelven en el ClusterIP del servicio de MCP a través de la entrada hostAliases insertada. El contenedor del plano de datos del MCP presenta un certificado TLS firmado por la entidad emisora aprovisionada por Apigee Operator (el ClusterIssuer llamado apigee-ca-issuer). Los nombres alternativos del sujeto del certificado incluyen ambos nombres de host.

Restringe el acceso entrante al servicio de MCP

En Apigee hybrid 1.17.0, el plano de datos del MCP no autentica de forma independiente a sus llamadores. Confía en que las solicitudes que llegan a él ya fueron autenticadas por un proxy de MCP de Apigee que se ejecuta en Message Processor. El único llamador previsto del servicio de MCP es Message Processor. Cualquier otra carga de trabajo dentro del clúster que pueda acceder a la dirección IP del clúster del servicio de MCP en TCP 443 puede invocar herramientas de MCP sin una verificación de autenticación.

Restringe el acceso entrante a los Pods de MCP solo a los Pods de Message Processor con el motor de políticas de entrada del clúster de tu plataforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy o equivalente). La restricción:

  • Permite la entrada a los Pods con la etiqueta app=apigee-mcp-server en el espacio de nombres APIGEE_NAMESPACE en TCP 443 desde los Pods con la etiqueta app=apigee-runtime solo en el mismo espacio de nombres.
  • Rechaza todo el resto del tráfico de entrada en TCP 443 a los Pods con la etiqueta app=apigee-mcp-server.
  • Rechaza todo el ingreso en el clúster en TCP 15021 a los Pods con la etiqueta app=apigee-mcp-server. El puerto 15021 entrega un extremo /healthz/ready HTTP simple no autenticado que usa kubelet para el sondeo de preparación. Kubelet lo alcanza directamente en la IP del Pod, por lo que ninguna otra carga de trabajo dentro del clúster debería alcanzar los Pods de MCP en 15021.

Aplica esta restricción antes de completar la guía de inicio rápido de MCP y, luego, implementa tu primer proxy de detección de MCP en un entorno que no sea de desarrollo.

Contrato de actualidad de la configuración

Cuando el sidecar de MCP completa una extracción de configuración exitosa, el contenedor del plano de datos de MCP carga el paquete recuperado y sigue publicándolo hasta la próxima extracción exitosa. Si las extracciones posteriores fallan (no se puede acceder al plano de control de Apigee ni a Cloud Storage, se quitó el permiso de IAM en la cuenta de servicio del observador o se produjo un error en cualquier otra etapa de la canalización de extracción), el sidecar seguirá publicando el paquete que se sabe que funcionaba correctamente de forma indefinida. No hay un límite de obsolescencia integrado en 1.17.0: el pod permanece Ready y el tráfico de la herramienta de MCP sigue publicándose en el paquete obsoleto. El indicador de que la configuración dejó de actualizarse es una línea de registro de sidecar en el nivel ERROR que contiene un contador consecutive_failures (consulta Soluciona problemas de implementaciones de MCP para ver los mensajes específicos que emite el sidecar por etapa de falla).

En el caso de los entornos de producción regulados, se pagina en incrementos repetidos de este contador. Una alerta mínima viable es una página cuando cualquier contenedor secundario de MCP emite una línea de registro de nivel ERROR con consecutive_failures que alcanza un umbral que estableces según tu tolerancia a la obsolescencia. Los valores en aumento indican que el sidecar dejó de actualizar la configuración. Mientras tanto, el sidecar sigue publicando el paquete que se cargó correctamente por última vez.

Si el sidecar dejó de actualizar la configuración, investiga el modo de falla en los registros del sidecar. Consulta Soluciona problemas de implementaciones de MCP. Reiniciar los Pods del MCP no resuelve el problema subyacente de recuperación porque los Pods recién creados acceden a la misma ruta de recuperación.

Requisitos de red saliente

El sidecar del MCP (el contenedor de configuración dentro de cada Pod del MCP) necesita acceso de red saliente a los siguientes extremos en TCP 443. Elige la pestaña que coincida con si tu organización de Apigee usa residencia de datos, ya que los extremos requeridos difieren.

Sin residencia de datos

Extremo Se usa para
apigee.googleapis.com Recupera la referencia de configuración actual del MCP para tu organización desde el plano de control de Apigee en cada actualización de la configuración.
storage.googleapis.com Descarga la configuración del MCP de tu organización desde Google Cloud Storage.

Residencia de los datos

Si tu organización de Apigee usa la residencia de datos, el sidecar de MCP accede a tu endpoint regional del plano de control de Apigee (el mismo endpoint que usan tus otros componentes de Apigee hybrid, configurado a través del valor del gráfico contractProvider en tu overrides.yaml). Reemplaza CONTROL_PLANE_LOCATION por la ubicación del plano de control de tu organización (por ejemplo, us, eu).

Extremo Se usa para
CONTROL_PLANE_LOCATION-apigee.googleapis.com Recupera la referencia de configuración actual del MCP para tu organización desde el extremo regional del plano de control de Apigee en cada actualización de la configuración.
storage.googleapis.com Descarga la configuración del MCP de tu organización desde Google Cloud Storage. El bucket se encuentra en la región de tu organización, y Cloud Storage lo enruta automáticamente.

Además, el proceso secundario debe poder obtener tokens de acceso de Google Cloud para las credenciales ambientales con las que se ejecuta el pod (a través de Workload Identity o una clave de cuenta de servicio basada en archivos). Los extremos específicos de intercambio de tokens dependen de tu ruta de autenticación y son los mismos que otros componentes de Apigee Hybrid ya usan en tu clúster. Si el tráfico existente de Apigee hybrid a las APIs de Google Cloud se realiza correctamente desde este espacio de nombres, el intercambio de tokens del sidecar de MCP también se realizará correctamente.

Además, el proceso secundario necesita acceso dentro del clúster al servidor de la API de Kubernetes (a través de la dirección de servicio estándar dentro del clúster) para publicar su estado de actividad y preparación. Este tráfico nunca sale de tu clúster.

Soluciona problemas

Para obtener una lista de verificación de diagnóstico completa, consulta Soluciona problemas de implementaciones de MCP, que incluye una lista de verificación de diagnóstico del clúster para Apigee Hybrid.

Errores comunes de instalación

Síntoma Causa y solución
helm upgrade se completa, pero no aparecen recursos del MCP. El organigrama se actualizó antes que el gráfico del operador. Primero, ejecuta helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ y, luego, vuelve a ejecutar helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/.
Los pods de MCP están atascados en ContainerCreating o 1/2 Ready. Dos causas comunes: aún no se emitió el Certificate de cert-manager para el MCP o falla la extracción de la imagen del contenedor. Ejecuta kubectl describe pod en el pod afectado para conocer el motivo exacto.
El informe de registros del sidecar (apigee-mcp-server-config) se genera no MCP config from CP yet; skipping tick, pod stays Ready via seed en cada sondeo. Es el estado estable esperado cuando aún no se implementó ningún proxy de detección de MCP para tu organización. El plano de control de Apigee devuelve una referencia de configuración vacía, y el plano de datos de MCP solo tiene el receptor de disponibilidad de Kubernetes cargado en el puerto 15021. El puerto de solicitud de MCP 8443 aún no tiene un receptor, y las solicitudes a https://mcp.apigee.internal/mcp reciben una conexión rechazada. Para realizar la transición al estado de entrega, sigue la guía de inicio rápido de MCP para implementar un proxy de descubrimiento de MCP en un entorno del grupo de entornos que entrega este clúster.
Los registros de Sidecar informan CP fetch failed con un 403 o PermissionDenied HTTP integrado. La cuenta de servicio de Google Cloud del observador de Apigee perdió el rol roles/apigee.runtimeAgent (que otorga el permiso apigee.runtimeconfigs.get que necesita el sidecar) en tu proyecto de usuario de Apigee. La instalación básica de Apigee Hybrid otorga este rol automáticamente. Si se quitó con una limpieza de automatización de IAM, vuelve a aplicarlo en la cuenta de servicio de apigee-watcher de Google Cloud.
Los registros de Sidecar informan CP fetch failed con context deadline exceeded, errores de DNS o errores de TLS. El sidecar no puede acceder a apigee.googleapis.com ni a storage.googleapis.com desde el interior del clúster. Verifica la salida con respecto a los tres extremos que se indican en los requisitos de red saliente anteriores.
Los Pods de Message Processor no se reiniciaron después de helm upgrade. Verifica que la entrada hostAliases esté presente en cada Pod de MP: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. Si algún pod se muestra vacío, fuerza una renderización nueva borrando el pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). El controlador ApigeeDeployment lo volverá a crear a partir de la especificación actual, que incluye la entrada hostAliases. No uses kubectl rollout restart deploy, ya que no se aplica a ApigeeDeployment.
Los registros del pod de MP muestran errores de protocolo de enlace TLS al marcar https://mcp.apigee.internal/ o https://ORG_NAME.mcp.apigee.internal/ después de que el tráfico de la herramienta del MCP comienza a fluir a través de la guía de inicio rápido. El contenedor del plano de datos de MCP está publicando un certificado cuyos nombres alternativos del sujeto (SAN) no incluyen el nombre de host al que llamó el MP. Verifica el certificado: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server y, luego, kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. El dnsNames del certificado debe incluir tanto mcp.apigee.internal como ORG_NAME.mcp.apigee.internal en minúsculas. Si no es así, borra el recurso de MCP Certificate y deja que cert-manager vuelva a emitirlo.

¿Qué sigue?