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

O socket de governança

O socket inteiro em vez de apenas um de seus papéis: os quatro papéis — dois que julgam um build, dois que lhe dão forma —, os dois mecanismos de políticas que vêm no compilador e como um operador vincula um plugin.

Um operador vincula um plugin de governança Wasm para inspecionar um build e agir sobre o que ele encontra. O host do compilador permanece neutro quanto ao conteúdo e sem opiniões próprias: ele roteia o payload do build ao guest e age sobre o que o guest retorna, e nunca interpreta a política em si. Toda a inteligência de domínio das políticas — a linguagem de políticas, seu mecanismo e as regras — fica dentro do guest.

Este é o mesmo contrato de pureza ahead-of-time sob o qual todo socket é executado: o guest avalia o payload que recebe e retorna um resultado que o host consome literalmente (veja o contrato do sandbox). O host não aprende nada sobre a linguagem de políticas que o guest fala e não carrega nenhum código próprio de mecanismo de políticas.

Um plugin de governança é vinculado a exatamente um papel, e é o papel — não o plugin — que fixa tanto qual payload chega quanto o que a vinculação pode fazer com ele. Dois são papéis de veredito: a vinculação julga o build, e o host toma exatamente uma de três ações por veredito que ela retorna. Dois são papéis de transformação: a vinculação relata uma alteração nos rótulos ou nas anotações do build, e o host a aplica. Um plugin que atende mais de um papel é vinculado uma vez por papel, e não declara nenhum papel próprio — é a vinculação que o carrega.

Esta página é o tratamento completo do socket de governança: os quatro papéis e o payload que cada um carrega, as severidades dos vereditos sobre as quais o host age, o canal de entrada agnóstico em relação ao mecanismo que um operador fornece, como escrever uma política para qualquer um dos dois mecanismos de políticas que vêm dentro do compilador — um que avalia Rego, outro que avalia CEL —, como um guest encapsula um mecanismo de políticas externo, os guests de referência distribuídos e como um operador vincula um plugin a um espaço de trabalho. Para o lugar do socket no pipeline e suas formas de transmissão tipadas, veja plugin-contract.md; para criar e publicar um plugin como entidade do catálogo, veja o Guia do desenvolvedor de plugins Wasm.

O modelo mental: o host roteia, o guest decide

Em um build, o host monta o payload para o papel da vinculação, entrega-o através da fronteira da ABI e lê de volta o que o guest retornou. Em um papel de veredito, isso é uma lista de vereditos, cada um com uma severidade e uma mensagem legível por uma pessoa: o host mapeia cada severidade para uma ação de build, e não lê a mensagem em busca de significado, não sabe o que a política verificou e não sabe qual mecanismo produziu a decisão. Em um papel de transformação, é a alteração a fazer, endereçada aos rótulos ou às anotações que esse papel governa e a nada mais.

Como o host não interpreta o conteúdo das políticas, toda a superfície das políticas pertence ao guest: em qual linguagem as regras são escritas, qual mecanismo as avalia e como uma regra que dispara se torna um veredito ou uma alteração. O contrato do socket é estreito por design — um papel, um conjunto de entradas e um resultado — para que qualquer tecnologia de políticas que compile para Wasm possa atendê-lo.

Um papel de veredito aceita ou rejeita e não faz mais nada: o host lê sua saída apenas como uma decisão e nunca a aplica como uma alteração, de modo que uma política não pode tornar silenciosamente conforme um build não conforme. Um papel de transformação é a exceção deliberada, e o que o torna uma exceção é que o operador o vinculou — vincular um plugin para moldar rótulos é uma declaração de que os rótulos devem ser moldados. O que uma vinculação desse tipo pode alterar é limitado à superfície do seu próprio papel, e o build é interrompido de forma explícita diante de qualquer coisa fora dela.

As quatro funções

Um plugin é vinculado a exatamente um papel, e o papel define em que ponto do pipeline o host o avalia, qual payload ele recebe e o que ele pode retornar. Um plugin que deve atender a dois papéis é vinculado duas vezes — uma por papel.

Os papéis de veredito: ir-verdict e render-verdict

  • ir-verdict — o guest raciocina sobre o grafo da representação intermediária, antes da renderização. O payload carrega o grafo de IR completo, agnóstico em relação às capacidades (cada nó, aresta e vinculação que o compilador mantém), mais os caminhos de roteamento que o analisador enumera, para que uma política possa raciocinar sobre topologia e alcançabilidade sem percorrer o grafo novamente. Essa lista de caminhos é limitada por nó de partida — uma topologia densamente conectada ou cíclica pode conter mais rotas distintas do que a enumeração emite, e, uma vez atingido o limite, as rotas restantes a partir desse nó de partida não são listadas. Um caminho presente é, portanto, real, enquanto a ausência de um caminho não prova que nenhum exista: uma política cujo veredito depende de algo ser inalcançável deve estabelecer isso a partir dos nós e das arestas, que o payload carrega por completo, e não apenas da lista de caminhos. Uma coisa no grafo não está como foi escrita: cada valor que um autor declarou sensível — nos values ou no infra de uma vinculação, no infra de uma vinculação no nível da fronteira, nos values ou no infra próprios de um nó, ou nos values ou no infra próprios de uma conexão — chega como o marcador de retenção {"aggrega_withheld": "declared"}, enquanto sua chave, sua marcação de sensibilidade e cada valor não declarado ao lado dele chegam como foram escritos. Uma política julga por onde trafega o material declarado sensível e nunca recebe o material; veja os fatos de vinculação que uma política de governança lê. Uma política ir-verdict é executada no ponto de controle da análise estática, antes que qualquer artefato seja produzido. Use-a para políticas sobre arquitetura e cabeamento — invariantes de topologia, autenticação entre fronteiras, forma do fluxo de credenciais — que devem interromper um build antes que ele renderize qualquer coisa.
  • render-verdict — o guest raciocina sobre a saída renderizada, depois da renderização. O payload carrega os artefatos emitidos ordenados por caminho, de modo que os dados transmitidos são idênticos byte a byte entre execuções com entrada idêntica. Cada artefato carrega seu caminho de saída e seu texto renderizado; além disso, carrega o formato em que foi renderizado, quando o provedor que o produziu declarou um, e uma visão estruturada e analisada do seu conteúdo, quando o conteúdo está em um formato que foi analisado antes da política. Uma política render-verdict vê exatamente o que o build produziu, e nada nele é retido: um valor que uma Recipe renderizou em um artefato chega como foi renderizado, porque o artefato é o que a política julga. Use-a para políticas sobre a saída concreta — por exemplo, uma regra que inspeciona serviços do Docker Compose ou objetos do Kubernetes renderizados.

Os papéis de transformação: annotation-transform e label-transform

  • annotation-transform — o guest relata as anotações a adicionar, durante a resolução e antes da expansão de anotações. O payload carrega cada componente que a vinculação pode anotar, cada um com as anotações que já tem, mais as chaves de anotação para as quais o Manifest registra um binding. Uma anotação injetada sob uma chave registrada passa então a se expandir em uma vinculação de Feature, e é assim que esse papel adiciona a um build uma capacidade que o desenvolvedor não digitou.

    Os componentes que ela pode anotar são cada componente que uma fronteira nomeia sob components: e cada componente que a entrada de roteamento aggregates: de uma fronteira roteia para dentro. Uma entrada de roteamento posiciona cada componente do seu módulo, incluindo os componentes dos módulos aninhados dentro dele, quer o seu próprio components: nomeie todos eles, alguns ou nenhum, como faz documents: {}, que não nomeia nenhum; o payload carrega cada um deles. Um componente roteado é endereçado pelo id que carrega no grafo de build — o nome do módulo, um ponto e o nome do componente dentro do módulo, como em documents.backend, com mais um nome de módulo e um ponto para cada módulo aninhado —, que é como o grafo de build e seus diagnósticos o escrevem, de modo que uma decisão também o nomeia dessa forma. Um componente que a entrada de roteamento posiciona sem nomeá-lo não carrega anotações próprias no payload, e uma anotação injetada nele é aplicada como uma escrita nele sob a entrada de roteamento.

  • label-transform — o guest relata as alterações de rótulos a aplicar, durante a construção da topologia: depois que o grafo é construído e antes que o grafo seja julgado. O payload carrega uma projeção dos nós do build — cada um com o Component que instancia, a versão resolvida para ele, os rótulos que carrega atualmente e os valores que sua instância declara, somente leitura e com cada valor que seu Component declara sensível retido da mesma forma que o veredito sobre o grafo o retém — mais o nome e o ambiente da Release. Use-o para metadados derivados que um desenvolvedor nunca deveria ter de digitar (escopo de conformidade, propriedade, atribuição de custos) e para um rótulo de capacidade que a configuração declarada de um desenvolvedor conquista.

Os papéis carregam payloads diferentes porque atuam em momentos diferentes e respondem a perguntas diferentes. Todos os quatro carregam o mesmo canal de entrada fornecido pelo operador, descrito abaixo. Para ver um payload em vez de ler sobre ele, aggrega build --release <release> --policy-input <dir> grava o payload que cada papel entrega a um plugin vinculado ali — incluindo um papel sem nada vinculado — como um arquivo JSON por papel, ou por vinculação quando as vinculações de um papel recebem payloads diferentes, e, combinado com --dry-run, grava esses arquivos e nada mais. Em annotation-transform, label-transform e ir-verdict, o arquivo é o documento input que uma política lê. Em render-verdict, o mecanismo de políticas remodela o payload antes que uma política o leia — os documents de cada artefato são analisados a partir dele —, de modo que uma política render-verdict em um mecanismo dentro do compilador é testada em um build, vinculada em warn ou info, como mostra Testar uma política antes que ela bloqueie um build. Para um plugin cujo .wasm você mesmo compilou, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json o executa sobre esse arquivo.

Vereditos e severidades

As severidades abaixo são o vocabulário dos papéis de veredito. Um papel de transformação relata uma alteração em vez de um veredito, por isso não carrega severidade.

Um guest retorna uma lista de vereditos. Cada veredito carrega uma severidade que determina a ação de build:

  • halt — interrompe o build; o host apresenta a mensagem do veredito como motivo. O build não produz artefatos.
  • warn — sinaliza o veredito; o build prossegue.
  • info — registra o veredito; o resultado do build não muda.

Essas três são o conjunto completo, e são as mesmas três que os diagnósticos de todos os outros sockets usam, de modo que uma severidade significa a mesma coisa onde quer que você a leia.

