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

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-injector e selector-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ânciaComponent do catálogoo que é aqui
dbcore/datastore/mariadba base de dados da loja
cachecore/datastore/redisa sua cache de sessões
webcore/devtool/admineruma 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:

pluginpapelo que 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 definiçõ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: 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, como core/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ó db declara 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:

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

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

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

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

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

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

Terminal window
cd policy-label-transform

Compilação

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

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

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

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

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

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

Terminal window
./check.sh

check.sh faz quatro compilações através do helper build-release e verifica cada resultado face ao que esta página descreve:

  • release-production.yaml numa cópia deste espaço de trabalho sem nenhum anexo de governação, como referência;
  • release-staging.yaml e release-production.yaml aqui, 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.yaml numa cópia cuja política cobre apenas a categoria datastore, que tem de ser interrompido com E0005 e 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 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 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 comando aggrega build equivalente.
  • check.sh — faz as quatro compilações e verifica cada resultado.