Políticas que moldam rótulos: um nível de suporte por ambiente, e um veredito que o lê
Plugins de governança rotulam cada componente que este espaço de trabalho implanta com o seu proprietário, o nível de suporte que o seu ambiente lhe confere, o seu agendamento de backup e uma tag curta, de modo que nenhum desenvolvedor digita nenhum deles. Os rótulos são derivados durante o build, por quatro vinculações de governança:
- três no papel
label-transform, que moldam os rótulos nos nós do build: uma política Rego que lê o ambiente da Release, e os dois plugins de marcação compilados na CLI,label-injectoreselector-tagger; - uma no papel
ir-verdict, uma política Rego sobre o grafo de build que interrompe um build de produção em que um nó ficou sem nível de suporte.
Duas Releases de um Aggregate diferem no seu ambiente, staging e production, e os seus nós terminam com rótulos diferentes. Um terceiro build, que check.sh faz a partir de uma cópia deste espaço de trabalho cuja política cobre uma categoria a menos, é interrompido e nomeia o nó que ela deixou de fora.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/mariadb | o banco de dados da loja |
cache | core/datastore/redis | o seu cache de sessão |
web | core/devtool/adminer | uma interface de administração de banco de dados, ligada a db |
Os três são compilados para Docker Compose, em dist/compose/docker-compose.yaml. O Aggregate e ambas as Releases não nomeiam nenhum rótulo próprio: cada rótulo abaixo é escrito por uma vinculação.
As quatro vinculações
Elas são vinculadas no .aggrega-config.yaml deste espaço de trabalho, sob plugins.governance, então cada build executado aqui as aplica:
| plugin | papel | o que ele escreve | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, com policies/support-tier.rego | label-transform | ops.example.com/environment em cada nó; ops.example.com/support-tier em cada nó cuja categoria as suas configurações listam |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner em cada nó; backup.example.com/schedule em cada nó da categoria datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, a partir do mapa em policies/tags.yaml |
| 4 | governance/rego:0.9.0, com policies/production-support.rego | ir-verdict | nada: ele interrompe o build ou o deixa ser concluído |
0.9.0 é a versão das três entidades Plugin no catálogo da biblioteca padrão; os próprios plugins são compilados na CLI, e um build os serve a partir dela. aggrega build --release release-production.yaml --auto-pull --detail lista ambos, para cada um dos três:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]As vinculações em um mesmo papel rodam na ordem em que estão listadas, e cada uma lê os rótulos que as anteriores escreveram: o injetor de rótulos recebe os dois rótulos que a política Rego escreveu, e o etiquetador de seletores recebe esses e os do injetor de rótulos. O veredito roda depois das três, sobre o grafo que elas deixam.
O que uma política label-transform lê
Uma política em label-transform lê os nós em input.graph.nodes, indexados por id de nó, cada um com:
component— o Component que o nó instancia, comocore/datastore/mariadb;resolved_version— a versão para a qual esse Component foi resolvido;labels— os rótulos que o nó carrega quando a política roda: os próprios do Component, e os que qualquer transformação anterior escreveu;values— os valores que a instância do nó declara no Aggregate, ausente onde ela não declara nenhum. Aqui sódbdeclara um,database: appdb.
Ela lê a Release em input.compilation_context: release_name e environment. É isso que permite a uma única política decidir de forma diferente por ambiente.
Uma política em ir-verdict lê, em vez disso, o grafo de build inteiro, e os seus nós ficam um nível mais abaixo, em input.graph.spec.nodes. Uma regra movida de um papel para o outro é editada, não copiada: com o caminho errado, ela não lê nada e nunca dispara. O payload de ir-verdict não carrega nenhum compilation_context, então um veredito não pode ler o ambiente a partir da Release. É por isso que a primeira política aqui também escreve ops.example.com/environment em cada nó: o veredito lê o ambiente a partir desse rótulo.
Para ver os payloads em vez de ler sobre eles, faça o build uma vez para que o arquivo de bloqueio exista e, então:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsescreve o payload que cada vinculação recebe em payloads/, um arquivo por vinculação quando várias em um mesmo papel recebem payloads diferentes — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — ao lado de um arquivo para cada outro papel, e não escreve mais nada.
A política Rego
policies/support-tier.rego reúne as suas decisões sob labels, uma por rótulo, cada uma nomeando o nó, a chave do rótulo e o valor:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}As suas configurações são o documento data da política, e contêm o vocabulário da organização:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursO que cada plugin integrado escreve
label-injector aplica uma lista de regras. Um nó cujos rótulos incluem cada par sob o match de uma regra recebe cada par sob o seu set, adicionado, ou substituindo o valor de um rótulo que o nó já carrega. Um match sem pares corresponde a todos os nós. Ele lê as regras da sua configuração rules, como aqui, ou, quando as configurações não trazem nenhuma, do primeiro arquivo sob sources que as traga. As suas duas regras aqui dão a cada nó ops.example.com/owner: shop-team, e a db e cache, os dois nós da categoria datastore, backup.example.com/schedule: nightly. web está na categoria devtool e não recebe nenhum agendamento de backup.
selector-tagger escreve um rótulo, sempre sob a chave tag. O seu valor vem de um mapa de nomes de Component para tags, lido dos arquivos sob sources. Um nó cujo Component o mapa não lista recebe a configuração default, e sem default fica sem tag. policies/tags.yaml mapeia o banco de dados e o cache:
core/datastore/mariadb: orderscore/datastore/redis: sessionse o default da vinculação é untagged, então web recebe a tag untagged.
Ambos decidem apenas a partir dos rótulos de um nó e do seu Component. Nenhum dos dois lê o ambiente, então eles escrevem os mesmos rótulos nas duas Releases.
Ambos servem apenas label-transform. Vinculado em ir-verdict, qualquer um dos dois é recusado antes de rodar; selector-tagger vinculado ali interrompe o build com:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxGerar 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-label-transformEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd policy-label-transformBuild
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullO catálogo da biblioteca padrão fornece aqui cada Component, Recipe e Feature, e as três entidades Plugin. 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 é buscado 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.
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-label-transform`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-label-transform` e sem `dir`: ela grava o exemplo em uma nova pasta `policy-label-transform`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-staging.yaml` e `release-production.yaml` — cada vez com `workspace_root` definido como `policy-label-transform`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `policy-label-transform/dist/`.Os rótulos com que cada nó termina
--ir-graph imprime o grafo de build na saída padrão, antes do resumo do build, e o grafo carrega os rótulos de cada nó tal como as transformações os deixaram. Depois de aggrega build --release release-production.yaml --auto-pull --ir-graph, web diz:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Os três primeiros rótulos são os próprios do Component; os quatro últimos foram escritos pelas três transformações. check.sh lê o grafo de cada build e lista os rótulos que as vinculações escreveram:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedSó os dois rótulos da política Rego mudam entre as Releases.
Depois que um build preencheu o arquivo de bloqueio, aggrega inspect release-production.yaml --ir-graph imprime o mesmo grafo sem fazer o build, antes da sua visão legível da Release, porque as transformações leem os seus arquivos a partir do arquivo de bloqueio. Sem o arquivo de bloqueio, o grafo que ele imprime não carrega nenhum dos rótulos que esses arquivos decidem: nenhum ops.example.com/environment ou ops.example.com/support-tier, e tag: untagged em cada nó.
Uma transformação muda rótulos, e nada mais
Uma decisão em label-transform nomeia um nó, uma chave de rótulo e o seu valor, ou pede que um rótulo seja removido. Não existe decisão que adicione um nó, mude o Component ou a versão de um nó, ou toque nos seus valores, então uma transformação não pode expressar nada disso. Uma decisão que nomeia um nó que o build não tem não é ignorada: o build é interrompido com E0069 e nomeia o nó e o rótulo que não pôde definir.
Os dois builds de release-production.yaml, com essas vinculações e sem nenhuma, mostram isso. Os seus grafos de build diferem nos rótulos listados acima e em nada mais. A sua saída renderizada não difere em nada: as Recipes Compose aqui não renderizam nenhum desses rótulos, então dist/compose/docker-compose.yaml é o mesmo arquivo, byte a byte, com as vinculações e sem elas, e check.sh compara as duas árvores a cada execução. Os rótulos vivem no grafo de build, onde o veredito os lê.
O veredito, e o build que ele interrompe
policies/production-support.rego é vinculada em ir-verdict, depois das transformações, e lê os rótulos que elas escreveram:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Ambas as Releases fazem build: em staging o veredito não pede nada, e em produção cada nó carrega um nível. Restrinja a cobertura da política, e o veredito detecta o nó que ela deixa de fora. Com supported_categories escrito [datastore] em .aggrega-config.yaml, web não recebe nenhum nível de suporte, e aggrega build --release release-production.yaml --auto-pull é interrompido:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationO build sai com 1 e não escreve nenhum dist/. release-staging.yaml continua fazendo build com a política restrita: os seus nós são rotulados staging, e o veredito não pede nada a eles. check.sh faz esse build em uma cópia do espaço de trabalho, então nada aqui precisa ser editado para vê-lo.
Um veredito aceita ou recusa e não faz mais nada: ele não pode adicionar o rótulo ausente para fazer o build passar. Qual rótulo um nó de produção deve carregar é a regra da organização, escrita na sua política; o compilador leva os rótulos ao grafo como strings e não lhes atribui nenhum significado.
O que o lockfile registra
O arquivo de bloqueio registra os dois tipos de vinculação de forma diferente. Depois de um build de produção, release-production.lock carrega cada vinculação de transformação sob mutators: — o seu plugin, o seu papel, as suas configurações, e o conteúdo e o digest de cada um dos seus arquivos — e fixa cada plugin de transformação sob plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0A vinculação do veredito aparece apenas sob verdict_inputs:, pelo sha256 do seu arquivo:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoUma vinculação de veredito não é fixada. Com o veredito vinculado sozinho — as três transformações removidas de .aggrega-config.yaml — o arquivo de bloqueio carrega mutators: [] e plugins: [], e o arquivo do veredito sob verdict_inputs:. Uma transformação muda o build com que o resto do pipeline trabalha, então o arquivo de bloqueio guarda o plugin que fez a mudança; um veredito decide apenas se o build é concluído.
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 quatro builds por meio do helper build-release e verifica cada resultado em relação ao que esta página descreve:
release-production.yamlem uma cópia deste espaço de trabalho sem nenhuma vinculação de governança, como referência;release-staging.yamlerelease-production.yamlaqui, cada um dos quais precisa ser concluído com os rótulos listados acima em cada nó, com a árvore de produção idêntica byte a byte à da referência;release-production.yamlem uma cópia cuja política cobre apenas a categoriadatastore, que precisa ser interrompido comE0005e a frase acima, sem nenhuma outra recusa ao lado.
Ele imprime uma linha por build, depois os rótulos, e sai com 1 se algum resultado for diferente, imprimindo a saída desse build:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.As duas cópias são criadas em um diretório temporário, com o caminho do catálogo no seu .aggrega-config.yaml tornado absoluto para que ainda seja resolvido a partir dali. Nenhum arquivo neste diretório é editado; os dois builds feitos aqui preenchem os seus arquivos de bloqueio, como qualquer build faz. 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 compara as árvores que os builds escrevem, e não deixa nenhuma para trás. O seu status de saída é todo o veredito.
Onde o compilador não interpreta
O compilador entrega a cada transformação os nós e o ambiente da Release, aplica os rótulos que ela decide e entrega o resultado ao veredito. Ele não sabe o que é um nível de suporte, que on-call está acima de office-hours, nem que um devtool precisa de um: esses significados são as configurações e as regras das políticas. Para os papéis, os payloads e como uma política nomeia um rótulo, veja o socket de governança, e para onde a política se situa no produto, Governança e conformidade.
Arquivos
aggregate.yaml— o banco de dados, o cache e a interface de administração conectada ao banco de dados; nenhum rótulo.manifest.yaml— associa cada tipo de componente e a Feature de secret à sua Recipe do Docker Compose. Compartilhado pelas duas Releases.release-staging.yaml,release-production.yaml— os dois ambientes..aggrega-config.yaml— o registry padrão e as quatro vinculações de governança.policies/support-tier.rego— a política label-transform.policies/production-support.rego— o veredito.policies/tags.yaml— o mapa de componentes para tags do etiquetador de seletores.build-release.sh— faz o build de uma Release, exibindo o comandoaggrega buildequivalente.check.sh— faz os quatro builds e verifica cada resultado.