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

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 build

sua política

conectada ao compilador

passa

arquivos escritos

prontos para revisar e implantar

falha

build interrompido

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

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ânciaComponent do catálogoo que é aqui
dbcore/datastore/postgreso banco de dados de pedidos
reportcore/compute/taskum 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:

Manifestdbreport
manifest-helm.yamlhelm/postgres, um StatefulSethelm/task, um CronJob mantido suspenso
manifest-compose.yamlcompose/postgres, um serviçocompose/task, um serviço atrás de um perfil
manifest-terraform.yamlterraform/postgres-rds, uma instância RDSterraform/task-ecs, uma definição de tarefa do Amazon ECS
manifest-cloudformation.yamlcloudformation/postgres-rds, uma instância RDScloudformation/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

Releasedestinoo que a regra encontrao build
release-helm.yamlKubernetesreport executa registry.example.com/orders-report:1.4.2é concluído
release-helm-unpinned.yamlKubernetesreport executa a mesma imagem com a tag latesté interrompido
release-compose.yamlDocker Composereport executa registry.example.com/orders-report:1.4.2é concluído
release-compose-unpinned.yamlDocker Composereport executa a imagem sem tagé interrompido
release-terraform.yamlTerraforma instância é criptografada com a chave que a Release nomeiaé concluído
release-terraform-unencrypted.yamlTerraforma Release não nomeia nenhuma chave, então a instância não é criptografadaé interrompido
release-cloudformation.yamlCloudFormationa Release ativa StorageEncryptedé concluído
release-cloudformation-unencrypted.yamlCloudFormationa 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 em dist/, como terraform/modules/db/main.tf;
  • content — o texto do arquivo, como foi escrito;
  • format — o formato que o provedor do destino declarou para o arquivo: yaml para o arquivo Compose, json para o template CloudFormation, hcl para 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 de documents.

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:

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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: services

Ela 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:

Terminal window
aggrega scaffold --example policy-render-verdict

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd policy-render-verdict

Build

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Troque 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 violation

Cada 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 latest
policy 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 latest
policy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted

Cada 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.

Terminal window
./check.sh

check.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 OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel 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 em render-verdict por 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 comando aggrega build equivalente.
  • check.sh — faz os vinte builds e verifica cada resultado.