Um veredito que carrega qualquer outro valor é uma violação do contrato, e não uma quarta via. O build é interrompido, e a mensagem nomeia o plugin, o valor que o veredito carregava e os três que o contrato declara — de modo que uma severidade escrita errado é relatada como um erro de build em vez de passar como um veredito sobre o qual nada age. Um guest que relata com um dos três não é afetado.

Uma avaliação que permite não retorna nada. Um guest emite um veredito apenas quando uma regra dispara, de modo que uma lista de vereditos vazia significa que a política permitiu o build. Não existe um veredito “pass” a emitir — o silêncio é a permissão.

Um guest pode retornar muitos vereditos em uma única avaliação, misturando severidades. O host percorre todos eles: qualquer halt interrompe o build (e cada mensagem halt é apresentada), enquanto vereditos warn e info são relatados sem bloquear. Isso espelha a separação entre interromper e avisar que distingue uma política que interrompe o build de uma verificação de lint consultiva.

O canal with: fontes e configurações

Um guest de políticas costuma ser genérico em relação às regras específicas que aplica — o mecanismo vem embutido no guest, mas as regras são fornecidas por vinculação. O canal with carrega essa entrada por vinculação. Ele tem dois campos agnósticos em relação ao mecanismo:

  • sources — os arquivos de definição de políticas que o guest carrega. O host lê cada arquivo nomeado no momento do build e passa seus bytes ao guest de forma opaca: ele nunca analisa uma fonte, e o caminho que entrega ao guest é o nome base do arquivo, nunca um caminho absoluto do host. O que os bytes significam é inteiramente assunto do guest — um arquivo .rego para um guest, algum outro formato de política para outro, e um arquivo compactado codificado em base64 de um conjunto inteiro de políticas para um guest que leia um.
  • settings — um mapa de configuração que o guest mapeia para o seu mecanismo. Um guest lê seus parâmetros ajustáveis (um teto de réplicas, uma chave de rótulo obrigatória) desse mapa. Por padrão, o host o repassa literalmente sem agir sobre ele; um guest pode, além disso, declarar um esquema para ele (veja abaixo), caso em que o host valida o mapa em relação a esse esquema antes de executar o guest.

Um guest totalmente pré-compilado — um cujas regras são compiladas nele em vez de fornecidas no momento da vinculação — omite with por completo. O canal é opcional em todos os papéis.

Configurações tipadas

Um guest pode declarar um JSON Schema para as settings que espera. Quando o faz, o host valida as settings da vinculação em relação a esse esquema antes de executar o guest. Configurações não conformes interrompem o build com uma mensagem que nomeia a chave problemática e o que o esquema esperava — uma chave obrigatória ausente, um valor do tipo errado, uma chave desconhecida ou um valor fora do intervalo são detectados antecipadamente, em vez de surgirem como uma falha obscura do guest ou, pior, como um build errado, mas bem-sucedido.

As configurações tipadas são opcionais e declaradas pelo guest, não pelo host. Um guest que não declara nenhum esquema de configurações mantém o comportamento livre: o host repassa suas settings sem verificá-las. O host executa uma validação JSON Schema comum em relação a qualquer esquema que o guest tenha declarado; ele não interpreta o que as configurações significam. Isso mantém a verificação neutra em relação ao mecanismo — cada guest descreve a forma das configurações que lê, e o host impõe exatamente essa forma e nada além disso.

Uma vinculação que não declara configurações é validada como JSON null. É isso que permite a um guest tornar suas configurações obrigatórias: um esquema que admite apenas um objeto recusa uma vinculação que não fornece nenhuma, e o build é interrompido. A consequência também vale no sentido inverso, e é aquela para a qual se deve escrever deliberadamente: um guest cujas configurações são realmente opcionais deve declarar um esquema que admita null além de um objeto, ou não poderá ser vinculado sem configurações de forma alguma. Os dois mecanismos de políticas que vêm dentro do compilador declaram "type": ["object", "null"] exatamente por esse motivo — vincule um sem bloco with: e ele é executado com seus valores padrão. Um guest que declara apenas "type": "object" tornou suas configurações obrigatórias, fosse essa a intenção ou não.

A ABI é própria do Aggrega

O contrato do socket é a ABI própria do Aggrega, não a de algum mecanismo de políticas. É isso que permite que qualquer tecnologia de políticas compilada para Wasm sirva como um guest intercambiável: o guest expõe para fora a superfície do Aggrega — describe(), mais o export que o papel que ele atende chama — e qualquer mecanismo que ele use é um detalhe de implementação por trás dessa superfície.

Um guest que encapsula um mecanismo de políticas externo absorve a ABI desse mecanismo dentro de si. Se o mecanismo tem sua própria ABI Wasm, seus próprios pontos de entrada ou seu próprio protocolo de callback para o host, o guest que o encapsula o instancia e o conduz internamente e mapeia a decisão do mecanismo para a forma de veredito do socket. O host do compilador vê apenas a superfície padrão de vereditos de governança; ele nunca fica sabendo qual mecanismo está envolvido e não carrega nenhum código específico de mecanismo. Trocar uma política de um mecanismo para outro é uma alteração na vinculação, não uma alteração no host.

Dois mecanismos de políticas vêm dentro do compilador

Dois mecanismos de políticas são compilados no binário da CLI, e um operador vincula um ou outro — ou ambos — da mesma forma que qualquer plugin de governança é vinculado:

CoordenadaLinguagem de políticasFonte vinculada
governance/regoRegoArquivos .rego ou um arquivo compactado codificado em base64 de um conjunto inteiro de políticas
governance/celCommon Expression Language (CEL)Arquivos de expressões .cel ou documentos de regras .yaml / .yml

Tudo o que cerca a linguagem é compartilhado. Ambos atendem aos quatro papéis, ambos leem o mesmo payload por papel sob os mesmos nomes de campo, ambos mapeiam suas decisões para as mesmas três severidades de veredito por meio da mesma configuração translation, e ambos falham de forma explícita em vez de permitir um build que não conseguiram avaliar. Cada um carrega como versão a release do compilador que o inclui, e nenhum precisa de uma toolchain externa nem busca nada no momento do build. O que cada linguagem consegue dizer não é compartilhado: uma regra que em Rego são algumas regras auxiliares pode exigir configurações e repetição em CEL — veja O que uma expressão pode dizer antes de escrever uma que percorra uma rota.

O que difere é a linguagem em que as regras são escritas, e essa é toda a base da escolha. Uma organização que já mantém um corpus de Rego — ou uma equipe que escreve Rego para controle de admissão em outro lugar — vincula o mecanismo Rego, e suas políticas são executadas como estão. Uma equipe que expressa suas regras como expressões únicas sobre um documento, como faz uma política de admissão de validação do Kubernetes, vincula o mecanismo CEL. Os dois são vinculados por papel, de modo que um espaço de trabalho pode executar Rego em um papel e CEL em outro, ou ambos no mesmo papel como duas vinculações.

O host é agnóstico em relação a qual dos dois produziu uma decisão: ele roteia o payload, lê de volta um veredito ou uma alteração e age de acordo. Trocar uma política de uma linguagem para a outra é uma alteração na vinculação e uma reescrita das regras — nunca uma alteração no host.

Políticas Rego: dois caminhos

Rego é uma linguagem de políticas comum, e há dois caminhos para executá-la — um mecanismo de baixo atrito que vem dentro do compilador e uma via de escape de fidelidade total.

O mecanismo Rego no compilador é o caminho de baixo atrito. Ele traz um avaliador Rego nativo de Wasm, de modo que um operador coloca um arquivo .rego em sources e vincula o plugin — nenhuma toolchain externa e nada buscado no momento do build. Ele atende aos quatro papéis: o mesmo plugin julga o grafo de build, julga a saída renderizada, molda rótulos ou injeta anotações, conforme o papel ao qual está vinculado. Sua identidade de catálogo é o nome simples rego sob pluginType: governance — a coordenada governance/rego — e sua versão é a release do compilador que o inclui. Escrever uma política para esse mecanismo é a próxima seção.

O avaliador reimplementa Rego de forma independente em vez de incorporar a implementação de referência, e não implementa todas as funções integradas do Rego. Quando uma política chama uma função integrada que o avaliador não implementa, a vinculação falha de forma explícita: retorna uma falha, não uma permissão. O build é então interrompido com uma falha que nomeia o plugin — deliberadamente distinta de um veredito halt, para que “o mecanismo não consegue avaliar esta política” nunca seja confundido com “a política permite o build”. Uma política não avaliável interrompe o build; ela nunca passa silenciosamente.

A via de escape opa build -t wasm é o caminho de fidelidade total. Quando uma política precisa do conjunto completo de funções integradas ou da semântica exata do mecanismo de referência, compile-a com a própria toolchain do OPA para um módulo Wasm e execute esse módulo por trás de um guest adaptador enxuto. O adaptador absorve a ABI Wasm do OPA inteiramente dentro de si (conforme A ABI é própria do Aggrega, acima): ele instancia o módulo gerado pelo OPA, define a entrada, invoca a avaliação e mapeia a decisão de volta para a forma de veredito. O host vê apenas a superfície padrão de vereditos de governança.

Um guest adaptador de referência vem como exemplo completo. Ele incorpora uma política escrita em Rego e pré-compilada com opa build -t wasm em um módulo WebAssembly — um artefato fixado e versionado no repositório, de modo que a avaliação é executada inteiramente dentro do guest, sem nenhum processo do OPA e sem buscar nada. A cada build, o adaptador instancia esse módulo pré-compilado dentro de si com um interpretador Wasm embutido, satisfaz as importações do próprio módulo (sua memória linear e seus callbacks de funções integradas), lê o payload como o documento input do OPA e as settings da vinculação como o documento data do OPA, avalia cada ponto de entrada compilado e mapeia o nome de ponto de entrada deny / warn / audit de cada um para uma severidade de veredito — halt, warn e info, respectivamente. Se uma política pré-compilada precisar de uma função integrada fornecida pelo host que o adaptador não implementa, o adaptador falha de forma explícita — recusando o módulo em vez de retornar uma permissão —, de modo que uma política não avaliável interrompe o build em vez de passar silenciosamente. Regenerar o módulo pré-compilado a partir de sua fonte Rego é uma etapa de criação executada com a CLI do OPA, não uma dependência no momento do build. ../examples/policy-data-class-route/ constrói esse adaptador em torno de um módulo próprio e fornece os comandos que regeneram ambos.

Os dois caminhos compartilham o mesmo contrato com o host, de modo que mover uma política do mecanismo no compilador para o mecanismo completo é uma alteração na vinculação.

Escrever uma política para o mecanismo Rego

