cristiano.hoshikawa/agent_platform_oci
1
2
Fork 0
mirror of https://github.com/hoshikawa2/agent_platform_oci.git synced 2026-09-07 18:23:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
05077a91bc41e6edd02f80f41a7836d9c12b71c7
agent_platform_oci/deploy/oke/README_OKE_DEPLOYMENT.md

10 KiB
Raw Blame History

Deployment do Agent Platform OCI em OCI OKE

Este pacote adiciona os artefatos necessários para publicar o agent_platform_oci em um cluster OCI OKE / Kubernetes.

O objetivo é atender a três pontos principais:

  1. Publicar o agent_framework como biblioteca dentro das imagens Python, permitindo imports como:

    from agent_framework import ...

  2. Implantar o agent_template_backend com múltiplos pods, Service interno e HorizontalPodAutoscaler, permitindo escalabilidade horizontal.

  3. Implantar os componentes externos da plataforma:

    • agent_gateway
    • channel_gateway
    • mcp_gateway
    • agent_frontend

O desenho recomendado em OKE é:

Usuário / Canal
   |
   | HTTP/S
   v
OCI Load Balancer
   |
   +--> agent_frontend        Serviço LoadBalancer
   +--> agent_gateway         Serviço LoadBalancer
   +--> channel_gateway       Serviço LoadBalancer
   +--> mcp_gateway           Serviço LoadBalancer

Dentro do cluster:

agent_gateway  ---> agent_template_backend Service ---> vários pods do agente
agent_backend  ---> mcp_gateway Service
mcp_gateway    ---> MCP servers internos ou externos

Observação: este pacote deixa os gateways como serviços externos LoadBalancer, conforme solicitado. Em produção, é comum expor apenas o channel_gateway, agent_gateway ou um Ingress/API Gateway corporativo, mantendo mcp_gateway interno.

Estrutura criada

deploy/oke/
  README_OKE_DEPLOYMENT.md
  .dockerignore
  dockerfiles/
    Dockerfile.agent-template-backend
    Dockerfile.agent-gateway
    Dockerfile.channel-gateway
    Dockerfile.mcp-gateway
    Dockerfile.agent-frontend
  nginx/
    default.conf
  k8s/base/
    00-namespace.yaml
    01-configmap.yaml
    02-secret-template.yaml
    03-agent-template-backend.yaml
    04-agent-gateway.yaml
    05-channel-gateway.yaml
    06-mcp-gateway.yaml
    07-frontend.yaml
    kustomization.yaml
  scripts/
    build_images.sh
    push_images.sh
    create_runtime_secret.sh
    deploy_oke.sh
    status.sh
  examples/
    oke.env.example

Por que foram criados novos Dockerfiles

Os Dockerfiles existentes usam caminhos relativos ao diretório da aplicação, por exemplo:

COPY agent_framework /agent_framework
COPY agent_template_backend /app

No repositório atual, o framework está em:

libs/agent_framework

E o backend está em:

templates/agent_template_backend

Por isso, os Dockerfiles de OKE usam a raiz do repositório como build context e fazem:

COPY libs/agent_framework /opt/agent_framework
RUN pip install -e /opt/agent_framework

Assim, o agent_framework fica instalado como biblioteca Python dentro das imagens dos componentes que precisam dele.

Pré-requisitos

Na máquina de build/deploy:

  • Docker
  • kubectl
  • OCI CLI configurado
  • Acesso ao cluster OKE
  • Acesso ao OCIR
  • Usuário OCI com permissões para push no OCIR
  • Token de autenticação OCI para login no Docker Registry

Login no OCIR:

docker login <region-key>.ocir.io

Exemplo para São Paulo:

docker login gru.ocir.io

O usuário normalmente segue o formato:

<tenancy-namespace>/<user>

1. Configurar o arquivo de ambiente

Copie o exemplo:

cp deploy/oke/examples/oke.env.example deploy/oke/oke.env

