Ativar o Protocolo de Contexto de Modelo (MCP) na Apigee híbrida

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como ativar o Protocolo de Contexto de Modelo (MCP) em um cluster da Apigee híbrida que executa a versão 1.17.0 ou mais recente. Depois de concluir esse procedimento, seu cluster vai executar um novo plano de dados do MCP no cluster, e o Message Processor estará pronto para encaminhar as chamadas de ferramentas do MCP para ele. Em seguida, implante seu primeiro proxy de descoberta do MCP seguindo o guia de início rápido do MCP compartilhado.

Para conceitos, arquitetura e detalhes de recursos do MCP compartilhados entre a Apigee e a Apigee híbrida, consulte a visão geral do MCP na Apigee.

O que esse procedimento faz

Ativar o MCP em um cluster híbrido da Apigee faz as seguintes mudanças:

  1. Concede à identidade apigee-watcher acesso à configuração do MCP no plano de controle da Apigee. Adicione a conta de serviço apigee-watcher à lista watcher_identities no recurso controlPlaneAccess da organização da Apigee para que o sidecar do MCP possa extrair pacotes de configuração do MCP do plano de controle da Apigee. Essa é uma mudança no plano de controle, com escopo na organização da Apigee, e é uma etapa única por organização, não importa quantos clusters atendam a ela.
  2. Adiciona um novo plano de dados do MCP no cluster. Um novo conjunto de pods do MCP é criado no mesmo namespace do Kubernetes em que a Apigee híbrida está instalada (padrão apigee), junto com os recursos de suporte do Kubernetes (serviço, escalonador automático horizontal de pods e RBAC) necessários para executá-los. As chamadas de ferramentas do MCP são processadas por estes pods.
  3. Configura o processador de mensagens para alcançar o plano de dados do MCP. O operador do Apigee atualiza a especificação do pod do processador de mensagens para que o MP direcione as chamadas de ferramentas do MCP para o novo plano de dados do MCP no cluster. A aplicação dessa mudança aciona um lançamento canário em etapas do processador de mensagens (gerenciado pelo controlador ApigeeDeployment). O pod anterior continua atendendo ao tráfego até que o novo pod seja Ready. A liberação é acionada apenas nas transições de ativação e desativação, não na atividade contínua do MCP ou no tráfego do MCP em estado estável. Execute esse procedimento em uma janela de manutenção aprovada e aguarde a conclusão do lançamento antes de continuar.

Etapa 1: editar overrides.yaml

Abra o arquivo overrides.yaml que você usa para os gráficos Helm da Apigee híbrida. No nível superior do arquivo, adicione:

enableMcpServer: true

Essa é a configuração mínima necessária para ativar o MCP. Ele usa os padrões integrados do gráfico apigee-org: duas réplicas do plano de dados do MCP que escalonam automaticamente para dez em 70% de utilização da CPU, com solicitações de recursos de 500 m de CPU e 512 Mi de memória e limites de 2.000 m de CPU e 1 Gi de memória no contêiner do plano de dados do MCP. Para personalizar contagens de réplicas, solicitações de recursos ou a conta de serviço do MCP, consulte Referência: campos do MCP em overrides.yaml mais adiante nesta página.

Confira a seguir exemplos completos de um overrides.yaml mesclado, um para cada estilo de autenticação. Use o exemplo que corresponde à configuração da sua instalação de base atual. As linhas específicas do MCP são destacadas com comentários e são as mesmas nas três variantes.

Escolha a guia que corresponde à forma como sua instalação básica autentica os componentes da Apigee no Google Cloud. A seleção se aplica a todos os blocos de código no escopo da variante nesta página.

Identidade da carga de trabalho (GKE)

