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ítica para toda a organização: a regra de uma equipe, a de uma organização e a de um pipeline

A política de uma equipe, a da sua organização e a do seu pipeline são executadas juntas em um mesmo build, cada uma vinculada em um arquivo de configuração próprio. A equipe vincula a sua regra no seu espaço de trabalho; a organização adiciona uma em cada build, e o pipeline adiciona mais uma, sem que nenhum dos dois edite o arquivo da equipe. Um build lê todos os arquivos que se aplicam a ele e executa cada vinculação que eles contêm.

As regras reportam com as três severidades de veredito: info e warn deixam o build ser concluído, e halt o interrompe. Uma delas, a da organização, é vinculada duas vezes e reportada com uma severidade diferente a cada vez, por meio de um bloco translation.

O que ele constrói

instânciaComponent do catálogoo que é aqui
dbcore/datastore/mariadbo banco de dados da loja
webcore/devtool/admineruma interface de administração de banco de dados, ligada a db

Ambos são compilados para Docker Compose, em dist/compose/docker-compose.yaml. Um Aggregate, um Manifest e uma Release, release.yaml; nenhum deles nomeia uma política.

Os três arquivos

quemarquivocomo um build o lêonde a vinculação é escrita
a equipe.aggrega-config.yamlmarca este diretório como o espaço de trabalho, então todo build aqui o lêplugins.governance
a organizaçãoorg/config.yamlcomo o arquivo de configuração global, nomeado para um único build com --config org/config.yamlplugins.governance_append
o pipelinepipeline/.aggrega-config-append-ci.yamldepois de copiado para este diretório, como a sobreposição do pipelineplugins.governance_append

As três vinculações são o mecanismo Rego, governance/rego:0.9.0, no papel ir-verdict, que julga o grafo de build antes que qualquer coisa seja renderizada. 0.9.0 é a versão da sua entidade Plugin no catálogo da biblioteca padrão. O próprio mecanismo é compilado na CLI — aggrega plugin list lista governance/rego entre os built-ins embutidos —, então nenhum build aqui busca um plugin.

O arquivo da organização é um arquivo de configuração global. Uma máquina tem um, lido em todo build: a partir do seu local padrão, ou o arquivo que a variável de ambiente AGGREGA_CONFIG nomeia. --config <path> nomeia, em vez disso, um para uma única execução, e os próprios arquivos do espaço de trabalho continuam sendo lidos por cima dele. Em uma organização, o arquivo ficaria no local padrão na máquina de cada desenvolvedor e em cada pipeline; aqui ele fica em org/, e os builds que devem lê-lo o nomeiam. Nomear o arquivo global explicitamente expõe a ordem em que as três formas são tentadas.

O arquivo do pipeline é uma sobreposição. Um build lê .aggrega-config-append-ci.yaml nos diretórios dos quais lê .aggrega-config.yaml, ao lado dele. Ele é mantido aqui em pipeline/, onde um build executado neste diretório não o lê, porque ele interrompe todo build que o lê; a etapa do pipeline é copiá-lo para dentro:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .

Cada arquivo adiciona, e a sobreposição do pipeline apenas adiciona

A organização e o pipeline escrevem ambos a sua vinculação em plugins.governance_append, a contraparte de adição da lista plugins.governance. As entradas em uma contraparte são concatenadas à lista resolvida depois que as próprias listas de cada arquivo são lidas, então o plugins.governance da equipe e a entrada da organização são ambos executados, e nenhum dos dois arquivos nomeia o outro. A organização escreve a contraparte, e não o próprio plugins.governance, porque uma lista plugins.governance no arquivo do espaço de trabalho substitui a do arquivo global: uma regra da organização escrita ali é descartada pela lista da equipe, e o build não imprime nada sobre isso. Estender uma lista em vez de substituí-la lista a contraparte de cada configuração de lista.

A sobreposição do pipeline só pode adicionar. O que ela escreve para uma configuração de lista é adicionado ao que os outros arquivos resolveram; ela não remove nada e não sobrescreve uma configuração que contém um único valor, como auto_pull. Esta traz auto_pull: true, e um build que a lê ignora a chave e informa isso em um aviso. Com <workspace> representando o caminho absoluto do diretório em que o build foi executado, a linha diz:

warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)

As regras, e a severidade com que cada uma é reportada

Uma política Rego reúne cada decisão sob uma chave de decisão, e a chave escolhe a severidade com que a decisão é reportada. Sem translation, as chaves são deny, warn e audit, reportadas com halt, warn e info:

severidadeo que o build faz
halté interrompido, sai com 1 e não escreve nenhum dist/
warné concluído, imprime a mensagem e escreve dist/
infoé concluído, imprime a mensagem e escreve dist/

A regra da equipe, policies/team.rego, reúne sob warn, e a sua vinculação não declara nenhuma translation, então ela é reportada com warn:

warn contains msg if {
some id, node in input.graph.spec.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v runs with high availability off", [id])
}

A regra da organização, org/policies/estate.rego, recusa componentes em uma categoria que as suas configurações listam, e registra o que cada componente executa:

deny contains msg if {
some id, node in input.graph.spec.nodes
category := node.labels["component.aggrega.ai/category"]
category in data.refused_categories
msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])
}
audit contains msg if {
some id, node in input.graph.spec.nodes
msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])
}

refused_categories é uma configuração de cada vinculação, e uma política lê as configurações da sua vinculação como o seu documento data.

Tradução: uma regra, duas severidades

