Uma política sobre a saída renderizada: uma regra interna, quatro destinos, dois mecanismos
Uma regra interna, vinculada no papel render-verdict, julga os arquivos que um build escreve para quatro destinos e recusa uma violação plantada em cada um. A regra tem duas cláusulas:
Toda imagem de contêiner nomeia uma versão fixa — uma tag diferente de
latest, ou um digest. Toda instância de banco de dados armazena os seus dados criptografados.
Este espaço de trabalho faz o build de um Aggregate para quatro destinos — Kubernetes via Helm, Docker Compose, Terraform e CloudFormation. O papel render-verdict julga os arquivos que um build escreve, depois que cada destino os renderizou, e a regra lê a estrutura de saída própria de cada destino: as imagens nos objetos Kubernetes e em um arquivo Compose, a instância RDS em um arquivo Terraform e em um template CloudFormation. Cada destino tem uma Release que passa e uma Release com uma violação plantada, que a regra recusa.
A regra é escrita duas vezes, uma para cada mecanismo de políticas compilado na CLI — Rego e CEL — e as duas cópias concordam em cada build aqui. Um script ao lado das Releases faz o build das dezesseis combinações e verifica cada resultado.
aggrega buildsua política
conectada ao compilador
passa
arquivos escritos
prontos para revisar e implantar
falha
build interrompido
Uma política pode interromper um build e dizer o que corrigir. Ela nunca altera seus arquivos para fazê-los passar.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/postgres | o banco de dados de pedidos |
report | core/compute/task | um job de relatório que lê db, iniciado manualmente: ele traz core/manual-trigger, então nenhuma execução começa quando a Release é implantada |
report lê o endereço, a porta e o nome do banco de dados pela sua conexão database, como DB_HOST, DB_PORT e DB_NAME. O Aggregate é o mesmo arquivo para todo build; cada Release nomeia o Manifest que escolhe o destino:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, um StatefulSet | helm/task, um CronJob mantido suspenso |
manifest-compose.yaml | compose/postgres, um serviço | compose/task, um serviço atrás de um perfil |
manifest-terraform.yaml | terraform/postgres-rds, uma instância RDS | terraform/task-ecs, uma definição de tarefa do Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, uma instância RDS | cloudformation/task-ecs, uma definição de tarefa do Amazon ECS |
Toda Recipe aqui renderiza apenas a partir do catálogo: o banco de dados Kubernetes é sintetizado em vez de baixado como chart, o corpo do banco de dados Terraform é escrito pela sua Recipe, e o módulo da tarefa Terraform fica ao lado da sua Recipe. Assim, todo build roda offline.
As oito Releases
| Release | destino | o que a regra encontra | o build |
|---|---|---|---|
release-helm.yaml | Kubernetes | report executa registry.example.com/orders-report:1.4.2 | é concluído |
release-helm-unpinned.yaml | Kubernetes | report executa a mesma imagem com a tag latest | é interrompido |
release-compose.yaml | Docker Compose | report executa registry.example.com/orders-report:1.4.2 | é concluído |
release-compose-unpinned.yaml | Docker Compose | report executa a imagem sem tag | é interrompido |
release-terraform.yaml | Terraform | a instância é criptografada com a chave que a Release nomeia | é concluído |
release-terraform-unencrypted.yaml | Terraform | a Release não nomeia nenhuma chave, então a instância não é criptografada | é interrompido |
release-cloudformation.yaml | CloudFormation | a Release ativa StorageEncrypted | é concluído |
release-cloudformation-unencrypted.yaml | CloudFormation | a Release o deixa desativado | é interrompido |
A imagem é da Release: core/compute/task não empacota nenhum software, então a Release nomeia em infra.image a imagem que uma execução roda, tag incluída. Nos dois destinos AWS, a criptografia do banco de dados também é da Release. A Recipe Terraform lê infra.overrides.kms_key_id e, quando ele está definido, renderiza storage_encrypted = true ao lado da chave; a Recipe CloudFormation lê infra.overrides.StorageEncrypted e KmsKeyId com os próprios nomes das propriedades do recurso. Uma Release que não define nenhum dos dois renderiza uma instância sem nenhum atributo de criptografia, que é o que fazem as Releases com violação plantada.
Os bancos de dados Kubernetes e Compose executam a imagem postgres:16, uma tag fixa, então a regra os julga e os deixa passar em toda Release.
Vincular a regra
.aggrega-config.yaml nomeia o hub como seu registro e nenhum diretório do catálogo, e nenhuma vinculação de governança. A regra é vinculada pelo arquivo que um build nomeia com --config: governance-rego.yaml para o mecanismo Rego, governance-cel.yaml para o mecanismo CEL. O do Rego diz:
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config nomeia o arquivo de configuração global para essa execução, no lugar daquele que a máquina leria de outra forma, e o .aggrega-config.yaml deste espaço de trabalho continua se sobrepondo a ele. Uma lista plugins.governance no arquivo do espaço de trabalho substituiria a que o arquivo nomeado traz, e é por isso que o arquivo do espaço de trabalho não declara nenhuma. 0.9.0 é a versão da entidade Plugin de cada mecanismo no catálogo da biblioteca padrão. Os dois mecanismos são compilados na CLI — aggrega plugin list lista governance/rego e governance/cel entre os plugins integrados embutidos — então nenhum build aqui baixa um plugin.
O que uma política render-verdict lê
Uma política em render-verdict lê os arquivos que o build escreve em input.artifacts, uma entrada por arquivo, ordenadas por caminho. Cada uma traz:
path— o caminho do arquivo emdist/, comoterraform/modules/db/main.tf;content— o texto do arquivo, como foi escrito;format— o formato que o provedor do destino declarou para o arquivo:yamlpara o arquivo Compose,jsonpara o template CloudFormation,hclpara todo arquivo Terraform, incluindo o corpo do banco de dados que a sua Recipe escreve. Onde nada declarou um, é a string vazia, como acontece com os arquivos Kubernetes aqui;documents— o conteúdo do arquivo analisado em uma estrutura, como uma lista de documentos: um para cada arquivo aqui;parse_error— presente apenas em um arquivo que não pôde ser analisado, no lugar dedocuments.
Ao lado dos arquivos, input.sources contém o próprio arquivo de política da vinculação, e input.settings as suas configurações — aqui o objeto vazio, já que esta vinculação não declara nenhuma.
aggrega build --release <release> --dry-run --policy-input <dir> escreve em <dir> o payload que cada papel recebe e não escreve mais nada. Em render-verdict, esse arquivo é o que o mecanismo recebe, e não o que a política lê: cada arquivo nele traz o seu path e content e o format que o seu provedor declarou, e o mecanismo analisa os documents a partir do conteúdo depois de receber o payload. Então o arquivo lista os arquivos que serão mostrados a uma regra, mas não os seus documentos. Depois que um build de release-terraform.yaml preencheu o seu arquivo de bloqueio:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Um caminho que uma regra lê dentro de documents é verificado em um build, em que o mecanismo os analisou. Nenhum arquivo que estas Recipes escrevem falha na análise, então nenhum arquivo aqui traz parse_error. Cada cláusula desta regra lê documents, então um arquivo que não pôde ser analisado passaria por ela sem ser examinado; uma regra que não pode deixar isso acontecer acrescenta uma cláusula que recusa um arquivo que traga parse_error.
Como cada cláusula lê a estrutura do seu destino
Cada cláusula nomeia a estrutura que lê, e um arquivo de outra estrutura não traz o que a cláusula nomeia: em Rego o caminho é indefinido e a cláusula não vale. Assim, uma regra roda sobre a saída de todo destino e cada cláusula encontra apenas a sua.
Compose escreve um arquivo cujo documento indexa cada serviço pelo nome em services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Os objetos Kubernetes trazem os seus contêineres em um template de pod, que um CronJob contém um nível mais abaixo que as outras cargas de trabalho, em spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform em HCL nativo aninha um bloco sob o seu tipo e depois sob cada um dos seus rótulos, e o último rótulo contém uma lista de blocos, porque blocos que compartilham tipo e rótulos são reunidos em uma única lista. Assim, os atributos de uma instância ficam um índice abaixo do seu nome, e a cláusula percorre a lista:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}A lista importa mais aqui do que para uma regra que procura um valor, porque esta cláusula recusa diante de uma ausência. Escrita para um único bloco — some name, block in doc.resource.aws_db_instance — block é a lista, block.storage_encrypted é indefinido nela, e not vale para qualquer coisa indefinida: a cláusula recusa também release-terraform.yaml, cuja instância é criptografada, com a mesma mensagem da Release com violação plantada.
Um arquivo .tf.json é lido como a sua Recipe o escreveu, com o nome contendo diretamente o bloco, então uma regra escrita para uma forma não lê a outra. É por isso que a cláusula lê format primeiro: native_hcl aceita um arquivo cujo formato é hcl, ou cujo formato é vazio e cujo nome termina em .tf — um arquivo para o qual nenhum provedor declarou um formato é analisado pelo nome, então a regra também o reconhece pelo nome, em vez de ignorá-lo. Todo arquivo Terraform gerado no build aqui é declarado hcl, então nenhum arquivo aqui é reconhecido pelo nome. Estas Recipes não escrevem nenhum arquivo .tf.json, então a regra não lê nenhuma outra forma. O que o payload de cada papel expõe apresenta as duas formas.
CloudFormation escreve um template cujos recursos são indexados por ID lógico em Resources, cada um com o seu Type e as suas Properties:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Uma instância sem a propriedade StorageEncrypted, ou com ela definida com qualquer valor diferente de true, é recusada: not … == true vale para os dois casos.
Por que a regra CEL é escrita de outra forma
policies/house-rule.cel expressa as mesmas duas cláusulas e chega ao mesmo veredito em cada build aqui. Ela é escrita de outra forma em três pontos, cada um por um motivo do mecanismo.
Ela testa cada chave antes de lê-la. Ler uma chave que um valor não traz é, em CEL, uma falha de avaliação em vez de um caminho indefinido, e uma falha interrompe o build. Os arquivos de cada destino não têm chaves que os de outro trazem — um objeto Kubernetes não tem services, um arquivo Compose não tem kind — então cada cláusula testa primeiro com has() as chaves que lê:
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Sem o teste has(d.services), aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull é interrompido, quaisquer que sejam as imagens que os objetos Kubernetes executam, sai com 1 e não escreve nenhum dist/, e a linha que relata a falha nomeia o arquivo de política e a chave:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesEla relata um único elemento infrator por arquivo. Uma chave de decisão coleta mensagens, e uma expressão CEL não tem como juntar em uma só lista as listas que constrói por arquivo. Então cada cláusula CEL relata um elemento infrator em cada arquivo: o primeiro contêiner de um template de pod ou, entre os serviços, instâncias e recursos que um arquivo indexa pelo nome, aquele cujo nome vem primeiro na ordenação. Uma compreensão percorre um mapa sem ordem fixa, então escolher pelo nome é o que mantém a mensagem igual de um build para o seguinte. A regra Rego relata todos os elementos infratores. Com dois serviços não fixados em um arquivo Compose, o mecanismo Rego é interrompido com duas mensagens e o mecanismo CEL com uma, para o serviço cujo nome vem primeiro na ordenação; com um só, como em toda Release aqui, os dois são interrompidos com a mesma mensagem.
Ela se repete. CEL não oferece como nomear uma subexpressão, então um teste usado duas vezes é escrito duas vezes, e o teste da imagem é escrito por extenso em cada cláusula em vez de ser chamado como unpinned é chamado em Rego.
Os dois arquivos são uma quase duplicata deliberada, cada um escrito por conta própria a partir da regra acima em vez de gerado um a partir do outro, de modo que um build em que os mecanismos discordam mostre a discordância.
Um veredito nunca altera a saída
Uma política em render-verdict aceita o build ou o recusa. Ela recebe os arquivos que o build escreveu e retorna vereditos; nada do que ela retorna é aplicado a eles. Assim, uma Release de controle gera os mesmos arquivos, byte a byte, com a regra vinculada e sem ela, e check.sh compara as duas árvores a cada execução. Um build recusado não escreve nenhum dist/. Para corrigir uma recusa, a Release muda — uma tag fixada, uma chave de criptografia — e o build seguinte é julgado de novo.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example policy-render-verdictEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd policy-render-verdictBuild
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Troque governance-rego.yaml por governance-cel.yaml para executar a mesma regra no mecanismo CEL, e terraform no nome do arquivo da Release por helm, compose ou cloudformation, com as suas Releases com violação plantada release-helm-unpinned.yaml, release-compose-unpinned.yaml e release-cloudformation-unencrypted.yaml.
O catálogo da biblioteca padrão fornece aqui cada Component, Recipe, Feature e FeatureRecipe, e traz as entidades Plugin dos dois mecanismos. Eles são resolvidos a partir de hub.aggrega.ai, o registry padrão que .aggrega-config.yaml nomeia. Com um checkout do catálogo (onde obter um) nomeado com --catalog, nada é baixado de um registry, então os builds rodam offline. --auto-pull preenche o arquivo de bloqueio de cada Release durante o build; os arquivos de bloqueio e a saída renderizada são gerados, não distribuídos.
A Release de controle Terraform é concluída. A Release com violação plantada é interrompida:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationCada mensagem nomeia o arquivo que a regra julgou, pelo seu caminho em dist/, e o elemento infrator nele. As outras Releases com violação plantada são interrompidas da mesma forma:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedCada linha é a que vem depois de [POLICY_ERROR E0005] na saída do seu build, mostrada a partir da margem esquerda. A primeira vem do mecanismo Rego e as outras duas do mecanismo CEL, cada uma nomeando o mecanismo que a relatou; o outro mecanismo imprime a mesma mensagem com o seu próprio nome.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `policy-render-verdict`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-render-verdict` e sem `dir`: ela grava o exemplo em uma nova pasta `policy-render-verdict`. Em seguida, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a flag `--config` dele, uma vez para cada Release, nesta ordem — `release-terraform.yaml` e `release-terraform-unencrypted.yaml` — cada vez com `workspace_root` definido como `policy-render-verdict`, `release` definido como esse arquivo, `auto_pull` definido como true e `config` definido como `governance-rego.yaml`. O segundo deve ser recusado, então leia para mim a recusa. Diga-me quais arquivos o primeiro build gravou; eles ficam em `policy-render-verdict/dist/`.Verificando cada build
Esta autoverificação é executada em um checkout do repositório da documentação, que contém o script auxiliar de build compartilhado que ela usa; uma cópia escrita por aggrega scaffold --example não traz esse script auxiliar.
./check.shcheck.sh faz o build de cada Release de controle uma vez sem nenhuma política vinculada, como referência, e depois das oito Releases com cada mecanismo, por meio do helper build-release. Uma Release de controle precisa ser concluído e gravar os mesmos arquivos, byte a byte, que a sua referência; uma Release com a violação plantada precisa ser interrompida com E0005 e a mensagem esperada para ela, sem nenhuma outra recusa ao lado, e não gravar nenhum dist/. Os dois mecanismos são obrigados à mesma mensagem. Ele imprime uma linha por build e sai com 1 se algum resultado for diferente, imprimindo a saída desse build:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.Ele usa o binário que ./build-release.sh resolve, então AGGREGA_BIN o escolhe, e os argumentos depois de -- chegam a cada build. Ele se recusa a iniciar enquanto houver um dist/ neste diretório, porque move a árvore de cada build para outro lugar para compará-la, e não deixa nenhuma para trás; os builds preenchem os arquivos de bloqueio deste diretório, como qualquer build faz. O seu status de saída é todo o veredito.
Onde o compilador não interpreta
O compilador renderiza os arquivos de cada destino, entrega-os ao mecanismo vinculado como texto com o formato que o seu provedor declarou, e age conforme a severidade que cada veredito traz. Ele não sabe o que é uma tag de imagem, que latest muda, nem que uma instância RDS deveria estar criptografada: esses significados são da regra. Para os papéis, os payloads e as chaves de decisão, veja o socket de governança.
Arquivos
aggregate.yaml— o banco de dados e o job de relatório conectado a ele.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— associam cada tipo de componente e a Feature de disparo manual às suas Recipes em um destino.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— uma Release de controle e uma violação plantada por destino..aggrega-config.yaml— o registry padrão; nenhuma vinculação de governança.governance-rego.yaml,governance-cel.yaml— a regra vinculada emrender-verdictpor meio de cada mecanismo, cada um nomeado com--config.policies/house-rule.rego,policies/house-rule.cel— a regra, uma vez por mecanismo.build-release.sh— faz o build de uma Release, exibindo o comandoaggrega buildequivalente.check.sh— faz os vinte builds e verifica cada resultado.