Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Polityka w całej organizacji: reguła zespołu, reguła organizacji i reguła potoku

Polityka zespołu, polityka jego organizacji i polityka jego potoku działają razem w jednej kompilacji, a każda jest dołączona we własnym pliku konfiguracyjnym. Zespół dołącza swoją regułę w swoim obszarze roboczym; organizacja dodaje jedną do każdej kompilacji, a potok dodaje jeszcze jedną, przy czym żadne z nich nie edytuje pliku zespołu. Kompilacja odczytuje wszystkie pliki, które jej dotyczą, i uruchamia każde dołączenie, które zawierają.

Reguły zgłaszają wyniki na wszystkich trzech poziomach ważności werdyktu: info i warn pozwalają kompilacji się zakończyć, a halt ją zatrzymuje. Jedna z nich, reguła organizacji, jest dołączona dwukrotnie i za każdym razem zgłaszana z innym poziomem ważności, dzięki blokowi translation.

Co powstaje

instancjaencja Component z kataloguczym jest tutaj
dbcore/datastore/mariadbbaza danych sklepu
webcore/devtool/adminerinterfejs administracyjny bazy danych, połączony z db

Oba są kompilowane do Docker Compose, do dist/compose/docker-compose.yaml. Jeden Aggregate, jeden Manifest i jeden Release, release.yaml; żaden z nich nie wskazuje polityki.

Trzy pliki

ktoplikjak kompilacja go odczytujegdzie zapisane jest dołączenie
zespół.aggrega-config.yamloznacza ten katalog jako obszar roboczy, więc każda kompilacja tutaj go odczytujeplugins.governance
organizacjaorg/config.yamljako globalny plik konfiguracyjny, wskazany dla jednej kompilacji przez --config org/config.yamlplugins.governance_append
potokpipeline/.aggrega-config-append-ci.yamlpo skopiowaniu do tego katalogu, jako nakładka potokuplugins.governance_append

Wszystkie trzy dołączenia to silnik Rego, governance/rego:0.9.0, w roli ir-verdict, która ocenia graf kompilacji, zanim cokolwiek zostanie wyrenderowane. 0.9.0 to wersja jego encji Plugin w katalogu biblioteki standardowej. Sam silnik jest wkompilowany w CLI — aggrega plugin list wymienia governance/rego wśród osadzonych wbudowanych pluginów — więc żadna kompilacja tutaj nie pobiera pluginu.

Plik organizacji jest globalnym plikiem konfiguracyjnym. Maszyna ma jeden taki plik, odczytywany przy każdej kompilacji: z domyślnej lokalizacji albo z pliku wskazanego przez zmienną środowiskową AGGREGA_CONFIG. --config <path> wskazuje zamiast tego plik dla pojedynczego uruchomienia, a własne pliki obszaru roboczego są nadal odczytywane na jego wierzchu. W organizacji plik znajdowałby się w domyślnej lokalizacji na maszynie każdego programisty i w każdym potoku; tutaj znajduje się w org/, a kompilacje, które powinny go odczytać, go wskazują. Jawne wskazanie pliku globalnego opisuje kolejność, w jakiej próbowane są te trzy sposoby.

Plik potoku jest nakładką. Kompilacja odczytuje .aggrega-config-append-ci.yaml w katalogach, z których odczytuje .aggrega-config.yaml, obok niego. Tutaj jest przechowywany w pipeline/, gdzie kompilacja uruchomiona w tym katalogu go nie odczytuje, ponieważ zatrzymuje on każdą kompilację, która go odczyta; krokiem potoku jest skopiowanie go tutaj:

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

Każdy plik dodaje, a nakładka potoku tylko dodaje

Zarówno organizacja, jak i potok zapisują swoje dołączenie pod plugins.governance_append, towarzyszącym ustawieniem dołączającym dla listy plugins.governance. Wpisy pod ustawieniem towarzyszącym są doklejane do rozwiązanej listy po odczytaniu własnych list każdego pliku, więc działają zarówno plugins.governance zespołu, jak i wpis organizacji, a żaden plik nie wskazuje drugiego. Organizacja zapisuje ustawienie towarzyszące, a nie samo plugins.governance, ponieważ lista plugins.governance w pliku obszaru roboczego zastępuje listę z pliku globalnego: reguła organizacji zapisana tam zostaje odrzucona przez listę zespołu, a kompilacja nic o tym nie wypisuje. Rozszerzanie listy zamiast jej zastępowania wymienia ustawienie towarzyszące dla każdego ustawienia listowego.

