Polityki kształtujące etykiety: poziom wsparcia dla każdego środowiska i werdykt, który go odczytuje
Wtyczki zarządzania oznaczają każdy komponent wdrażany przez ten obszar roboczy etykietami: jego właścicielem, poziomem wsparcia należnym jego środowisku, harmonogramem kopii zapasowych i krótkim tagiem, tak aby żaden programista nie musiał ich wpisywać. Etykiety są wyprowadzane podczas kompilacji przez cztery dołączenia zarządzania:
- trzy w roli
label-transform, które kształtują etykiety na węzłach kompilacji: polityka Rego odczytująca środowisko encji Release oraz dwie wtyczki tagujące wkompilowane w CLI,label-injectoriselector-tagger; - jedno w roli
ir-verdict, polityka Rego na grafie kompilacji, która zatrzymuje kompilację produkcyjną, w której jakiś węzeł pozostał bez poziomu wsparcia.
Dwie encje Releases jednej encji Aggregate różnią się środowiskiem, staging i production, a ich węzły kończą z różnymi etykietami. Trzecia kompilacja, którą check.sh wykonuje z kopii tego obszaru roboczego, której polityka obejmuje o jedną kategorię mniej, zatrzymuje się i wskazuje pominięty węzeł.
Co powstaje
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
db | core/datastore/mariadb | baza danych sklepu |
cache | core/datastore/redis | jego pamięć podręczna sesji |
web | core/devtool/adminer | interfejs administracyjny bazy danych, połączony z db |
Wszystkie trzy są kompilowane do Docker Compose, do dist/compose/docker-compose.yaml. Ani encja Aggregate, ani obie encje Releases nie określają własnych etykiet: każdą etykietę poniżej zapisuje dołączenie.
Cztery dołączenia
Są dołączone w .aggrega-config.yaml tego obszaru roboczego, w plugins.governance, więc stosuje je każda uruchamiana tu kompilacja:
| wtyczka | rola | co zapisuje | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, z policies/support-tier.rego | label-transform | ops.example.com/environment na każdym węźle; ops.example.com/support-tier na każdym węźle, którego kategorię wymieniają jej ustawienia |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner na każdym węźle; backup.example.com/schedule na każdym węźle w kategorii datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, z mapy w policies/tags.yaml |
| 4 | governance/rego:0.9.0, z policies/production-support.rego | ir-verdict | nic: zatrzymuje kompilację albo pozwala jej się zakończyć |
0.9.0 to wersja trzech encji Plugin w katalogu biblioteki standardowej; same wtyczki są wkompilowane w CLI i kompilacja udostępnia je stamtąd. aggrega build --release release-production.yaml --auto-pull --detail wymienia jedno i drugie dla każdej z trzech:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]Dołączenia w jednej roli działają w kolejności, w jakiej są wymienione, i każde odczytuje etykiety zapisane przez poprzednie: wstrzykiwacz etykiet otrzymuje dwie etykiety zapisane przez politykę Rego, a tagger selektorów otrzymuje je oraz etykiety wstrzykiwacza. Werdykt działa po wszystkich trzech, na grafie, który pozostawiają.
Co odczytuje polityka label-transform
Polityka na label-transform odczytuje węzły w input.graph.nodes, kluczowane identyfikatorem węzła, z których każdy ma:
component— encję Component, której instancję tworzy węzeł, na przykładcore/datastore/mariadb;resolved_version— wersję, do której rozwiązała się ta encja Component;labels— etykiety, które węzeł ma w chwili uruchomienia polityki: własne etykiety encji Component oraz te zapisane przez dowolną wcześniejszą transformację;values— wartości, które instancja węzła deklaruje w encji Aggregate; nieobecne, gdy nie deklaruje żadnych. Tutaj tylkodbdeklaruje jedną:database: appdb.
Encję Release odczytuje w input.compilation_context: release_name i environment. To właśnie pozwala jednej polityce decydować inaczej dla każdego środowiska.
Polityka na ir-verdict odczytuje natomiast cały graf kompilacji, a jego węzły leżą o jeden poziom głębiej, w input.graph.spec.nodes. Regułę przeniesioną z jednej roli do drugiej należy edytować, a nie kopiować: z błędną ścieżką nic nie odczytuje i nigdy się nie uruchamia. Ładunek ir-verdict nie zawiera compilation_context, więc werdykt nie może odczytać środowiska z encji Release. Dlatego pierwsza polityka zapisuje tu też ops.example.com/environment na każdym węźle: werdykt odczytuje środowisko z tej etykiety.
Aby zobaczyć ładunki, zamiast o nich czytać, należy raz wykonać kompilację, aby powstał plik blokady, a następnie:
aggrega build --release release-production.yaml --dry-run --policy-input payloadszapisuje ładunek otrzymywany przez każde dołączenie do payloads/, po jednym pliku na dołączenie tam, gdzie kilka dołączeń w jednej roli otrzymuje różne ładunki — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — obok jednego pliku dla każdej innej roli, i nie zapisuje nic więcej.
Polityka Rego
policies/support-tier.rego zbiera swoje decyzje w labels, po jednej na etykietę, wskazując węzeł, klucz etykiety i wartość:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}Jej ustawienia to dokument data polityki i przechowują słownictwo organizacji:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursCo zapisuje każda wbudowana wtyczka
label-injector stosuje listę reguł. Węzeł, którego etykiety obejmują każdą parę z match reguły, otrzymuje każdą parę z jej set — dodaną lub zastępującą wartość etykiety, którą węzeł już ma. match bez par pasuje do każdego węzła. Reguły odczytuje z ustawienia rules, jak tutaj, albo, gdy ustawienia ich nie zawierają, z pierwszego pliku w sources, który je zawiera. Jego dwie reguły nadają tu każdemu węzłowi ops.example.com/owner: shop-team, a db i cache, dwóm węzłom w kategorii datastore, backup.example.com/schedule: nightly. web należy do kategorii devtool i nie otrzymuje harmonogramu kopii zapasowych.
selector-tagger zapisuje jedną etykietę, zawsze pod kluczem tag. Jej wartość pochodzi z mapy nazw encji Component na tagi, odczytanej z plików w sources. Węzeł, którego encji Component mapa nie wymienia, przyjmuje ustawienie default, a bez default pozostaje bez tag. policies/tags.yaml mapuje bazę danych i pamięć podręczną:
core/datastore/mariadb: orderscore/datastore/redis: sessionsa default dołączenia to untagged, więc web otrzymuje tag untagged.
Obie decydują wyłącznie na podstawie etykiet węzła i jego encji Component. Żadna nie odczytuje środowiska, więc zapisują te same etykiety w obu encjach Releases.
Obie obsługują wyłącznie label-transform. Dołączona w ir-verdict, każda z nich jest odrzucana przed uruchomieniem; selector-tagger dołączony tam zatrzymuje kompilację komunikatem:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxGenerowanie 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:
aggrega scaffold --example policy-label-transformNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd policy-label-transformKompilacja
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullKatalog biblioteki standardowej dostarcza każdą encję Component, Recipe i Feature użytą tutaj oraz trzy encje Plugin. 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 każdej encji Release podczas kompilacji; pliki blokady i wyrenderowane wyjście są generowane, a nie dostarczane.
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-label-transform`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `policy-label-transform` i bez `dir`: zapisuje ono przykład w nowym folderze `policy-label-transform`. Następnie wywołaj narzędzie `build` raz dla każdej encji Release, w tej kolejności — `release-staging.yaml` i `release-production.yaml` — za każdym razem z `workspace_root` ustawionym na `policy-label-transform`, `release` ustawionym na ten plik, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, jakie pliki zapisała każda kompilacja; znajdują się w `policy-label-transform/dist/`.Etykiety, z którymi kończy każdy węzeł
--ir-graph wypisuje graf kompilacji na standardowe wyjście, przed podsumowaniem kompilacji, a graf zawiera etykiety każdego węzła w postaci, w jakiej pozostawiły je transformacje. Po aggrega build --release release-production.yaml --auto-pull --ir-graph węzeł web wygląda tak:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Pierwsze trzy etykiety to własne etykiety encji Component; ostatnie cztery zapisały trzy transformacje. check.sh odczytuje graf każdej kompilacji i wymienia etykiety zapisane przez dołączenia:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedMiędzy encjami Releases zmieniają się tylko dwie etykiety polityki Rego.
Gdy kompilacja wypełni plik blokady, aggrega inspect release-production.yaml --ir-graph wypisuje ten sam graf bez kompilowania, przed swoim czytelnym widokiem encji Release, ponieważ transformacje odczytują swoje pliki z pliku blokady. Bez pliku blokady wypisywany graf nie zawiera żadnej z etykiet, o których decydują te pliki: nie ma ops.example.com/environment ani ops.example.com/support-tier, a na każdym węźle jest tag: untagged.
Transformacja zmienia etykiety i nic więcej
Decyzja na label-transform wskazuje jeden węzeł, jeden klucz etykiety i jego wartość albo żąda usunięcia jednej etykiety. Nie ma decyzji, która dodaje węzeł, zmienia encję Component lub wersję węzła albo dotyka jego wartości, więc transformacja nie może wyrazić żadnej z tych rzeczy. Decyzja wskazująca węzeł, którego kompilacja nie ma, nie jest ignorowana: kompilacja zatrzymuje się z E0069 i wskazuje węzeł oraz etykietę, której nie mogła ustawić.
Pokazują to dwie kompilacje release-production.yaml, z tymi dołączeniami i bez nich. Ich grafy kompilacji różnią się etykietami wymienionymi powyżej i niczym więcej. Ich wyrenderowane wyjście nie różni się wcale: tutejsze Recipes dla Compose nie renderują żadnej z tych etykiet, więc dist/compose/docker-compose.yaml jest tym samym plikiem, bajt w bajt, z dołączeniami i bez nich, a check.sh porównuje oba drzewa przy każdym uruchomieniu. Etykiety żyją w grafie kompilacji, gdzie odczytuje je werdykt.
Werdykt i kompilacja, którą zatrzymuje
policies/production-support.rego jest dołączona w ir-verdict, po transformacjach, i odczytuje zapisane przez nie etykiety:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Obie encje Releases się kompilują: w staging werdykt niczego nie wymaga, a w production każdy węzeł ma poziom. Po zawężeniu zakresu polityki werdykt wychwytuje pominięty węzeł. Gdy supported_categories zostanie zapisane jako [datastore] w .aggrega-config.yaml, web nie otrzymuje poziomu wsparcia, a aggrega build --release release-production.yaml --auto-pull zatrzymuje się:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationKompilacja kończy z kodem 1 i nie zapisuje dist/. release-staging.yaml nadal się kompiluje z zawężoną polityką: jego węzły mają etykietę staging, a werdykt niczego od nich nie wymaga. check.sh wykonuje tę kompilację w kopii obszaru roboczego, więc aby ją zobaczyć, nie trzeba tu niczego edytować.
Werdykt akceptuje lub odrzuca i nie robi nic więcej: nie może dodać brakującej etykiety, aby kompilacja przeszła. To, jaką etykietę musi mieć węzeł produkcyjny, jest regułą organizacji, zapisaną w jej polityce; kompilator przenosi etykiety do grafu jako ciągi znaków i nie przypisuje im żadnego znaczenia.
Co zapisuje plik blokady
Plik blokady zapisuje oba rodzaje dołączeń inaczej. Po kompilacji produkcyjnej release-production.lock zawiera każde dołączenie transformujące w mutators: — jego wtyczkę, rolę, ustawienia oraz treść i skrót każdego z jego plików — i przypina każdą wtyczkę transformującą w plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0Dołączenie werdyktu pojawia się tylko w verdict_inputs:, przez sha256 swojego pliku:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoDołączenie werdyktu nie jest przypinane. Gdy dołączony jest sam werdykt — po usunięciu trzech transformacji z .aggrega-config.yaml — plik blokady zawiera mutators: [] i plugins: [], a plik werdyktu w verdict_inputs:. Transformacja zmienia kompilację, na której pracuje reszta potoku, więc plik blokady przechowuje wtyczkę, która wprowadziła zmianę; werdykt decyduje tylko o tym, czy kompilacja się zakończy.
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.
./check.shcheck.sh wykonuje cztery kompilacje za pomocą pomocnika build-release i porównuje każdy wynik z tym, który opisuje ta strona:
release-production.yamlw kopii tego obszaru roboczego bez dołączenia zarządzania, jako wzorzec;release-staging.yamlirelease-production.yamltutaj, z których każda musi się zakończyć z wymienionymi powyżej etykietami na każdym węźle, a drzewo produkcyjne musi być bajt w bajt takie jak wzorzec;release-production.yamlw kopii, której polityka obejmuje tylko kategoriędatastore, która musi zatrzymać się zE0005i powyższym zdaniem, bez żadnej innej odmowy obok.
Wypisuje jeden wiersz na kompilację, następnie etykiety, i kończy z kodem 1, jeśli którykolwiek wynik się różni, wypisując wyjście tej kompilacji:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Obie kopie są tworzone w katalogu tymczasowym, ze ścieżką katalogu encji w ich .aggrega-config.yaml zamienioną na bezwzględną, aby nadal rozwiązywała się stamtąd. Żaden plik w tym katalogu nie jest edytowany; dwie wykonywane tu kompilacje wypełniają jego pliki blokady, jak każda kompilacja. Używa pliku binarnego, który wskazuje ./build-release.sh, więc wybiera go AGGREGA_BIN, a argumenty po -- trafiają do każdej kompilacji. Odmawia uruchomienia, dopóki w tym katalogu znajduje się dist/, ponieważ porównuje drzewa zapisywane przez kompilacje, i nie pozostawia żadnego po sobie. Jego kod wyjścia stanowi cały werdykt.
Gdzie kompilator nie interpretuje
Kompilator przekazuje każdej transformacji węzły i środowisko encji Release, stosuje etykiety, o których ona decyduje, i przekazuje wynik werdyktowi. Nie wie, czym jest poziom wsparcia, że on-call stoi wyżej niż office-hours ani że devtool potrzebuje poziomu: te znaczenia to ustawienia i reguły polityk. Role, ładunki i sposób, w jaki polityka wskazuje etykietę, opisuje gniazdo zarządzania, a miejsce polityki w produkcie — Zarządzanie i zgodność.
Pliki
aggregate.yaml— baza danych, pamięć podręczna i interfejs administracyjny połączony z bazą danych; bez etykiet.manifest.yaml— wiąże każdy typ komponentu i encję Feature dla sekretów z odpowiadającym jej Docker Compose Recipe. Wspólny dla obu encji Releases.release-staging.yaml,release-production.yaml— dwa środowiska..aggrega-config.yaml— domyślny rejestr i cztery dołączenia nadzoru.policies/support-tier.rego— polityka przekształcania etykiet.policies/production-support.rego— werdykt.policies/tags.yaml— mapa komponentów na tagi dla tagera selektorów.build-release.sh— buduje jedną encję Release, wypisując równoważne polecenieaggrega build.check.sh— wykonuje cztery kompilacje i sprawdza wynik każdej z nich.