Features e políticas
Esta página explica uma única ideia, vincular um comportamento a um componente e verificar o resultado com uma política, e não é um espaço de trabalho executável. Uma política que interrompe um build quando dados restritos chegam sem mascaramento a um modelo gerenciado mostra as duas coisas em um espaço de trabalho que você compila; grave-o em uma pasta sua com:
aggrega scaffold --example policy-data-class-routeEm seguida ele imprime os próximos comandos a executar:
cd policy-data-class-routeaggrega build --release release-masked.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-unmasked.yaml --config governance-rego.yaml --auto-pull # halts; exits 1aggrega build --release release-masking-off-route.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Uma Feature é vinculada, e realizada por uma FeatureRecipe
Uma Feature é um comportamento que um componente não tem por si só — mascaramento, um backup, um ingress, uma credencial — e que um autor vincula a ele em features:. Quem a vincula decorre de quem decide suas entradas: o desenvolvedor vincula, no Aggregate, uma Feature cujo comportamento faz parte do que a aplicação é; o operador vincula, na Release, uma cujas entradas são todas operacionais. Em ambos os casos, o Manifest associa cada Feature a uma FeatureRecipe, que decide como ela é realizada para o destino.
No exemplo, o desenvolvedor vincula a core/data-masking da biblioteca padrão a um gateway de IA e lista o que mascarar, a partir de aggregate.yaml sem os comentários:
masking-gateway: type: core/gateway/litellm values: model: chat features: masking: type: core/data-masking values: patterns: - name: claim_number regex: '\bCLM-[0-9]{8}\b' entities: [PERSON, EMAIL_ADDRESS]O desenvolvedor não indica nenhum endereço, guardrail ou configuração de provedor. O Manifest associa core/data-masking a helm/data-masking-litellm, que escreve o mascaramento na configuração que a própria Recipe do gateway renderiza, por meio de etapas do pipeline de plugins que encerra a renderização, e adiciona ao lado um módulo que o gateway carrega. Todos os outros arquivos que o build escreve são idênticos byte a byte aos de um build sem o anexo.
O que a vinculação não faz é declarado com o mesmo cuidado que o que ela faz: o texto com o qual nenhum padrão corresponde e que o reconhecedor não detecta passa inalterado, o gateway e os dois serviços do reconhecedor veem o texto original, e o tráfego que não passa pelo gateway não é tocado. Os comentários da FeatureRecipe listam o que este gateway recusa e o que ele repassa como foi enviado.
Os rótulos decidem onde uma Feature pode ir
Os rótulos são a identidade semântica de um componente, e determinam o posicionamento de uma Feature, os seletores de sockets e as políticas sem nenhuma alteração no compilador. O campo appliesTo de uma Feature é um seletor de rótulos sobre o componente ao qual ela está vinculada. core/data-masking declara appliesTo: "dataplane.aggrega.ai/content-masking", uma chave isolada, que corresponde a qualquer componente que tenha esse rótulo, seja qual for o seu valor; core/gateway/litellm o tem, com o valor entity-recognition. Um seletor também pode corresponder a valores, component.aggrega.ai/type in (server, worker), ou excluir um rótulo, !model.aggrega.ai/capability; os requisitos de um mesmo seletor, separados por vírgulas, devem ser todos atendidos, e a Feature se vincula apenas a um componente ao qual eles correspondam. Vinculação baseada em rótulos apresenta a gramática completa dos seletores.
Mais duas declarações restringem as vinculações:
- Interoperabilidade. Uma Feature pode nomear Features com as quais não pode compartilhar um componente.
core/data-maskingdeclarainteroperability.conflictsWith: [core/semantic-caching], então um build em que um componente acabe carregando ambas — vinculadas ao próprio componente, ou a um subsistema ou fronteira que o contém — é interrompido antes da renderização. - Exigências de presença. Um Component pode exigir que uma vinculação de determinado tipo esteja presente. O
example/compute/servicedo catálogo tem a anotaçãofeatures.aggrega.ai/requiredType.monitoring: core/prometheus-exporter, então um build em que uma instância dele não tenha nenhumacore/prometheus-exporter, em nenhum escopo, é interrompido nomeando o requisitomonitoring. Repita a chave com outro sufixo para exigir um segundo tipo; veja entities/component.md “Presence mandates (Exigências de presença)” para saber como uma exigência difere de um slot de vinculação.
Uma Feature fica no componente cujo comportamento ela altera. core/caller-allowlist é vinculada a um servidor de modelos, não aos gateways autorizados a chamá-lo; Um servidor de modelos que só o seu gateway pode chamar faz o build disso.
Uma política lê o grafo construído
As políticas são vinculadas pelo operador em plugins.governance na configuração do espaço de trabalho, cada vinculação em um papel. Uma política no papel label-transform adiciona rótulos ao grafo; uma no papel ir-verdict o julga e pode interromper o build. O motor Rego executa ambas; ele é compilado na CLI, e governance/rego é a sua entidade Plugin no catálogo da biblioteca padrão.
A primeira regra abaixo marca cada gateway que analisa o payload de modelo que encaminha como um ponto em que os prompts saem para um provedor de modelos. Nesse papel, os nós ficam em input.graph.nodes:
# policies/egress-tagging.rego: attached at the label-transform rolepackage aggrega.tagging
import rego.v1
labels contains {"node": id, "key": "compliance.aggrega.ai/egress", "value": "model-provider"} if { some id, node in input.graph.nodes node.labels["gateway.aggrega.ai/intelligence"] == "semantic"}A segunda interrompe qualquer caminho através de um gateway desse tipo que não tenha mascaramento:
# policies/model-egress.rego: attached at the ir-verdict rolepackage aggrega.security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some egress in path.nodes input.graph.spec.nodes[egress].labels["compliance.aggrega.ai/egress"] == "model-provider" not "core/data-masking" in path.attached_features
msg := sprintf( "BLOCKED: path %v sends model traffic through %v without core/data-masking attached.", [concat(" -> ", path.nodes), egress] )}O id de um nó é a chave sob a qual ele fica em input.graph.spec.nodes; attached_features lista os tipos de Feature vinculados a qualquer nó do caminho, então a pertinência é testada com in; a regra verifica que o mascaramento está vinculado, não o que ele lista; e uma decisão coletada em deny é reportada com a severidade halt, que interrompe o build. Uma regra sobre caminhos só vê um nó onde uma aresta chega a ele ou sai dele, então uma política que também precise cobrir um nó não conectado lê os próprios nós.
O operador vincula o motor uma vez por papel, cada vinculação com o seu próprio arquivo de política; um caminho relativo em sources é resolvido em relação ao diretório do arquivo de configuração, e a transformação é executada antes do veredito:
plugins: governance: - uri: governance/rego:0.9.0 role: label-transform with: sources: - policies/egress-tagging.rego - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/model-egress.regoA página do socket de governança é a superfície de autoria completa: o payload que cada papel expõe, as chaves de decisão e como nomear as suas. O exemplo Políticas que moldam rótulos vincula uma política que molda rótulos ao lado dos dois plugins de rotulagem integrados e faz o build dela.