Use essa variante se a instalação básica autenticar componentes da Apigee no Google Cloud pela Identidade da carga de trabalho do GKE (sem arquivos de chave de conta de serviço no 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: {}
# ----------------------------------------------------------------------------

Chaves de conta de serviço baseadas em arquivo

Use essa variante se a instalação básica autenticar componentes do Apigee no Google Cloud por arquivos de chave de conta de serviço distribuídos para cada cluster.

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

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

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

Federação de identidade da carga de trabalho (AKS/EKS)

Use essa variante se a instalação básica estiver no AKS ou no EKS e se autenticar no Google Cloud pela federação de identidade da carga de trabalho. O MCP usa o arquivo de configuração de credencial que o apigee-watcher já usa, de watcher.serviceAccountPath, portanto, não é necessário adicionar nenhuma configuração de identidade específica do MCP. Se você armazenar a configuração de credenciais em um secret do Kubernetes, consulte Outros mecanismos de identidade.

Adicione a chave de nível superior do MCP ao seu overrides.yaml do WIF:

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

Não defina mcpServer.gsa e mcpServer.serviceAccountPath. O sidecar do MCP usa o mesmo arquivo de configuração de credenciais que apigee-watcher, de watcher.serviceAccountPath.

Etapa 2: conceder à identidade do observador acesso à configuração do MCP no plano de controle

O sidecar do MCP busca o pacote de configuração no plano de controle do Apigee usando a conta de serviço do Google Cloud do componente apigee-watcher (a identidade selecionada na etapa 1). Antes do início dos pods do MCP, adicione essa conta de serviço à lista watcher_identities no recurso controlPlaneAccess da organização da Apigee. Sem essa concessão, as chamadas do sidecar do MCP para apigee.googleapis.com para recuperar a referência de configuração do MCP retornam 404 Not Found, e o plano de dados do MCP nunca fica pronto para atender ao tráfego de ferramentas.

Esta é uma etapa única por organização, não por cluster. Pule esta etapa se você já tiver concedido acesso a um cluster anterior na mesma organização do Apigee.

  1. Defina as variáveis de shell usadas para a chamada de API. Reutilize os valores da sua instalação: 
    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)

    Em que:

    • YOUR_ORG_NAME é o nome da sua organização da Apigee híbrida.
    • YOUR_GCP_PROJECT_ID é o projeto na nuvem do Google Cloud que hospeda sua organização Apigee híbrida.
    • WATCHER_SA é o endereço de e-mail da conta de serviço apigee-watcher. Se você substituiu watcher.gsa em overrides.yaml, use esse valor em vez do apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com padrão.
  2. Chame a API updateControlPlaneAccess para adicionar a conta de serviço do observador à lista watcher_identities:

    Sem residência de dados

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

    Residência de dados

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

    Em que CONTROL_PLANE_LOCATION é o local dos dados do plano de controle se a instalação da Apigee híbrida usar a residência de dados. Para a lista de locais disponíveis, consulte Regiões disponíveis do plano de controle da API Apigee.

    A chamada retorna uma operação de longa duração. Aguarde a conclusão antes de executar a etapa de verificação abaixo.

  3. Verifique se o benefício foi feito. Chame getControlPlaneAccess e confirme se a conta de serviço do observador aparece no campo watcherIdentities da resposta:

    Sem residência de dados

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

    Residência de dados

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

    A resposta precisa incluir uma matriz watcherIdentities com a conta de serviço do observador. Exemplo:

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

    Se watcherIdentities não estiver na resposta ou não contiver sua conta de serviço do observador, execute o comando PATCH novamente e verifique o status da operação para erros antes de continuar.

Etapa 3: fazer upgrade do gráfico apigee-operator

Faça upgrade do gráfico do operador primeiro. O gráfico do operador é proprietário do esquema para os novos recursos do MCP, e o gráfico da organização os referencia. Fazer upgrade na ordem errada resulta em um helm upgrade bem-sucedido que não cria pods do MCP.

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

O comando é concluído em menos de um minuto. Confirme se a implantação do operador foi totalmente implementada com a nova imagem. O apigee-controller-manager Deployment é um recurso do Kubernetes padrão, não um ApigeeDeployment. Portanto, kubectl rollout status deploy é o comando correto aqui:

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

Saída esperada:

deployment "apigee-controller-manager" successfully rolled out

Etapa 4: fazer upgrade do gráfico apigee-org

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

Agora, dois loops de reconciliação são executados em paralelo:

  • O operador do Apigee cria a implantação, o serviço, o HPA, a conta de serviço, a função e a vinculação de função do MCP. Os pods do MCP aparecem dois por vez (sujeito ao agendamento do Kubernetes). O contêiner secundário em cada pod realiza a primeira busca de configuração do plano de controle do Apigee logo após a inicialização.
  • O operador da Apigee injeta a entrada hostAliases na especificação do pod do processador de mensagens, o que aciona uma versão do apigee-runtime ApigeeDeployment.

Etapa 5: verificar a instalação

Verificar se o plano de dados do MCP está em execução

Inspecione os quatro recursos relacionados ao MCP criados pelo operador. Os nomes de recursos incluem um sufixo derivado da organização. Os exemplos a seguir usam ORG_CR_SUFFIX como marcador de posição para esse sufixo. Os sufixos de pod e o ClusterIP do serviço serão diferentes no seu ambiente.

