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

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-injector e selector-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ânciaComponent do catálogoo que é aqui
dbcore/datastore/mariadbo banco de dados da loja
cachecore/datastore/rediso seu cache de sessão
webcore/devtool/admineruma 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:

pluginpapelo que ele escreve
1governance/rego:0.9.0, com policies/support-tier.regolabel-transformops.example.com/environment em cada nó; ops.example.com/support-tier em cada nó cuja categoria as suas configurações listam
2governance/label-injector:0.9.0label-transformops.example.com/owner em cada nó; backup.example.com/schedule em cada nó da categoria datastore
3governance/selector-tagger:0.9.0label-transformtag, a partir do mapa em policies/tags.yaml
4governance/rego:0.9.0, com policies/production-support.regoir-verdictnada: 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, como core/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ó db declara 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:

Terminal window
aggrega build --release release-production.yaml --dry-run --policy-input payloads

escreve 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-hours

O 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: orders
core/datastore/redis: sessions

e 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 sandbox

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-label-transform

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

Terminal window
cd policy-label-transform

Build

Terminal window
aggrega build --release release-staging.yaml --auto-pull
aggrega build --release release-production.yaml --auto-pull

O 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: untagged

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

O 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.0

A 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.rego

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

Terminal window
./check.sh

check.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.yaml em uma cópia deste espaço de trabalho sem nenhuma vinculação de governança, como referência;
  • release-staging.yaml e release-production.yaml aqui, 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.yaml em uma cópia cuja política cobre apenas a categoria datastore, que precisa ser interrompido com E0005 e 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 OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-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 comando aggrega build equivalente.
  • check.sh — faz os quatro builds e verifica cada resultado.