Uma política sobre a saída renderizada: uma regra interna, quatro destinos, dois motores
Uma regra interna, anexada no papel render-verdict, julga os ficheiros que uma compilação escreve para quatro destinos e recusa uma violação plantada em cada um. A regra tem duas cláusulas:
Cada imagem de contentor nomeia uma versão fixa — uma tag diferente de
latest, ou um digest. Cada instância de base de dados armazena os seus dados cifrados.
Este espaço de trabalho compila um Aggregate para quatro destinos — Kubernetes através do Helm, Docker Compose, Terraform e CloudFormation. O papel render-verdict julga os ficheiros que uma compilação escreve, depois de cada destino os ter renderizado, e a regra lê a estrutura de saída própria de cada destino: as imagens nos objetos Kubernetes e num ficheiro Compose, a instância RDS num ficheiro Terraform e num template CloudFormation. Cada destino tem uma Release que passa e uma Release com uma violação plantada, que a regra recusa.
A regra está escrita duas vezes, uma para cada motor de políticas compilado na CLI — Rego e CEL — e as duas cópias concordam em cada compilação aqui. Um script ao lado das Releases compila as dezasseis combinações e verifica cada resultado.
aggrega builda sua política
ligada ao compilador
passa
ficheiros escritos
prontos para rever e implementar
falha
compilação interrompida
Uma política pode interromper uma compilação e indicar o que corrigir. Nunca altera os seus ficheiros para os fazer passar.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/postgres | a base de dados de encomendas |
report | core/compute/task | um trabalho de relatório que lê db, iniciado manualmente: contém core/manual-trigger, pelo que nenhuma execução começa quando a Release é implementada |
report lê o endereço, a porta e o nome da base de dados através da sua ligação database, como DB_HOST, DB_PORT e DB_NAME. O Aggregate é o mesmo ficheiro em cada compilação; 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 |
Cada Recipe aqui renderiza apenas a partir do catálogo: a base de dados Kubernetes é sintetizada em vez de obtida como chart, o corpo da base de dados Terraform é escrito pela sua Recipe, e o módulo da tarefa Terraform é mantido ao lado da sua Recipe. Assim, cada compilação é executada offline.
As oito Releases
| Release | destino | o que a regra encontra | a compilação |
|---|---|---|---|
release-helm.yaml | Kubernetes | report executa registry.example.com/orders-report:1.4.2 | é concluída |
release-helm-unpinned.yaml | Kubernetes | report executa a mesma imagem com a tag latest | é interrompida |
release-compose.yaml | Docker Compose | report executa registry.example.com/orders-report:1.4.2 | é concluída |
release-compose-unpinned.yaml | Docker Compose | report executa a imagem sem tag | é interrompida |
release-terraform.yaml | Terraform | a instância é cifrada com a chave que a Release nomeia | é concluída |
release-terraform-unencrypted.yaml | Terraform | a Release não nomeia nenhuma chave, pelo que a instância não é cifrada | é interrompida |
release-cloudformation.yaml | CloudFormation | a Release ativa StorageEncrypted | é concluída |
release-cloudformation-unencrypted.yaml | CloudFormation | a Release deixa-o desativado | é interrompida |
A imagem é da Release: core/compute/task não empacota nenhum software, pelo que a Release nomeia em infra.image a imagem que uma execução corre, tag incluída. Nos dois destinos AWS, a cifragem da base de dados também é da Release. A Recipe Terraform lê infra.overrides.kms_key_id e, quando 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 qualquer atributo de cifragem, que é o que fazem as Releases com violação plantada.
As bases de dados Kubernetes e Compose executam a imagem postgres:16, uma tag fixa, pelo que a regra as julga e as deixa passar em cada Release.
Anexar a regra
.aggrega-config.yaml indica o hub como o seu registo e nenhum diretório do catálogo, e nenhum anexo de governação. A regra é anexada pelo ficheiro que uma compilação nomeia com --config: governance-rego.yaml para o motor Rego, governance-cel.yaml para o motor 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 ficheiro de configuração global para essa execução, em vez daquele que a máquina leria de outro modo, e o .aggrega-config.yaml deste espaço de trabalho continua a sobrepor-se a ele. Uma lista plugins.governance no ficheiro do espaço de trabalho substituiria a que o ficheiro nomeado contém, e é por isso que o ficheiro do espaço de trabalho não declara nenhuma. 0.9.0 é a versão da entidade Plugin de cada motor no catálogo da biblioteca standard. Ambos os motores estão compilados na CLI — aggrega plugin list lista governance/rego e governance/cel entre os plugins integrados incorporados — pelo que nenhuma compilação aqui obtém um plugin.
O que uma política render-verdict lê
Uma política em render-verdict lê os ficheiros que a compilação escreve em input.artifacts, uma entrada por ficheiro, ordenadas por caminho. Cada uma contém:
path— o caminho do ficheiro emdist/, comoterraform/modules/db/main.tf;content— o texto do ficheiro, tal como foi escrito;format— o formato que o fornecedor do destino declarou para o ficheiro:yamlpara o ficheiro Compose,jsonpara o template CloudFormation,hclpara cada ficheiro Terraform, incluindo o corpo da base de dados que a sua Recipe escreve. Onde nada declarou um, é a cadeia vazia, como acontece com os ficheiros Kubernetes aqui;documents— o conteúdo do ficheiro analisado numa estrutura, como uma lista de documentos: um para cada ficheiro aqui;parse_error— presente apenas num ficheiro que não foi possível analisar, em vez dedocuments.
Ao lado dos ficheiros, input.sources contém o próprio ficheiro de política do anexo, e input.settings as suas definições — aqui o objeto vazio, uma vez que este anexo 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 ficheiro é o que o motor recebe, e não o que a política lê: cada ficheiro nele contém o seu path e content e o format que o seu fornecedor declarou, e o motor analisa os documents a partir do conteúdo depois de receber o payload. Assim, o ficheiro lista os ficheiros que serão mostrados a uma regra, mas não os seus documentos. Depois de uma compilação de release-terraform.yaml ter preenchido o seu ficheiro 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 numa compilação, em que o motor os analisou. Nenhum ficheiro que estas Recipes escrevem falha a análise, pelo que nenhum ficheiro aqui contém parse_error. Cada cláusula desta regra lê documents, pelo que um ficheiro que não foi possível analisar passaria por ela sem ser examinado; uma regra que não pode deixar que isso aconteça acrescenta uma cláusula que recusa um ficheiro que contenha parse_error.
Como cada cláusula lê a estrutura do seu destino
Cada cláusula nomeia a estrutura que lê, e um ficheiro de outra estrutura não contém o que a cláusula nomeia: em Rego o caminho é indefinido e a cláusula não se verifica. Assim, uma regra é executada sobre a saída de cada destino e cada cláusula encontra apenas a sua.
Compose escreve um ficheiro 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 contêm os seus contentores num template de pod, que um CronJob contém um nível mais abaixo do 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 uma das suas etiquetas, e a última etiqueta contém uma lista de blocos, porque os blocos que partilham tipo e etiquetas são reunidos numa ú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 perante 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 verifica-se para tudo o que é indefinido: a cláusula recusa também release-terraform.yaml, cuja instância está cifrada, com a mesma mensagem da Release com violação plantada.
Um ficheiro .tf.json é lido tal como a sua Recipe o escreveu, com o nome a conter diretamente o bloco, pelo que uma regra escrita para uma forma não lê a outra. É por isso que a cláusula lê primeiro format: native_hcl aceita um ficheiro cujo formato é hcl, ou cujo formato está vazio e cujo nome termina em .tf — um ficheiro para o qual nenhum fornecedor declarou um formato é analisado pelo nome, pelo que também a regra o reconhece pelo nome, em vez de o ignorar. Cada ficheiro Terraform compilado aqui está declarado como hcl, pelo que nenhum ficheiro aqui é reconhecido pelo nome. Estas Recipes não escrevem nenhum ficheiro .tf.json, pelo que a regra não lê nenhuma outra forma. O que o payload de cada papel expõe apresenta ambas as 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 verifica-se em ambos os casos.
Porque é que a regra CEL é escrita de outra forma
policies/house-rule.cel exprime as mesmas duas cláusulas e chega ao mesmo veredicto em cada compilação aqui. Está escrito de outra forma em três pontos, cada um por uma razão do motor.
Testa cada chave antes de a ler. Ler uma chave que um valor não contém é, em CEL, uma falha de avaliação em vez de um caminho indefinido, e uma falha interrompe a compilação. Aos ficheiros de cada destino faltam chaves que os de outro contêm — um objeto Kubernetes não tem services, um ficheiro Compose não tem kind — pelo que 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, sejam quais forem as imagens que os objetos Kubernetes executam, termina com 1 e não escreve nenhum dist/, e a linha que comunica a falha nomeia o ficheiro 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: servicesComunica um único elemento infrator por ficheiro. Uma chave de decisão recolhe mensagens, e uma expressão CEL não tem forma de juntar numa só lista as listas que constrói por ficheiro. Assim, cada cláusula CEL comunica um elemento infrator em cada ficheiro: o primeiro contentor de um template de pod ou, entre os serviços, instâncias e recursos que um ficheiro indexa pelo nome, aquele cujo nome vem primeiro na ordenação. Uma compreensão percorre um mapa sem ordem fixa, pelo que escolher pelo nome é o que mantém a mensagem igual de uma compilação para a seguinte. A regra Rego comunica todos os elementos infratores. Com dois serviços não fixados num ficheiro Compose, o motor Rego interrompe-se com duas mensagens e o motor CEL com uma, para o serviço cujo nome vem primeiro na ordenação; com um só, como em cada Release aqui, os dois interrompem-se com a mesma mensagem.
Repete-se. CEL não oferece forma de nomear uma subexpressão, pelo que 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 ficheiros são um quase duplicado deliberado, cada um escrito por si a partir da regra acima em vez de gerado um a partir do outro, de modo que uma compilação em que os motores discordam mostre a discordância.
Um veredicto nunca altera a saída
Uma política em render-verdict aceita a compilação ou recusa-a. Recebe os ficheiros que a compilação escreveu e devolve veredictos; nada do que devolve lhes é aplicado. Assim, uma Release de controlo produz os mesmos ficheiros, byte a byte, com a regra anexada e sem ela, e check.sh compara as duas árvores em cada execução. Uma compilação recusada não escreve nenhum dist/. Para corrigir uma recusa, é a Release que muda — uma tag fixada, uma chave de cifragem — e a compilação seguinte é julgada de novo.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example policy-render-verdictDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd policy-render-verdictCompilação
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-se governance-rego.yaml por governance-cel.yaml para executar a mesma regra no motor CEL, e terraform no nome do ficheiro da Release por helm, compose ou cloudformation, com as respetivas Releases com violação plantada release-helm-unpinned.yaml, release-compose-unpinned.yaml e release-cloudformation-unencrypted.yaml.
O catálogo da biblioteca standard fornece aqui cada Component, Recipe, Feature e FeatureRecipe, e contém as entidades Plugin dos dois motores. São resolvidos a partir de hub.aggrega.ai, o registo predefinido que .aggrega-config.yaml nomeia. Com um checkout do catálogo (onde obter um) nomeado com --catalog, nada é obtido de um registo, pelo que as compilações são executadas offline. --auto-pull preenche o ficheiro de bloqueio de cada Release durante a compilação; os ficheiros de bloqueio e a saída renderizada são gerados, não distribuídos.
A Release de controlo 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 ficheiro 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 a seguir a [POLICY_ERROR E0005] na saída da sua compilação, mostrada a partir da margem esquerda. A primeira vem do motor Rego e as outras duas do motor CEL, cada uma a nomear o motor que a comunicou; o outro motor 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-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa 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`: esta escreve o exemplo numa nova pasta `policy-render-verdict`. Em seguida, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a respetiva flag `--config`, uma vez para cada Release, por esta ordem — `release-terraform.yaml` e `release-terraform-unencrypted.yaml` — de cada vez com `workspace_root` definido como `policy-render-verdict`, `release` definido como esse ficheiro, `auto_pull` definido como true e `config` definido como `governance-rego.yaml`. A segunda deve ser recusada, por isso leia-me a recusa. Indique-me que ficheiros a primeira compilação escreveu; encontram-se em `policy-render-verdict/dist/`.Verificar cada compilação
Esta autoverificação é executada num checkout do repositório da documentação, que contém o script auxiliar de compilação partilhado que usa; uma cópia escrita por aggrega scaffold --example não inclui esse script auxiliar.
./check.shcheck.sh faz a compilação de cada Release de controlo uma vez sem nenhuma política anexada, como referência, e depois das oito Releases com cada motor, através do helper build-release. Uma Release de controlo tem de ser concluído e escrever os mesmos ficheiros, byte a byte, que a sua referência; uma Release com a violação plantada tem de ser interrompida com E0005 e a mensagem esperada para ela, sem nenhuma outra recusa ao lado, e não escrever nenhum dist/. Os dois motores são obrigados à mesma mensagem. Imprime uma linha por compilação e termina com 1 se algum resultado for diferente, imprimindo a saída dessa compilação:
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.Usa o binário que ./build-release.sh resolve, pelo que AGGREGA_BIN o escolhe, e os argumentos depois de -- chegam a cada compilação. Recusa-se a arrancar enquanto existir um dist/ neste diretório, porque desloca a árvore de cada compilação para outro lado para a comparar, e não deixa nenhuma para trás; as compilações preenchem os ficheiros de bloqueio deste diretório, como qualquer compilação faz. O seu estado de saída é todo o veredicto.
Onde o compilador não interpreta
O compilador renderiza os ficheiros de cada destino, entrega-os ao motor anexado como texto com o formato que o seu fornecedor declarou, e age de acordo com a severidade que cada veredicto contém. Não sabe o que é uma tag de imagem, que latest muda, nem que uma instância RDS deveria estar cifrada: esses significados pertencem à regra. Para os papéis, os payloads e as chaves de decisão, ver o socket de governação.
Ficheiros
aggregate.yaml— a base de dados e o job de relatório ligado a ela.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— associam cada tipo de componente e a Feature de disparo manual às respetivas Recipes num destino.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— uma Release de controlo e uma violação plantada por destino..aggrega-config.yaml— o registo predefinido; nenhum anexo de governação.governance-rego.yaml,governance-cel.yaml— a regra anexada emrender-verdictatravés de cada motor, cada um nomeado com--config.policies/house-rule.rego,policies/house-rule.cel— a regra, uma vez por motor.build-release.sh— compila uma Release, mostrando o comandoaggrega buildequivalente.check.sh— faz as vinte compilações e verifica cada resultado.