Edite:

vi deploy/oke/oke.env

Campos principais:

OCI_REGION=sa-saopaulo-1
OCI_REGION_KEY=gru
OCI_TENANCY_NAMESPACE=your_tenancy_namespace
OCIR_REPOSITORY_PREFIX=agent-platform-oci
IMAGE_TAG=1.0.0
K8S_NAMESPACE=agent-platform
OKE_CLUSTER_OCID=ocid1.cluster.oc1..example

Para usar OCI Generative AI em vez de mock:

LLM_PROVIDER=oci_openai
OCI_GENAI_BASE_URL=https://inference.generativeai.sa-saopaulo-1.oci.oraclecloud.com/openai/v1
OCI_GENAI_MODEL=<modelo>
OCI_GENAI_API_KEY=<api-key>
OCI_COMPARTMENT_ID=<compartment-ocid>

Para primeiro teste sem custo de LLM, deixe:

LLM_PROVIDER=mock

2. Build das imagens

Execute a partir da raiz do projeto:

./deploy/oke/scripts/build_images.sh deploy/oke/oke.env

Imagens geradas:

agent-template-backend
agent-gateway
channel-gateway
mcp-gateway
agent-frontend

Todas serão tagueadas no padrão:

<region-key>.ocir.io/<tenancy-namespace>/<prefix>/<image>:<tag>

Exemplo:

gru.ocir.io/mytenancy/agent-platform-oci/agent-template-backend:1.0.0

3. Push para OCIR

./deploy/oke/scripts/push_images.sh deploy/oke/oke.env

4. Criar secrets de runtime

O script abaixo cria ou atualiza o secret agent-platform-secrets no namespace configurado:

./deploy/oke/scripts/create_runtime_secret.sh deploy/oke/oke.env

O arquivo 02-secret-template.yaml existe apenas como referência. Não coloque credenciais reais no Git.

5. Fazer deploy no OKE

./deploy/oke/scripts/deploy_oke.sh deploy/oke/oke.env

O script:

  1. Opcionalmente atualiza o kubeconfig via OCI CLI, se OKE_CLUSTER_OCID estiver preenchido.
  2. Cria/atualiza o namespace.
  3. Cria/atualiza os secrets.
  4. Aplica os manifests com Kustomize.
  5. Aguarda o rollout dos deployments.
  6. Lista os serviços e IPs externos.

6. Verificar status

./deploy/oke/scripts/status.sh

Ou manualmente:

kubectl -n agent-platform get pods -o wide
kubectl -n agent-platform get svc
kubectl -n agent-platform get hpa

Quando o Load Balancer estiver provisionado, os serviços externos aparecerão com EXTERNAL-IP:

kubectl -n agent-platform get svc agent-gateway
kubectl -n agent-platform get svc channel-gateway
kubectl -n agent-platform get svc mcp-gateway
kubectl -n agent-platform get svc agent-frontend

7. Testes rápidos

Health do backend interno:

kubectl -n agent-platform port-forward svc/agent-template-backend 8000:8000
curl http://localhost:8000/health

Health do Agent Gateway:

kubectl -n agent-platform port-forward svc/agent-gateway 8010:8010
curl http://localhost:8010/health

Envio de mensagem pelo Agent Gateway:

curl -X POST http://localhost:8010/gateway/message \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "web",
    "tenant_id": "default",
    "payload": {
      "message": "quero consultar minha fatura",
      "metadata": {
        "customer_key": "11999999999"
      }
    }
  }'

Escalabilidade

O agent_template_backend foi configurado com:

replicas: 3

E com HPA:

minReplicas: 3
maxReplicas: 10
averageUtilization: 70

Ajuste em:

deploy/oke/k8s/base/03-agent-template-backend.yaml

O Load Balancer externo fica nos gateways e no frontend. O backend do agente é ClusterIP, porque o acesso deve ocorrer via gateway.

