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ê
| arquivo | autor | o que diz aqui |
|---|---|---|
aggregate.yaml | o desenvolvedor | o gateway, o servidor de modelos e a conexão upstream do gateway até ele |
release.yaml | o operador | os dois namespaces e, na entrada do servidor de modelos, a vinculação allowlist com a sua infra |
manifest.yaml | o operador | qual 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ância | Component do catálogo | namespace | o que é aqui |
|---|---|---|---|
gateway | core/gateway/nginx | edge | o gateway que os clientes chamam; ele encaminha para o servidor de modelos |
model | core/ai-model/ollama | models | o 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:
aggrega scaffold --example model-server-caller-allowlistEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd model-server-caller-allowlistBuild
aggrega build --release release.yaml --auto-pullUma 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste 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>/distO 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.yamlA 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: prometheusno namespacemonitoring.
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, emedgeou em qualquer outro namespace — incluindo outro agente emmonitoring. - 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: trueda 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/namespaceda fronteiraedge, 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_sourcesque 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_sourcescom 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, como10.20.0.0/16. - Um segundo chamador. Adicione uma aresta
usesdele 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.