Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Um servidor de modelos que só o seu gateway pode chamar

Um servidor de modelos executado em um cluster responde a quem alcançar o seu endereço. Em uma rede de pods sem nenhuma política de rede, que é o padrão do Kubernetes, isso é toda carga de trabalho do cluster: o gateway colocado na frente do modelo é o caminho pelo qual o tráfego deve chegar, não o único caminho pelo qual ele pode chegar.

O Aggregate já diz quais componentes chamam quais: a conexão upstream do gateway nomeia o servidor de modelos. core/caller-allowlist, que o operador vincula ao servidor de modelos na Release, transforma essa conexão declarada na regra da rede do cluster. Este espaço de trabalho compila esse arranjo para manifestos do Kubernetes: um gateway NGINX no namespace edge, um servidor de modelos Ollama no namespace models, e a política de rede que a vinculação escreve ao lado do servidor de modelos.

Este workspace não cria nenhuma entidade de catálogo própria. Os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.

Quem escreve o quê

arquivoautoro que diz aqui
aggregate.yamlo desenvolvedoro gateway, o servidor de modelos e a conexão upstream do gateway até ele
release.yamlo operadoros dois namespaces e, na entrada do servidor de modelos, a vinculação allowlist com a sua infra
manifest.yamlo operadorqual Recipe realiza cada componente e a Feature no Kubernetes

O Aggregate não traz nada sobre política de rede. O desenvolvedor declara a conexão que o gateway faz; se o cluster recusa todas as outras é decisão do operador para este ambiente, tomada na Release em components.model.features. Toda entrada que a Feature recebe é infra, o pilar do operador. O que o desenvolvedor deve saber é a consequência: onde quer que uma Release vincule esta Feature a um componente, uma chamada que o Aggregate não declara como aresta uses para esse componente é recusada pelo cluster, onde o seu plugin de rede impõe a política de rede.

O que ele constrói

instânciaComponent do catálogonamespaceo que é aqui
gatewaycore/gateway/nginxedgeo gateway que os clientes chamam; ele encaminha para o servidor de modelos
modelcore/ai-model/ollamamodelso servidor de modelos, servindo llama3.1

Uma aresta uses: o socket upstream do gateway para o servidor de modelos. Uma vinculação de Feature, na Release: allowlist, core/caller-allowlist, no servidor de modelos. A Release afirma que o cluster impõe a política de rede e nomeia uma origem fora do Aggregate, um agente de monitoramento.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example model-server-caller-allowlist

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd model-server-caller-allowlist

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Uma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Este espaço de trabalho resolve as entidades de catálogo a partir do registro padrão que .aggrega-config.yaml nomeia; nada é baixado de um repositório de charts.

O build imprime, com <workspace> representando a pasta deste exemplo:

