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

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 build

a sua política

ligada ao compilador

passa

ficheiros escritos

prontos para rever e implementar

falha

compilação interrompida

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

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

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

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

Releasedestinoo que a regra encontraa compilação
release-helm.yamlKubernetesreport executa registry.example.com/orders-report:1.4.2é concluída
release-helm-unpinned.yamlKubernetesreport executa a mesma imagem com a tag latesté interrompida
release-compose.yamlDocker Composereport executa registry.example.com/orders-report:1.4.2é concluída
release-compose-unpinned.yamlDocker Composereport executa a imagem sem tagé interrompida
release-terraform.yamlTerraforma instância é cifrada com a chave que a Release nomeiaé concluída
release-terraform-unencrypted.yamlTerraforma Release não nomeia nenhuma chave, pelo que a instância não é cifradaé interrompida
release-cloudformation.yamlCloudFormationa Release ativa StorageEncryptedé concluída
release-cloudformation-unencrypted.yamlCloudFormationa 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 em dist/, como terraform/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: yaml para o ficheiro Compose, json para o template CloudFormation, hcl para 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 de documents.

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:

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

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

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd policy-render-verdict

Compilação

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

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

Terminal window
./check.sh

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

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 em render-verdict atravé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 comando aggrega build equivalente.
  • check.sh — faz as vinte compilações e verifica cada resultado.