Nakładka potoku może tylko dodawać. To, co zapisuje dla ustawienia listowego, jest dodawane do tego, co rozwiązały pozostałe pliki; niczego nie usuwa i nie nadpisuje ustawienia przechowującego pojedynczą wartość, takiego jak auto_pull. Ta nakładka zawiera auto_pull: true, a kompilacja, która ją odczytuje, ignoruje ten klucz i informuje o tym w ostrzeżeniu. Jeśli <workspace> oznacza ścieżkę bezwzględną katalogu, w którym uruchomiono kompilację, wiersz brzmi:

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)

Reguły i poziom ważności, z jakim każda jest zgłaszana

Polityka Rego zbiera każdą decyzję pod kluczem decyzji, a klucz wybiera poziom ważności, z jakim decyzja jest zgłaszana. Bez translation kluczami są deny, warn i audit, zgłaszane z poziomami halt, warn i info:

poziom ważnościco robi kompilacja
haltzatrzymuje się, kończy z kodem 1 i nie zapisuje dist/
warnkończy się, wypisuje komunikat i zapisuje dist/
infokończy się, wypisuje komunikat i zapisuje dist/

Reguła zespołu, policies/team.rego, zbiera decyzje pod warn, a jej dołączenie nie deklaruje translation, więc jest zgłaszana z poziomem 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])
}

Reguła organizacji, org/policies/estate.rego, odrzuca komponenty z kategorii wymienionej w jej ustawieniach i zapisuje, co uruchamia każdy komponent:

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 jest ustawieniem każdego dołączenia, a polityka odczytuje ustawienia swojego dołączenia jako dokument data.

Translacja: jedna reguła, dwa poziomy ważności

Blok translation w ustawieniach dołączenia deklaruje, które klucze decyzji są odczytywane i z jakim poziomem ważności zgłaszany jest każdy z nich. Zastępuje on domyślne mapowanie, zamiast je rozszerzać: klucz, którego nie wymienia, nie jest odczytywany.

Plik organizacji wprowadza jej regułę jako zalecenie. Jej dołączenie zgłasza deny z poziomem warn, a audit z poziomem info:

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

Potok dołącza ten sam plik i sprawia, że ta sama reguła zatrzymuje kompilację. Jego translacja wymienia tylko deny, więc jego dołączenie nie zgłasza rekordów audit po raz drugi:

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

Tak więc jedna reguła, dla tego samego web, jest ostrzeżeniem w kompilacji programisty i powodem zatrzymania kompilacji w potoku.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd policy-org-overlay

Kompilacja

Katalog biblioteki standardowej dostarcza encje Components, Recipes, Feature i jej FeatureRecipe. Są one rozwiązywane z hub.aggrega.ai, domyślnego rejestru wskazanego w .aggrega-config.yaml. Gdy kopia robocza katalogu (skąd ją wziąć) jest wskazana za pomocą --catalog, nic nie jest pobierane z rejestru, więc kompilacje działają offline. --auto-pull wypełnia plik blokady podczas kompilacji; plik blokady i wyrenderowany wynik są generowane, a nie dostarczane.

Tylko z plikiem zespołu:

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

kompilacja wypisuje ostrzeżenie zespołu i kończy się. Także z plikiem organizacji:

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

wypisuje rekordy organizacji z poziomem info i jej regułę z poziomem warn, obok ostrzeżenia zespołu, i nadal się kończy:

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]

Każdy werdykt wskazuje plugin, który go zgłosił, rego, a nie plik, który go dołączył, więc ostrzeżenie zespołu i ostrzeżenie organizacji wyglądają tak samo; komunikat mówiący, czyja to reguła, tak jak komunikat organizacji, pozwala je odróżnić.

Po skopiowaniu nakładki potoku to samo polecenie się zatrzymuje:

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