Pods do MCP (dois por padrão; escalonamento automático para dez sob 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 pod precisa mostrar 2/2 na coluna READY. Os dois contêineres em cada pod são:

  • apigee-mcp-server: o contêiner do plano de dados do MCP a que os pods do MP se conectam.
  • apigee-mcp-server-config: o sidecar de configuração (um modo do binário apigee-watcher) que busca pacotes de configuração do plano de controle da Apigee e os grava em um volume compartilhado que o contêiner do plano de dados do MCP lê.

MCP ApigeeDeployment (um recurso personalizado do Kubernetes, não um Deployment simples):

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

O estado esperado é running. Verifique também se o pod subjacente é 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

Serviço do 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

Confirme se MINPODS corresponde a mcpServer.replicaCountMin do seu overrides.yaml (padrão 2) e se MAXPODS corresponde a mcpServer.replicaCountMax (padrão 10). As colunas TARGETS, REPLICAS e AGE dependem de métricas em tempo real e do estado do cluster.

Verificar se os pods do processador de mensagens receberam a entrada hostAliases

Todos os pods do MP precisam mostrar a entrada injetada. Se um pod estiver faltando, ele não poderá rotear chamadas de ferramentas do MCP. Liste todos os pods do MP e os respectivos hostAliases:

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

Saída esperada: cada pod do MP lista uma matriz hostAliases que contém uma entrada com dois nomes de host apontando para o ClusterIP do serviço MCP da etapa anterior (o segundo nome de host usa o nome da organização em letras minúsculas). Os nomes dos pods do processador de mensagens seguem o modelo apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, em que TRUNCATED_ORG é o nome da sua organização (truncado para se ajustar ao limite de 63 caracteres do Kubernetes se o nome da organização for longo), ENV_GROUP_HASH é um hash de grupo de implantação por ambiente, REV é o número da revisão da versão atual (quatro dígitos, por exemplo, 1170) e POD_HASH é um sufixo aleatório por pod. Exemplo:

apigee-runtime-myorg-env1-abc12-1170-def34   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
apigee-runtime-myorg-env1-abc12-1170-ghi56   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]

Se algum pod mostrar um valor hostAliases vazio, o processador de mensagens ApigeeDeployment não capturou totalmente a especificação atualizada do pod. Force uma nova versão canário em etapas excluindo os pods atuais do processador de mensagens. O controlador ApigeeDeployment vai renderizar novamente com base na especificação atual (que agora inclui a entrada hostAliases):

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

O controlador ApigeeDeployment vai recriar os pods em um minuto. O comando kubectl rollout restart deploy (Kubernetes padrão) não funciona no processador de mensagens porque ele é implantado como um recurso personalizado ApigeeDeployment, não um Deployment.

Instalação concluída

Juntas, as três verificações anteriores confirmam que o plano de dados do MCP está em execução e pode ser endereçado pelo MP:

  • Cada pod do MCP é 2/2 Running. O contêiner do plano de dados do MCP falha na sondagem de prontidão do Kubernetes na porta 15021 se o certificado TLS emitido pelo operador não for carregado e o sidecar ainda não tiver carregado a configuração inicial do MCP. Portanto, os pods Ready têm essas duas pré-condições.
  • A especificação de cada pod do MP contém a entrada hostAliases fixando mcp.apigee.internal e ORG_NAME.mcp.apigee.internal no ClusterIP do serviço MCP. Portanto, os pods do MP podem resolver os endpoints de destino do proxy do MCP para o plano de dados do MCP no cluster.
  • Um pod do MP resolve mcp.apigee.internal para o ClusterIP do serviço MCP pela entrada hostAliases injetada.

Você verifica o tráfego de ferramentas do MCP de ponta a ponta (uma chamada real de initialize ou tools/list do MCP pelo ingresso da Apigee) como parte do início rápido do MCP compartilhado, depois de implantar o primeiro proxy de descoberta do MCP.

Se alguma das três verificações anteriores falhar, consulte Solução de problemas de implantações do MCP antes de prosseguir para o guia de início rápido.

Etapa 6: ativar o MCP nos clusters restantes

As solicitações da MCP para um determinado nome do host podem ser encaminhadas para qualquer cluster que atenda ao grupo de ambiente correspondente da Apigee. Se o MCP estiver ativado em alguns clusters e não em outros no mesmo grupo de ambiente, as solicitações do MCP que forem roteadas para um cluster sem o MCP ativado vão falhar (normalmente retornadas ao cliente como 503 Service Unavailable).

Ative o MCP de maneira uniforme em todos os clusters que atendem ao mesmo grupo de ambiente. Para cada cluster adicional, repita as etapas 1, 3, 4 e 5. Não é necessário repetir a etapa 2 (conceder acesso à identidade de observador): essa concessão é limitada à organização da Apigee e se aplica a todos os clusters na mesma organização.

Reverter

Para desativar o MCP em um cluster, defina enableMcpServer: false (ou remova o campo inteiramente) em overrides.yaml e faça upgrade do gráfico apigee-org:

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