O mecanismo avalia o Rego escrito pelo operador inteiramente dentro do guest, em qualquer um dos quatro papéis ao qual esteja vinculado. Vinculá-lo duas vezes, em dois papéis, com dois arquivos de política diferentes, é como um único mecanismo cobre dois momentos do mesmo build.

O payload do papel da vinculação é o documento input da política, e o objeto settings da vinculação é o documento data da política — assim, uma política lê um limiar fornecido pelo operador como data.max_replicas. Cada arquivo que a vinculação declara sob sources se torna um módulo de política, e cada pacote que esses arquivos declaram é avaliado.

Em qual sintaxe de regras uma política é escrita

Rego é escrito em duas sintaxes de regras, e o mecanismo aceita ambas, módulo a módulo. Um conjunto de políticas montado antes de a sintaxe atual existir é, portanto, avaliado ao lado de um escrito hoje, na mesma vinculação.

Na sintaxe atual, o corpo de uma regra é introduzido por if, uma regra que coleta em um conjunto diz isso com contains, e o módulo indica em qual sintaxe está escrito declarando import rego.v1 em uma linha própria abaixo da declaração de pacote:

package example
import rego.v1
deny contains msg if {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Na sintaxe antiga com cabeça entre colchetes, o valor que uma regra coleta fica entre colchetes na cabeça da regra, e o corpo vem logo em seguida. Um módulo nessa sintaxe não declara nada, porque é reconhecido por não ser analisado como a atual:

package example
deny[msg] {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Um módulo que é analisado como a sintaxe atual sem declarar nada é recusado, nominalmente. A declaração é o que fixa a leitura, e sem ela o mesmo texto de regra pode chegar à decisão oposta: um corpo de regra que nunca é satisfeito não contribui com nenhuma decisão na sintaxe atual e contribui com uma na sintaxe antiga — de modo que uma política que deveria ter ficado em silêncio interrompe o build, e o caso espelhado deixa passar um build que uma regra foi escrita para interromper. Em vez de escolher uma leitura para tal módulo, o mecanismo o recusa e diz o que adicionar:

policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.

A recusa é uma falha de build que nomeia o plugin, e não um veredito, de modo que interrompe o build da mesma forma que uma política não avaliável e nunca é lida como uma política que o permitiu.

Vale a pena conhecer dois casos-limite antes que eles surpreendam você. Um módulo sem nenhum corpo de regra — um que só declara dados — é analisado como a sintaxe atual, então a declaração também é exigida dele, mesmo que as duas leituras não pudessem ter divergido para ele. E um módulo escrito na sintaxe antiga nunca é recusado, porque não é analisado como a atual: é o próprio mecanismo que distingue as duas, de modo que uma política deliberadamente escrita com cabeça entre colchetes nunca é confundida com uma de sintaxe atual que se esqueceu de dizer isso.

Uma política coleta suas decisões sob uma chave de decisão

Cada papel lê as decisões de uma política a partir de uma chave de decisão — uma regra nomeada na qual a política coleta. Quais chaves são lidas, e o que uma decisão sob uma delas significa, é fixado pelo papel.

Em um papel de veredito, uma decisão é uma mensagem, e a chave sob a qual ela foi coletada fixa a severidade com que essa mensagem é relatada. Por padrão, as chaves são os nomes de coleta convencionais do Rego:

Coletado sobRelatado comoEfeito no build
denyhaltinterrompe o build
warnwarnaparece junto a um build que é concluído
auditinforegistrado; o resultado do build não muda

Mantenha os dois vocabulários separados, porque são dois: deny, warn e audit são nomes na sua política, e halt, warn e info são as severidades com que o socket relata. A coluna da esquerda você pode renomear; a coluna da direita é o conjunto fechado que todo socket compartilha.

Uma política que nomeia suas decisões de outra forma declara o mapeamento nas configurações da vinculação:

with:
settings:
translation:
- key: blocked
severity: halt
- key: advisory
severity: warn

Um mapeamento declarado substitui o padrão em vez de estendê-lo: as chaves que ele nomeia são exatamente as chaves lidas, de modo que uma política que ainda coleta em deny não chega a nenhum veredito depois que o mapeamento acima é declarado. A ordem em que as regras são declaradas é a ordem em que os vereditos são relatados. Uma chave que a política não declara é uma decisão ausente, e não um erro, de modo que um mesmo arquivo de política pode atender a várias vinculações.

Uma severidade fora das três, e um mapeamento declarado vazio, são recusados pelo esquema de configurações que o plugin declara — o host valida as configurações de uma vinculação em relação a ele antes do envio. A mesma chave mapeada duas vezes é recusada quando o mapeamento é lido, o que também acontece antes que qualquer política seja executada. De qualquer forma, o build é interrompido antes de se chegar a uma decisão, nunca com um mapeamento aplicado pela metade.

Fora isso, as configurações são os dados próprios da política: o mapeamento é lido do objeto, e o objeto chega inalterado ao documento data da política, de modo que uma política escrita para as chaves padrão vê exatamente o documento de dados que teria visto sem nenhum mapeamento configurado.

Em um papel de transformação, uma decisão é a alteração a fazer em vez de uma mensagem, de modo que não há severidade a fixar e, em vez disso, é a chave que é fixada: labels no papel que molda rótulos, annotations no papel que injeta anotações. Uma configuração translation só é lida onde vereditos são relatados, de modo que uma vinculação de transformação que declare uma carrega uma configuração que seu papel não consome.

Uma chave de decisão é lida de todo pacote que a vinculação carrega, de modo que um conjunto de políticas pode distribuir suas regras entre pacotes, e cada um contribui com o que coletou. O outro lado disso vale a pena conhecer antes que cause problemas: dentro de uma vinculação, a chave de decisão é um nome de regra reservado em todo pacote, de modo que um pacote auxiliar que por acaso coleta em labels para os próprios fins tem suas entradas lidas como decisões de rótulos. Isso falha de forma explícita, e não silenciosamente — a vinculação relata que algo coletado sob a chave não é uma decisão daquela forma —, mas a maneira mais rápida de ler uma mensagem dessas é como uma colisão de nomes; portanto, reserve a chave para a decisão e dê a uma regra auxiliar um nome diferente.

O que o payload de cada papel expõe

O payload é o documento input da política, de modo que uma política o lê pelos nomes que o formato de transmissão lhe dá.

O grafo de build fica em um caminho diferente nos dois papéis que carregam um. Um veredito sobre o grafo recebe o documento inteiro do grafo, então seus nós ficam em input.graph.spec.nodes; o papel que molda rótulos recebe uma projeção dos nós, então seus nós ficam em input.graph.nodes. Uma regra movida entre esses dois papéis é, portanto, editada, não copiada — e o sintoma de esquecer isso é uma regra que nunca dispara, em vez de um erro, porque um caminho que não existe é simplesmente indefinido.

PapelO que uma política lê
ir-verdictinput.graph — o documento inteiro do grafo de build: nós em input.graph.spec.nodes, indexados por id de nó, arestas em input.graph.spec.edges. Um valor que um autor declarou sensível é lido como {"aggrega_withheld": "declared"}. input.precalculated_paths — os caminhos de roteamento enumerados, cada um com sua lista ordenada nodes e attached_features, os tipos de Feature vinculados em qualquer ponto dele (veja abaixo). A lista está sempre presente: um build sem nenhuma rota entre componentes carrega uma lista vazia.
render-verdictinput.artifacts — uma entrada por arquivo emitido, cada uma com path, content, format e documents, os documentos analisados do arquivo. format é o formato que o provedor que renderizou o arquivo declarou para ele — o provedor Terraform declara hcl para cada arquivo .tf que emite e json para cada arquivo .tf.json, incluindo os arquivos de um módulo vendorizado — e a string vazia onde nenhum provedor declarou um, como para um arquivo com que uma Recipe contribui para a saída compartilhada de uma fronteira. Esse arquivo ainda é analisado pela extensão, de modo que seus documents estão lá de qualquer forma. Um artefato que não pôde ser lido de forma estruturada carrega parse_error e nenhum documento, para que uma política possa rejeitar com base na própria falha em vez de deixar passar sem exame um arquivo ilegível.
label-transforminput.graph.nodes — os nós do build indexados por id de nó, cada um com component, resolved_version, labels e values: os valores que a instância do nó declara no Aggregate, com seus templates avaliados em relação aos seus parâmetros, ausente quando ela não declara nenhum. Um valor que o Component do nó declara sensível é lido como {"aggrega_withheld": "declared"}, assim como em ir-verdict, e seus irmãos não declarados são lidos como foram escritos. Uma regra lê input.graph.nodes[id].values para decidir um rótulo; ela não pode alterar um valor. input.compilation_context — o release_name e o environment da Release, para que uma política possa decidir de forma diferente por ambiente.
annotation-transforminput.targets — cada componente que a vinculação pode anotar, cada um com boundary_path, component_name — para um componente que uma entrada de roteamento posiciona, seu id no grafo de build, como metrics.query — e as annotations que a Release escreve no próprio componente, cada valor como foi escrito: uma string, um objeto de subchaves ou null onde o componente abre mão de uma anotação que herdaria. Toda chave que o componente carrega está presente, seja qual for seu valor, de modo que uma regra pode deixar em paz uma chave que alguém já escreveu. input.binding_keys — as chaves de anotação para as quais o Manifest registra um binding.

Um recurso do Terraform é lido em um caminho diferente em cada uma das duas formas do Terraform. Nos documents de um arquivo .tf nativo, um bloco é aninhado sob seu tipo e depois sob cada um de seus rótulos, e o último rótulo contém uma lista de blocos, porque blocos que compartilham um tipo e rótulos são coletados em uma única lista na ordem do código-fonte. Um atributo de recurso é, portanto, lido em input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — para uma instância RDS de qualquer nome, input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Um arquivo .tf.json é lido como a Recipe o escreveu, de modo que sua forma de objeto convencional, em que o nome contém o próprio bloco, é lida em resource.<type>.<name>.<attr>, e uma política pensada para ambas as formas lê ambos os caminhos. Isso vale para os dois mecanismos de políticas dentro do compilador. Uma regra Rego escrita para a outra forma encontra indefinido o caminho que nomeia: uma regra que testa um valor ali nunca dispara, e uma que recusa diante de um valor ausente, com not, dispara em todo recurso; uma expressão CEL que indexa ou seleciona na outra forma interrompe o build com uma falha de avaliação que nomeia seu arquivo de política. O adaptador de renderização Rego de referência, descrito em Adaptadores de políticas para a etapa de renderização abaixo, analisa ele mesmo um arquivo .tf nativo e lê um único bloco como um objeto, de modo que um caminho do Terraform é editado, não copiado, quando uma política passa entre esse adaptador e um mecanismo dentro do compilador.

Todo papel carrega ainda input.sources — os arquivos próprios da vinculação, cada um com seu nome base como path e seu content. Uma política só é executada como um desses arquivos, de modo que, onde quer que uma regra leia a lista, ela contém pelo menos esse arquivo.

input.settings é o objeto de configurações da vinculação, o mesmo objeto que o documento data da política, e está presente quando a vinculação declara configurações. Quando a vinculação não declara nenhuma, o que uma regra encontra depende do papel: em ir-verdict, label-transform e annotation-transform o campo está ausente, de modo que input.settings é indefinido como qualquer caminho que o payload não carrega, e em render-verdict ele é o objeto vazio. Assim, uma regra que depende de uma configuração ter sido definida testa a configuração que lê em vez do objeto, o que se comporta da mesma forma em todo papel — um max_nodes configurado é lido, e um não configurado deixa input.settings.max_nodes indefinido e a regra em silêncio:

package example
import rego.v1
deny contains msg if {
limit := input.settings.max_nodes
count(input.graph.spec.nodes) > limit
msg := sprintf("this build declares more than %v nodes", [limit])
}

O mecanismo CEL trata de forma diferente um objeto de configurações não declarado e explica isso em sua própria seção mais abaixo.

attached_features e binding_keys são listas, e não objetos, de modo que uma política testa a pertinência com in:

package security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some gateway in path.nodes
input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"]
not "core/data-masking" in path.attached_features
msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])
}