warning: node "model" (provider "helm"): target "helm" does not support annotation aggrega.ai/namespace on artifacts-only input and ignored it
[… omitted: the resolution's summary and a total build time, which differ per run]
Build completed: 6 files written to <workspace>/dist

O aviso é sobre a política. O destino não coloca os manifestos próprios de uma Feature em um namespace, então o template da vinculação escreve na política o namespace em que o StatefulSet do servidor de modelos é emitido — namespace: "models" abaixo.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use somente as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `model-server-caller-allowlist`, chame a ferramenta `scaffold` uma vez com `example` definido como `model-server-caller-allowlist` e sem `dir`: ela grava o exemplo em uma nova pasta `model-server-caller-allowlist`. Depois chame a ferramenta `build` com `workspace_root` definido como `model-server-caller-allowlist`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `model-server-caller-allowlist/dist/`.

A árvore renderizada

dist/
├── edge/helm/
│ ├── gateway-default-service.yaml
│ └── gateway-deployment.yaml
└── models/helm/
├── model--allowlist--networkpolicy.yaml
├── model-default-service.yaml
├── model-headless-service.yaml
└── model-statefulset.yaml

A vinculação adiciona um arquivo, a política. Todos os outros arquivos são, byte a byte, o que a mesma Release renderiza sem ela.

O que pode alcançar o servidor de modelos

dist/models/helm/model--allowlist--networkpolicy.yaml, a partir do seu spec:

spec:
podSelector:
matchLabels:
"app": "model"
policyTypes:
- Ingress
ingress:
- from:
-
namespaceSelector:
matchLabels:
"kubernetes.io/metadata.name": "models"
podSelector:
matchLabels:
"app": "model"
-
namespaceSelector:
matchLabels:
"kubernetes.io/metadata.name": "edge"
podSelector:
matchLabels:
"app": "gateway"
-
namespaceSelector:
matchLabels:
"kubernetes.io/metadata.name": "monitoring"
podSelector:
matchLabels:
"app.kubernetes.io/name": "prometheus"
ports:
- port: 11434
protocol: "TCP"

A política fica em models, o namespace em que o StatefulSet do servidor de modelos é emitido, seleciona os pods do servidor de modelos e admite conexões para eles a partir de três origens, na única porta que o contêiner do servidor de modelos declara:

  • Os próprios pods do servidor de modelos, em models, para que as réplicas de um mesmo servidor possam alcançar umas às outras.
  • Os pods do gateway, no namespace edge. O seletor de namespace e o seletor de pods ficam em uma única entrada, então um pod precisa corresponder aos dois. Uma carga de trabalho em outro namespace com os mesmos rótulos — o mesmo Aggregate implantado novamente em outro lugar, por exemplo — não é o gateway e não é admitida.
  • O agente de monitoramento que a Release nomeia: pods rotulados app.kubernetes.io/name: prometheus no namespace monitoring.

Os pods de cada componente são selecionados pelo seletor que o seu próprio controlador escreve — app: model para o StatefulSet do servidor de modelos, app: gateway para o Deployment do gateway — e cada namespace é aquele em que a sua carga de trabalho é emitida, ambos lidos do que as renderizações emitiram em vez de repetidos à mão. Nenhum dos seletores traz uma versão, então quando um novo build é implantado, os pods do anterior continuam selecionados e continuam admitidos até serem substituídos.

O que não pode alcançá-lo

  • Qualquer outra carga de trabalho, em models, em edge ou em qualquer outro namespace — incluindo outro agente em monitoring.
  • Um controlador de ingress, ou qualquer cliente fora do cluster. Nada fora do Aggregate é admitido a menos que a Release o nomeie, e esta Release nomeia apenas o agente de monitoramento. Os clientes alcançam o servidor de modelos por meio do gateway, que é a conexão que o Aggregate declara.
  • Qualquer porta diferente de 11434.

A política restringe quem pode se conectar, não o que uma conexão transporta: uma requisição que o gateway encaminha chega ao modelo tal como o gateway a enviou.

O que o build não pode saber

Se a regra é imposta. Uma política de rede é imposta pelo plugin de rede do cluster, e somente onde esse plugin implementa política de rede; um cluster cujo plugin não a implementa aceita a política e não impõe nada. O build escreve a política e não consegue ver o cluster, e é por isso que a Release traz control_plane_present: true na vinculação: é a declaração do operador de que o cluster de destino a impõe, e o build é interrompido até que ela seja feita.

Outros três limites vêm de como a política de rede funciona, e não desta Feature:

  • As políticas se somam. Onde outra política no cluster seleciona os mesmos pods, uma conexão que qualquer uma delas admite é admitida.
  • O gateway não é restringido por esta vinculação. Ela protege o servidor de modelos; vincule a Feature também à entrada do gateway na Release para restringir quem alcança o gateway, e nomeie ali os clientes que ele atende.
  • O tráfego de saída não é afetado. O servidor de modelos continua alcançando o registro do qual baixa os pesos, e resolve nomes como antes.

O que interrompe o build

Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:

  • O pré-requisito não é afirmado. Remova control_plane_present: true da Release:

    [… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the template position and the assertion's own source]
    error calling fail: assertion failed: core/caller-allowlist attachment "allowlist" on "model" writes a network policy, which restricts connections only where the cluster's network plugin enforces network policy; once the target cluster's plugin does, affirm it by setting infra.control_plane_present to true on this attachment in the Release
  • Um chamador cuja carga de trabalho não é emitida em nenhum namespace. Remova a anotação aggrega.ai/namespace da fronteira edge, e o Deployment do gateway é emitido sem nenhum:

    [… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the artifact being rendered, the template position and the template's own source]
    error calling fail: core/caller-allowlist attachment "allowlist" on "model": "gateway" connects to "model" through its "upstream" socket, but the Deployment "gateway" it renders is emitted into no namespace, so the policy cannot name where its pods run; set aggrega.ai/namespace on the boundary holding "gateway", or on its own entry, in the Release, or have the manifest that carries it write one
  • A carga de trabalho do servidor de modelos não emitida em nenhum namespace, pelo mesmo motivo: uma política seleciona pods apenas no seu próprio namespace.

  • Uma carga de trabalho de qualquer um dos dois que não escreve nenhum seletor de controlador e não traz nenhum dos rótulos de identidade que o build aplica aos seus pods — um Job de um chart que depende do seletor que o cluster gera, por exemplo. Selecioná-la por cada rótulo que ela traz deixaria de corresponder aos seus pods na primeira vez que um rótulo de versão mudasse, então o build é interrompido em vez disso.

  • Um chamador, ou o servidor de modelos, cuja renderização não emite nenhum pod — um realizado por um recurso personalizado cujo controlador cria os pods depois, ou alcançado em um endereço fora do cluster. Esse componente não pode ser nomeado em uma política, então o build é interrompido em vez de escrever uma política que o recusaria ou não selecionaria nada.

  • Uma origem em admitted_sources que nomeia tanto um intervalo de endereços quanto pods, ou nenhum dos dois.

Onde o compilador não interpreta

O compilador canaliza para a política, como strings, os seletores, rótulos e namespaces que cada renderização informou. Ele não contata o cluster, não sabe qual plugin de rede roda ali e não sabe quais cargas de trabalho já rodam em um namespace. Cada interrupção acima é declarada pelas próprias entidades do catálogo, na realização da Feature, e nenhuma delas se baseia em qualquer conhecimento do cluster.

Adaptando-o

  • Admitir um controlador de ingress. Adicione uma entrada a admitted_sources com o seu namespace e os rótulos dos seus pods — ambos em uma única entrada, para que apenas esses pods nesse namespace sejam admitidos.
  • Admitir um intervalo de endereços. Adicione uma entrada com cidr, como 10.20.0.0/16.
  • Um segundo chamador. Adicione uma aresta uses dele para o servidor de modelos no Aggregate e coloque-o em um namespace que a Release declara; o próximo build o admite sem nenhuma alteração na vinculação.
  • Compose. A Feature não é realizada ali: um stack do Compose coloca todos os serviços de um grupo em uma única rede, e a configuração de um serviço não pode tirar outro serviço dela, então uma Release que associa esta Feature no Compose é interrompida por falta de uma realização.