O campo enableMcpServer é consumido apenas pelo gráfico apigee-org. Portanto, não é necessário fazer upgrade do gráfico do operador durante uma desativação. O operador do Apigee (inalterado) detecta a mudança de configuração do recurso personalizado ApigeeOrganization, exclui os recursos do MCP e remove a entrada hostAliases da especificação do pod do processador de mensagens, o que aciona uma versão do apigee-runtime ApigeeDeployment. Reverta em uma janela de manutenção aprovada.

Após o rollback, os proxies de descoberta do MCP implantados no ambiente da Apigee ainda estarão presentes no plano de controle da Apigee, mas nenhum cluster nesse grupo de ambientes vai atender ao tráfego do MCP. Cancele a implantação dos proxies de descoberta do MCP para desfazer totalmente o recurso ou deixe-os implantados e reative o MCP nos clusters mais tarde.

Referência: campos do MCP em overrides.yaml

A tabela a seguir lista todos os campos overrides.yaml da Apigee híbrida que controlam o comportamento do MCP na versão 1.17.0. Apenas enableMcpServer é obrigatório. Todos os outros campos têm padrões seguros que atendem à maioria das instalações.

As definições de campo correspondem aos padrões do gráfico Helm apigee-org para o híbrido 1.17.0.

Campo Tipo Padrão Ajuste recomendado
enableMcpServer booleano false Obrigatório. Defina como true para ativar o MCP neste cluster. Alternar esse campo aciona uma versão canário gradual do processador de mensagens. Ative apenas em uma janela de manutenção e aguarde a conclusão do lançamento antes de continuar.
mcpServer.replicaCountMin integer 2 Mantenha em 2 para alta disponibilidade. Aumente apenas se você tiver um valor de referência de tráfego alto de MCP. O HPA será escalonado automaticamente sob pressão da CPU. Indicador: HPA sustentado em replicaCountMax e CPU acima da meta.
mcpServer.replicaCountMax integer 10 Aumente se você observar que o HPA atingiu o limite de 10 durante o pico. Indicador: kubectl top pods -l app=apigee-mcp-server mostra todos os pods perto do limite de CPU no pico. Se metrics-server não estiver instalado, use kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server e verifique se a coluna REPLICAS está no limite de MAXPODS.
mcpServer.targetCPUUtilizationPercentage integer 70 Diminua para 50–60 em cargas de trabalho sensíveis à latência (escalonamento mais cedo). Aumente para 80–85 para reduzir a contagem de réplicas em clusters sensíveis a custos. Indicador: a latência de solicitação p95 está correlacionada com a CPU por pod.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi Aumente as solicitações se os pods forem frequentemente OOMKilled ou tiverem limitação de CPU em estado estável. Indicador: kubectl describe pod mostra condições de OOMKilled ou restrição.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi Aumente o limite de CPU antes de aumentar a contagem de réplicas quando a latência p95 estiver alta, mas o QPS geral estiver baixo (poucas solicitações caras). Aumente o limite de memória somente se você encontrar OOMKills.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi Raramente precisa de ajuste. O sidecar cria e grava periodicamente pacotes de configuração. O uso de CPU em estado estável é mínimo.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi Raramente precisa de ajuste. Aumente a memória apenas se você implantar um número muito grande de ferramentas de MCP em um único proxy de descoberta.
mcpServer.terminationGracePeriodSeconds integer 30 Raramente precisa de ajuste. Aumente se solicitações de MCP em trânsito de longa duração precisarem de mais tempo para serem concluídas durante um esgotamento do pod.
mcpServer.annotations mapa {} Adicione anotações extras de pod se o cluster exigir.
mcpServer.serviceAccountPath string não definido Deixe sem definir, a menos que você precise de separação de identidade por componente. Quando não definido, o MCP usa watcher.serviceAccountPath. O MCP não usa envs[].serviceAccountPaths.runtime. A identidade apigee-watcher já tem as permissões necessárias para o sidecar do MCP. Se você substituir esse campo, especifique o caminho para um arquivo JSON de chave de conta de serviço Google Cloud . Mutuamente exclusivo com mcpServer.gsa.

Se a Identidade da carga de trabalho não estiver ativada e você não definir mcpServer.serviceAccountRef nem serviceAccountSecretProviderClass, defina mcpServer.serviceAccountPath ou watcher.serviceAccountPath. Se você não definir nenhum dos dois, helm upgrade vai falhar com o erro mcpServer.serviceAccountPath or watcher.serviceAccountPath is required!!.

