Políticas que moldam etiquetas: um nível de suporte por ambiente, e um veredicto que o lê
Plugins de governação etiquetam cada componente que este espaço de trabalho implementa com o seu proprietário, o nível de suporte que o seu ambiente lhe confere, o seu agendamento de cópias de segurança e uma tag curta, para que nenhum programador escreva nenhum deles. As etiquetas são derivadas durante a compilação, por quatro anexos de governação:
- três no papel
label-transform, que moldam as etiquetas nos nós da compilação: uma política Rego que lê o ambiente da Release, e os dois plugins de marcação compilados na CLI,label-injectoreselector-tagger; - um no papel
ir-verdict, uma política Rego sobre o grafo de compilação que interrompe uma compilação 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 acabam com etiquetas diferentes. Uma terceira compilação, que check.sh faz a partir de uma cópia deste espaço de trabalho cuja política abrange uma categoria a menos, é interrompida e nomeia o nó que deixou de fora.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/mariadb | a base de dados da loja |
cache | core/datastore/redis | a sua cache de sessões |
web | core/devtool/adminer | uma interface de administração de bases 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 nenhuma etiqueta própria: cada etiqueta abaixo é escrita por um anexo.
Os quatro anexos
São anexados no .aggrega-config.yaml deste espaço de trabalho, sob plugins.governance, pelo que cada compilação executada aqui os aplica:
| plugin | papel | o que 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 definiçõ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: interrompe a compilação ou deixa-a concluir-se |
0.9.0 é a versão das três entidades Plugin no catálogo da biblioteca standard; os próprios plugins estão compilados na CLI, e uma compilação serve-os 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]Os anexos num mesmo papel são executados pela ordem em que estão listados, e cada um lê as etiquetas que os anteriores escreveram: o injetor de etiquetas recebe as duas etiquetas que a política Rego escreveu, e o etiquetador de seletores recebe essas e as do injetor de etiquetas. O veredicto é executado depois dos três, sobre o grafo que 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— as etiquetas que o nó contém quando a política é executada: as próprias do Component, e as que qualquer transformação anterior tenha escrito;values— os valores que a instância do nó declara no Aggregate, ausente onde não declara nenhum. Aqui sódbdeclara um,database: appdb.
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 compilação 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, não lê nada e nunca dispara. O payload de ir-verdict não contém nenhum compilation_context, pelo que um veredicto 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 veredicto lê o ambiente a partir dessa etiqueta.
Para ver os payloads em vez de ler sobre eles, compile uma vez para que o ficheiro de bloqueio exista e, depois:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsescreve o payload que cada anexo recebe em payloads/, um ficheiro por anexo quando vários num 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 ficheiro 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 etiqueta, cada uma a nomear o nó, a chave da etiqueta 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 definições são o documento data da política, e contêm o vocabulário do parque:
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ó cujas etiquetas incluem cada par sob o match de uma regra recebe cada par sob o seu set, acrescentado, ou em substituição do valor de uma etiqueta que o nó já contém. Um match sem pares corresponde a todos os nós. Lê as regras da sua definição rules, como aqui, ou, quando as definições não contêm nenhuma, do primeiro ficheiro sob sources que as contenha. As suas duas regras dão aqui 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 cópias de segurança.
selector-tagger escreve uma etiqueta, sempre sob a chave tag. O seu valor vem de um mapa de nomes de Component para tags, lido dos ficheiros sob sources. Um nó cujo Component o mapa não lista recebe a definição default, e sem default fica sem tag. policies/tags.yaml mapeia a base de dados e a cache:
core/datastore/mariadb: orderscore/datastore/redis: sessionse o default do anexo é untagged, pelo que web recebe a tag untagged.
Ambos decidem apenas a partir das etiquetas de um nó e do seu Component. Nenhum dos dois lê o ambiente, pelo que escrevem as mesmas etiquetas nas duas Releases.
Ambos servem apenas label-transform. Anexado em ir-verdict, qualquer um dos dois é recusado antes de ser executado; selector-tagger anexado aí interrompe a compilação 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
É 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-label-transformDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd policy-label-transformCompilação
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullO catálogo da biblioteca standard fornece aqui cada Component, Recipe e Feature, e as três entidades Plugin. 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.
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-label-transform`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-label-transform` e sem `dir`: esta escreve o exemplo numa nova pasta `policy-label-transform`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-staging.yaml` e `release-production.yaml` — de cada vez com `workspace_root` definido como `policy-label-transform`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada compilação escreveu; encontram-se em `policy-label-transform/dist/`.As etiquetas com que cada nó acaba
--ir-graph imprime o grafo de compilação na saída padrão, antes do resumo da compilação, e o grafo contém as etiquetas de cada nó tal como as transformações as 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]}As três primeiras etiquetas são as próprias do Component; as quatro últimas foram escritas pelas três transformações. check.sh lê o grafo de cada compilação e lista as etiquetas que os anexos 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ó as duas etiquetas da política Rego mudam entre as Releases.
Depois de uma compilação ter preenchido o ficheiro de bloqueio, aggrega inspect release-production.yaml --ir-graph imprime o mesmo grafo sem compilar, antes da sua vista legível da Release, porque as transformações leem os seus ficheiros a partir do ficheiro de bloqueio. Sem o ficheiro de bloqueio, o grafo que imprime não contém nenhuma das etiquetas que esses ficheiros decidem: nenhum ops.example.com/environment ou ops.example.com/support-tier, e tag: untagged em cada nó.
Uma transformação altera etiquetas, e nada mais
Uma decisão em label-transform nomeia um nó, uma chave de etiqueta e o seu valor, ou pede que uma etiqueta seja removida. Não existe nenhuma decisão que acrescente um nó, altere o Component ou a versão de um nó, ou toque nos seus valores, pelo que uma transformação não pode exprimir nada disso. Uma decisão que nomeia um nó que a compilação não tem não é ignorada: a compilação é interrompida com E0069 e nomeia o nó e a etiqueta que não conseguiu definir.
As duas compilações de release-production.yaml, com estes anexos e sem nenhum, mostram-no. Os seus grafos de compilação diferem nas etiquetas listadas acima e em mais nada. A sua saída renderizada não difere em nada: as Recipes Compose aqui não renderizam nenhuma destas etiquetas, pelo que dist/compose/docker-compose.yaml é o mesmo ficheiro, byte a byte, com os anexos e sem eles, e check.sh compara as duas árvores em cada execução. As etiquetas vivem no grafo de compilação, onde o veredicto as lê.
O veredicto, e a compilação que interrompe
policies/production-support.rego está anexada em ir-verdict, depois das transformações, e lê as etiquetas que estas 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 compilam: em staging o veredicto não pede nada, e em produção cada nó contém um nível. Restrinja-se a cobertura da política, e o veredicto apanha 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 violationA compilação termina com 1 e não escreve nenhum dist/. release-staging.yaml continua a compilar com a política restringida: os seus nós estão etiquetados com staging, e o veredicto não lhes pede nada. check.sh faz esta compilação numa cópia do espaço de trabalho, pelo que nada aqui tem de ser editado para a ver.
Um veredicto aceita ou recusa e não faz mais nada: não pode acrescentar a etiqueta em falta para fazer a compilação passar. Que etiqueta um nó de produção tem de conter é a regra do parque, escrita na sua política; o compilador leva as etiquetas ao grafo como cadeias de caracteres e não lhes atribui nenhum significado.
O que o lockfile regista
O ficheiro de bloqueio regista os dois tipos de anexo de forma diferente. Depois de uma compilação de produção, release-production.lock contém cada anexo de transformação sob mutators: — o seu plugin, o seu papel, as suas definições, e o conteúdo e o digest de cada um dos seus ficheiros — 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.0O anexo do veredicto aparece apenas sob verdict_inputs:, pelo sha256 do seu ficheiro:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoUm anexo de veredicto não é fixado. Com o veredicto anexado sozinho — as três transformações removidas de .aggrega-config.yaml — o ficheiro de bloqueio contém mutators: [] e plugins: [], e o ficheiro do veredicto sob verdict_inputs:. Uma transformação altera a compilação a partir da qual trabalha o resto do pipeline, pelo que o ficheiro de bloqueio guarda o plugin que fez a alteração; um veredicto decide apenas se a compilação é concluída.
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 quatro compilações através do helper build-release e verifica cada resultado face ao que esta página descreve:
release-production.yamlnuma cópia deste espaço de trabalho sem nenhum anexo de governação, como referência;release-staging.yamlerelease-production.yamlaqui, cada um dos quais tem de ser concluído com as etiquetas listadas acima em cada nó, com a árvore de produção idêntica byte a byte à da referência;release-production.yamlnuma cópia cuja política cobre apenas a categoriadatastore, que tem de ser interrompido comE0005e a frase acima, sem nenhuma outra recusa ao lado.
Imprime uma linha por compilação, depois as etiquetas, e termina com 1 se algum resultado for diferente, imprimindo a saída dessa compilação:
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 num diretório temporário, com o caminho do catálogo no seu .aggrega-config.yaml tornado absoluto para que continue a ser resolvido a partir daí. Nenhum ficheiro neste diretório é editado; as duas compilações feitas aqui preenchem os seus ficheiros de bloqueio, como qualquer compilação faz. 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 compara as árvores que as compilações escrevem, e não deixa nenhuma para trás. O seu estado de saída é todo o veredicto.
Onde o compilador não interpreta
O compilador entrega a cada transformação os nós e o ambiente da Release, aplica as etiquetas que esta decide e entrega o resultado ao veredicto. 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 definições e as regras das políticas. Para os papéis, os payloads e a forma como uma política nomeia uma etiqueta, ver o socket de governação, e para o lugar da política no produto, Governação e conformidade.
Ficheiros
aggregate.yaml— a base de dados, a cache e a interface de administração ligada à base de dados; nenhuma etiqueta.manifest.yaml— associa cada tipo de componente e a Feature de secret à sua Recipe do Docker Compose. Partilhado pelas duas Releases.release-staging.yaml,release-production.yaml— os dois ambientes..aggrega-config.yaml— o registo predefinido e os quatro anexos de governação.policies/support-tier.rego— a política label-transform.policies/production-support.rego— o veredicto.policies/tags.yaml— o mapa de componentes para tags do etiquetador de seletores.build-release.sh— compila uma Release, mostrando o comandoaggrega buildequivalente.check.sh— faz as quatro compilações e verifica cada resultado.