attached_features é a união dos tipos de Feature de toda vinculação mantida por qualquer nó do caminho — incluindo uma vinculação escrita em uma das conexões desse nó, seja qual for a conexão em que foi escrita —, de modo que a regra é satisfeita por uma vinculação core/data-masking no próprio gateway, que é onde essa Feature se vincula: ela seleciona pela capacidade de mascaramento de conteúdo que o gateway declara. O que a vinculação mascara é o texto de chat e de completion que passa por esse gateway; a regra verifica que a vinculação existe, não o que ela lista.

Como é uma união sobre o caminho inteiro, a lista diz que uma Feature está vinculada em algum lugar de uma rota, e nunca onde. Uma regra que precisa saber se uma Feature fica entre dois componentes específicos de uma rota — o que mantém dados restritos e o que ele alcança — lê em ordem os nodes da rota e as vinculações próprias de cada nó, em input.graph.spec.feature_values_mapping[<node>]; feita a attached_features, a mesma pergunta deixa passar uma rota em que a Feature fica além do segundo componente. ../examples/policy-data-class-route/ é escrito dessa forma, para o mecanismo Rego, o mecanismo CEL e o OPA.

Um objeto de nó não carrega id próprio: o id é a chave sob a qual ele está em input.graph.spec.nodes, e é por isso que a regra acima leva para sua mensagem os ids que leu de path.nodes em vez de ler um campo id.

A ordem em que uma política encontra as chaves de um mapa

O grafo mantém a ordem que seu autor escreveu: os nós na ordem em que os componentes foram declarados, e os rótulos de cada nó na ordem em que o nó os carrega. Essa ordem chega intacta ao guest — o payload carrega ambos como entradas ordenadas (veja mapas que mantêm sua ordem). Se uma política a encontra ou não é decidido pela forma como o mecanismo que avalia a política guarda um objeto, não pelo payload:

  • O mecanismo Rego guarda as chaves de um objeto ordenadas. Uma regra que itera sobre input.graph.spec.nodes, sobre os labels de um nó ou sobre qualquer outro objeto — incluindo um escrito na própria política — encontra as chaves ordenadas: componentes declarados web, api, metrics são encontrados como api, metrics, web.
  • O mecanismo CEL não fixa nenhuma ordem para um mapa. Uma compreensão sobre input.graph.spec.nodes ou sobre os labels de um nó pode encontrar as chaves em uma ordem diferente em dois builds com entrada idêntica, e dois percursos do mesmo mapa dentro de uma mesma expressão podem diferir um do outro. É por isso que as mensagens sob uma mesma chave de decisão são ordenadas: escreva uma regra cuja decisão não dependa da posição em que uma chave está.
  • Um guest escrito com um kit de plugins encontra a ordem do autor. Decodificados por meio do seu kit, os nós e os rótulos de cada nó chegam ao contêiner do kit que mantém a ordem, na ordem em que o payload os carrega, e o esqueleto de adaptador de governança que cada kit fornece entrega ao seu mecanismo um documento JSON escrito nessa mesma ordem. Um mecanismo que converte esse documento em um tipo de valor próprio encontra, em vez disso, a ordem desse tipo, como descreve mapas que mantêm sua ordem.

Moldar rótulos: uma política nomeia o rótulo, e o mecanismo o endereça

No papel que molda rótulos, uma política coleta uma decisão por rótulo sob labels, nomeando o nó, a chave do rótulo e o valor que o rótulo assume:

package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

Definir uma chave que já está presente substitui o seu valor. Uma decisão pode, em vez disso, pedir que uma chave seja removida:

labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if {
some id, node in input.graph.nodes
node.labels["draft.example.com/scratch"]
}

Uma política nomeia o rótulo em vez de escrever a instrução de edição que o build aplica, e vale a pena conhecer o motivo: a instrução endereça um rótulo por caminho, e uma chave de rótulo do Aggrega rotineiramente contém uma /, que é o separador de caminho — de modo que um caminho escrito à mão endereçaria uma posição aninhada em vez de um único rótulo. O mecanismo endereça o rótulo que a decisão nomeia, de modo que o escape é escrito uma vez em vez de em cada política, e uma política continua legível como uma afirmação sobre rótulos, e não sobre caminhos.

Uma decisão só pode alterar um rótulo. Cada instrução que o mecanismo emite endereça um rótulo em um nó, de modo que uma política não tem como expressar uma alteração no Component de um nó, na sua versão resolvida, no conjunto de nós ou em um valor de rótulo que não seja uma string. Uma decisão que nomeia um nó que o build não tem, ou que remove um rótulo que o nó não carrega, é recusada pelo build com uma mensagem que nomeia a instrução — nunca ignorada silenciosamente.

../examples/policy-label-transform/ vincula uma política desse tipo ao lado dos dois plugins de etiquetagem integrados, além de um veredito sobre o grafo que lê os rótulos que eles escrevem. O que cada um desses plugins lê e escreve está em Os plugins de etiquetagem integrados.

Injetar anotações

No papel que injeta anotações, uma política coleta uma decisão por anotação sob annotations, nomeando o destino pela coordenada que o próprio destino carrega, mais a chave e o seu valor:

package tagging
import rego.v1
annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
} if {
some target in input.targets
not target.annotations["backup.example.com/schedule"]
}

Os nomes de campo que uma decisão escreve são os nomes de campo sob os quais ela leu seus destinos, de modo que a convenção pode ser aprendida apenas pelo payload. Ler input.binding_keys permite a uma política injetar apenas chaves para as quais o Manifest registrou um significado — são elas que se expandem em uma vinculação de Feature.

O valor de uma decisão é um que você mesmo poderia escrever nessa anotação: uma string, ou um objeto de subchaves. Um binding que roteia uma subchave recebe uma string; um binding que roteia várias recebe um objeto que nomeia cada uma delas, exatamente como um operador o escreve na Release:

annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "feature.aggrega.ai/monitoring",
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
some target in input.targets
not target.annotations["feature.aggrega.ai/monitoring"]
}

O build lê um valor injetado exatamente como lê o mesmo valor escrito na Release, de modo que ele se expande da mesma forma e é verificado da mesma forma em relação à Feature do binding. O mecanismo guarda as chaves de um objeto ordenadas, de modo que as subchaves chegam ao build em ordem. Um valor de qualquer outra forma — null, uma lista, um número, um booleano ou um objeto sem subchaves — é recusado pelo build, que nomeia a injeção: o papel adiciona anotações, e null ou um objeto vazio é lido como a exclusão que um autor escreve para remover uma. Uma decisão que nomeia um componente que o payload não carrega é recusada da mesma forma, nomeando a coordenada e a anotação.

Quando o build recusa uma anotação injetada pela forma como ela é roteada ou pelo que ela carrega — uma string passada a um binding que roteia várias subchaves, um valor de subchave que o esquema da Feature do binding não admite, ou uma subchave roteada pelo pilar values, que uma anotação do lado da Release não pode usar —, a recusa nomeia o plugin que a injetou e o papel de governança ao qual ele está vinculado, de modo que o valor é rastreado até a política que o decidiu, e não até uma linha da Release que ninguém escreveu.

../examples/policy-annotation-transform/ vincula uma política desse tipo, injetando uma string sob um binding e um objeto de subchaves sob outro, e faz o build dos mesmos arquivos que uma Release que escreve essas anotações à mão.

Vincular um conjunto inteiro de políticas como um único arquivo compactado

Um conjunto de políticas é vinculado arquivo por arquivo, ou como um único arquivo compactado que carrega juntos seus arquivos de políticas e seus documentos de dados — a forma que uma toolchain Rego constrói. O conteúdo de um arquivo vinculado viaja até o guest como texto, e um arquivo compactado é composto de bytes arbitrários em vez de texto, de modo que um arquivo compactado é vinculado codificado em base64, com um nome que termina em .base64:

Terminal window
tar czf bundle.tar.gz policy.rego data.json
base64 -w0 bundle.tar.gz > bundle.tar.gz.base64
with:
sources:
- ./policies/bundle.tar.gz.base64

O nome é o que marca um arquivo como arquivo compactado em vez de como texto de política, o que mantém a escolha como uma declaração explícita do próprio operador: um arquivo compactado danificado é então relatado como um arquivo compactado danificado, nomeando o arquivo e a etapa que falhou, em vez de ser lido como um arquivo de política que não pode ser analisado. Codificar o arquivo compactado é uma etapa que o operador adiciona depois que sua toolchain o constrói.

Dentro do arquivo compactado, cada membro .rego é um módulo de política e cada membro data.json ou data.yaml é um documento de dados aninhado sob o diretório em que está — um limits/data.json contendo {"max": 3} é lido por uma política como data.limits.max. Membros de qualquer outro tipo são carregados pelo arquivo compactado para a sua própria toolchain e não são entrada de política.

Um arquivo compactado que não pode ser aberto é uma falha que nomeia o arquivo vinculado: uma codificação que não se decodifica, um fluxo que não se descompacta, um arquivo compactado truncado, um arquivo de dados que não pode ser lido ou um arquivo compactado sem nenhuma política. Nenhum deles produz um conjunto de políticas vazio, porque um conjunto de políticas vazio não alcança nenhuma decisão — e “o arquivo compactado estava ilegível” nunca deve ser indistinguível de “a política permitiu o build”.

