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

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-injector i selector-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

instancjaencja Component z kataloguczym jest tutaj
dbcore/datastore/mariadbbaza danych sklepu
cachecore/datastore/redisjego pamięć podręczna sesji
webcore/devtool/adminerinterfejs 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:

wtyczkarolaco zapisuje
1governance/rego:0.9.0, z policies/support-tier.regolabel-transformops.example.com/environment na każdym węźle; ops.example.com/support-tier na każdym węźle, którego kategorię wymieniają jej ustawienia
2governance/label-injector:0.9.0label-transformops.example.com/owner na każdym węźle; backup.example.com/schedule na każdym węźle w kategorii datastore
3governance/selector-tagger:0.9.0label-transformtag, z mapy w policies/tags.yaml
4governance/rego:0.9.0, z policies/production-support.regoir-verdictnic: 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ład core/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 tylko db deklaruje 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:

Terminal window
aggrega build --release release-production.yaml --dry-run --policy-input payloads

zapisuje ł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-hours

Co 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: orders
core/datastore/redis: sessions

a 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 sandbox

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-label-transform

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

Terminal window
cd policy-label-transform

Kompilacja

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

Katalog 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: untagged

Mię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 violation

Kompilacja 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.0

Dołą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.rego

Dołą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.

Terminal window
./check.sh

check.sh wykonuje cztery kompilacje za pomocą pomocnika build-release i porównuje każdy wynik z tym, który opisuje ta strona:

  • release-production.yaml w kopii tego obszaru roboczego bez dołączenia zarządzania, jako wzorzec;
  • release-staging.yaml i release-production.yaml tutaj, 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.yaml w kopii, której polityka obejmuje tylko kategorię datastore, która musi zatrzymać się z E0005 i 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 OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-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 polecenie aggrega build.
  • check.sh — wykonuje cztery kompilacje i sprawdza wynik każdej z nich.