Sempre que possível, prefira a Identidade da carga de trabalho (GKE) ou a federação de identidade da carga de trabalho (AKS/EKS). As chaves de conta de serviço baseadas em arquivos precisam ser alternadas, armazenadas com segurança e distribuídas para todos os clusters. Elas são a fonte mais comum de vazamentos em artefatos de suporte (consulte Casos de suporte).
mcpServer.gsa string não definido Deixe sem definir, a menos que você precise de separação de identidade por componente. Quando não definido, o MCP volta para watcher.gsa e depois para gcp.workloadIdentity.gsa. A identidade apigee-watcher já tem as permissões necessárias para o sidecar do MCP. Por isso, recomendamos reutilizá-la. Substitua por um e-mail dedicado de conta de serviço do Google Cloud somente se sua organização exigir uma identidade distinta para o sidecar do MCP por motivos de auditoria.
mcpServer.serviceAccountRef string não definido Avançado. Nome de um Secret do Kubernetes no namespace do Apigee que contém uma chave de conta de serviço do Google Cloud para o sidecar do MCP. Use isso apenas se você gerenciar secrets de chaves conta de serviço fora dos gráficos do Helm do Apigee. Mutuamente exclusivo com mcpServer.serviceAccountPath e mcpServer.gsa.

O MCP não usa watcher.serviceAccountRef. Se a instalação básica armazenar a chave apigee-watcher em um secret do Kubernetes com watcher.serviceAccountRef, defina essa propriedade com o mesmo nome do secret.
mcpServer.podDisruptionBudget mapa não definido PodDisruptionBudget opcional para os pods do MCP. Aceita minAvailable ou maxUnavailable (string de porcentagem ou número inteiro). Defina um, não os dois. Deixe sem definição, a menos que seu cluster tenha políticas de interrupção voluntária rigorosas que exijam um orçamento explícito.
mcpServer.tolerations list unset (volta ao tolerations de nível superior) Tolerâncias padrão do Kubernetes para pods do MCP. Defina apenas se os pods do MCP precisarem tolerar taints que outros componentes da Apigee não toleram.
mcpServer.image.pullPolicy string IfNotPresent Política de pull de imagem para o contêiner do servidor MCP. Raramente mudado.
mcpServer.sidecar.image.pullPolicy string IfNotPresent Política de extração de imagem para o contêiner secundário do MCP. Raramente mudado.

Estimar a capacidade da ferramenta MCP

A Apigee híbrida não impõe um número máximo fixo de ferramentas do MCP por organização. Em vez disso, a capacidade da ferramenta é limitada por quatro limites de tamanho fixos aplicados no momento da implantação ou da solicitação. Se um número específico de ferramentas se encaixa, isso depende do tamanho de cada uma, que é derivado da especificação OpenAPI que define a ferramenta.

Capacidade típica

Para a maioria das especificações OpenAPI (uma combinação de ferramentas com contagens de parâmetros, tamanhos de corpo de solicitação e comprimentos de descrição variados, com a maioria das ferramentas se enquadrando no intervalo de tamanho pequeno a médio), é possível incluir 10.000 ferramentas MCP por organização no limite de tamanho de resposta tools/list padrão.

A capacidade real varia de acordo com o formato específico da especificação OpenAPI. Organizações cujas especificações são dominadas por ferramentas com muitos parâmetros, corpos de solicitação grandes ou descrições longas se encaixam em um número proporcionalmente menor de ferramentas antes de atingir um dos quatro limites máximos abaixo. Para validar a capacidade das suas especificações, siga as instruções em Estimar a capacidade da sua especificação abaixo.

Limites absolutos

Quatro limites de tamanho se aplicam na versão 1.17.0 da Apigee híbrida. O limite mais baixo aplicável é o que vincula; aumentar um não aumenta os outros.

Limite Valor Escopo Modo de falha
Tamanho do arquivo de especificação OpenAPI 3 MiB por arquivo .yaml 400 em proxy validate
Tamanho do pacote de proxy do MCP (descompactado) 50 MiB por proxy de descoberta do MCP 400 em "proxy validate"
Tamanho da resposta tools/list 10 MiB (padrão) por nome de host 502 com TooBigBody
Nomes de host por grupo de ambiente 100 por grupo de ambientes 400 na atualização do grupo de ambientes

O que impulsiona o tamanho por ferramenta

O tamanho por ferramenta é composto quase inteiramente pelo inputSchema da ferramenta, que é derivado do parameters e do requestBody da especificação OpenAPI para a operação. Três propriedades são as mais importantes:

  • Número de parâmetros. Cada entrada de parâmetro contribui com aproximadamente 100 bytes para o tamanho da ferramenta na resposta tools/list.
  • Número de propriedades do corpo da solicitação. Cada propriedade do corpo da solicitação contribui com aproximadamente 100 bytes. Portanto, as operações com um corpo de solicitação (normalmente POST e PUT) são substancialmente maiores do que as operações sem um corpo (normalmente GET e DELETE).
  • Tamanho da descrição. As descrições de operações são copiadas quase ipsis litteris para a ferramenta. Portanto, uma descrição mais longa aumenta diretamente o tamanho da ferramenta.

