O socket de governação
O socket completo em vez de apenas um dos seus papéis: os quatro papéis — dois que julgam uma compilação, dois que lhe dão forma —, os dois motores de políticas incluídos no compilador e como um operador anexa um plugin.
Um operador anexa um plugin de governação Wasm para inspecionar uma compilação e agir sobre aquilo que este encontra. O anfitrião do compilador mantém-se neutro quanto ao conteúdo e sem opiniões próprias: encaminha o payload da compilação para o guest e age sobre aquilo que o guest devolve, e nunca interpreta a política em si. Toda a inteligência de domínio das políticas — a linguagem de políticas, o seu motor e as regras — reside dentro do guest.
Este é o mesmo contrato de pureza ahead-of-time sob o qual todos os sockets são executados: o guest avalia o payload que lhe é entregue e devolve um resultado que o anfitrião consome literalmente (ver o contrato da sandbox). O anfitrião não fica a saber nada sobre a linguagem de políticas que o guest fala e não transporta qualquer código próprio de motor de políticas.
Um plugin de governação é anexado a exatamente um papel, e é o papel — não o plugin — que fixa tanto o payload que chega como aquilo que o anexo pode fazer com ele. Dois são papéis de veredicto: o anexo julga a compilação, e o anfitrião toma exatamente uma de três ações por cada veredicto que este devolve. Dois são papéis de transformação: o anexo comunica uma alteração às etiquetas ou anotações da compilação, e o anfitrião aplica-a. Um plugin que serve mais de um papel é anexado uma vez por papel, e não declara qualquer papel próprio — é o anexo que o transporta.
Esta página é o tratamento completo do socket de governação: os quatro papéis e o payload que cada um transporta, as severidades dos veredictos com base nas quais o anfitrião age, o canal de entrada agnóstico em relação ao motor que um operador fornece, como escrever uma política para qualquer um dos dois motores de políticas incluídos no compilador — um que avalia Rego, outro que avalia CEL —, como um guest encapsula um motor de políticas externo, os guests de referência distribuídos e como um operador anexa um plugin a um espaço de trabalho. Para o lugar do socket no pipeline e as suas formas de transmissão tipadas, ver plugin-contract.md; para criar e publicar um plugin como entidade do catálogo, ver o Guia do programador de plugins Wasm.
O modelo mental: o anfitrião encaminha, o guest decide
Numa compilação, o anfitrião monta o payload para o papel do anexo, entrega-o através da fronteira da ABI e lê de volta o que o guest devolveu. Num papel de veredicto, trata-se de uma lista de veredictos, cada um com uma severidade e uma mensagem legível por uma pessoa: o anfitrião faz corresponder cada severidade a uma ação de compilação, e não lê a mensagem à procura de significado, não sabe o que a política verificou e não sabe que motor produziu a decisão. Num papel de transformação, trata-se da alteração a fazer, dirigida às etiquetas ou às anotações que esse papel governa e a nada mais.
Como o anfitrião não interpreta o conteúdo das políticas, toda a superfície das políticas pertence ao guest: em que linguagem as regras são escritas, que motor as avalia e como uma regra que dispara se torna um veredicto ou uma alteração. O contrato do socket é estreito por conceção — um papel, um conjunto de entradas e um resultado — para que qualquer tecnologia de políticas que compile para Wasm o possa servir.
Um papel de veredicto aceita ou rejeita e não faz mais nada: o anfitrião lê a sua saída apenas como uma decisão e nunca a aplica como uma alteração, pelo que uma política não pode tornar silenciosamente conforme uma compilação não conforme. Um papel de transformação é a exceção deliberada, e o que faz dele uma exceção é o operador tê-lo anexado — anexar um plugin para moldar etiquetas é uma declaração de que as etiquetas devem ser moldadas. O que um anexo desse tipo pode alterar está limitado à superfície do seu próprio papel, e a compilação é interrompida de forma explícita perante qualquer coisa fora dela.
Os quatro papéis
Um plugin é anexado a exatamente um papel, e o papel fixa em que ponto do pipeline o anfitrião o avalia, que payload recebe e o que pode devolver. Um plugin que deva servir dois papéis é anexado duas vezes — uma por papel.
Os papéis de veredicto: ir-verdict e render-verdict
ir-verdict— o guest raciocina sobre o grafo da representação intermédia, antes da renderização. O payload transporta o grafo de IR completo, agnóstico em relação às capacidades (cada nó, aresta e anexo que o compilador detém), mais os caminhos de encaminhamento que o analisador enumera, para que uma política possa raciocinar sobre topologia e alcançabilidade sem voltar a percorrer o grafo. Essa lista de caminhos está limitada por nó de partida — uma topologia densamente ligada ou cíclica pode conter mais rotas distintas do que as 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, ao passo que a ausência de um caminho não prova que nenhum exista: uma política cujo veredicto dependa de algo ser inalcançável deve estabelecê-lo a partir dos nós e das arestas, que o payload transporta por inteiro, e não apenas a partir da lista de caminhos. Há uma coisa no grafo que não está tal como foi escrita: cada valor que um autor declarou sensível — nosvaluesou noinfrade um anexo, noinfrade um anexo ao nível da fronteira, nos própriosvaluesou no próprioinfrade um nó, ou nos própriosvaluesou no próprioinfrade uma ligação — chega como o marcador de retenção{"aggrega_withheld": "declared"}, enquanto a sua chave, a sua marcação de sensibilidade e cada valor não declarado ao lado dele chegam tal como foram escritos. Uma política avalia por onde viaja o material declarado sensível e nunca recebe o material; ver os factos de anexo que uma política de governação lê. Uma políticair-verdicté executada no ponto de controlo da análise estática, antes de ser produzido qualquer artefacto. Use-se para políticas sobre arquitetura e cablagem — invariantes de topologia, autenticação entre fronteiras, forma do fluxo de credenciais — que devam interromper uma compilação antes de esta renderizar o que quer que seja.render-verdict— o guest raciocina sobre a saída renderizada, depois da renderização. O payload transporta os artefactos emitidos ordenados por caminho, pelo que os dados transmitidos são idênticos byte a byte entre execuções com entrada idêntica. Cada artefacto transporta o seu caminho de saída e o seu texto renderizado; além disso, transporta o formato em que foi renderizado, quando o fornecedor que o produziu declarou um, e uma vista estruturada e analisada do seu conteúdo, quando o conteúdo está num formato que foi analisado antes da política. Uma políticarender-verdictvê exatamente o que a compilação produziu, e nada nela é retido: um valor que uma Recipe renderizou num artefacto chega tal como foi renderizado, porque o artefacto é aquilo que a política avalia. Use-se 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 comunica as anotações a acrescentar, durante a resolução e antes da expansão de anotações. O payload transporta cada componente que o anexo pode anotar, cada um com as anotações que já tem, mais as chaves de anotação para as quais o Manifest regista uma associação. Uma anotação injetada sob uma chave registada passa depois a expandir-se num anexo de Feature, e é assim que este papel acrescenta a uma compilação uma capacidade que o programador não escreveu.Os componentes que pode anotar são cada componente que uma fronteira nomeia sob
components:e cada componente que a entrada de encaminhamentoaggregates:de uma fronteira encaminha para dentro. Uma entrada de encaminhamento coloca cada componente do seu módulo, incluindo os componentes dos módulos aninhados dentro dele, quer o seu própriocomponents:nomeie todos, alguns ou nenhum, como fazdocuments: {}, que não nomeia nenhum; o payload transporta cada um deles. Um componente encaminhado é endereçado pelo id que transporta no grafo de compilação — o nome do módulo, um ponto e o nome do componente dentro do módulo, como emdocuments.backend, com mais um nome de módulo e um ponto por cada módulo aninhado —, que é a forma como o grafo de compilação e os seus diagnósticos o escrevem, pelo que uma decisão também o nomeia dessa forma. Um componente que a entrada de encaminhamento coloca sem o nomear não transporta anotações próprias no payload, e uma anotação injetada nele é aplicada como uma escrita nele sob a entrada de encaminhamento. -
label-transform— o guest comunica as alterações de etiquetas a aplicar, durante a construção da topologia: depois de o grafo ser construído e antes de o grafo ser avaliado. O payload transporta uma projeção dos nós da compilação — cada um com o Component que instancia, a versão resolvida para ele, as etiquetas que transporta atualmente e os valores que a sua instância declara, apenas de leitura e com cada valor que o seu Component declara sensível retido tal como o veredicto sobre o grafo o retém — mais o nome e o ambiente da Release. Use-se para metadados derivados que um programador nunca deveria ter de escrever (âmbito de conformidade, propriedade, atribuição de custos) e para uma etiqueta de capacidade que a configuração declarada de um programador conquista.
Os papéis transportam payloads diferentes porque atuam em momentos diferentes e respondem a perguntas diferentes. Todos os quatro transportam o mesmo canal de entrada fornecido pelo operador, descrito mais abaixo. Para ver um payload em vez de ler sobre ele, aggrega build --release <release> --policy-input <dir> escreve o payload que cada papel entrega a um plugin aí anexado — incluindo um papel sem nada anexado — como um ficheiro JSON por papel, ou por anexo quando os anexos de um papel recebem payloads diferentes, e, combinado com --dry-run, escreve esses ficheiros e nada mais. Em annotation-transform, label-transform e ir-verdict, o ficheiro é o documento input que uma política lê. Em render-verdict, o motor de políticas remodela o payload antes de uma política o ler — os documents de cada artefacto são analisados a partir dele —, pelo que uma política render-verdict num motor incluído no compilador é testada numa compilação, anexada em warn ou info, como mostra Testar uma política antes de ela bloquear uma compilação. Para um plugin cujo .wasm tenha compilado por si, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json executa-o sobre esse ficheiro.
Veredictos e severidades
As severidades abaixo são o vocabulário dos papéis de veredicto. Um papel de transformação comunica uma alteração em vez de um veredicto, pelo que não transporta severidade.
Um guest devolve uma lista de veredictos. Cada veredicto transporta uma severidade que determina a ação de compilação:
halt— interrompe a compilação; o anfitrião apresenta a mensagem do veredicto como motivo. A compilação não produz artefactos.warn— sinaliza o veredicto; a compilação prossegue.info— regista o veredicto; o resultado da compilação não se altera.
Estas três são o conjunto completo, e são as mesmas três que os diagnósticos de todos os outros sockets utilizam, pelo que uma severidade significa o mesmo onde quer que se leia uma.
Um veredicto que transporte qualquer outro valor é uma violação do contrato, e não uma quarta via. A compilação é interrompida, e a mensagem nomeia o plugin, o valor que o veredicto transportava e os três que o contrato declara — pelo que uma severidade mal escrita é comunicada como um erro de compilação em vez de passar como um veredicto sobre o qual nada atua. Um guest que comunica com um dos três não é afetado.
Uma avaliação que permite não devolve nada. Um guest emite um veredicto apenas quando uma regra dispara, pelo que uma lista de veredictos vazia significa que a política permitiu a compilação. Não existe um veredicto «pass» a emitir — o silêncio é a permissão.
Um guest pode devolver muitos veredictos numa única avaliação, misturando severidades. O anfitrião percorre-os todos: qualquer halt interrompe a compilação (e cada mensagem halt é apresentada), enquanto os veredictos warn e info são comunicados sem bloquear. Isto espelha a separação entre interromper e avisar que distingue uma política que interrompe a compilação de uma verificação de lint consultiva.
O canal with: fontes e definições
Um guest de políticas é normalmente genérico em relação às regras específicas que aplica — o motor está incorporado no guest, mas as regras são fornecidas por anexo. O canal with transporta essa entrada por anexo. Tem dois campos agnósticos em relação ao motor:
sources— os ficheiros de definição de políticas que o guest carrega. O anfitrião lê cada ficheiro nomeado no momento da compilação e passa os seus bytes ao guest de forma opaca: nunca analisa uma fonte, e o caminho que entrega ao guest é o nome base do ficheiro, nunca um caminho absoluto do anfitrião. O que os bytes significam é inteiramente assunto do guest — um ficheiro.regopara um guest, outro formato de política para outro, e um arquivo codificado em base64 de um conjunto completo de políticas para um guest que leia um.settings— um mapa de configuração que o guest faz corresponder ao seu motor. Um guest lê os seus parâmetros ajustáveis (um teto de réplicas, uma chave de etiqueta obrigatória) a partir deste mapa. Por predefinição, o anfitrião entrega-o tal como está sem atuar sobre ele; um guest pode, além disso, declarar um esquema para ele (ver abaixo), caso em que o anfitrião valida o mapa em relação a esse esquema antes de executar o guest.
Um guest totalmente pré-compilado — um cujas regras estão compiladas no seu interior em vez de serem fornecidas no momento do anexo — omite with por completo. O canal é opcional em todos os papéis.
Definições tipadas
Um guest pode declarar um JSON Schema para as settings que espera. Quando o faz, o anfitrião valida as settings do anexo em relação a esse esquema antes de executar o guest. Definições não conformes interrompem a compilação com uma mensagem que nomeia a chave problemática e o que o esquema esperava — uma chave obrigatória em falta, um valor do tipo errado, uma chave desconhecida ou um valor fora do intervalo são detetados à partida, em vez de surgirem como uma falha obscura do guest ou, pior, como uma compilação errada mas bem-sucedida.
As definições tipadas são opcionais e declaradas pelo guest, não pelo anfitrião. Um guest que não declara nenhum esquema de definições mantém o comportamento livre: o anfitrião passa as suas settings sem as verificar. O anfitrião executa uma validação JSON Schema comum em relação a qualquer esquema que o guest tenha declarado; não interpreta o que as definições significam. Isto mantém a verificação neutra em relação ao motor — cada guest descreve a forma das definições que lê, e o anfitrião impõe exatamente essa forma e nada mais.
Um anexo que não declara definições é validado como JSON null. É isso que permite a um guest tornar as suas definições obrigatórias: um esquema que só admite um objeto recusa um anexo que não forneça nenhuma, e a compilação é interrompida. A consequência também vale no sentido inverso, e é aquela para a qual se deve escrever deliberadamente: um guest cujas definições sejam realmente opcionais tem de declarar um esquema que admita null além de um objeto, ou não poderá de todo ser anexado sem definições. Os dois motores de políticas incluídos no compilador declaram "type": ["object", "null"] precisamente por esse motivo — anexe-se um sem bloco with: e é executado com os seus valores predefinidos. Um guest que declara apenas "type": "object" tornou as suas definições obrigatórias, fosse ou não essa a intenção.
A ABI é própria do Aggrega
O contrato do socket é a ABI própria do Aggrega, não a de qualquer motor de políticas. É isso que permite que qualquer tecnologia de políticas compilada para Wasm sirva como guest intercambiável: o guest expõe para o exterior a superfície do Aggrega — describe(), mais o export que o papel que serve chama — e o motor que utilize, seja ele qual for, é um detalhe de implementação por trás dessa superfície.
Um guest que encapsula um motor de políticas externo absorve a ABI desse motor no seu interior. Se o motor tiver a sua própria ABI Wasm, os seus próprios pontos de entrada ou o seu próprio protocolo de callback para o anfitrião, o guest que o encapsula instancia-o e controla-o internamente e faz corresponder a decisão do motor à forma de veredicto do socket. O anfitrião do compilador vê apenas a superfície padrão de veredictos de governação; nunca fica a saber que motor está envolvido e não transporta qualquer código específico de um motor. Mudar uma política de um motor para outro é uma alteração do anexo, não uma alteração do anfitrião.
Dois motores de políticas estão incluídos no compilador
Dois motores de políticas estão compilados no binário da CLI, e um operador anexa um ou outro — ou ambos — da mesma forma que qualquer plugin de governação é anexado:
| Coordenada | Linguagem de políticas | Fonte anexada |
|---|---|---|
governance/rego | Rego | Ficheiros .rego ou um arquivo codificado em base64 de um conjunto completo de políticas |
governance/cel | Common Expression Language (CEL) | Ficheiros de expressões .cel ou documentos de regras .yaml / .yml |
Tudo o que rodeia a linguagem é partilhado. Ambos servem os quatro papéis, ambos leem o mesmo payload por papel sob os mesmos nomes de campo, ambos fazem corresponder as suas decisões às mesmas três severidades de veredicto através da mesma definição translation, e ambos falham de forma explícita em vez de permitirem uma compilação que não conseguiram avaliar. Cada um transporta como versão a release do compilador que o inclui, e nenhum precisa de uma cadeia de ferramentas externa nem obtém o que quer que seja no momento da compilação. O que cada linguagem consegue dizer não é partilhado: uma regra que em Rego são algumas regras auxiliares pode exigir definições e repetição em CEL — ver 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. Um parque que já mantém um corpus de Rego — ou uma equipa que escreve Rego para controlo de admissão noutro lado — anexa o motor Rego, e as suas políticas são executadas tal como estão. Uma equipa que exprime as suas regras como expressões únicas sobre um documento, como faz uma política de admissão de validação do Kubernetes, anexa o motor CEL. Os dois são anexados por papel, pelo que um espaço de trabalho pode executar Rego num papel e CEL noutro, ou ambos no mesmo papel como dois anexos.
O anfitrião é agnóstico em relação a qual dos dois produziu uma decisão: encaminha o payload, lê de volta um veredicto ou uma alteração e atua em conformidade. Mudar uma política de uma linguagem para a outra é uma alteração do anexo e uma reescrita das regras — nunca uma alteração do anfitrião.
Políticas Rego: dois caminhos
Rego é uma linguagem de políticas comum, e há dois caminhos para a executar — um motor de baixo atrito incluído no compilador e uma via de escape de fidelidade total.
O motor Rego no compilador é o caminho de baixo atrito. Contém um avaliador Rego nativo de Wasm, pelo que um operador coloca um ficheiro .rego em sources e anexa o plugin — nenhuma cadeia de ferramentas externa e nada obtido no momento da compilação. Serve os quatro papéis: o mesmo plugin avalia o grafo de compilação, avalia a saída renderizada, molda etiquetas ou injeta anotações, consoante o papel em que está anexado. A sua identidade de catálogo é o nome simples rego sob pluginType: governance — a coordenada governance/rego — e a sua versão é a release do compilador que o inclui. Escrever uma política para este motor é a secção seguinte.
O avaliador reimplementa o 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, o anexo falha de forma explícita: devolve uma falha, não uma permissão. A compilação é então interrompida com uma falha que nomeia o plugin — deliberadamente distinta de um veredicto halt, para que «o motor não consegue avaliar esta política» nunca seja confundido com «a política permite a compilação». Uma política que não pode ser avaliada interrompe a compilação; 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 motor de referência, compila-se com a própria cadeia de ferramentas do OPA num módulo Wasm e executa-se esse módulo por trás de um guest adaptador fino. O adaptador absorve inteiramente a ABI Wasm do OPA no seu interior (conforme A ABI é própria do Aggrega, acima): instancia o módulo gerado pelo OPA, define a entrada, invoca a avaliação e faz corresponder a decisão à forma de veredicto. O anfitrião vê apenas a superfície padrão de veredictos de governação.
Um guest adaptador de referência é incluído como exemplo completo. Incorpora uma política escrita em Rego e pré-compilada com opa build -t wasm num módulo WebAssembly — um artefacto fixado e versionado no repositório, pelo que a avaliação decorre inteiramente no guest, sem qualquer processo do OPA e sem obter nada. Em cada compilação, o adaptador instancia esse módulo pré-compilado no seu interior com um interpretador Wasm incorporado, satisfaz as importações do próprio módulo (a sua memória linear e os seus callbacks de funções integradas), lê o payload como o documento input do OPA e as settings do anexo como o documento data do OPA, avalia cada ponto de entrada compilado e faz corresponder o nome de ponto de entrada deny / warn / audit de cada um a uma severidade de veredicto — halt, warn e info, respetivamente. Se uma política pré-compilada precisar de uma função integrada fornecida pelo anfitrião que o adaptador não implementa, o adaptador falha de forma explícita — recusando o módulo em vez de devolver uma permissão —, pelo que uma política que não pode ser avaliada interrompe a compilação em vez de passar silenciosamente. Regenerar o módulo pré-compilado a partir da sua fonte Rego é um passo de criação executado com a CLI do OPA, não uma dependência no momento da compilação. ../examples/policy-data-class-route/ constrói esse adaptador em torno de um módulo próprio e indica os comandos que regeneram ambos.
Os dois caminhos partilham o mesmo contrato com o anfitrião, pelo que mudar uma política do motor no compilador para o motor completo é uma alteração do anexo.
Escrever uma política para o motor Rego
O motor avalia o Rego escrito pelo operador inteiramente no interior do guest, em qualquer um dos quatro papéis em que esteja anexado. Anexá-lo duas vezes, em dois papéis, com dois ficheiros de política diferentes, é a forma de um único motor cobrir dois momentos da mesma compilação.
O payload do papel do anexo é o documento input da política, e o objeto settings do anexo é o documento data da política — assim, uma política lê um limiar fornecido pelo operador como data.max_replicas. Cada ficheiro que o anexo declara sob sources torna-se um módulo de política, e cada pacote que esses ficheiros declaram é avaliado.
Em que sintaxe de regras uma política é escrita
O Rego escreve-se em duas sintaxes de regras e o motor 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, no mesmo anexo.
Na sintaxe atual, o corpo de uma regra é introduzido por if, uma regra que recolhe para um conjunto indica-o com contains, e o módulo indica em que sintaxe está escrito declarando import rego.v1 numa 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 parênteses retos, o valor que uma regra recolhe fica entre parênteses retos na cabeça da regra e o corpo segue-a diretamente. 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 — pelo que uma política que deveria ter ficado em silêncio interrompe a compilação, e o caso simétrico deixa passar uma compilação que uma regra foi escrita para interromper. Em vez de escolher uma leitura para um módulo desse tipo, o motor recusa-o e diz o que acrescentar:
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 compilação que nomeia o plugin, e não um veredicto, pelo que interrompe a compilação tal como uma política que não pode ser avaliada e nunca é lida como uma política que a permitiu.
Convém conhecer dois casos-limite antes que surpreendam. Um módulo sem qualquer corpo de regra — um que só declara dados — é analisado como a sintaxe atual, pelo que também lhe é pedida a declaração, embora 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 motor que distingue as duas, pelo que uma política deliberadamente escrita com cabeça entre parênteses retos nunca é confundida com uma de sintaxe atual que se esqueceu de o indicar.
Uma política recolhe as 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 com nome para a qual a política recolhe. Quais as chaves lidas, e o que significa uma decisão sob uma delas, é fixado pelo papel.
Num papel de veredicto, uma decisão é uma mensagem, e a chave sob a qual foi recolhida fixa a severidade com que essa mensagem é comunicada. Por predefinição, as chaves são os nomes de recolha convencionais do Rego:
| Recolhido sob | Comunicado como | Efeito na compilação |
|---|---|---|
deny | halt | interrompe a compilação |
warn | warn | surge a par de uma compilação que é concluída |
audit | info | registado; o resultado da compilação não se altera |
Mantenham-se separados os dois vocabulários, 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 comunica. A coluna da esquerda pode ser renomeada; a coluna da direita é o conjunto fechado que todos os sockets partilham.
Uma política que nomeia as suas decisões de outra forma declara a correspondência nas definições do anexo:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnUma correspondência declarada substitui a predefinida em vez de a estender: as chaves que nomeia são exatamente as chaves lidas, pelo que uma política que ainda recolhe para deny não chega a nenhum veredicto depois de declarada a correspondência acima. A ordem em que as regras são declaradas é a ordem em que os veredictos são comunicados. Uma chave que a política não declara é uma decisão ausente e não um erro, pelo que um mesmo ficheiro de política pode servir vários anexos.
Uma severidade fora das três, e uma correspondência declarada vazia, são recusadas pelo esquema de definições que o plugin declara — o anfitrião valida as definições de um anexo em relação a ele antes do envio. A mesma chave mapeada duas vezes é recusada quando a correspondência é lida, o que também acontece antes de qualquer política ser executada. Em qualquer dos casos, a compilação é interrompida antes de se chegar a uma decisão, nunca com uma correspondência aplicada a meio.
De resto, as definições são os dados próprios da política: a correspondência é lida a partir do objeto e o objeto chega inalterado ao documento data da política, pelo que uma política escrita para as chaves predefinidas vê exatamente o documento de dados que teria visto sem qualquer correspondência configurada.
Num papel de transformação, uma decisão é a alteração a fazer e não uma mensagem, pelo que não há severidade a fixar e é antes a chave que fica fixada: labels no papel que molda etiquetas, annotations no papel que injeta anotações. Uma definição translation só é lida onde são comunicados veredictos, pelo que um anexo de transformação que declare uma transporta uma definição que o seu papel não consome.
Uma chave de decisão é lida a partir de todos os pacotes que o anexo carrega, pelo que um conjunto de políticas pode distribuir as suas regras por vários pacotes e cada um contribui com o que recolheu. O reverso convém conhecê-lo antes que cause problemas: dentro de um anexo, a chave de decisão é um nome de regra reservado em todos os pacotes, pelo que um pacote auxiliar que por acaso recolha para labels para fins próprios vê as suas entradas lidas como decisões de etiquetas. Isso falha de forma explícita e não silenciosamente — o anexo comunica que algo recolhido sob a chave não é uma decisão dessa forma —, mas a maneira mais rápida de ler uma mensagem destas é como uma colisão de nomes; reserve-se, portanto, a chave para a decisão e dê-se outro nome a uma regra auxiliar.
O que o payload de cada papel expõe
O payload é o documento input da política, pelo que uma política o lê pelos nomes que o formato de transmissão lhe dá.
O grafo de compilação fica num caminho diferente nos dois papéis que transportam um. Um veredicto sobre o grafo recebe o documento inteiro do grafo, pelo que os seus nós ficam em input.graph.spec.nodes; o papel que molda etiquetas recebe uma projeção dos nós, pelo que os 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 o esquecer é uma regra que nunca dispara em vez de um erro, porque um caminho que não existe é simplesmente indefinido.
| Papel | O que uma política lê |
|---|---|
ir-verdict | input.graph — o documento inteiro do grafo de compilação: 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 lê-se como {"aggrega_withheld": "declared"}. input.precalculated_paths — os caminhos de encaminhamento enumerados, cada um com a sua lista ordenada nodes e attached_features, os tipos de Feature anexados em qualquer ponto dele (ver abaixo). A lista está sempre presente: uma compilação sem qualquer rota entre componentes transporta uma lista vazia. |
render-verdict | input.artifacts — uma entrada por ficheiro emitido, cada uma com path, content, format e documents, os documentos analisados do ficheiro. format é o formato que o fornecedor que renderizou o ficheiro declarou para ele — o fornecedor Terraform declara hcl para cada ficheiro .tf que emite e json para cada ficheiro .tf.json, incluindo os ficheiros de um módulo vendorizado — e a cadeia vazia onde nenhum fornecedor declarou um, como para um ficheiro com que uma Recipe contribui para a saída partilhada de uma fronteira. Esse ficheiro é ainda assim analisado pela sua extensão, pelo que os seus documents estão presentes em qualquer caso. Um artefacto que não pôde ser lido de forma estruturada transporta 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 ficheiro ilegível. |
label-transform | input.graph.nodes — os nós da compilação 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 os seus templates avaliados em relação aos seus parâmetros, ausente quando não declara nenhum. Um valor que o Component do nó declara sensível lê-se como {"aggrega_withheld": "declared"}, tal como em ir-verdict, e os seus irmãos não declarados leem-se tal como foram escritos. Uma regra lê input.graph.nodes[id].values para decidir uma etiqueta; 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-transform | input.targets — cada componente que o anexo pode anotar, cada um com boundary_path, component_name — para um componente que uma entrada de encaminhamento coloca, o seu id no grafo de compilação, como metrics.query — e as annotations que a Release escreve no próprio componente, cada valor tal como foi escrito: uma cadeia, um objeto de subchaves ou null onde o componente prescinde de uma anotação que herdaria. Cada chave que o componente transporta está presente seja qual for o seu valor, pelo que uma regra pode deixar intacta uma chave que alguém já escreveu. input.binding_keys — as chaves de anotação para as quais o Manifest regista uma associação. |
Um recurso Terraform lê-se num caminho diferente em cada uma das duas formas do Terraform. Nos documents de um ficheiro .tf nativo, um bloco fica aninhado sob o seu tipo e depois sob cada uma das suas etiquetas, e a última etiqueta contém uma lista de blocos, porque os blocos que partilham um tipo e etiquetas são recolhidos numa única lista pela ordem da fonte. Um atributo de recurso lê-se, portanto, 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 ficheiro .tf.json é lido tal como a Recipe o escreveu, pelo que a sua forma de objeto convencional, em que o nome contém o próprio bloco, se lê em resource.<type>.<name>.<attr>, e uma política pensada para ambas as formas lê ambos os caminhos. Isto vale para os dois motores de políticas incluídos no compilador. Uma regra Rego escrita para a outra forma encontra indefinido o caminho que nomeia: uma regra que testa um valor aí nunca dispara, e uma que recusa perante um valor ausente, com not, dispara em todos os recursos; uma expressão CEL que indexa ou seleciona na outra forma interrompe a compilação com uma falha de avaliação que nomeia o seu ficheiro de política. O adaptador de renderização Rego de referência, descrito em Adaptadores de políticas para a fase de renderização mais abaixo, analisa por si próprio um ficheiro .tf nativo e lê um único bloco como um objeto, pelo que um caminho Terraform é editado, não copiado, quando uma política passa entre esse adaptador e um motor incluído no compilador.
Todos os papéis transportam ainda input.sources — os ficheiros próprios do anexo, cada um com o seu nome base como path e o seu content. Uma política só é executada como um desses ficheiros, pelo que, onde quer que uma regra leia a lista, esta contém pelo menos esse ficheiro.
input.settings é o objeto de definições do anexo, o mesmo objeto que o documento data da política, e está presente quando o anexo declara definições. Quando o anexo não declara nenhuma, o que uma regra encontra depende do papel: em ir-verdict, label-transform e annotation-transform o campo está ausente, pelo que input.settings é indefinido como qualquer caminho que o payload não transporta, e em render-verdict é o objeto vazio. Assim, uma regra que depende de uma definição ter sido configurada testa a definição que lê e não o objeto, o que se comporta da mesma forma em todos os papéis — 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 motor CEL trata de forma diferente um objeto de definições não declarado, e explica-o na sua própria secção mais abaixo.
attached_features e binding_keys são listas e não objetos, pelo que uma política testa a pertença 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 todos os anexos detidos por qualquer nó do caminho — incluindo um anexo escrito numa das ligações desse nó, seja qual for a ligação em que foi escrito —, pelo que a regra é satisfeita por um anexo core/data-masking no próprio gateway, que é onde essa Feature se anexa: seleciona pela capacidade de mascaramento de conteúdo que o gateway declara. O que o anexo mascara é o texto de chat e de completion que passa por esse gateway; a regra verifica que o anexo existe, não o que lista.
Por ser uma união sobre o caminho inteiro, a lista diz que uma Feature está anexada algures numa rota e nunca onde. Uma regra que precise de saber se uma Feature se encontra entre dois componentes concretos de uma rota — o que detém dados restritos e o que este alcança — lê por ordem os nodes da rota e os anexos próprios de cada nó, em input.graph.spec.feature_values_mapping[<node>]; colocada a attached_features, a mesma pergunta deixa passar uma rota em que a Feature se encontra para lá do segundo componente. ../examples/policy-data-class-route/ está escrito dessa forma, para o motor Rego, o motor CEL e o OPA.
Um objeto de nó não transporta id próprio: o id é a chave sob a qual se encontra em input.graph.spec.nodes, e é por isso que a regra acima leva para a sua mensagem os ids que leu de path.nodes em vez de ler um campo id.
A ordem pela qual uma política encontra as chaves de um mapa
O grafo mantém a ordem que o seu autor escreveu: os nós pela ordem em que os componentes foram declarados, e as etiquetas de cada nó pela ordem em que o nó as transporta. Essa ordem chega intacta ao guest — o payload transporta ambos como entradas ordenadas (ver mapas que mantêm a sua ordem). Se uma política a encontra ou não é decidido pela forma como o motor que avalia a política guarda um objeto, não pelo payload:
- O motor Rego guarda as chaves de um objeto ordenadas. Uma regra que itere sobre
input.graph.spec.nodes, sobre aslabelsde um nó ou sobre qualquer outro objeto — incluindo um escrito na própria política — encontra as chaves ordenadas: componentes declaradosweb,api,metricssão encontrados comoapi,metrics,web. - O motor CEL não fixa nenhuma ordem para um mapa. Uma compreensão sobre
input.graph.spec.nodesou sobre aslabelsde um nó pode encontrar as chaves por uma ordem diferente em duas compilações 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-se uma regra cuja decisão não dependa da posição em que uma chave se encontra. - Um guest escrito com um kit de plugins encontra a ordem do autor. Descodificados através do seu kit, os nós e as etiquetas de cada nó chegam ao contentor do kit que mantém a ordem, pela ordem em que o payload os transporta, e o esqueleto de adaptador de governação que cada kit fornece entrega ao seu motor um documento JSON escrito nessa mesma ordem. Um motor que converta esse documento num tipo de valor próprio encontra, em vez disso, a ordem desse tipo, como descreve mapas que mantêm a sua ordem.
Moldar etiquetas: uma política nomeia a etiqueta, e o motor endereça-a
No papel que molda etiquetas, uma política recolhe uma decisão por etiqueta sob labels, nomeando o nó, a chave da etiqueta e o valor que a etiqueta 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 a etiqueta em vez de escrever a instrução de edição que a compilação aplica, e vale a pena conhecer a razão: a instrução endereça uma etiqueta por caminho, e uma chave de etiqueta do Aggrega contém habitualmente uma /, que é o separador de caminhos — pelo que um caminho escrito à mão endereçaria uma localização aninhada em vez de uma etiqueta. O motor endereça a etiqueta que a decisão nomeia, pelo que o escape é escrito uma vez em vez de em cada política, e uma política mantém-se legível como uma afirmação sobre etiquetas e não sobre caminhos.
Uma decisão só pode alterar uma etiqueta. Cada instrução que o motor emite endereça uma etiqueta num nó, pelo que uma política não tem forma de exprimir uma alteração ao Component de um nó, à sua versão resolvida, ao conjunto de nós ou a um valor de etiqueta que não seja uma cadeia de caracteres. Uma decisão que nomeie um nó que a compilação não tem, ou que remova uma etiqueta que o nó não transporta, é recusada pela compilação com uma mensagem que nomeia a instrução — nunca ignorada silenciosamente.
../examples/policy-label-transform/ anexa uma política desse tipo ao lado dos dois plugins de etiquetagem integrados, além de um veredicto sobre o grafo que lê as etiquetas que eles escrevem. O que cada um desses plugins lê e escreve encontra-se em Os plugins de etiquetagem integrados.
Injetar anotações
No papel que injeta anotações, uma política recolhe uma decisão por anotação sob annotations, nomeando o destino pela coordenada que o próprio destino transporta, 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 leu os seus destinos, pelo que a convenção se aprende apenas a partir do payload. Ler input.binding_keys permite a uma política injetar apenas chaves para as quais o Manifest registou um significado — são essas as que se expandem num anexo de Feature.
O valor de uma decisão é um valor que se poderia escrever diretamente nessa anotação: uma cadeia de caracteres, ou um objeto de subchaves. Uma associação que encaminha uma subchave aceita uma cadeia de caracteres; uma associação que encaminha várias aceita 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"]}A compilação lê um valor injetado exatamente como lê o mesmo valor escrito na Release, pelo que se expande da mesma forma e é verificado da mesma forma em relação à Feature da associação. O motor guarda as chaves de um objeto ordenadas, pelo que as subchaves chegam à compilação ordenadas. Um valor de qualquer outra forma — null, uma lista, um número, um booleano ou um objeto sem subchaves — é recusado pela compilação, que nomeia a injeção: o papel acrescenta anotações, e null ou um objeto vazio lê-se como a exclusão que um autor escreve para remover uma. Uma decisão que nomeie um componente que o payload não transporta é recusada da mesma forma, nomeando a coordenada e a anotação.
Quando a compilação recusa uma anotação injetada pela forma como é encaminhada ou pelo que transporta — uma cadeia de caracteres fornecida a uma associação que encaminha várias subchaves, um valor de subchave que o esquema da Feature da associação não admite, ou uma subchave encaminhada 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 governação ao qual está anexado, pelo que o valor é rastreado até à política que o decidiu e não até uma linha da Release que ninguém escreveu.
../examples/policy-annotation-transform/ anexa uma política desse tipo, injetando uma cadeia de caracteres sob uma associação e um objeto de subchaves sob outra, e compila os mesmos ficheiros que uma Release que escreve essas anotações à mão.
Anexar um conjunto completo de políticas como um único arquivo
Um conjunto de políticas é anexado ficheiro a ficheiro, ou como um único arquivo que transporta em conjunto os seus ficheiros de políticas e os seus documentos de dados — a forma que uma cadeia de ferramentas Rego constrói. O conteúdo de um ficheiro anexado viaja até ao guest como texto, e um arquivo comprimido é composto por bytes arbitrários e não por texto, pelo que um arquivo é anexado codificado em base64, com um nome que termina em .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64O nome é o que marca um ficheiro como arquivo e não como texto de política, o que mantém a escolha como uma declaração explícita do próprio operador: um arquivo danificado é então comunicado como um arquivo danificado, nomeando o ficheiro e o passo que falhou, em vez de ser lido como um ficheiro de política que não pode ser analisado. Codificar o arquivo é um passo que o operador acrescenta depois de a sua cadeia de ferramentas o ter construído.
Dentro do arquivo, 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 se encontra — um limits/data.json que contenha {"max": 3} é lido por uma política como data.limits.max. Os membros de qualquer outro tipo são transportados pelo arquivo para a sua própria cadeia de ferramentas e não são entrada de política.
Um arquivo que não pode ser aberto é uma falha que nomeia o ficheiro anexado: uma codificação que não se descodifica, um fluxo que não se descomprime, um arquivo truncado, um ficheiro de dados que não se lê, ou um arquivo que não contém política nenhuma. Nenhum destes casos produz um conjunto de políticas vazio, porque um conjunto de políticas vazio não alcança nenhuma decisão — e «o arquivo estava ilegível» nunca pode ser indistinguível de «a política permitiu a compilação».
Escrever uma política para o motor CEL
O motor avalia CEL escrito pelo operador inteiramente dentro do guest, em qualquer um dos quatro papéis em que esteja anexado. A sua identidade no catálogo é o nome simples cel sob pluginType: governance — a coordenada governance/cel — e a sua versão é a release do compilador que o inclui. Anexá-lo duas vezes, em dois papéis, com dois ficheiros de política diferentes, é a forma como um único motor cobre dois momentos da mesma compilação.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Uma política acede a todo o payload através de um único nome, input, pelo que os nomes que lê são os nomes que o formato de transmissão lhes dá: o grafo de compilação em input.graph, os caminhos de encaminhamento enumerados em input.precalculated_paths, os ficheiros renderizados em input.artifacts, os destinos de anotação em input.targets. Esses caminhos por papel são os que estão tabelados em O que o payload de cada papel expõe acima, e são idênticos para os dois motores — um único formato de transmissão, lido sob um único nome raiz.
Os ficheiros próprios do anexo estão em input.sources e as suas definições em input.settings, pelo que um limiar fornecido pelo operador se lê como input.settings.max_nodes. Não há um segundo documento a aprender: as definições fazem parte de input como tudo o resto. Ambos estão sempre presentes como valor — as definições são o objeto vazio em todos os papéis quando o anexo não declara nenhuma —, pelo que uma expressão que lhes aceda não precisa de se proteger contra a sua ausência, e saber se uma dada definição foi configurada é um teste sobre a sua chave: has(input.settings.max_nodes).
As duas formas de escrita, e o nome de ficheiro que escolhe entre elas
Uma política é anexada numa de duas formas, e é o nome do ficheiro que diz qual:
| O nome do ficheiro termina em | Lido como |
|---|---|
.cel | uma expressão, avaliada tal como está |
.yaml ou .yml | um documento de regras — uma lista de regras |
| qualquer outra coisa | uma expressão |
O nome é a regra inteira. Nenhuma definição seleciona uma forma, e o texto do ficheiro não é examinado para adivinhar uma — de qualquer modo não poderia responder à pergunta, porque o valor mais exterior de uma expressão é um mapa, tal como o de um documento de regras, o que torna as duas formas indistinguíveis pela estrutura.
A regra vale, portanto, nos dois sentidos, e ambos os erros são recusados em vez de mal lidos. 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 ficheiro. Mudar o nome do ficheiro é a correção nos dois sentidos.
Um conjunto de políticas tem tantos ficheiros quantos precisar, e as duas formas misturam-se livremente dentro de um mesmo anexo.
Uma expressão, num ficheiro chamado .cel
Uma linguagem de expressões não tem nomes de regras sob os quais recolher decisões, pelo que as decisões são o valor que a expressão produz: um mapa da chave de decisão para aquilo que essa chave recolhe. Num papel de veredicto, uma chave recolhe as mensagens alcançadas sob ela; num papel que molda a compilação, recolhe 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 ficheiro omite não alcançou nenhuma decisão aí, pelo que um ficheiro não precisa de nomear todas as chaves — e cada papel lê apenas a chave que lhe diz respeito, pelo que um mesmo conjunto de políticas pode servir um papel de veredicto e um papel que molda a compilação a partir dos mesmos ficheiros. Uma chave transporta uma lista daquilo que recolhe, um único elemento, ou o valor null para nenhum.
Uma expressão cuja avaliação dê outra coisa que não 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, num ficheiro chamado .yaml ou .yml
Um documento de regras é uma lista de regras, cada uma a nomear a chave de decisão que alcança, a expressão que decide se é alcançada e o que é comunicado 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 environmentO que uma regra comunica segue a chave de decisão que alcança, exatamente como numa expressão. Texto é a mensagem que um veredicto transporta. Um mapeamento são os campos da única decisão que um papel que molda a compilação lê:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldQual dos dois uma regra escreve é decidido apenas pela regra — não há nenhuma definição que o selecione —, e uma regra que escreva o errado para a sua chave é recusada, pelo nome.
Um pormenor de YAML que vale a pena conhecer antes que cause problemas: uma expressão que comece com aspas duplas tem de 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: nightlyUm documento de regras é lido como a expressão que representa antes de qualquer coisa ser avaliada. Cada regra torna-se a sua chave de decisão, que transporta o que a regra comunica quando a expressão é verdadeira e nada quando não é, e as regras que partilham uma chave são juntas. Assim, um único avaliador executa as duas formas, e um documento de regras decide exatamente o que decide a expressão que representa — em todos os papéis, tanto veredictos como decisões que moldam a compilação. Daí decorrem duas consequências. Um documento e a expressão escrita à mão que 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 comunicadas pela ordem em que foram escritas.
Que forma usar — não são intercambiáveis
As duas formas passam por um único avaliador, pelo que nenhuma é mais rápida nem mais fiável do 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 enunciar a divisão com clareza em vez de a deixar ao gosto de cada um. Escolha-se pelo que a regra comunica.
- Um documento de regras, quando o que é comunicado é fixo. A mensagem ou a decisão é escrita uma vez, ao lado da expressão que a alcança, e o ficheiro lê-se como uma lista de guardas. É a forma mais curta para «se isto for verdade, dizer exatamente isto».
- Uma expressão, quando o que é comunicado nomeia o que encontrou. Uma única expressão filtra os componentes de uma compilação e produz uma mensagem — ou uma decisão — por componente, pelo que quem lê obtém
component payments tracks the latest version; pin itpara cada elemento infrator em vez de uma frase sobre uma contagem.
Essa segunda tarefa é aquela que um documento de regras não consegue fazer: cada uma das suas regras transporta uma única comunicação, escrita antecipadamente, pelo que 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 acaba na reescrita da regra como expressão, pelo que vale a pena escolher com base nessa pergunta desde o início.
O que uma expressão pode dizer
As expressões que este motor avalia usam as compreensões filter, map e exists, + sobre cadeias de caracteres e sobre listas, size, in, startsWith, string(), o operador condicional e uma lista indexada por um inteiro calculado. 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 aceita uma única variável, pelo que uma forma de duas variáveis como exists(i, v, …) é recusada da mesma forma. Uma recusa é uma falha de compilação que nomeia o ficheiro 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á forma de dar nome a um valor intermédio. Uma subexpressão usada duas vezes escreve-se duas vezes, ou liga-se a um nome aplicando map a uma lista de um único elemento:
[value].map(name, …)[0]avalia o seu corpo uma vez comnameligado avalue. - Não há forma de percorrer as posições de uma lista. Uma regra que compara por posição os componentes de uma rota obtém as posições a partir das suas definições — uma lista
positionscomo[0, 1, 2, …]— e indexa a rota em cada uma delas, pelo que tem de se proteger contra uma rota mais longa do que a própria lista, interrompendo a compilação perante uma rota dessas, em vez de a ler em parte. - Uma chave de decisão recolhe mensagens, não listas de mensagens. Uma expressão que produza uma lista de mensagens por rota é recusada sob uma chave de decisão — a falha diz que recolheu um valor do tipo lista em vez de uma mensagem —, pelo que uma regra produz um registo por rota e constrói a mensagem a partir dele. E uma mensagem que a expressão produza duas vezes é comunicada duas vezes: a ordenação descrita abaixo ordena o que uma chave recolheu, e não remove uma repetição.
../examples/policy-data-class-route/ contém uma regra CEL escrita tendo em conta as três, ao lado da mesma regra para o motor Rego.
Chaves de decisão e severidades
As chaves de decisão, a correspondência predefinida com as severidades e a definição translation que as renomeia são as mesmas do motor Rego — ver Uma política recolhe as suas decisões sob uma chave de decisão acima. Por predefinição, deny é comunicado como halt, warn como warn e audit como info; uma translation declarada substitui essa correspondência predefinida em vez de a estender, e a ordem que declara é a ordem em que os veredictos são comunicados.
Os dois motores declaram o mesmo esquema de definições para ela, pelo que um bloco translation significa o mesmo seja qual for a linguagem em que as decisões são expressas, e um bloco malformado é recusado antes de qualquer política ser executada.
Num papel que molda a compilação, a chave é fixa em vez de mapeada: labels no papel que molda etiquetas, 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 comunicadas por ordem. Isso faz parte do contrato e não é uma escolha de apresentação, e convém ter presente a razão: 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 por uma ordem que o avaliador não fixa. Sem mais nada, uma entrada idêntica comunicaria as mesmas mensagens numa sequência diferente em cada compilação. A ordenação elimina isso.
Daí decorrem duas coisas que é fácil tomar por erros e que não o são:
- As regras de um documento de regras também são comunicadas ordenadas, e não pela ordem em que foram escritas — porque o documento é avaliado como a expressão que representa, e a ordenação aplica-se ao que uma chave recolheu.
- Uma lista escrita à mão também é ordenada. Uma chave que transporte
["second", "first"]comunicafirstantes desecond. Nada num resultado avaliado distingue uma lista que o autor escreveu de uma produzida por uma compreensão, pelo que não existe uma ordem do autor a preservar.
Entre chaves, a ordem é a ordem declarada em translation. Entre ficheiros, é a ordem dos nomes de ficheiro, porque as fontes de um anexo chegam ordenadas por nome e não pela ordem em que o anexo as lista.
Num papel que molda a compilação, o mesmo raciocínio aplica-se às próprias decisões, e a ordem é mais forte: as decisões são comunicadas por ordem crescente de tudo o que nomeiam, o que é uma ordem total sobre o que uma decisão pode exprimir — o nó, depois a chave da etiqueta, depois se a etiqueta é acrescentada ou removida, 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 a etiquetas ou anotações chega à saída renderizada, pelo que uma ordem arbitrária significaria que uma entrada idêntica seria renderizada de forma diferente de uma compilação para a seguinte.
Moldar etiquetas
No papel que molda etiquetas, uma política recolhe uma decisão por etiqueta sob labels, nomeando o nó, a chave da etiqueta e o valor que a etiqueta 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 à sua volta, e um ficheiro que não nomeie nenhuma chave labels não decide nenhuma etiqueta.
Uma política nomeia a etiqueta em vez de escrever a instrução de edição que a compilação aplica, pela razão dada na secção sobre moldar etiquetas do motor Rego: uma chave de etiqueta do Aggrega contém habitualmente uma /, e um caminho escrito à mão endereçaria uma localização aninhada em vez de uma etiqueta. O motor endereça a etiqueta que a decisão nomeia.
Ler uma etiqueta que um nó pode não transportar é uma falha e não um valor vazio, e é por isso que o segundo exemplo pergunta se a chave está presente antes de a ler. É a regra da própria linguagem de expressões sobre a leitura de uma chave ausente, e manifesta-se de forma explícita: uma política que procura uma etiqueta que nenhum nó transporta comunica que não pôde ser avaliada em vez de, silenciosamente, não decidir nada.
Uma decisão só pode alterar uma etiqueta. Uma decisão que nomeie um nó que a compilação não tem, ou que remova uma etiqueta que o nó não transporta, é recusada pela compilação com uma mensagem que nomeia a instrução — nunca ignorada silenciosamente.
Deve alcançar-se uma única decisão por nó e chave de etiqueta. Uma regra que possa produzir dois valores diferentes para a mesma etiqueta no mesmo nó está subespecificada: resolva-se o valor dentro da expressão — com uma condicional, ou com um filtro que admita um único ramo — em vez de emitir ambas as decisões.
../examples/policy-label-transform/ mostra de ponta a ponta o papel que molda etiquetas, com a sua política escrita para o motor Rego.
Injetar anotações sob uma chave registada
No papel que injeta anotações, uma política recolhe uma decisão por anotação sob annotations, nomeando o destino pela coordenada que o próprio destino transporta, 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 leu os seus destinos, pelo que a convenção se aprende apenas a partir do payload. Ler input.binding_keys permite a uma política injetar apenas chaves para as quais o Manifest registou um significado — são essas as que se expandem num anexo de Feature. Todos os campos são obrigatórios: uma anotação com uma chave vazia ou um nome de componente vazio não é algo que uma política pretendesse pedir. A fronteira sob a qual um componente se encontra pode legitimamente ser nomeada pela cadeia vazia, pelo que esse campo tem de estar presente, mas pode estar vazio.
O valor é um valor que se poderia escrever diretamente nessa anotação: uma cadeia de caracteres, ou um mapa de subchaves, que é o que alimenta uma associação que encaminha várias subchaves de uma vez — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. O motor escreve as subchaves de um mapa ordenadas, uma vez que a linguagem de expressões não fixa nenhuma ordem para um mapa, e passa o valor tal como a expressão o produziu; um valor que o modelo JSON não consegue conter — bytes, um carimbo temporal, uma duração — é recusado em vez de convertido em texto. A compilação lê depois 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 transportam cada valor existente tal como foi escrito — uma cadeia de caracteres, um mapa, ou null para uma exclusão —, pelo que testar "feature.aggrega.ai/monitoring" in t.annotations encontra uma chave seja qual for o seu valor.
Uma decisão que nomeie um componente que o payload não transporta é recusada pela compilação, nomeando a coordenada e a anotação. Quando a compilação recusa uma anotação injetada pelo seu encaminhamento, pelos valores das suas subchaves ou pelo seu pilar, a recusa nomeia o plugin que a injetou e o papel em que está anexado. Tal como com as etiquetas, deve alcançar-se 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 a sua política escrita para os dois motores.
Quando uma política ou uma decisão não pode ser lida
Uma política que o motor não consegue ler, não consegue avaliar, ou que produz algo diferente de decisões na forma documentada faz a compilação falhar em vez de devolver um veredicto ou uma alteração. A falha é comunicada como uma falha de compilação que nomeia o ficheiro e, quando a falha pertence a uma parte do ficheiro, a posição dentro dele — deliberadamente distinta de um veredicto halt, para que «não foi possível avaliar esta política» nunca seja confundido com «esta política permite a compilação».
Para uma expressão, isso abrange uma fonte que não pode ser analisada — comunicada com a linha e a coluna do próprio analisador e um caret sob a posição problemática — e uma fonte cuja avaliação dê outra coisa que não um mapa da chave de decisão para aquilo que essa chave recolhe.
Para um documento de regras, abrange um texto que não é uma lista de regras, uma lista sem regras, uma regra a que falta um campo ou que transporta um campo vazio, um campo que a forma não define, uma comunicação 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 seu próprio ficheiro — e a sua chave de decisão. Uma regra cuja expressão não pode ser analisada é recusada antes da avaliação, pelo que o caret cai dentro da expressão que o autor escreveu e não numa posição de um texto traduzido que nunca viu.
Para uma decisão num papel que molda a compilação, abrange uma mensagem onde deveria estar uma decisão, uma coordenada em falta e um campo que a forma de decisão deste motor não define. Este último merece ser referido à parte: um annotation_valu mal escrito é recusado, não ignorado, pelo que o erro é comunicado em vez de se injetar silenciosamente um valor vazio e deixar uma compilação que é concluída sem a alteração. Cada recusa deste tipo nomeia o ficheiro e termina nomeando o que uma decisão desse tipo tem de nomear.
Adaptadores de políticas para a fase de renderização
Um adaptador para a fase de renderização raciocina sobre a saída renderizada da compilação em vez de sobre o seu grafo IR. O payload de renderização transporta os artefactos emitidos — cada um com o seu caminho de saída e o seu conteúdo renderizado e, quando aplicáveis, o formato em que foi renderizado e uma vista estruturada e analisada dele — além das fontes e das definições próprias do anexo, cada uma onde o anexo a declara. Um adaptador lê esse conteúdo para a forma de saída a que se destina, avalia uma política sobre o resultado estruturado e faz corresponder o desfecho a veredictos halt / warn / info. Como o payload não nomeia nenhuma forma de saída própria, um único padrão de adaptador serve qualquer destino de renderização; uma nova forma de saída é um novo adaptador, não uma alteração ao anfitrião.
Cada adaptador para a fase de renderização é um adaptador no sentido descrito acima: fala a ABI do Aggrega para o exterior e absorve para o seu interior um formato específico do destino ou o contrato de um motor de políticas externo, pelo que o compilador se mantém livre de qualquer lógica de formato de saída ou de política. Os motores Rego e CEL no compilador servem diretamente o papel render-verdict; além deles, dois adaptadores de referência para a fase de renderização são incluídos como exemplos completos entre os exemplos em Rust do kit de desenvolvimento de plugins, um por cada forma de saída comum.
../examples/policy-render-verdict/ anexa uma regra em render-verdict sobre a saída de quatro destinos — objetos Kubernetes, um ficheiro Docker Compose, uma configuração raiz do Terraform e um modelo CloudFormation —, escrita uma vez para cada motor do compilador, e verifica que a violação plantada em cada destino interrompe a compilação e que o seu caso de controlo passa.
Para escrever um adaptador próprio, neste papel ou em qualquer outro, parta-se do esqueleto de adaptador de governação que cada kit de desenvolvimento de plugins fornece: Escrever o seu próprio plugin de governação percorre-o desde o esqueleto até uma compilação 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 fase de renderização: o mesmo avaliador Rego nativo de Wasm do motor no compilador, e a mesma convenção de recolha deny / warn / audit feita corresponder às mesmas três severidades de veredicto, raciocinando sobre ficheiros renderizados em vez de sobre o grafo de compilação.
É independente da forma de saída entre destinos YAML/JSON. O adaptador analisa o conteúdo de cada artefacto como um ou mais documentos YAML ou JSON — o YAML é um superconjunto do JSON, pelo que um modelo JSON como uma stack CloudFormation é analisado pelo mesmo analisador — e expõe à política os documentos analisados a par do conteúdo em bruto. Uma política raciocina sobre a saída de renderização estruturada de qualquer destino desse tipo com Rego comum: input.artifacts[_].documents[_] devolve os documentos analisados (os services de um ficheiro Docker Compose, os Resources de um modelo CloudFormation), input.artifacts[_].content devolve o texto em bruto, e o objeto settings do anexo é o documento data do Rego. Uma política que exige um registo aprovado sobre saída Docker Compose, por exemplo, recusa qualquer serviço cuja imagem não transporte nenhum prefixo de registo.
O adaptador também raciocina sobre a saída de renderização em HCL nativo do Terraform. Um ficheiro .tf nativo não é nem YAML nem JSON, pelo que o adaptador o projeta no mesmo objeto canónico em que um ficheiro 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, seja qual for a forma do Terraform que o compilador emitiu. Os tipos dos atributos são preservados (um número continua a ser um número, um booleano um booleano), e uma expressão Terraform não resolvida continua a ser uma cadeia de caracteres na sua forma ${ ... }. Os conteúdos Terraform-JSON (.tf.json, .auto.tfvars.json) são analisados pelo caminho YAML/JSON sem alteração, e um ficheiro de modelo Terraform (.tftpl) — texto de modelo 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 ficheiro de variáveis carregado automaticamente é o caso em que 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 desse componente na configuração raiz da fronteira —, pelo que essa forma só chega à vista de uma política quando um módulo vendorizado inclui um próprio, que o caminho dos módulos referenciados copia tal como está para a saída. Uma política escrita na expectativa de que o compilador produza um nunca disparará.
Quando o conteúdo de um artefacto não pode ser analisado, o adaptador não o deixa passar silenciosamente: mantém o conteúdo em bruto, não expõe nenhum documento analisado para esse artefacto e regista a mensagem do analisador em input.artifacts[_].parse_error, para que uma política possa interromper explicitamente a compilação perante um artefacto malformado. Tal como no motor Rego no compilador, uma política que chame uma função integrada que o avaliador incorporado 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 ao estilo Kubewarden sobre manifestos Kubernetes renderizados. Absorve para o seu interior o contrato de admission review do Kubernetes: uma política Kubewarden recebe um pedido que envolve um único objeto e devolve uma resposta de aceitação ou rejeição. Na fase de renderização, a saída da compilação já é um conjunto de recursos Kubernetes, o que faz dessa fase o local natural para executar uma política em forma de admissão. Para cada objeto renderizado, o adaptador deriva os campos de admissão a partir do próprio objeto analisado, envolve o objeto num pedido em forma de admission review dentro do guest, executa a política e faz corresponder a resposta a um veredicto: uma rejeição torna-se um veredicto; uma aceitação não emite nada. A política de referência incluída é uma regra que exige uma etiqueta — cada objeto tem de transportar uma chave de etiqueta nomeada por settings —, um padrão comum do Kubewarden.
Âmbito comum aos adaptadores para a fase de renderização
- Fase de renderização, uma forma de saída por adaptador. Um adaptador para a fase de renderização raciocina sobre artefactos renderizados, não sobre o grafo IR, e destina-se à 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 fase do grafo, ou uma política sobre uma forma de saída que nenhum adaptador incluído analisa, é um guest diferente.
- Apenas validação. Um adaptador para a fase de renderização aceita ou rejeita; nunca devolve 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 veredicto de política. Uma política decide; não edita.
Anexar uma política
Um operador anexa um plugin de governação através da lista plugins.governance na configuração do espaço de trabalho (.aggrega-config.yaml). Cada entrada nomeia um plugin, o role em que está anexado e, opcionalmente, o canal with que fornece as suas regras e os seus parâmetros ajustáveis:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3O uri resolve-se para o plugin. O anfitrião lê cada ficheiro de sources no momento da compilação e entrega os seus bytes ao guest, e passa settings tal como está. Uma compilação sem nenhum plugin de governação anexado executa o socket como uma operação nula, pelo que o anexo é puramente aditivo para um espaço de trabalho.
Um plugin que serve vários papéis é anexado uma vez por papel, cada anexo com as suas próprias regras e as suas próprias definiçõ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: haltQue versão um anexo nomeia. Um uri nomeia uma entidade Plugin — a coordenada <pluginType>/<name> e, depois dos dois pontos, uma versão — e a versão participa na resolução. Para os dois motores compilados na CLI, a entidade provém de um de dois sítios. 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 standard contém-nas, cada uma na versão da release que a publicou; um espaço de trabalho lê-as a partir dos diretórios de catálogo que indica. O binário aggrega contém uma entidade de cada um, na versão da sua própria release e em nenhuma outra. Um anexo que nomeie uma versão que nenhum dos dois contenha, e que nenhum pull tenha obtido para a cache de conteúdo, interrompe a compilação com E0137, indicando a referência.
Assim, um anexo nomeia uma versão contida no catálogo que o espaço de trabalho lê. Essa versão resolve-se 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 — se resolve apenas com essa release, tanto num papel de veredicto como num papel de transformação. Num papel de transformação, o pull fixa no ficheiro de bloqueio a versão que resolveu e recusa com E0103 uma versão que não esteja contida nem num catálogo que o espaço de trabalho lê nem no binário. A versão seleciona a entidade Plugin, que regista os exports e os limites de execução do plugin, e não o motor: uma vez resolvida a referência, o motor que é executado é o que está compilado no binário que executa a compilação, porque os plugins integrados no binário são o primeiro local a partir do qual o módulo de um plugin é lido. Um plugin de governação que o próprio espaço de trabalho declara — uma entidade Plugin no seu próprio diretório de catálogo, com o seu .wasm ao lado — é nomeado na versão que essa entidade regista.
Cada papel seleciona uma função de entrada predefinida — verdict_ir para o papel que julga o grafo, verdict_render para o papel que julga os artefactos renderizados, mutate para o papel que molda etiquetas, transform_annotations para o papel que injeta anotações — e um anexo pode apontar um papel para outro export com function:. O anfitrião recusa um envio para um export que o guest não declarou na sua autodescrição describe(), pelo que um anexo que nomeie um papel que o seu guest não serve é reportado pelo nome, antes de o guest ser executado, em vez de não fazer nada silenciosamente.
function: nomeia um export no plugin que o uri nomeia. Um anexo num papel de veredicto — ir-verdict ou render-verdict — que nomeie uma function: e nenhum uri: nomeia uma função em nenhum plugin, pelo que a configuração é recusada logo na leitura, com E0224, indicando o ficheiro e a posição da entrada na sua lista: deve acrescentar-se 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, pelo que um espaço de trabalho ou uma configuração global compõe anexos de políticas em vez de ocultar uma lista base.
A sobreposição pertencente à CI
Ao lado do .aggrega-config.yaml escrito à mão, um pipeline automatizado pode ser dono de um ficheiro de sobreposição separado, .aggrega-config-append-ci.yaml. Existe para que um pipeline possa anexar políticas (ou outra configuração com valores de lista) que controla sem nunca editar a configuração base escrita à mão pelo programador — o pipeline pode substituir integralmente o seu próprio ficheiro de sobreposição.
A sobreposição é estritamente aditiva. É validada com o mesmo esquema de configuração que o ficheiro base e, para cada campo com valores de lista, as suas entradas são concatenadas à lista resolvida. Só pode acrescentar: não pode remover uma entrada base nem substituir um valor escalar base — uma chave escalar ou de mapa que contenha não tem significado aditivo e é ignorada (e indicada num aviso de resolução) em vez de aplicada. E nunca ancora a raiz de um espaço de trabalho: só um .aggrega-config.yaml com um bloco workspace: o faz, pelo que colocar a sobreposição num diretório acrescenta anexos sem mudar onde o espaço de trabalho começa.
Isto dá a um pipeline um ponto de junção limpo para impor políticas a nível de toda a organização: o pipeline coloca um .aggrega-config-append-ci.yaml que nomeia os plugins de política obrigatórios, e esses anexos são fundidos por cima do que o programador escreveu, nunca em vez disso.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ constrói um espaço de trabalho com o anexo de uma equipa, o de uma organização acrescentado através do governance_append de um ficheiro de configuração global e o de um pipeline acrescentado através desta sobreposição, e verifica o que cada combinação imprime e se é concluída.
Testar uma política antes de ela bloquear uma compilação
Uma regra Rego que nomeie um caminho que o payload do seu papel não contém não é um erro: o caminho é indefinido, a regra nunca se verifica e a compilação é concluída como se a política a tivesse permitido. Assim, uma nova política ganha halt em três passos: anexá-la com uma severidade que reporta sem interromper, verificar cada caminho que nomeia em relação ao payload que o seu papel recebe, e ler o que reporta sobre as compilações que vai julgar.
Os comandos abaixo são executados numa cópia de examples/policy-org-overlay/ cujo .aggrega-config.yaml anexa uma nova política em vez da da equipa. Destina-se a recusar um armazenamento de dados que funciona com a alta disponibilidade desativada, e a sua regra foi copiada de uma política que molda etiquetas:
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])}Anexá-la de forma a que reporte. A política recolhe em deny, que por predefinição interrompe a compilação. Uma translation que nomeie apenas deny, em warn, reporta cada uma das suas decisões como aviso e deixa a compilação concluir-se; info regista-as em vez disso. A própria política fica tal 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: warnEscrever o payload e procurar nele os caminhos. Depois de uma compilação ter preenchido o ficheiro de bloqueio da Release,
aggrega build --release release.yaml --dry-run --policy-input payloadsescreve em payloads/ o payload que cada papel entrega aos seus anexos, e nada mais, reportando, com <workspace> a representar o diretório em que a compilação foi executada:
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 anexado também é escrito, para que uma política possa ser verificada em relação ao seu papel antes de ser anexada em qualquer lado. Em ir-verdict, label-transform e annotation-transform o ficheiro é o documento input que uma política lê, pelo que cada caminho que uma regra nomeie pode ser lido dele com qualquer ferramenta JSON antes de se confiar na regra:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -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 etiquetas os coloca, e em ir-verdict estão em input.graph.spec.nodes (ver O que o payload de cada papel expõe). O ficheiro diz também o que a regra corrigida tem de decidir: db é um armazenamento de dados, a sua alta disponibilidade está desativada e deve ser reportado.
Onde o OPA está instalado, uma política Rego é avaliada diretamente sobre o mesmo ficheiro, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. O motor Rego no compilador é uma implementação independente, pelo que a compilação continua a ser a avaliação que decide: uma função integrada que ele não implementa interrompe a compilação em vez de ser avaliada.
Em render-verdict o ficheiro não é o input da política. Cada artefacto nele contém o seu path, content e format; os documents que uma regra lê são analisados a partir do conteúdo pelo motor de políticas assim que recebe o payload, pelo que uma regra sobre documents não encontra nada no ficheiro. Uma política nesse papel testa-se onde o motor os analisa: numa compilação, como mostra o passo seguinte.
Compilar e comparar o que reporta com o que o payload diz. Com o caminho copiado,
aggrega build --release release.yaml --auto-pullconclui-se e não reporta 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 nada disse sobre ele: esse silêncio é o erro, e nada mais na compilação o assinala. Com a regra a ler input.graph.spec.nodes, o mesmo comando reporta db e conclui-se:
policy plugin "rego" warning: db is a datastore running with high availability offPull 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]Acrescentar --dry-run reporta os mesmos veredictos e não escreve nenhum dist/, pelo que o ciclo é executado sobre um espaço de trabalho sem perturbar a sua saída.
A mesma regra escrita para o motor CEL não falha silenciosamente. Aí, ler uma chave que o payload não contém é uma falha de avaliação, pelo que o caminho copiado, em policies/datastore-ha.cel anexado 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 a compilação mesmo em warn. O comando termina com 1, e a sua última linha nomeia o ficheiro 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: nodesUma política render-verdict testa-se da mesma forma. Anexada 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 anfitrião,
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])}reporta o único serviço que o faz:
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, aplicá-la. Remover a translation devolve deny a halt, e a compilação que reportava db passa a parar nele, termina 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 violationO anexo que reporta não precisa de ser removido em todo o lado ao mesmo tempo. Um ficheiro de configuração pode manter a translation do seu anexo em warn enquanto a sobreposição de um pipeline anexa a mesma política com deny em halt, e é assim que examples/policy-org-overlay/ introduz a regra de uma organização: um aviso na compilação de um programador, e o motivo pelo qual a compilação de um pipeline para.
Executar políticas em CI, sobre a saída da compilação
Tudo o que foi descrito acima anexa uma política dentro de uma compilação. Há uma segunda via, e não precisa de nada do socket: executar a sua própria ferramenta no pipeline, sobre os ficheiros que a compilação escreveu.
Funciona por causa do que uma compilação emite. Os destinos Kubernetes e Compose escrevem YAML; o destino Terraform escreve HCL nativo, ou JSON na sua forma .tf.json. São esses os formatos que as ferramentas de configuração do ecossistema já leem — e aggrega build escreve ficheiros simples num diretório, sem formato de invólucro, sem índice e sem nada para descompactar. Assim, uma ferramenta que lê YAML, JSON ou HCL é executada sobre a saída de uma compilação da mesma forma que sobre uma configuração que uma pessoa escreveu à mão, e o Aggrega não ganha nenhum socket, nenhum tipo de plugin nem nenhuma chave de configuração para isso.
Assim, um corpus de regras existente não precisa de qualquer adaptação. Se já mantiver regras no Conftest, na CLI do Kyverno, no kubeconform, no Checkov ou no OPA, essas regras são executadas tal como estão sobre a saída de uma compilação do Aggrega, e a ferramenta que as avalia é a que o seu pipeline já instala.
Dois scripts de regras prontos a usar, cada um com o passo do pipeline que o invoca e as duas recusas que produziram sobre compilações reais, encontram-se em examples/policy-in-ci/. Usam yq e nada mais, pelo que são executados sem nenhuma cadeia de ferramentas de políticas instalada; a forma que mostram — ler o diretório de saída, decidir, terminar com um código diferente de zero indicando os artefactos infratores — é a forma que qualquer ferramenta nesta posição assume.
A que via pertence uma regra
Ambas as vias são de primeira classe, e um espaço de trabalho usa frequentemente as duas. O que decide é o que a regra precisa de ver e quando precisa de agir.
Anexá-la ao socket quando:
- a compilação não deve de todo produzir o artefacto. Uma política
ir-verdicté executada no controlo de análise estática, antes de qualquer coisa ser renderizada, pelo que uma interrupção aí não deixa nada escrito — nenhum ficheiro de saída para rever, pôr em quarentena ou aplicar por engano. Uma verificação no pipeline é necessariamente executada depois de os ficheiros existirem. - a regra precisa de factos que só a compilação detém. O papel
ir-verdictlê o grafo montado: nós, arestas e os seus sockets, cada anexo com a ranhura que preencheu, que valores um autor declarou sensíveis, os caminhos de encaminhamento. Nada disso sobrevive na saída renderizada — um manifesto do Kubernetes não regista que socket entregou um valor nem que Feature contribuiu com um recurso — pelo que uma regra sobre a topologia ou sobre a proveniência tem um único lugar, e é o socket. - a regra tem de valer onde quer que a compilação seja executada. Um anexo de governação vive na configuração do espaço de trabalho, pelo que se aplica à compilação local de um programador tanto quanto à do pipeline. Uma verificação no pipeline aplica-se onde o pipeline é executado.
- a regra deve moldar a compilação em vez de a julgar. Só um papel de transformação faz isso, e só porque um operador o anexou.
Executá-la em CI quando:
- a regra já existe, numa ferramenta que a sua equipa executa e revê, sobre um formato que essa ferramenta já analisa. Reexprimi-la como conteúdo de política para o socket é trabalho que, no fim, não traz nenhuma cobertura nova.
- a regra diz respeito aos artefactos tal como o destino os vai receber — o conjunto final de ficheiros, depois de cada transformação, na forma que é aplicada. Esse é também o objeto do papel
render-verdict, pelo que, neste ponto isolado, as duas vias veem a mesma coisa e a escolha depende dos outros. - a constatação destina-se a um revisor e não à compilação. Um pipeline que publica os artefactos e as constatações lado a lado dá ambos a um revisor; uma compilação interrompida dá-lhe uma mensagem.
- a verificação vai além de uma compilação — comparando a saída desta compilação com a da anterior, com o estado real de um cluster ou com um inventário que nenhum payload de compilação contém. Uma política em qualquer um dos papéis de veredicto vê a compilação à qual está anexada, e é tudo o que vê.
As vias compõem-se em vez de competirem: um invariante de topologia interrompe a compilação a partir de ir-verdict, e o mesmo pipeline executa depois as regras de artefactos existentes do parque sobre o que essa compilação escreveu.
Referências cruzadas
plugin-contract.md— o posicionamento do socket no pipeline, as formas de transmissão tipadas que transporta e a sandbox sob a qual cada plugin é executado.plugin-developer-guide.md— a criação de um plugin, a autodescriçãodescribe()e o ciclo de vida publish → pull → build.../entities/plugin.md— a entidadePluginque leva um plugin para o catálogo.../cli/aggrega-build.md— o comando de compilação que aciona o socket.../schema/other/aggrega-config.md— o esquema da configuração do espaço de trabalho, incluindo a superfície de anexoplugins.governance.../examples/policy-in-ci/— dois scripts de regras executáveis sobre a saída de uma compilação, com o passo do pipeline de cada um.../examples/policy-data-class-route/— uma regrair-verdictsobre rotas, escrita para o motor Rego, o motor CEL e o OPA por trás do guest adaptador de referência, anexada por compilação através de um ficheiro--configpor motor, com um script que verifica que os três chegam ao mesmo resultado em cada Release.