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ância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/mariadb | o banco de dados da loja |
web | core/devtool/adminer | uma 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
| quem | arquivo | como um build o lê | onde a vinculação é escrita |
|---|---|---|---|
| a equipe | .aggrega-config.yaml | marca este diretório como o espaço de trabalho, então todo build aqui o lê | plugins.governance |
| a organização | org/config.yaml | como o arquivo de configuração global, nomeado para um único build com --config org/config.yaml | plugins.governance_append |
| o pipeline | pipeline/.aggrega-config-append-ci.yaml | depois de copiado para este diretório, como a sobreposição do pipeline | plugins.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:
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:
| severidade | o 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: infoO 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: haltAssim, 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:
aggrega scaffold --example policy-org-overlayEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd policy-org-overlayBuild
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:
aggrega build --release release.yaml --auto-pullo build imprime o aviso da equipe e é concluído. Com o arquivo da organização também:
aggrega build --release release.yaml --auto-pull --config org/config.yamlele 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 shipPull 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:
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 violationO 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.
./check.shcheck.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 OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + 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 comandoaggrega buildequivalente.check.sh— faz os cinco builds e verifica cada resultado.