Escrever uma política para o mecanismo CEL

O mecanismo avalia CEL escrito pelo operador inteiramente dentro do guest, em qualquer um dos quatro papéis ao qual esteja vinculado. Sua identidade no catálogo é o nome simples cel sob pluginType: governance — a coordenada governance/cel — e sua versão é a release do compilador que o inclui. Vinculá-lo duas vezes, em dois papéis, com dois arquivos de política diferentes, é a forma como um único mecanismo cobre dois momentos do mesmo build.

plugins:
governance:
- uri: governance/cel:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.cel
settings:
max_nodes: 20

Uma política acessa todo o payload por meio de um único nome, input, de modo que os nomes que ela lê são os nomes que o formato de transmissão lhes dá: o grafo de build em input.graph, os caminhos de roteamento enumerados em input.precalculated_paths, os arquivos renderizados em input.artifacts, os destinos de anotação em input.targets. Esses caminhos por papel são os tabulados em O que o payload de cada papel expõe acima, e são idênticos para os dois mecanismos — um único formato de transmissão, lido sob um único nome raiz.

Os próprios arquivos da vinculação estão em input.sources e suas configurações em input.settings, de modo que um limite fornecido pelo operador é lido como input.settings.max_nodes. Não há um segundo documento a aprender: as configurações fazem parte de input como todo o resto. Ambos estão sempre presentes como valor — as configurações são o objeto vazio em todos os papéis quando a vinculação não declara nenhuma —, de modo que uma expressão que os acessa não precisa se proteger contra a sua ausência, e saber se uma determinada configuração foi definida é um teste sobre a sua chave: has(input.settings.max_nodes).

As duas formas de escrita, e o nome de arquivo que escolhe entre elas

Uma política é vinculada em uma de duas formas, e o nome do arquivo diz qual:

O nome do arquivo termina emLido como
.celuma expressão, avaliada como está
.yaml ou .ymlum documento de regras — uma lista de regras
qualquer outra coisauma expressão

O nome é a regra inteira. Nenhuma configuração seleciona uma forma, e o texto do arquivo não é examinado para adivinhar uma — ele não poderia responder à pergunta de qualquer forma, porque o valor mais externo de uma expressão é um mapa, assim como o de um documento de regras, o que torna as duas formas indistinguíveis pela estrutura.

Então a regra vale nos dois sentidos, e ambos os erros são recusados em vez de mal interpretados. Um documento de regras chamado policy.cel é recusado, porque uma lista de regras YAML não é uma expressão; uma expressão chamada policy.yaml é recusada, porque uma expressão não é uma lista de regras. Cada recusa nomeia o arquivo. Renomear o arquivo é a correção nas duas direções.

Um conjunto de políticas tem quantos arquivos precisar, e as duas formas se misturam livremente dentro de uma mesma vinculação.

Uma expressão, em um arquivo chamado .cel

Uma linguagem de expressões não tem nomes de regras sob os quais coletar decisões, de modo que as decisões são o valor que a expressão produz: um mapa da chave de decisão para o que essa chave coleta. Em um papel de veredito, uma chave coleta as mensagens alcançadas sob ela; em um papel que molda o build, ela coleta as decisões a aplicar.

{
"deny": input.graph.spec.nodes
.filter(n, input.graph.spec.nodes[n].resolved_version == "latest")
.map(n, "component " + n + " tracks the latest version; pin it"),
"warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],
}

Uma chave que o arquivo omite não alcançou nenhuma decisão ali, de modo que um arquivo não precisa nomear todas as chaves — e cada papel lê apenas a chave que lhe diz respeito, de modo que um mesmo conjunto de políticas pode atender a um papel de veredito e a um papel que molda o build a partir dos mesmos arquivos. Uma chave carrega uma lista do que coleta, um único item, ou o valor null para nenhum.

Uma expressão avaliada como qualquer coisa diferente de um mapa é recusada, nomeando a forma a escrever. Um simples size(input.graph.spec.nodes) <= 5 é o erro a esperar: é um booleano, e ler false como uma interrupção significaria inventar uma mensagem que o autor nunca escreveu.

Um documento de regras, em um arquivo chamado .yaml ou .yml

Um documento de regras é uma lista de regras, cada uma nomeando a chave de decisão que alcança, a expressão que decide se ela é alcançada e o que é relatado quando é:

- key: deny
expression: size(input.graph.spec.nodes) > 20
message: this build declares a lot of components
- key: warn
expression: has(input.settings.max_nodes)
message: a component ceiling is configured for this environment

O que uma regra relata segue a chave de decisão que ela alcança, exatamente como em uma expressão. Texto é a mensagem que um veredito carrega. Um mapeamento são os campos da única decisão que um papel que molda o build lê:

- key: labels
expression: input.compilation_context.environment == "production"
message:
node: app
key: compliance.example.com/tier
value: gold

Qual dos dois uma regra escreve é decidido apenas pela regra — não há configuração que o selecione —, e uma regra que escreve o errado para a sua chave é recusada, pelo nome.

Um detalhe de YAML que vale a pena conhecer antes que ele cause problemas: uma expressão que começa com aspas duplas precisa ser colocada entre aspas para o leitor do documento, porque um valor que começa com " é lido como um escalar entre aspas, e não como um texto que começa com aspas.

- key: annotations
expression: '"backup.example.com/schedule" in input.binding_keys'
message:
boundary_path: main
component_name: app
annotation_key: backup.example.com/schedule
annotation_value: nightly

Um documento de regras é lido como a expressão que ele representa antes que qualquer coisa seja avaliada. Cada regra se torna a sua chave de decisão, carregando o que a regra relata quando a expressão é verdadeira e nada quando não é, e regras que compartilham uma chave são unidas. Assim, um único avaliador executa as duas formas, e um documento de regras decide exatamente o que a expressão que ele representa decide — em todos os papéis, tanto vereditos quanto decisões que moldam o build. Duas consequências decorrem disso. Um documento e a expressão escrita à mão que ele representa alcançam as mesmas decisões, porque são a mesma avaliação. E as regras de ordenação descritas abaixo são as da forma avaliada, e não as do documento — as regras de um documento não são relatadas na ordem em que foram escritas.

Qual forma usar — elas não são intercambiáveis

As duas formas passam por um único avaliador, de modo que nenhuma é mais rápida ou mais confiável que a outra. O que difere é o que cada uma consegue dizer, e como duas formas são duas coisas a aprender, vale a pena declarar a divisão com clareza em vez de deixá-la ao gosto de cada um. Escolha pelo que a regra relata.

  • Um documento de regras, quando o que é relatado é fixo. A mensagem ou a decisão é escrita uma vez, ao lado da expressão que a alcança, e o arquivo se lê como uma lista de guardas. Essa é a forma mais curta para “se isto for verdade, diga exatamente isto”.
  • Uma expressão, quando o que é relatado nomeia o que ela encontrou. Uma única expressão filtra os componentes de um build e produz uma mensagem — ou uma decisão — por componente, de modo que quem lê recebe component payments tracks the latest version; pin it para cada elemento infrator em vez de uma frase sobre uma contagem.

Essa segunda tarefa é a que um documento de regras não consegue fazer: cada uma das suas regras carrega um único relato, escrito antecipadamente, de modo que ela não tem nada a dizer sobre qual componente a disparou. Optar pela forma de documento e depois querer o nome do elemento infrator na mensagem é o caminho que termina com a reescrita da regra como uma expressão, então vale a pena escolher com base nessa pergunta desde o início.

O que uma expressão pode dizer

As expressões que esse mecanismo avalia usam as compreensões filter, map e exists, + em strings e em listas, size, in, startsWith, string(), o operador condicional e uma lista indexada por um inteiro calculado. Elas não oferecem as funções de extensão que alguns ambientes CEL acrescentam: join, split, substring, indexOf, flatten, cel.bind e lists.range são, cada uma, recusadas como referência não declarada, e uma compreensão recebe uma única variável, de modo que uma forma de duas variáveis como exists(i, v, …) é recusada da mesma forma. Uma recusa é uma falha de build que nomeia o arquivo e a referência:

policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'

Três consequências moldam uma regra que percorre uma rota:

  • Não há como nomear um valor intermediário. Uma subexpressão usada duas vezes é escrita duas vezes, ou ligada a um nome aplicando map a uma lista de um único item: [value].map(name, …)[0] avalia seu corpo uma vez com name ligado a value.
  • Não há como percorrer as posições de uma lista. Uma regra que compara por posição os componentes de uma rota obtém as posições das suas configurações — uma lista positions como [0, 1, 2, …] — e indexa a rota em cada uma delas, de modo que precisa se proteger contra uma rota mais longa que a própria lista, interrompendo o build diante de uma rota assim, em vez de lê-la em parte.
  • Uma chave de decisão coleta mensagens, não listas de mensagens. Uma expressão que produz uma lista de mensagens por rota é recusada sob uma chave de decisão — a falha diz que ela coletou um valor do tipo lista em vez de uma mensagem —, de modo que uma regra produz um registro por rota e constrói a mensagem a partir dele. E uma mensagem que a expressão produz duas vezes é relatada duas vezes: a ordenação descrita abaixo ordena o que uma chave coletou, e não remove uma repetição.

../examples/policy-data-class-route/ traz uma regra CEL escrita levando em conta as três, ao lado da mesma regra para o mecanismo Rego.

Chaves de decisão e severidades

As chaves de decisão, o mapeamento padrão para severidades e a configuração translation que as renomeia são os mesmos do mecanismo Rego — veja Uma política coleta suas decisões sob uma chave de decisão acima. Por padrão, deny é relatado como halt, warn como warn e audit como info; uma translation declarada substitui esse mapeamento padrão em vez de estendê-lo, e a ordem que ela declara é a ordem em que os vereditos são relatados.

Os dois mecanismos declaram o mesmo esquema de configurações para ela, de modo que um bloco translation significa a mesma coisa qualquer que seja a linguagem que expressa as decisões, e um malformado é recusado antes que qualquer política seja executada.

Em um papel que molda o build, a chave é fixa em vez de mapeada: labels no papel que molda rótulos, annotations no papel que injeta anotações.

Ordenação: ordenadas dentro de uma chave, e uma ordem total sobre as decisões

As mensagens sob uma mesma chave de decisão são relatadas em ordem. Isso faz parte do contrato, e não é uma escolha de apresentação, e vale a pena guardar o motivo: uma compreensão sobre um mapa — .filter(...) e .map(...) sobre input.graph.spec.nodes, que é a forma mais natural de escrever uma regra por componente — percorre esse mapa em uma ordem que o avaliador não fixa. Sem isso, uma entrada idêntica relataria as mesmas mensagens em uma sequência diferente a cada build. A ordenação elimina isso.