Os esquemas de resposta não são contabilizados no orçamento de tamanho. Somente parameters e requestBody alcançam a configuração do MCP. Portanto, dimensionar a capacidade apenas pelo tamanho do arquivo OpenAPI tende a superestimar o custo, porque a maioria das especificações OpenAPI reais inclui definições de esquema de resposta que não afetam o tamanho da ferramenta.

Estimar a capacidade para sua especificação

A maneira mais confiável de estimar a capacidade da ferramenta para suas especificações OpenAPI é medir um subconjunto representativo:

  1. Implante um proxy de descoberta do MCP que faça referência a um pequeno subconjunto representativo das ferramentas que você planeja publicar (por exemplo, de 50 a 100 ferramentas que refletem a combinação de contagens de parâmetros, tamanhos de corpo da solicitação e comprimentos de descrição na sua especificação completa).
  2. Chame tools/list no proxy implantado e registre o tamanho da resposta em bytes e o número de ferramentas retornadas.
  3. Divida o tamanho da resposta pela contagem de ferramentas para obter o tamanho médio por ferramenta da sua especificação.
  4. Divida o limite de tamanho de resposta tools/list aplicável (10 MiB por padrão) por essa média para estimar o número máximo de ferramentas que cabem em um nome de host para uma especificação desse formato.

Aumentar a capacidade

Dois mecanismos aumentam a capacidade da ferramenta além dos padrões:

  • Fragmentar ferramentas em nomes de host. O limite de respostas do tools/list é por nome do host. Dividir ferramentas em vários nomes de host no mesmo grupo de ambientes multiplica o headroom por nome de host (sujeito ao limite de 100 nomes de host por grupo de ambientes). O sharding não aumenta o limite por pacote de proxy. O limite de 50 MiB continua sendo aplicado a todos os nomes de host em um único proxy de descoberta do MCP.
  • Aumente o limite de tamanho da resposta tools/list. O limite padrão é de 10 MiB por nome de host. É possível aumentar esse valor para até 30 MiB. No mínimo, isso envolve definir envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory e envs.components.runtime.cwcAppend.bin_setenv_max_mem no overrides.yaml e executar helm upgrade no gráfico apigee-org. Consulte Configurar o suporte a payloads de mensagens grandes na Apigee híbrida para o procedimento completo, incluindo variantes por ambiente e por instalação inteira, orientações sobre dimensionamento de heap do processador de mensagens e exemplos completos de overrides.yaml. Aumentar o limite de respostas não afeta o limite de tamanho do pacote de proxy do MCP de 50 MiB. Se a capacidade for limitada por esse limite, essa mudança não vai ajudar.

Segurança

Limite de confiança

O plano de dados do MCP é executado no seu próprio cluster do Kubernetes. O Google não tem acesso em tempo de execução ao plano de dados. O plano de controle da Apigee oferece a configuração do MCP derivada da sua especificação OpenAPI, mas não observa o tráfego de solicitações do MCP. Os dados de configuração em repouso são armazenados em um bucket do Cloud Storage gerenciado pela Apigee e com escopo para o projeto de locatário da Apigee, buscados pelo sidecar do MCP usando a conta de serviço ambiente do Google Cloud.

O operador da Apigee provisiona um Role e um RoleBinding do Kubernetes no escopo do MCP no namespace da Apigee (APIGEE_NAMESPACE) para a conta de serviço do plano de dados do MCP. A função concede acesso somente leitura:

  • get, list, watch em services no grupo principal de APIs.
  • get, list, watch em apigeeroutes no grupo de APIs apigee.cloud.google.com.

A função não concede verbos de gravação nem acesso a Secrets, ConfigMaps ou status do pod. Seu auditor pode verificar as regras exatas diretamente do cluster com:

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

A função apigee-mcp-server-APIGEE_ORG_CR e o RoleBinding são os recursos do RBAC no escopo do MCP. Os nomes deles incluem o nome completo do recurso personalizado ApigeeOrganization (derivado do nome da organização da Apigee e de um hash curto). Eles não têm um rótulo app=apigee-mcp-server no nível do recurso (apenas os pods têm), então uma pesquisa com base em rótulos não retorna resultados. Se o comando de seletor de campo acima não retornar nada, liste todos os recursos RBAC relacionados ao MCP no namespace com:

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

TLS entre o processador de mensagens e o plano de dados do MCP