Kompilacja kończy się z kodem 1 i nie zapisuje dist/. Reguła organizacji jest zgłaszana dwukrotnie, raz przez każde dołączenie: z poziomem warn przez dołączenie organizacji i z poziomem halt przez dołączenie potoku. Rekordy audit pojawiają się raz, tylko z dołączenia organizacji. Aby ponownie kompilować bez niego, należy usunąć .aggrega-config-append-ci.yaml z tego katalogu.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `policy-org-overlay`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `policy-org-overlay` i bez `dir`: zapisuje ono przykład w nowym folderze `policy-org-overlay`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `policy-org-overlay`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true, i powiedz mi, co zgłosiła polityka. Potem wywołaj narzędzie `cli-build`, które uruchamia `aggrega build` i przyjmuje jego flagę `--config`, z `workspace_root` ustawionym na `policy-org-overlay`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `config` ustawionym na `org/config.yaml`, i powiedz mi, co tym razem zgłosiła polityka. Powiedz mi, jakie pliki zapisała każda kompilacja; znajdują się w `policy-org-overlay/dist/`.

Sprawdzanie każdej kompilacji

Ten autotest działa w kopii roboczej repozytorium dokumentacji, która zawiera używany przez niego wspólny skrypt pomocniczy budowania; kopia zapisana przez aggrega scaffold --example tego skryptu nie zawiera.

Terminal window
./check.sh

check.sh kompiluje release.yaml pięć razy, za pomocą skryptu pomocniczego build-release, za każdym razem w kopii tego obszaru roboczego: tylko z plikiem zespołu, z plikiem organizacji wskazanym przez --config, ze skopiowaną nakładką potoku, z oboma, oraz z kopią pliku organizacji, która zapisuje swoje dołączenie pod plugins.governance zamiast w ustawieniu towarzyszącym — wtedy lista zespołu je zastępuje i wypisywany jest tylko werdykt zespołu. Dla każdej z nich sprawdza kod wyjścia, czy zapisano dist/, oraz każdy werdykt wypisany przez kompilację — jego poziom ważności i komunikat, bez braków i bez niczego więcej — a tam, gdzie odczytywana jest nakładka, ostrzeżenie wskazujące auto_pull. Wypisuje jeden wiersz na kompilację, a potem werdykty wypisane przez każdą z nich, i kończy z kodem 1, jeśli którykolwiek wynik się różni, wypisując wyjście tej kompilacji:

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.

Kopie są tworzone w katalogu tymczasowym, a ścieżka katalogu w ich .aggrega-config.yaml jest zamieniana na bezwzględną, aby nadal się stamtąd rozwiązywała; żaden plik w tym katalogu nie jest edytowany ani zapisywany. Używa pliku binarnego, który wskazuje ./build-release.sh, więc wybiera go AGGREGA_BIN, a argumenty po -- trafiają do każdej kompilacji. Jego kod wyjścia stanowi cały werdykt.

Gdzie kompilator nie interpretuje

Kompilator odczytuje trzy pliki, łączy zawarte w nich dołączenia, przekazuje każdej polityce graf kompilacji i jej ustawienia oraz działa zgodnie z poziomem ważności, z jakim zgłaszana jest każda decyzja. Nie wie, czym jest devtool, dlaczego organizacja nie chciałaby go dostarczać ani że wysoka dostępność jest ważna dla zespołu: te znaczenia to reguły i ustawienia polityk. Role, ładunki i klucze decyzji opisuje gniazdo nadzoru.

Pliki

  • aggregate.yaml — baza danych i połączony z nią interfejs administracyjny.
  • manifest.yaml — wiąże każdy typ komponentu i encję Feature dla sekretów z odpowiadającym jej Docker Compose Recipe.
  • release.yaml — jedyna encja Release.
  • .aggrega-config.yaml — plik zespołu: domyślny rejestr i dołączenie zespołu.
  • policies/team.rego — reguła zespołu.
  • org/config.yaml — globalny plik konfiguracyjny organizacji i jej dołączenie.
  • org/policies/estate.rego — reguła organizacji.
  • pipeline/.aggrega-config-append-ci.yaml — nakładka potoku, odczytywana po skopiowaniu do tego katalogu.
  • build-release.sh — kompiluje encję Release, wypisując równoważne polecenie aggrega build.
  • check.sh — wykonuje pięć kompilacji i sprawdza każdy wynik.