Daí decorrem duas coisas que é fácil tomar por bugs e que não são:

  • As regras de um documento de regras também são relatadas ordenadas, e não na ordem em que foram escritas — porque o documento é avaliado como a expressão que ele representa, e a ordenação se aplica ao que uma chave coletou.
  • Uma lista escrita à mão também é ordenada. Uma chave que carrega ["second", "first"] relata first antes de second. Nada em um resultado avaliado distingue uma lista que o autor digitou de uma produzida por uma compreensão, de modo que não há ordem do autor a preservar.

Entre chaves, a ordem é a ordem declarada em translation. Entre arquivos, é a ordem dos nomes de arquivo, porque as fontes de uma vinculação chegam ordenadas por nome, e não na ordem em que a vinculação as lista.

Em um papel que molda o build, o mesmo raciocínio se aplica às próprias decisões, e a ordem é mais forte: as decisões são relatadas em ordem crescente de tudo o que nomeiam, o que é uma ordem total sobre o que uma decisão pode expressar — o nó, depois a chave do rótulo, depois se o rótulo é adicionado ou removido, depois o valor; e, para uma injeção, a fronteira, depois o componente, depois a chave da anotação, depois o seu valor. Uma alteração em rótulos ou anotações chega à saída renderizada, de modo que uma ordem arbitrária significaria uma entrada idêntica renderizada de forma diferente de um build para o seguinte.

Moldar rótulos

No papel que molda rótulos, uma política coleta uma decisão por rótulo sob labels, nomeando o nó, a chave do rótulo e o valor que o rótulo assume:

{
"labels": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server")
.map(n, {
"node": n,
"key": "compliance.example.com/tier",
"value": input.compilation_context.environment == "production" ? "gold" : "bronze",
}),
}

Definir uma chave que já está presente substitui o seu valor. Uma decisão pode, em vez disso, pedir que uma chave seja removida, indicando op como remove:

{
"labels": input.graph.nodes
.filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels)
.map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),
}

Uma única decisão não precisa de uma lista em volta, e um arquivo que não nomeia nenhuma chave labels não decide nenhum rótulo.

Uma política nomeia o rótulo em vez de escrever a instrução de edição que o build aplica, pelo motivo dado na seção sobre moldar rótulos do mecanismo Rego: uma chave de rótulo do Aggrega rotineiramente contém uma /, e um caminho escrito à mão endereçaria uma posição aninhada em vez de um único rótulo. O mecanismo endereça o rótulo que a decisão nomeia.

Ler um rótulo que um nó pode não carregar é uma falha, e não um valor vazio, e é por isso que o segundo exemplo pergunta se a chave está presente antes de lê-la. Essa é a regra da própria linguagem de expressões sobre a leitura de uma chave ausente, e ela se manifesta de forma explícita: uma política que busca um rótulo que nenhum nó carrega relata que não pôde ser avaliada, em vez de silenciosamente não decidir nada.

Uma decisão só pode alterar um rótulo. Uma decisão que nomeia um nó que o build não tem, ou que remove um rótulo que o nó não carrega, é recusada pelo build com uma mensagem que nomeia a instrução — nunca ignorada silenciosamente.

Alcance uma única decisão por nó e chave de rótulo. Uma regra que pode produzir dois valores diferentes para o mesmo rótulo no mesmo nó está subespecificada: resolva o valor dentro da expressão — com uma condicional, ou com um filtro que admita um único ramo — em vez de emitir as duas decisões.

../examples/policy-label-transform/ mostra de ponta a ponta o papel que molda rótulos, com sua política escrita para o mecanismo Rego.

Injetar anotações sob uma chave registrada

No papel que injeta anotações, uma política coleta uma decisão por anotação sob annotations, nomeando o destino pela coordenada que o próprio destino carrega, mais a chave e o seu valor:

{
"annotations": input.targets
.filter(t, "backup.example.com/schedule" in input.binding_keys)
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
}),
}

Os nomes de campo que uma decisão escreve são os nomes de campo sob os quais ela leu seus destinos, de modo que a convenção pode ser aprendida apenas pelo payload. Ler input.binding_keys permite a uma política injetar apenas chaves para as quais o Manifest registrou um significado — são elas que se expandem em uma vinculação de Feature. Todo campo é obrigatório: uma anotação com uma chave vazia ou um nome de componente vazio não é algo que uma política pretendia pedir. A fronteira sob a qual um componente está pode legitimamente ser nomeada pela string vazia, de modo que esse campo deve estar presente, mas pode estar vazio.

O valor é um que você mesmo poderia escrever nessa anotação: uma string, ou um mapa de subchaves, que é o que alimenta um binding que roteia várias subchaves de uma vez — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. O mecanismo escreve as subchaves de um mapa em ordem, já que a linguagem de expressões não fixa nenhuma ordem para um mapa, e repassa o valor como a expressão o produziu; um valor que o modelo JSON não consegue conter — bytes, um timestamp, uma duração — é recusado em vez de convertido em texto. O build então lê o valor exatamente como lê o mesmo valor escrito na Release, e recusa null, uma lista, um número, um booleano ou um mapa vazio, nomeando a injeção. Duas decisões para um mesmo componente e uma mesma chave com valores diferentes são ordenadas pelo JSON do valor. As annotations de um destino carregam cada valor existente como foi escrito — uma string, um mapa, ou null para uma exclusão —, de modo que testar "feature.aggrega.ai/monitoring" in t.annotations encontra uma chave qualquer que seja o seu valor.

Uma decisão que nomeia um componente que o payload não carrega é recusada pelo build, nomeando a coordenada e a anotação. Quando o build recusa uma anotação injetada pelo seu roteamento, pelos valores das suas subchaves ou pelo seu pilar, a recusa nomeia o plugin que a injetou e o papel ao qual ele está vinculado. Assim como com rótulos, alcance uma única decisão por componente e chave de anotação, resolvendo o valor dentro da expressão em vez de emitir duas decisões para uma mesma chave.

../examples/policy-annotation-transform/ mostra de ponta a ponta o papel que injeta anotações, com sua política escrita para os dois mecanismos.

Quando uma política ou uma decisão não pode ser lida

Uma política que o mecanismo não consegue ler, não consegue avaliar, ou que produz algo diferente de decisões na forma documentada faz o build falhar em vez de retornar um veredito ou uma alteração. A falha é relatada como uma falha de build que nomeia o arquivo e, quando a falha pertence a uma parte do arquivo, a posição dentro dele — deliberadamente distinta de um veredito halt, para que “não foi possível avaliar esta política” nunca seja confundido com “esta política permite o build”.

Para uma expressão, isso abrange uma fonte que não pode ser analisada — relatada com a linha e a coluna do próprio analisador e um caret sob a posição problemática — e uma fonte avaliada como algo diferente de um mapa da chave de decisão para o que essa chave coleta.

Para um documento de regras, abrange um texto que não é uma lista de regras, uma lista sem nenhuma regra, uma regra sem um campo ou com um campo vazio, um campo que a forma não define, um relato que não é nem texto nem um mapeamento de texto para texto, e uma expressão que não pode ser lida. Uma falha que pertence a uma regra nomeia a posição dessa regra — contada a partir de um, como um autor conta o próprio arquivo — e a sua chave de decisão. Uma regra cuja expressão não pode ser analisada é recusada antes da avaliação, de modo que o caret cai dentro da expressão que o autor escreveu, e não em uma posição de um texto traduzido que ele nunca viu.

Para uma decisão em um papel que molda o build, abrange uma mensagem onde cabe uma decisão, uma coordenada ausente e um campo que a forma de decisão desse mecanismo não define. Este último merece ser destacado: um annotation_valu com erro de digitação é recusado, não ignorado, de modo que o erro é relatado em vez de injetar silenciosamente um valor vazio e deixar um build que é concluído sem a alteração. Toda recusa desse tipo nomeia o arquivo e termina nomeando o que uma decisão daquele tipo deve nomear.

Adaptadores de políticas para a etapa de renderização

Um adaptador para a etapa de renderização raciocina sobre a saída renderizada do build em vez do seu grafo IR. O payload de renderização carrega os artefatos emitidos — cada um com seu caminho de saída e seu conteúdo renderizado e, quando se aplicam, o formato em que foi renderizado e uma visão estruturada e analisada dele — além das fontes e das configurações próprias da vinculação, cada uma onde a vinculação a declara. Um adaptador lê esse conteúdo para a forma de saída que tem como alvo, avalia uma política sobre o resultado estruturado e mapeia o desfecho para vereditos halt / warn / info. Como o payload não nomeia nenhuma forma de saída própria, um único padrão de adaptador atende a qualquer destino de renderização; uma nova forma de saída é um novo adaptador, não uma alteração no host.

Cada adaptador para a etapa de renderização é um adaptador no sentido descrito acima: fala a ABI do Aggrega para fora e absorve para dentro um formato específico do destino ou o contrato de um mecanismo de políticas externo, de modo que o compilador permanece livre de qualquer lógica de formato de saída ou de política. Os mecanismos Rego e CEL do compilador atendem diretamente ao papel render-verdict; além deles, dois adaptadores de referência para a etapa de renderização vêm como exemplos completos entre os exemplos em Rust do kit de desenvolvimento de plugins, um para cada forma de saída comum.

../examples/policy-render-verdict/ vincula uma regra em render-verdict sobre a saída de quatro destinos — objetos Kubernetes, um arquivo Docker Compose, uma configuração raiz do Terraform e um template do CloudFormation —, escrita uma vez para cada mecanismo do compilador, e verifica que a violação plantada em cada destino interrompe o build e que o seu caso de controle passa.

Para escrever um adaptador próprio, nesse papel ou em qualquer outro, comece pelo esqueleto de adaptador de governança que cada kit de desenvolvimento de plugins fornece: Escrever seu próprio plugin de governança o percorre do esqueleto até um build que ele recusa.

Saída YAML, JSON e HCL do Terraform — o adaptador de renderização Rego de referência

O adaptador de renderização Rego de referência executa Rego fornecido pelo operador sobre qualquer saída de renderização YAML ou JSON, e sobre a saída HCL nativa do Terraform. É um exemplo completo da forma da etapa de renderização: o mesmo avaliador Rego nativo de Wasm do mecanismo no compilador, e a mesma convenção de coleta deny / warn / audit mapeada para as mesmas três severidades de veredito, raciocinando sobre arquivos renderizados em vez do grafo de build.