Os pods do processador de mensagens discam o plano de dados do MCP em https://mcp.apigee.internal/ ou https://ORG_NAME.mcp.apigee.internal/. Esses nomes de host são resolvidos para o ClusterIP do serviço MCP pela entrada hostAliases injetada. O contêiner do plano de dados do MCP apresenta um certificado TLS assinado pelo emissor provisionado pelo operador do Apigee (o ClusterIssuer chamado apigee-ca-issuer). Os nomes alternativos do assunto do certificado incluem os dois nomes de host.

Restringir o acesso de entrada ao serviço MCP

Na Apigee híbrida 1.17.0, o plano de dados do MCP não autentica os chamadores de forma independente. Ele confia que as solicitações que chegam a ele já foram autenticadas por um proxy MCP da Apigee em execução no processador de mensagens. O único chamador pretendido do serviço MCP é o processador de mensagens. Qualquer outra carga de trabalho no cluster que possa acessar o ClusterIP do serviço MCP em TCP 443 pode invocar ferramentas do MCP sem uma verificação de autenticação.

Restrinja o acesso de entrada aos pods do MCP somente aos pods do processador de mensagens, usando o mecanismo de política de entrada do cluster da sua plataforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy ou equivalente). A restrição:

  • Permite a entrada em pods com o rótulo app=apigee-mcp-server no namespace APIGEE_NAMESPACE no TCP 443 de pods com o rótulo app=apigee-runtime apenas no mesmo namespace.
  • Nega toda a entrada em TCP 443 para pods com o rótulo app=apigee-mcp-server.
  • Nega toda a entrada no cluster em TCP 15021 para pods com o rótulo app=apigee-mcp-server. A porta 15021 atende a um endpoint /healthz/ready HTTP simples não autenticado usado pelo kubelet para sondagem de prontidão. O kubelet o acessa diretamente no IP do pod, portanto, nenhuma outra carga de trabalho no cluster deve acessar os pods do MCP em 15021.

Aplique essa restrição antes de concluir o guia de início rápido do MCP e implante seu primeiro proxy de descoberta do MCP em um ambiente que não seja de desenvolvimento.

Contrato de atualização da configuração

Quando o sidecar do MCP conclui um pull de configuração bem-sucedido, o contêiner do plano de dados do MCP carrega o pacote buscado e continua veiculando-o até o próximo pull bem-sucedido. Se as extrações subsequentes falharem (plano de controle da Apigee inacessível, Cloud Storage inacessível, permissão do IAM removida na conta de serviço do observador ou um erro em qualquer outra etapa do pipeline de extração), o sidecar vai continuar veiculando o último pacote funcional conhecido indefinidamente. Não há um limite máximo de inatividade integrado no 1.17.0: o pod permanece Ready e o tráfego da ferramenta MCP continua sendo veiculado no pacote desatualizado. O sinal de que a configuração parou de ser atualizada é uma linha de registro do sidecar no nível ERROR que carrega um contador consecutive_failures. Consulte Solução de problemas de implantações do MCP para ver as mensagens específicas que o sidecar emite por estágio de falha.

Para ambientes de produção regulamentados, faça paginação em incrementos repetidos desse contador. Um alerta mínimo viável é: página quando qualquer contêiner secundário do MCP emite uma linha de registro no nível ERROR com consecutive_failures atingindo um limite definido com base na sua tolerância a dados desatualizados. Valores crescentes indicam que o sidecar parou de atualizar a configuração. Enquanto isso, ele continua veiculando o pacote mais recente.

Se o sidecar parou de atualizar a configuração, investigue o modo de falha nos registros do sidecar. Consulte Resolver problemas de implantações do MCP. A reinicialização dos pods do MCP não resolve o problema de busca subjacente porque os pods recém-criados atingem o mesmo caminho de busca.

Requisitos de rede de saída

O arquivo secundário do MCP (o contêiner de configuração em cada pod do MCP) precisa de acesso à rede de saída aos seguintes endpoints no TCP 443. Escolha a guia que corresponde ao uso da residência de dados pela sua organização da Apigee. Os endpoints necessários são diferentes.

Sem residência de dados

Endpoint Usado para
apigee.googleapis.com Recupere a referência de configuração atual do MCP para sua organização no plano de controle da Apigee em cada atualização de configuração.
storage.googleapis.com Faça o download da configuração do MCP da sua organização no Google Cloud Storage.

Residência de dados

Se a sua organização da Apigee usa residência de dados, o sidecar do MCP acessa o endpoint regional do plano de controle da Apigee (o mesmo endpoint usado pelos outros componentes do Apigee híbrido, configurado pelo valor do gráfico contractProvider em overrides.yaml). Substitua CONTROL_PLANE_LOCATION pelo local do plano de controle da sua organização (por exemplo, us, eu).