Um bloco translation nas configurações de uma vinculação declara quais chaves de decisão são lidas e a severidade com que cada uma é reportada. Ele substitui o mapeamento padrão em vez de estendê-lo: uma chave que ele não nomeia não é lida.

O arquivo da organização introduz a sua regra como recomendação. A sua vinculação reporta deny com warn, e audit com info:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: warn
- key: audit
severity: info

O pipeline vincula o mesmo arquivo e faz com que a mesma regra interrompa o build. A sua tradução nomeia apenas deny, então a sua vinculação não reporta uma segunda vez os registros audit:

settings:
refused_categories: [devtool]
translation:
- key: deny
severity: halt

Assim, uma única regra, sobre o mesmo web, é um aviso no build de um desenvolvedor e o motivo pelo qual o build de um pipeline é interrompido.

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-org-overlay

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

Terminal window
cd policy-org-overlay

Build

O catálogo da biblioteca padrão fornece os Components, as Recipes, a Feature e a sua FeatureRecipe. 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 durante o build; o arquivo de bloqueio e a saída renderizada são gerados, não distribuídos.

Apenas com o arquivo da equipe:

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

o build imprime o aviso da equipe e é concluído. Com o arquivo da organização também:

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

ele imprime os registros da organização com info e a sua regra com warn, ao lado do aviso da equipe, e ainda assim é concluído:

info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Cada veredito nomeia o plugin que o reportou, rego, e não o arquivo que o vinculou, então o aviso da equipe e o da organização são lidos da mesma forma; uma mensagem que diz de quem é a regra, como faz a da organização, é a forma de distingui-los.

Com a sobreposição do pipeline copiada para dentro, o mesmo comando é interrompido:

Terminal window
cp pipeline/.aggrega-config-append-ci.yaml .
aggrega build --release release.yaml --auto-pull --config org/config.yaml
[… omitted: the overlay's warning shown above]
[… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them]
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
policy plugin "rego" warning: db runs with high availability off
policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship
caused by: policy violation

O build sai com 1 e não escreve nenhum dist/. A regra da organização é reportada duas vezes, uma por cada vinculação: com warn pela da organização e com halt pela do pipeline. Os registros audit aparecem uma vez, apenas a partir da vinculação da organização. Remova .aggrega-config-append-ci.yaml deste diretório para fazer o build sem ela novamente.

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-org-overlay`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-org-overlay` e sem `dir`: ela grava o exemplo em uma nova pasta `policy-org-overlay`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `policy-org-overlay`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true, e diga-me o que a política relatou. Depois, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a flag `--config` dele, com `workspace_root` definido como `policy-org-overlay`, `release` definido como `release.yaml`, `auto_pull` definido como true e `config` definido como `org/config.yaml`, e diga-me o que a política relatou desta vez. Diga-me quais arquivos cada build gravou; eles ficam em `policy-org-overlay/dist/`.

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 o build de release.yaml cinco vezes, por meio do helper build-release, cada uma em uma cópia deste espaço de trabalho: apenas com o arquivo da equipe, com o arquivo da organização nomeado por --config, com a sobreposição do pipeline copiada para dentro, com ambos, e com uma cópia do arquivo da organização que escreve a sua vinculação em plugins.governance em vez da contraparte — onde a lista da equipe a substitui, e apenas o veredito da equipe é impresso. Para cada um, ele verifica o status de saída, se dist/ foi escrito, e cada veredito que o build imprimiu — a sua severidade e a sua mensagem, sem nada faltando e nada a mais — e, onde a sobreposição é lida, o aviso que nomeia auto_pull. Ele imprime uma linha por build, depois os vereditos que cada um imprimiu, e sai com 1 se algum resultado for diferente, imprimindo a saída desse build:

LAYERS EXIT DIST VERDICT
----------------------------------------------------------------------------------------------------
team 0 yes OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + organization, plugins.governance 0 yes OK
team:
warn db runs with high availability off
team + organization:
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline:
ignored auto_pull
warn db runs with high availability off
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three:
ignored auto_pull
info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved
info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved
warn db runs with high availability off
warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance:
warn db runs with high availability off
check: every build ended as expected.

As 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 ou escrito. 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. O seu status de saída é todo o veredito.

Onde o compilador não interpreta

O compilador lê os três arquivos, concatena as vinculações que eles contêm, entrega a cada política o grafo de build e as suas configurações, e age de acordo com a severidade com que cada decisão é reportada. Ele não sabe o que é um devtool, por que uma organização não distribuiria um, nem que a alta disponibilidade importa para uma equipe: esses significados são as regras e as configurações das políticas. Para os papéis, os payloads e as chaves de decisão, veja o socket de governança.

Arquivos

  • aggregate.yaml — o banco de dados e a interface de administração conectada a ele.
  • manifest.yaml — associa cada tipo de componente e a Feature de secret à sua Recipe do Docker Compose.
  • release.yaml — a única Release.
  • .aggrega-config.yaml — o arquivo da equipe: o registry padrão e a vinculação da equipe.
  • policies/team.rego — a regra da equipe.
  • org/config.yaml — o arquivo de configuração global da organização e a sua vinculação.
  • org/policies/estate.rego — a regra da organização.
  • pipeline/.aggrega-config-append-ci.yaml — a sobreposição do pipeline, lida depois de copiada para este diretório.
  • build-release.sh — faz o build da Release, exibindo o comando aggrega build equivalente.
  • check.sh — faz os cinco builds e verifica cada resultado.