Ele é independente da forma de saída entre destinos YAML/JSON. O adaptador analisa o conteúdo de cada artefato como um ou mais documentos YAML ou JSON — YAML é um superconjunto de JSON, de modo que um template JSON como uma stack do CloudFormation é analisado pelo mesmo analisador — e expõe à política os documentos analisados junto com o conteúdo bruto. Uma política raciocina sobre a saída de renderização estruturada de qualquer destino desse tipo com Rego comum: input.artifacts[_].documents[_] produz os documentos analisados (os services de um arquivo Docker Compose, os Resources de um template do CloudFormation), input.artifacts[_].content produz o texto bruto, e o objeto settings da vinculação é o documento data do Rego. Uma política que exige um registro aprovado sobre a saída Docker Compose, por exemplo, nega qualquer serviço cuja imagem não carregue nenhum prefixo de registro.

O adaptador também raciocina sobre a saída de renderização em HCL nativo do Terraform. Um arquivo .tf nativo não é nem YAML nem JSON, então o adaptador o projeta no mesmo objeto canônico em que um arquivo Terraform-JSON (.tf.json) já é analisado: uma política lê um atributo de recurso em input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — para uma instância RDS, input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — da mesma forma, qualquer que seja a forma do Terraform que o compilador emitiu. Os tipos de atributo são preservados (um número continua sendo um número, um booleano um booleano), e uma expressão do Terraform não resolvida continua sendo uma string na sua forma ${ ... }. Conteúdos Terraform-JSON (.tf.json, .auto.tfvars.json) são analisados pelo caminho YAML/JSON sem alteração, e um arquivo de template do Terraform (.tftpl) — texto de template em vez de configuração autônoma — não é projetado e expõe parse_error como qualquer conteúdo não estruturado.

Essa lista diz o que o analisador do adaptador aceita, não o que o compilador emite. Os dois não são o mesmo conjunto, e um arquivo de variáveis carregado automaticamente é o caso em que eles diferem: o compilador não emite tal sobreposição em nenhum caminho — as entradas de um módulo referenciado são os argumentos do bloco de módulo daquele componente na configuração raiz da fronteira —, de modo que essa forma só chega à visão de uma política quando um módulo vendorizado traz um próprio, que o caminho dos módulos referenciados copia literalmente para a saída. Uma política escrita esperando que o compilador produza um nunca disparará.

Quando o conteúdo de um artefato não pode ser analisado, o adaptador não o deixa passar silenciosamente: ele mantém o conteúdo bruto, não expõe nenhum documento analisado para esse artefato e registra a mensagem do analisador em input.artifacts[_].parse_error, de modo que uma política pode interromper explicitamente o build diante de um artefato malformado. Assim como no mecanismo Rego do compilador, uma política que chama uma função integrada que o avaliador embutido não implementa falha de forma explícita — uma falha que nomeia o plugin, nunca uma permissão silenciosa.

Saída Kubernetes — o adaptador de renderização Kubewarden

O adaptador de renderização Kubewarden executa políticas de admissão no estilo Kubewarden sobre manifestos Kubernetes renderizados. Ele absorve para dentro o contrato de admission review do Kubernetes: uma política Kubewarden recebe uma requisição que envolve um único objeto e retorna uma resposta de aceitação ou rejeição. Na etapa de renderização, a saída do build já é um conjunto de recursos Kubernetes, o que torna essa etapa o lugar natural para executar uma política em forma de admissão. Para cada objeto renderizado, o adaptador deriva os campos de admissão do próprio objeto analisado, envolve o objeto em uma requisição em forma de admission review dentro do guest, executa a política e mapeia a resposta para um veredito: uma rejeição se torna um veredito; uma aceitação não emite nada. A política de referência incluída é uma regra que exige um rótulo — todo objeto deve carregar uma chave de rótulo nomeada por settings —, um padrão comum do Kubewarden.

Escopo comum aos adaptadores para a etapa de renderização

  • Etapa de renderização, uma forma de saída por adaptador. Um adaptador para a etapa de renderização raciocina sobre artefatos renderizados, não sobre o grafo IR, e tem como alvo a forma de saída que analisa — YAML/JSON e HCL nativo do Terraform para o adaptador de renderização Rego de referência, objetos Kubernetes para o adaptador Kubewarden. Uma política para a etapa do grafo, ou uma política sobre uma forma de saída que nenhum adaptador fornecido analisa, é um guest diferente.
  • Somente validação. Um adaptador para a etapa de renderização aceita ou rejeita; nunca retorna um objeto modificado. O objeto modificado de uma política de mutação é ignorado — o compilador nunca reescreve a saída renderizada a partir de um veredito de política. Uma política decide; ela não edita.

Vincular uma política

Um operador vincula um plugin de governança por meio da lista plugins.governance na configuração do espaço de trabalho (.aggrega-config.yaml). Cada entrada nomeia um plugin, o role em que ele é vinculado e, opcionalmente, o canal with que fornece suas regras e seus parâmetros ajustáveis:

plugins:
governance:
- uri: <resolvable-plugin-reference>
role: ir-verdict
with:
sources:
- ./policies/replicas.rego
settings:
max_replicas: 3

O uri é resolvido para o plugin. O host lê cada arquivo de sources no momento do build e entrega seus bytes ao guest, e repassa settings sem alteração. Um build sem nenhum plugin de governança vinculado executa o socket como uma operação nula, então a vinculação é puramente aditiva para um espaço de trabalho.

Um plugin que atende a vários papéis é vinculado uma vez por papel, cada vinculação com suas próprias regras e suas próprias configurações:

plugins:
governance:
- uri: governance/rego:<version>
role: label-transform
with:
sources:
- ./policies/tagging.rego
- uri: governance/rego:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.rego
settings:
translation:
- key: blocked
severity: halt

Qual versão uma vinculação nomeia. Um uri nomeia uma entidade Plugin — a coordenada <pluginType>/<name> e, após os dois-pontos, uma versão — e a versão participa da resolução. Para os dois mecanismos compilados na CLI, a entidade vem de um de dois lugares. Cada release do compilador publica as entidades Plugin de governance/rego e governance/cel na sua própria versão, e o catálogo da biblioteca padrão as contém, cada uma na versão da release que a publicou; um espaço de trabalho as lê dos diretórios de catálogo que lista. O binário aggrega contém uma entidade de cada um, na versão da sua própria release e em nenhuma outra. Uma vinculação que nomeia uma versão que nenhum dos dois contém, e que nenhum pull buscou para o cache de conteúdo, interrompe o build com E0137, nomeando a referência.

Assim, uma vinculação nomeia uma versão que o catálogo lido pelo espaço de trabalho contém. Essa versão é resolvida a partir do catálogo também sob uma release do aggrega diferente da sua, enquanto uma versão que só o binário contém — a da sua própria release — é resolvida apenas com essa release, tanto em um papel de veredito quanto em um papel de transformação. Em um papel de transformação, o pull fixa no arquivo de bloqueio a versão que resolveu e recusa com E0103 uma versão que não está contida nem em um catálogo lido pelo espaço de trabalho nem no binário. A versão seleciona a entidade Plugin, que registra os exports e os limites de execução do plugin, e não o mecanismo: uma vez resolvida a referência, o mecanismo que é executado é o compilado no binário que executa o build, porque os plugins integrados ao binário são o primeiro lugar de onde o módulo de um plugin é lido. Um plugin de governança que o próprio espaço de trabalho declara — uma entidade Plugin no seu próprio diretório de catálogo, com seu .wasm ao lado — é nomeado na versão que essa entidade registra.

Cada papel seleciona uma função de entrada padrão — verdict_ir para o papel que julga o grafo, verdict_render para o papel que julga os artefatos renderizados, mutate para o papel que molda rótulos, transform_annotations para o papel que injeta anotações — e uma vinculação pode apontar um papel para outro export com function:. O host recusa um envio para um export que o guest não declarou em seu autorrelato describe(), então uma vinculação que nomeia um papel que seu guest não atende é relatada pelo nome, antes de o guest ser executado, em vez de silenciosamente não fazer nada.

function: nomeia um export no plugin que o uri nomeia. Uma vinculação em um papel de veredito — ir-verdict ou render-verdict — que nomeia uma function: e nenhum uri: nomeia uma função em nenhum plugin, então a configuração é recusada já na leitura, sob E0224, nomeando o arquivo e a posição da entrada na sua lista: adicione o uri do plugin que exporta a função.

A lista plugins.governance tem uma contraparte aditiva, plugins.governance_append: as entradas da contraparte são concatenadas à lista governance resolvida em cada camada de configuração, então um espaço de trabalho ou uma configuração global compõe vinculações de políticas em vez de ocultar uma lista base.

A sobreposição de propriedade da CI

Ao lado do .aggrega-config.yaml escrito à mão, um pipeline automatizado pode ser dono de um arquivo de sobreposição separado, .aggrega-config-append-ci.yaml. Ele existe para que um pipeline possa vincular políticas (ou outra configuração com valores de lista) que controla sem nunca editar a configuração base escrita à mão pelo desenvolvedor — o pipeline pode sobrescrever inteiramente o seu próprio arquivo de sobreposição.

A sobreposição é estritamente aditiva. Ela é validada com o mesmo esquema de configuração que o arquivo base, e para cada campo com valores de lista suas entradas são concatenadas à lista resolvida. Ela só pode adicionar: não pode remover uma entrada base e não pode sobrescrever um valor escalar base — uma chave escalar ou de mapa que ela traga não tem significado aditivo e é ignorada (e nomeada em um aviso de resolução) em vez de aplicada. E ela nunca ancora a raiz de um espaço de trabalho: só um .aggrega-config.yaml com um bloco workspace: faz isso, então colocar a sobreposição em um diretório adiciona vinculações sem mudar onde o espaço de trabalho começa.

Isso dá a um pipeline um ponto de junção limpo para impor políticas em toda a organização: o pipeline coloca um .aggrega-config-append-ci.yaml que nomeia os plugins de política obrigatórios, e essas vinculações são mescladas por cima do que o desenvolvedor escreveu, nunca no lugar disso.

# .aggrega-config-append-ci.yaml — owned by the pipeline, additive only
plugins:
governance_append:
- uri: <organization-policy-plugin-reference>
role: render-verdict
with:
settings:
required_label: app.kubernetes.io/name

examples/policy-org-overlay/ constrói um espaço de trabalho com a vinculação de uma equipe, a de uma organização adicionada por meio do governance_append de um arquivo de configuração global e a de um pipeline adicionada por meio desta sobreposição, e verifica o que cada combinação imprime e se ela é concluída.

Testar uma política antes que ela bloqueie um build