Endpoint Usado para
CONTROL_PLANE_LOCATION-apigee.googleapis.com Recupere a referência de configuração atual do MCP para sua organização no endpoint regional do plano de controle da Apigee em cada atualização de configuração.
storage.googleapis.com Faça o download da configuração do MCP da sua organização no Google Cloud Storage. O bucket está localizado na região da sua organização, e o Cloud Storage faz o roteamento para ele automaticamente.

Além disso, o sidecar precisa conseguir tokens de acesso do Google Cloud para as credenciais ambientais em que o pod é executado (pela Identidade da carga de trabalho ou uma chave de conta de serviço baseada em arquivo). Os endpoints específicos de troca de tokens dependem do seu caminho de autenticação e são os mesmos que outros componentes da Apigee híbrida já usam no seu cluster. Se o tráfego da Apigee híbrida para as APIs do Cloud do Google Cloud for bem-sucedido nesse namespace, a troca de tokens do sidecar do MCP também será bem-sucedida.

Além disso, o sidecar precisa de acesso no cluster ao servidor da API Kubernetes (pelo endereço do serviço padrão no cluster) para publicar o estado de atividade e prontidão. Esse tráfego nunca sai do cluster.

Solução de problemas

Para conferir uma lista de verificação de diagnóstico completa, consulte Solução de problemas de implantações do MCP, que inclui uma lista de verificação de diagnóstico do lado do cluster para a Apigee híbrida.

Falhas de instalação comuns

Sintoma Causa e correção
O helm upgrade é concluído, mas nenhum recurso do MCP aparece. O organograma foi atualizado antes do gráfico do operador. Execute helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ primeiro e depois execute helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ novamente.
Pods do MCP travados em ContainerCreating ou 1/2 Ready. Duas causas comuns: o Certificate do cert-manager para MCP ainda não foi emitido ou a extração da imagem do contêiner está falhando. Execute kubectl describe pod no pod afetado pelo motivo exato.
O relatório de registros do arquivo secundário (apigee-mcp-server-config)no MCP config from CP yet; skipping tick, pod stays Ready via seedé gerado em todas as pesquisas. Estado estável esperado quando nenhum proxy de descoberta do MCP foi implantado para sua organização. O plano de controle da Apigee retorna uma referência de configuração vazia e o plano de dados do MCP tem apenas o listener de prontidão do Kubernetes carregado na porta 15021. A porta de solicitação do MCP 8443 ainda não tem um listener, e as solicitações para https://mcp.apigee.internal/mcp recebem uma conexão recusada. Para fazer a transição para o estado de veiculação, siga o guia de início rápido do MCP para implantar um proxy de descoberta do MCP em um ambiente no grupo de ambientes atendido por esse cluster.
Os registros do sidecar informam CP fetch failed com um 403 ou PermissionDenied HTTP incorporado. A conta de serviço do Google Cloud do observador da Apigee perdeu a função roles/apigee.runtimeAgent (que concede a permissão apigee.runtimeconfigs.get necessária para o sidecar) no projeto de locatário da Apigee. A instalação básica do Apigee híbrido concede esse papel automaticamente. Se ele foi removido por uma limpeza de automação do IAM, aplique-o novamente na conta de serviço do Google Cloud apigee-watcher.
Os registros do sidecar informam CP fetch failed com context deadline exceeded, erros de DNS ou erros de TLS. O sidecar não consegue acessar apigee.googleapis.com ou storage.googleapis.com de dentro do cluster. Verifique a saída em relação aos três endpoints listados em Requisitos de rede de saída acima.
Os pods do processador de mensagens não foram reiniciados após helm upgrade. Verifique se a entrada hostAliases está presente em todos os pods do MP: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'. Se algum pod estiver vazio, force uma nova renderização excluindo o pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime). O controlador ApigeeDeployment vai recriá-lo com base na especificação atual, que inclui a entrada hostAliases. Não use kubectl rollout restart deploy, porque não se aplica a ApigeeDeployment.
Os registros do pod do MP mostram erros de handshake de TLS ao discar https://mcp.apigee.internal/ ou https://ORG_NAME.mcp.apigee.internal/ depois que o tráfego da ferramenta MCP começa a fluir pelo guia de início rápido. O contêiner do plano de dados do MCP está veiculando um certificado cujos nomes alternativos do assunto (SANs) não incluem o nome do host discado pelo MP. Verifique o certificado: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server e kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. O dnsNames do certificado precisa incluir mcp.apigee.internal e ORG_NAME.mcp.apigee.internal em letras minúsculas. Se não, exclua o recurso MCP Certificate e deixe o cert-manager emitir novamente.

A seguir