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í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ânciaComponent do catálogoo que é aqui
dbcore/datastore/mariadba base de dados da loja
webcore/devtool/admineruma 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

quemficheirocomo uma compilação o lêonde o anexo é escrito
a equipa.aggrega-config.yamlmarca este diretório como o espaço de trabalho, pelo que todas as compilações aqui o leemplugins.governance
a organizaçãoorg/config.yamlcomo o ficheiro de configuração global, indicado para uma única compilação 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

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á:

Terminal window
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:

severidadeo que a compilação faz
halté interrompida, termina com 1 e não escreve nenhum dist/
warnconclui-se, imprime a mensagem e escreve dist/
infoconclui-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: info

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

Assim, 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:

Terminal window
aggrega scaffold --example policy-org-overlay

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

Terminal window
cd policy-org-overlay

Compilaçã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:

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

a compilação imprime o aviso da equipa e conclui-se. Também com o ficheiro da organização:

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

imprime 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 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 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:

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

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

Terminal window
./check.sh

check.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 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 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 comando aggrega build equivalente.
  • check.sh — faz as cinco compilações e verifica cada resultado.