Política à escala da organização: a regra de uma equipa, a de uma organização e a de um pipeline
A política de uma equipa, a da sua organização e a do seu pipeline são executadas em conjunto numa mesma compilação, cada uma anexada num ficheiro de configuração próprio. A equipa anexa a sua regra no seu espaço de trabalho; a organização acrescenta uma em cada compilação, e o pipeline acrescenta mais uma, sem que nenhum dos dois edite o ficheiro da equipa. Uma compilação lê todos os ficheiros que se lhe aplicam e executa cada anexo que estes contêm.
As regras reportam com as três severidades de veredicto: info e warn deixam a compilação concluir-se, e halt interrompe-a. Uma delas, a da organização, é anexada duas vezes e reportada com uma severidade diferente de cada vez, através de um bloco translation.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
db | core/datastore/mariadb | a base de dados da loja |
web | core/devtool/adminer | uma interface de administração de bases 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 ficheiros
| quem | ficheiro | como uma compilação o lê | onde o anexo é escrito |
|---|---|---|---|
| a equipa | .aggrega-config.yaml | marca este diretório como o espaço de trabalho, pelo que todas as compilações aqui o leem | plugins.governance |
| a organização | org/config.yaml | como o ficheiro de configuração global, indicado para uma única compilação 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 |
Os três anexos são o motor Rego, governance/rego:0.9.0, no papel ir-verdict, que julga o grafo de compilação antes de qualquer coisa ser renderizada. 0.9.0 é a versão da sua entidade Plugin no catálogo da biblioteca standard. O próprio motor está compilado na CLI — aggrega plugin list lista governance/rego entre os built-ins incorporados —, pelo que nenhuma compilação aqui obtém um plugin.
O ficheiro da organização é um ficheiro de configuração global. Uma máquina tem um, lido em cada compilação: a partir da sua localização predefinida, ou o ficheiro que a variável de ambiente AGGREGA_CONFIG indica. --config <path> indica, em vez disso, um para uma única execução, e os próprios ficheiros do espaço de trabalho continuam a ser lidos por cima dele. Numa organização, o ficheiro estaria na localização predefinida na máquina de cada programador e em cada pipeline; aqui está em org/, e as compilações que o devem ler indicam-no. Indicar explicitamente o ficheiro global expõe a ordem pela qual as três formas são tentadas.
O ficheiro do pipeline é uma sobreposição. Uma compilação lê .aggrega-config-append-ci.yaml nos diretórios a partir dos quais lê .aggrega-config.yaml, ao lado deste. É guardado aqui em pipeline/, onde uma compilação executada neste diretório não o lê, porque interrompe todas as compilações que o leem; a etapa do pipeline consiste em copiá-lo para cá:
cp pipeline/.aggrega-config-append-ci.yaml .Cada ficheiro acrescenta, e a sobreposição do pipeline só acrescenta
A organização e o pipeline escrevem ambos o seu anexo em plugins.governance_append, a contraparte de acréscimo da lista plugins.governance. As entradas numa contraparte são concatenadas à lista resolvida depois de lidas as listas próprias de cada ficheiro, pelo que o plugins.governance da equipa e a entrada da organização são ambos executados, e nenhum dos dois ficheiros nomeia o outro. A organização escreve a contraparte, e não o próprio plugins.governance, porque uma lista plugins.governance no ficheiro do espaço de trabalho substitui a do ficheiro global: uma regra da organização escrita aí é descartada pela lista da equipa, e a compilação não imprime nada sobre isso. Estender uma lista em vez de a substituir lista a contraparte de cada definição de lista.
A sobreposição do pipeline só pode acrescentar. O que escreve para uma definição de lista é acrescentado ao que os outros ficheiros resolveram; não remove nada, e não substitui uma definição que contém um único valor, como auto_pull. Esta contém auto_pull: true, e uma compilação que a lê ignora a chave e indica-o num aviso. Com <workspace> a representar o caminho absoluto do diretório em que a compilação foi executada, 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 a compilação faz |
|---|---|
halt | é interrompida, termina com 1 e não escreve nenhum dist/ |
warn | conclui-se, imprime a mensagem e escreve dist/ |
info | conclui-se, imprime a mensagem e escreve dist/ |
A regra da equipa, policies/team.rego, reúne sob warn, e o seu anexo não declara nenhuma translation, pelo que é 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 numa categoria que as suas definições listam, e regista 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 definição de cada anexo, e uma política lê as definições do seu anexo como o seu documento data.
Tradução: uma regra, duas severidades
Um bloco translation nas definições de um anexo declara quais as chaves de decisão que são lidas e a severidade com que cada uma é reportada. Substitui o mapeamento predefinido em vez de o expandir: uma chave que não nomeia não é lida.
O ficheiro da organização introduz a sua regra como recomendação. O seu anexo reporta deny com warn, e audit com info:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoO pipeline anexa o mesmo ficheiro e faz com que a mesma regra interrompa a compilação. A sua tradução nomeia apenas deny, pelo que o seu anexo não reporta uma segunda vez as entradas audit:
settings: refused_categories: [devtool] translation: - key: deny severity: haltAssim, uma única regra, sobre o mesmo web, é um aviso na compilação de um programador e o motivo pelo qual a compilação de um pipeline é interrompida.
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:
aggrega scaffold --example policy-org-overlayDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd policy-org-overlayCompilação
O catálogo da biblioteca standard fornece os Components, as Recipes, a Feature e a sua FeatureRecipe. 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) indicado com --catalog, nada é obtido de um registo, pelo que as compilações são executadas offline. --auto-pull preenche o ficheiro de bloqueio durante a compilação; o ficheiro de bloqueio e a saída renderizada são gerados, não distribuídos.
Apenas com o ficheiro da equipa:
aggrega build --release release.yaml --auto-pulla compilação imprime o aviso da equipa e conclui-se. Também com o ficheiro da organização:
aggrega build --release release.yaml --auto-pull --config org/config.yamlimprime as entradas da organização com info e a sua regra com warn, ao lado do aviso da equipa, e conclui-se mesmo assim:
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 veredicto nomeia o plugin que o reportou, rego, e não o ficheiro que o anexou, pelo que o aviso da equipa e o da organização se leem da mesma forma; uma mensagem que diz de quem é a regra, como faz a da organização, é a forma de os distinguir.
Com a sobreposição do pipeline copiada para cá, 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 violationA compilação termina com 1 e não escreve nenhum dist/. A regra da organização é reportada duas vezes, uma por cada anexo: com warn pelo da organização e com halt pelo do pipeline. As entradas audit aparecem uma vez, apenas a partir do anexo da organização. Remova-se .aggrega-config-append-ci.yaml deste diretório para compilar novamente sem ela.
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-org-overlay`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-org-overlay` e sem `dir`: esta escreve o exemplo numa 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 indique-me o que a política reportou. Depois, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a respetiva flag `--config`, 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 indique-me o que a política reportou desta vez. Indique-me que ficheiros cada compilação escreveu; encontram-se em `policy-org-overlay/dist/`.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 compila release.yaml cinco vezes, através do helper build-release, cada uma numa cópia deste espaço de trabalho: apenas com o ficheiro da equipa, com o ficheiro da organização indicado por --config, com a sobreposição do pipeline copiada para cá, com ambos, e com uma cópia do ficheiro da organização que escreve o seu anexo em plugins.governance em vez da contraparte — onde a lista da equipa o substitui, e apenas o veredicto da equipa é impresso. Para cada uma verifica o estado de saída, se dist/ foi escrito, e cada veredicto que a compilação imprimiu — a sua severidade e a sua mensagem, sem nada em falta e nada a mais — e, onde a sobreposição é lida, o aviso que nomeia auto_pull. Imprime uma linha por compilação, depois os veredictos que cada uma imprimiu, e termina com 1 se algum resultado for diferente, imprimindo a saída dessa compilação:
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 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 ou escrito. 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. O seu estado de saída é todo o veredicto.
Onde o compilador não interpreta
O compilador lê os três ficheiros, concatena os anexos que estes contêm, entrega a cada política o grafo de compilação e as suas definições, e age de acordo com a severidade com que cada decisão é reportada. Não sabe o que é um devtool, porque é que uma organização não distribuiria um, nem que a alta disponibilidade é importante para uma equipa: esses significados são as regras e as definições das políticas. Para os papéis, os payloads e as chaves de decisão, ver o socket de governação.
Ficheiros
aggregate.yaml— a base de dados e a interface de administração ligada a ela.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 ficheiro da equipa: o registo predefinido e o anexo da equipa.policies/team.rego— a regra da equipa.org/config.yaml— o ficheiro de configuração global da organização e o seu anexo.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— compila a Release, mostrando o comandoaggrega buildequivalente.check.sh— faz as cinco compilações e verifica cada resultado.