Uma regra Rego que nomeia um caminho que o payload do seu papel não traz não é um erro: o caminho é indefinido, a regra nunca é satisfeita e o build é concluído como se a política o tivesse permitido. Por isso uma nova política conquista halt em três passos: vinculá-la com uma severidade que relata sem interromper, verificar cada caminho que ela nomeia no payload que o seu papel recebe, e ler o que ela relata sobre os builds que vai julgar.

Os comandos abaixo são executados em uma cópia de examples/policy-org-overlay/ cujo .aggrega-config.yaml vincula uma nova política no lugar da política da equipe. Ela deve recusar um armazenamento de dados que roda com a alta disponibilidade desativada, e sua regra foi copiada de uma política que molda rótulos:

package datastores
import rego.v1
deny contains msg if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v is a datastore running with high availability off", [id])
}

Vincule-a de modo que ela relate. A política coleta em deny, que por padrão interrompe o build. Uma translation que nomeia apenas deny, em warn, relata cada uma de suas decisões como aviso e deixa o build ser concluído; info as registra em vez disso. A própria política permanece como será aplicada:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/datastore-ha.rego
settings:
translation:
- key: deny
severity: warn

Escreva o payload e procure nele os caminhos. Depois que um build tiver preenchido o arquivo de bloqueio da Release,

Terminal window
aggrega build --release release.yaml --dry-run --policy-input payloads

escreve em payloads/ o payload que cada papel entrega às suas vinculações, e nada mais, relatando, com <workspace> representando o diretório em que o build foi executado:

policy input: 4 file(s) written to <workspace>/payloads
[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]

Os quatro são annotation-transform.json, ir-verdict.json, label-transform.json e render-verdict.json; um papel sem nada vinculado também é escrito, para que uma política possa ser verificada em relação ao seu papel antes de ser vinculada em qualquer lugar. Em ir-verdict, label-transform e annotation-transform o arquivo é o documento input que uma política lê, então cada caminho que uma regra nomeia pode ser lido dele com qualquer ferramenta JSON antes de se confiar na regra:

Terminal window
jq '.graph.nodes' payloads/ir-verdict.json
# null
jq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json
# ["db","web"]
jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json
# {"enabled":false,"read_replicas":0}

Os nós da regra não estão lá: input.graph.nodes é onde o papel que molda rótulos os traz, e em ir-verdict eles ficam em input.graph.spec.nodes (veja O que o payload de cada papel expõe). O arquivo também diz o que a regra corrigida deve decidir: db é um armazenamento de dados, sua alta disponibilidade está desativada e ele deve ser relatado.

Onde o OPA está instalado, uma política Rego é avaliada diretamente sobre o mesmo arquivo, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. O mecanismo Rego do compilador é uma implementação independente, então o build continua sendo a avaliação que decide: uma função integrada que ele não implementa interrompe o build em vez de ser avaliada.

Em render-verdict o arquivo não é o input da política. Cada artefato nele traz seu path, content e format; os documents que uma regra lê são analisados a partir do conteúdo pelo mecanismo de políticas assim que ele recebe o payload, então uma regra sobre documents não encontra nada no arquivo. Uma política nesse papel é testada onde o mecanismo os analisa: em um build, como mostra o próximo passo.

Faça o build e compare o que ele relata com o que o payload diz. Com o caminho copiado,

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

é concluído e não relata nada:

Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

O payload tem um armazenamento de dados com a alta disponibilidade desativada, e a política não disse nada sobre ele: esse silêncio é o erro, e nada mais no build aponta para ele. Com a regra lendo input.graph.spec.nodes, o mesmo comando relata db e é concluído:

policy plugin "rego" warning: db is a datastore running with high availability off
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Adicionar --dry-run relata os mesmos vereditos e não escreve nenhum dist/, então o ciclo roda sobre um espaço de trabalho sem perturbar sua saída.

A mesma regra escrita para o mecanismo CEL não falha silenciosamente. Lá, ler uma chave que o payload não traz é uma falha de avaliação, então o caminho copiado, em policies/datastore-ha.cel vinculado com a mesma translation,

{
"deny": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore"
&& input.graph.spec.infra_mapping[n].ha.enabled == false)
.map(n, n + " is a datastore running with high availability off"),
}

interrompe o build mesmo em warn. O comando sai com 1, e sua última linha nomeia o arquivo da política e a chave:

ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodes

Uma política render-verdict é testada da mesma forma. Vinculada em render-verdict no mesmo espaço de trabalho, com a mesma translation, uma regra que recusa um serviço do Compose que publica uma porta no host,

package published
import rego.v1
deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
count(service.ports) > 0
msg := sprintf("%v publishes a port on the host", [name])
}

relata o único serviço que faz isso:

policy plugin "rego" warning: web publishes a port on the host
[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]

Depois, aplique-a. Remover a translation devolve deny a halt, e o build que relatava db agora para nele, sai com 1 e não escreve nenhum dist/:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db is a datastore running with high availability off
caused by: policy violation

A vinculação que relata não precisa ser removida em todos os lugares de uma vez. Um arquivo de configuração pode manter a translation da sua vinculação em warn enquanto a sobreposição de um pipeline vincula a mesma política com deny em halt, e é assim que examples/policy-org-overlay/ introduz a regra de uma organização: um aviso no build de um desenvolvedor, e o motivo pelo qual o build de um pipeline para.

Executar políticas em CI, sobre a saída do build

Tudo o que foi descrito acima vincula uma política dentro de um build. Existe um segundo caminho, e ele não precisa de nada do socket: executar a sua própria ferramenta no pipeline, sobre os arquivos que o build escreveu.

Funciona por causa do que um build emite. Os alvos Kubernetes e Compose escrevem YAML; o alvo Terraform escreve HCL nativo, ou JSON na sua forma .tf.json. Esses são os formatos que as ferramentas de configuração do ecossistema já leem — e aggrega build escreve arquivos simples em um diretório, sem formato de empacotamento, sem índice e sem nada para descompactar. Então uma ferramenta que lê YAML, JSON ou HCL roda sobre a saída de um build da mesma forma que roda sobre uma configuração que uma pessoa escreveu à mão, e o Aggrega não ganha nenhum socket, nenhum tipo de plugin e nenhuma chave de configuração para isso.

Então um corpus de regras existente não precisa de nenhuma adaptação. Se você já mantém regras no Conftest, na CLI do Kyverno, no kubeconform, no Checkov ou no OPA, essas regras rodam sobre a saída de um build do Aggrega como estão, e a ferramenta que as avalia é a que o seu pipeline já instala.

Dois scripts de regras prontos para uso, cada um com a etapa do pipeline que o invoca e as duas recusas que produziram sobre builds reais, estão em examples/policy-in-ci/. Eles usam yq e nada mais, então rodam sem nenhuma toolchain de políticas instalada; a forma que mostram — ler o diretório de saída, decidir, sair com um código diferente de zero nomeando os artefatos infratores — é a forma que qualquer ferramenta nessa posição assume.

A qual caminho uma regra pertence

Os dois caminhos são de primeira classe, e um espaço de trabalho costuma usar ambos. O que decide é o que a regra precisa ver e quando ela precisa agir.

Vincule-a ao socket quando:

  • o build não deve produzir o artefato de forma alguma. Uma política ir-verdict é executada na verificação de análise estática, antes que qualquer coisa seja renderizada, então uma interrupção ali não deixa nada escrito — nenhum arquivo de saída para revisar, colocar em quarentena ou aplicar por acidente. Uma verificação no pipeline necessariamente roda depois que os arquivos existem.
  • a regra precisa de fatos que só o build tem. O papel ir-verdict lê o grafo montado: nós, arestas e seus sockets, cada vinculação com o slot que preencheu, quais valores um autor declarou sensíveis, os caminhos de roteamento. Nada disso sobrevive na saída renderizada — um manifesto do Kubernetes não registra qual socket entregou um valor nem qual Feature contribuiu com um recurso — então uma regra sobre topologia ou sobre proveniência tem um único lugar, e é o socket.
  • a regra deve valer onde quer que o build rode. Uma vinculação de governança fica na configuração do espaço de trabalho, então se aplica ao build local de um desenvolvedor tanto quanto ao do pipeline. Uma verificação no pipeline se aplica onde o pipeline roda.
  • a regra deve moldar o build em vez de julgá-lo. Só um papel de transformação faz isso, e só porque um operador o vinculou.

Execute-a em CI quando:

  • a regra já existe, em uma ferramenta que a sua equipe executa e revisa, sobre um formato que essa ferramenta já analisa. Reexpressá-la como conteúdo de política para o socket é trabalho sem nenhuma cobertura nova ao final.
  • a regra trata dos artefatos como o alvo os receberá — o conjunto final de arquivos, depois de cada transformação, na forma que é aplicada. Esse também é o assunto do papel render-verdict, então, nesse ponto isoladamente, os dois caminhos veem a mesma coisa e a escolha depende dos outros.
  • a constatação é para um revisor e não para o build. Um pipeline que publica os artefatos e as constatações lado a lado dá ambos a um revisor; um build interrompido lhe dá uma mensagem.
  • a verificação vai além de um build — comparando a saída deste build com a do anterior, com o estado real de um cluster ou com um inventário que nenhum payload de build traz. Uma política em qualquer um dos papéis de veredito vê o build ao qual está vinculada, e isso é tudo o que ela vê.

Os caminhos se compõem em vez de competir: um invariante de topologia interrompe o build a partir de ir-verdict, e o mesmo pipeline então executa as regras de artefatos existentes da organização sobre o que esse build escreveu.

Referências cruzadas

  • plugin-contract.md — o posicionamento do socket no pipeline, as formas de transmissão tipadas que ele carrega e o sandbox sob o qual cada plugin é executado.
  • plugin-developer-guide.md — a criação de um plugin, o autorrelato describe() e o ciclo de vida publish → pull → build.
  • ../entities/plugin.md — a entidade Plugin que leva um plugin para o catálogo.
  • ../cli/aggrega-build.md — o comando de build que aciona o socket.
  • ../schema/other/aggrega-config.md — o esquema da configuração do espaço de trabalho, incluindo a superfície de vinculação plugins.governance.
  • ../examples/policy-in-ci/ — dois scripts de regras executáveis sobre a saída de um build, com a etapa do pipeline de cada um.
  • ../examples/policy-data-class-route/ — uma regra ir-verdict sobre rotas, escrita para o mecanismo Rego, o mecanismo CEL e o OPA por trás do guest adaptador de referência, vinculada por build por um arquivo --config por mecanismo, com um script que verifica que os três chegam ao mesmo resultado em cada Release.