Sobre estado, sessão e persistência

O manifesto usa emptyDir para /data, suficiente para smoke test e validação inicial.

Para produção, substitua SQLite por um provider externo:

  • Autonomous Database
  • MongoDB
  • Redis para cache distribuído
  • Object Storage ou banco para artefatos persistentes

Não use SQLite local com múltiplos pods em produção para sessão, memória, checkpoints e usage, porque cada pod teria seu próprio estado.

Configurações relevantes no ConfigMap:

SESSION_REPOSITORY_PROVIDER: "sqlite"
MEMORY_REPOSITORY_PROVIDER: "sqlite"
CHECKPOINT_REPOSITORY_PROVIDER: "sqlite"
USAGE_REPOSITORY_PROVIDER: "sqlite"

Para produção, altere esses providers e injete as credenciais por Secret.

Ajuste do Agent Gateway para vários agentes

O arquivo:

deploy/oke/k8s/base/01-configmap.yaml

cria o ConfigMap agent-gateway-backends com:

backends:
  contas:
    url: http://agent-template-backend.agent-platform.svc.cluster.local:8000

Para adicionar novos agentes, crie novos deployments e serviços, depois adicione novas entradas:

backends:
  contas:
    url: http://agent-contas.agent-platform.svc.cluster.local:8000
  ofertas:
    url: http://agent-ofertas.agent-platform.svc.cluster.local:8000
  suporte:
    url: http://agent-suporte.agent-platform.svc.cluster.local:8000

Ajuste do MCP Gateway

O mcp_gateway é implantado com configuração vazia por padrão:

servers: {}
tools: {}

Edite o ConfigMap mcp-gateway-config em:

deploy/oke/k8s/base/01-configmap.yaml

Exemplo:

servers:
  telecom:
    enabled: true
    discover: true
    protocol: legacy_http
    transport: http
    url: http://telecom-mcp.agent-platform.svc.cluster.local:8100/mcp
    timeout_seconds: 30

Frontend

O frontend foi empacotado em Nginx e exposto com Service LoadBalancer.

Como o frontend atual é estático, o endereço do gateway pode ser informado na própria interface, caso ela já tenha campo de backend/gateway. Caso você queira fixar o endpoint em build/runtime, o próximo ajuste recomendado é adicionar um arquivo /config.js gerado por ConfigMap com a URL pública do agent_gateway.

Segurança recomendada para produção

Para produção, recomenda-se:

  1. Usar ClusterIP para mcp_gateway e expor apenas via rede privada.
  2. Usar OCI API Gateway ou Ingress Controller com TLS.
  3. Criar NetworkPolicy restringindo tráfego entre namespaces.
  4. Usar OCI Vault/External Secrets para credenciais.
  5. Usar Workload Identity ou Instance Principal quando aplicável.
  6. Usar Autonomous Database ou MongoDB externo para estado.
  7. Configurar observabilidade com OTel/Langfuse.
  8. Separar namespaces por ambiente: dev, test, prod.
  9. Não versionar .env nem secrets reais.

Comandos principais

cp deploy/oke/examples/oke.env.example deploy/oke/oke.env
vi deploy/oke/oke.env

./deploy/oke/scripts/build_images.sh deploy/oke/oke.env
./deploy/oke/scripts/push_images.sh deploy/oke/oke.env
./deploy/oke/scripts/deploy_oke.sh deploy/oke/oke.env
./deploy/oke/scripts/status.sh

Próximos passos recomendados

  1. Criar manifests separados por ambiente com overlays Kustomize: dev, hml, prod.
  2. Criar pipeline OCI DevOps ou GitHub Actions para build/push/deploy.
  3. Adicionar Ingress/API Gateway com TLS.
  4. Migrar estado de SQLite para Autonomous/MongoDB antes de produção.
  5. Criar manifests específicos para cada agente real derivado do agent_template_backend.
Reference in New Issue View Git Blame Copy Permalink