Gniazdo zarządzania
Całe gniazdo, a nie jedna jego rola: cztery role — dwie oceniające kompilację i dwie ją kształtujące — oba silniki zasad dostarczane w kompilatorze oraz sposób, w jaki operator dołącza plugin.
Operator dołącza plugin zarządzania Wasm, aby zbadać kompilację i zareagować na to, co w niej wykryje. Host kompilatora pozostaje neutralny wobec treści i bez własnego zdania: przekazuje ładunek kompilacji do gościa i działa na podstawie tego, co gość zwróci, nigdy nie interpretując samej zasady. Cała dziedzinowa logika zasad — język zasad, jego silnik i reguły — znajduje się wewnątrz gościa.
Jest to ten sam kontrakt czystości ahead-of-time, któremu podlega każde gniazdo: gość ocenia przekazany mu ładunek i zwraca wynik, który host wykorzystuje dosłownie (zob. kontrakt piaskownicy). Host nie dowiaduje się niczego o języku zasad, którym posługuje się gość, i nie zawiera własnego kodu silnika zasad.
Plugin zarządzania jest dołączany dokładnie w jednej roli, a to rola — nie plugin — określa zarówno to, jaki ładunek dociera, jak i to, co dołączenie może z nim zrobić. Dwie z nich to role werdyktu: dołączenie ocenia kompilację, a host podejmuje dokładnie jedno z trzech działań dla każdego zwróconego werdyktu. Dwie to role transformacji: dołączenie zgłasza zmianę etykiet lub adnotacji kompilacji, a host ją stosuje. Plugin obsługujący więcej niż jedną rolę jest dołączany raz dla każdej roli i nie deklaruje własnej roli — niesie ją dołączenie.
Ta strona stanowi wyczerpujące omówienie gniazda zarządzania: cztery role
i ładunek każdej z nich, poziomy ważności werdyktów, na które reaguje host,
niezależny od silnika kanał wejściowy dostarczany przez operatora, sposób pisania zasady dla każdego
z dwóch silników zasad dostarczanych w kompilatorze — jednego oceniającego Rego, drugiego
oceniającego CEL — sposób, w jaki gość opakowuje zewnętrzny silnik zasad, dostarczane gości referencyjnych
oraz sposób dołączania pluginu przez operatora do obszaru roboczego. Miejsce gniazda w potoku i jego typowane kształty przesyłanych danych opisano w
plugin-contract.md; tworzenie i publikowanie
pluginu jako encji katalogu opisano w
przewodniku dla twórców pluginów Wasm.
Model mentalny: host przekazuje, gość decyduje
Podczas kompilacji host składa ładunek dla roli danego podłączenia, przekazuje go przez granicę ABI i odczytuje to, co zwrócił gość. W roli werdyktu jest to lista werdyktów, z których każdy niesie poziom ważności i komunikat czytelny dla człowieka: host odwzorowuje każdy poziom ważności na akcję kompilacji, nie odczytuje znaczenia komunikatu, nie wie, co sprawdzała polityka, i nie wie, który silnik wytworzył decyzję. W roli transformacji jest to zmiana do wprowadzenia, skierowana do etykiet lub adnotacji, którymi zarządza dana rola, i do niczego innego.
Ponieważ host nie interpretuje treści polityk, cała powierzchnia polityk należy do gościa: w jakim języku są napisane reguły, który silnik je ewaluuje i jak zadziałanie reguły staje się werdyktem lub zmianą. Kontrakt gniazda jest celowo wąski — rola, zestaw danych wejściowych i wynik — tak aby mogła go obsłużyć każda technologia polityk, która kompiluje się do Wasm.
Rola werdyktu akceptuje lub odrzuca i nie robi nic więcej: host odczytuje jej wynik wyłącznie jako decyzję i nigdy nie stosuje go jako zmiany, więc polityka nie może po cichu doprowadzić niezgodnej kompilacji do zgodności. Rola transformacji jest celowym wyjątkiem, a wyjątkiem czyni ją to, że podłączył ją operator — podłączenie pluginu kształtującego etykiety jest deklaracją, że etykiety mają być kształtowane. To, co takie podłączenie może zmienić, jest ograniczone do powierzchni jego własnej roli, a kompilacja zatrzymuje się z wyraźnym błędem na wszystkim, co wykracza poza nią.
Cztery role
Plugin jest dołączany w dokładnie jednej roli, a rola określa, w którym miejscu potoku host go wykonuje, jaki ładunek otrzymuje i co może zwrócić. Plugin, który ma pełnić dwie role, dołącza się dwukrotnie — raz dla każdej roli.
Role werdyktów: ir-verdict i render-verdict
ir-verdict— gość wnioskuje na podstawie grafu reprezentacji pośredniej, przed renderowaniem. Ładunek zawiera pełny, agnostyczny wobec możliwości graf IR (każdy węzeł, krawędź i dołączenie, które przechowuje kompilator) oraz ścieżki routingu wyliczane przez analizator, dzięki czemu polityka może wnioskować o topologii i osiągalności bez ponownego przechodzenia grafu. Ta lista ścieżek jest ograniczona dla każdego węzła początkowego — gęsto połączona lub cykliczna topologia może zawierać więcej odrębnych tras, niż emituje wyliczenie, a po osiągnięciu limitu pozostałe trasy z tego węzła początkowego nie są wymieniane. Ścieżka, która jest obecna, jest więc rzeczywista, natomiast brak ścieżki nie dowodzi, że żadna nie istnieje: polityka, której werdykt zależy od tego, że coś jest nieosiągalne, powinna ustalać to na podstawie węzłów i krawędzi, które ładunek zawiera w całości, a nie wyłącznie na podstawie listy ścieżek. Jedna rzecz w grafie nie jest taka, jak ją zapisano: każda wartość, którą autor zadeklarował jako wrażliwą — wvalueslubinfradołączenia, winfradołączenia granicznego, we własnychvalueslubinfrawęzła albo we własnychvalueslubinfrapołączenia — dociera jako znacznik wstrzymania{"aggrega_withheld": "declared"}, natomiast jej klucz, oznaczenie wrażliwości i każda niezadeklarowana wartość obok niej docierają w postaci zapisanej. Polityka ocenia, dokąd trafia materiał zadeklarowany jako wrażliwy, i nigdy nie otrzymuje samego materiału; zob. fakty o dołączeniach odczytywane przez politykę zarządzania. Politykair-verdictdziała na bramce analizy statycznej, zanim powstaną jakiekolwiek artefakty. Należy jej używać do polityk dotyczących architektury i połączeń — niezmienników topologii, uwierzytelniania między granicami, kształtu przepływu poświadczeń — które powinny zatrzymać kompilację, zanim cokolwiek wyrenderuje.render-verdict— gość wnioskuje na podstawie wyrenderowanego wyniku, po renderowaniu. Ładunek zawiera emitowane artefakty posortowane według ścieżki, dzięki czemu dane przesyłane są identyczne bajt w bajt między uruchomieniami dla identycznego wejścia. Każdy artefakt zawiera swoją ścieżkę wyjściową i wyrenderowany tekst; dodatkowo zawiera format, w którym został wyrenderowany, jeśli dostawca, który go wytworzył, go zadeklarował, oraz sparsowany strukturalny widok swojej zawartości, jeśli zawartość jest w formacie parsowanym przed polityką. Politykarender-verdictwidzi dokładnie to, co wytworzyła kompilacja, i nic w tym nie jest wstrzymane: wartość, którą Recipe wyrenderował do artefaktu, dociera w postaci wyrenderowanej, ponieważ to artefakt jest oceniany przez politykę. Należy jej używać do polityk dotyczących konkretnego wyniku — na przykład reguły sprawdzającej wyrenderowane usługi Docker Compose lub obiekty Kubernetes.
Role transformacji: annotation-transform i label-transform
-
annotation-transform— gość zgłasza adnotacje do dodania, podczas rozwiązywania i przed rozwinięciem adnotacji. Ładunek zawiera każdy komponent, który dołączenie może opatrzyć adnotacją, wraz z adnotacjami, które już ma, oraz klucze adnotacji, dla których Manifest rejestruje powiązanie. Wstrzyknięta adnotacja pod zarejestrowanym kluczem rozwija się następnie w dołączenie encji Feature — w ten sposób ta rola dodaje do kompilacji możliwość, której programista nie wpisał.Komponenty, które może opatrzyć adnotacjami, to każdy komponent wskazany przez granicę w
components:oraz każdy komponent, który wprowadza wpis routinguaggregates:granicy. Wpis routingu umieszcza każdy komponent swojego modułu, łącznie z komponentami modułów w nim zagnieżdżonych, niezależnie od tego, czy jego własnecomponents:wskazuje je wszystkie, niektóre, czy żadnego, tak jakdocuments: {}nie wskazuje żadnego; ładunek zawiera każdy z nich. Do komponentu wprowadzonego przez routing odwołuje się przez identyfikator, który ma on w grafie buildu — nazwę modułu, kropkę i nazwę komponentu w module, jak wdocuments.backend, z kolejną nazwą modułu i kropką dla każdego zagnieżdżonego modułu — bo tak zapisują go graf buildu i jego diagnostyka, więc decyzja również nazywa go w ten sposób. Komponent, który wpis routingu umieszcza bez wskazywania go, nie ma w ładunku własnych adnotacji, a adnotacja wstrzyknięta do niego jest stosowana tak, jakby zapisano ją na nim pod wpisem routingu. -
label-transform— gość zgłasza zmiany etykiet do zastosowania, podczas budowania topologii: po zbudowaniu grafu i zanim graf zostanie oceniony. Ładunek zawiera projekcję węzłów kompilacji — każdy z encją Component, którą instancjonuje, rozwiązaną dla niego wersją, etykietami, które obecnie posiada, oraz wartościami deklarowanymi przez jego instancję, tylko do odczytu i z każdą wartością, którą jego Component deklaruje jako wrażliwą, wstrzymaną tak, jak wstrzymuje ją werdykt grafu — oraz nazwę i środowisko encji Release. Należy jej używać do metadanych pochodnych, których programista nigdy nie powinien musieć wpisywać (zakresu zgodności, własności, przypisania kosztów), oraz do etykiety możliwości, na którą zasługuje zadeklarowana przez programistę konfiguracja.
Role przenoszą różne ładunki, ponieważ działają w różnych momentach i odpowiadają na różne pytania. Wszystkie cztery przenoszą ten sam kanał wejściowy dostarczany przez operatora, opisany poniżej. Aby zobaczyć ładunek, zamiast o nim czytać, aggrega build --release <release> --policy-input <dir> zapisuje ładunek, który każda rola przekazuje dołączonej do niej wtyczce — łącznie z rolą, do której nic nie dołączono — jako jeden plik JSON na rolę albo na dołączenie, gdy dołączenia danej roli otrzymują różne ładunki, a w połączeniu z --dry-run zapisuje te pliki i nic więcej. W rolach annotation-transform, label-transform i ir-verdict plik jest dokumentem input, który odczytuje polityka. W roli render-verdict silnik polityk przekształca ładunek, zanim odczyta go polityka — documents każdego artefaktu są z niego parsowane — więc politykę render-verdict na silniku wbudowanym w kompilator testuje się w kompilacji, dołączoną z warn lub info, jak pokazuje sekcja Testowanie polityki, zanim zacznie blokować kompilację. Dla wtyczki, której .wasm zbudowano samodzielnie, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json uruchamia ją na tym pliku.
Werdykty i poziomy ważności
Poniższe poziomy ważności stanowią słownik ról werdyktowych. Rola transformująca zgłasza zmianę, a nie werdykt, więc nie ma poziomu ważności.
Gość zwraca listę werdyktów. Każdy werdykt ma poziom ważności, który określa działanie kompilacji:
halt— zatrzymuje kompilację; host przedstawia komunikat werdyktu jako przyczynę. Kompilacja nie tworzy żadnych artefaktów.warn— oznacza werdykt; kompilacja jest kontynuowana.info— rejestruje werdykt; wynik kompilacji pozostaje bez zmian.
Te trzy poziomy stanowią pełny zestaw i są tymi samymi trzema, których używa diagnostyka każdego innego gniazda, więc poziom ważności znaczy to samo, gdziekolwiek się go czyta.
Werdykt z jakąkolwiek inną wartością jest naruszeniem kontraktu, a nie czwartą ścieżką. Kompilacja zostaje zatrzymana, a komunikat podaje plugin, wartość, którą miał werdykt, oraz trzy wartości deklarowane przez kontrakt — dzięki temu błędnie zapisany poziom ważności jest zgłaszany jako błąd kompilacji, zamiast przejść jako werdykt, na który nic nie reaguje. Gość zgłaszający jedną z trzech wartości nie jest tym objęty.
Ewaluacja zezwalająca nie zwraca niczego. Gość emituje werdykt tylko wtedy, gdy reguła zostanie uruchomiona, więc pusta lista werdyktów oznacza, że polityka zezwoliła na kompilację. Nie ma werdyktu „pass” do wyemitowania — milczenie oznacza zezwolenie.
Gość może zwrócić wiele werdyktów w jednej ewaluacji, z różnymi poziomami ważności. Host
przetwarza je wszystkie: dowolny halt zatrzymuje kompilację (a każdy komunikat halt jest
przedstawiany), natomiast werdykty warn i info są zgłaszane bez blokowania. Odzwierciedla
to podział na zatrzymanie i doradzanie, który odróżnia politykę zatrzymującą kompilację od
doradczej kontroli lint.
Kanał with: źródła i ustawienia
Gość polityki jest zwykle generyczny względem konkretnych reguł, które egzekwuje — silnik
jest wbudowany w gościa, ale reguły są dostarczane osobno dla każdego dołączenia. Kanał
with przenosi te dane wejściowe dołączenia. Ma dwa pola niezależne od silnika:
sources— pliki definicji polityk, które ładuje gość. Host odczytuje każdy wskazany plik w czasie kompilacji i przekazuje jego bajty gościowi w sposób nieprzezroczysty: nigdy nie parsuje źródła, a ścieżka przekazywana gościowi to nazwa bazowa pliku, nigdy bezwzględna ścieżka hosta. Znaczenie bajtów jest wyłącznie sprawą gościa — dla jednego gościa to plik.rego, dla innego inny format polityk, a dla gościa, który takie odczytuje, archiwum całego zestawu polityk zakodowane w base64.settings— mapa konfiguracji, którą gość odwzorowuje na swój silnik. Gość odczytuje z tej mapy swoje parametry (górny limit replik, wymagany klucz etykiety). Domyślnie host przekazuje ją dosłownie, nie reagując na nią; gość może dodatkowo zadeklarować dla niej schemat (zob. niżej) i wtedy host sprawdza mapę względem tego schematu przed uruchomieniem gościa.
Gość w pełni wbudowany — taki, którego reguły są wkompilowane, a nie dostarczane w chwili
dołączenia — całkowicie pomija with. Kanał jest opcjonalny w każdej roli.
Typowane ustawienia
Gość może zadeklarować JSON Schema dla oczekiwanych settings. Jeśli to zrobi,
host sprawdza settings dołączenia względem tego schematu przed
uruchomieniem gościa. Niezgodne ustawienia zatrzymują kompilację z komunikatem
podającym błędny klucz i to, czego oczekiwał schemat — brak wymaganego klucza,
wartość złego typu, nieznany klucz lub wartość spoza zakresu są wychwytywane
z góry, zamiast ujawnić się jako niejasny błąd gościa albo, co gorsza,
błędna, ale udana kompilacja.
Typowane ustawienia są opcjonalne i deklaruje je gość, a nie host. Gość, który
nie deklaruje schematu ustawień, zachowuje swobodne zachowanie: host przekazuje jego
settings bez sprawdzania. Host wykonuje zwykłą walidację JSON Schema
względem schematu zadeklarowanego przez gościa; nie interpretuje znaczenia
ustawień. Dzięki temu sprawdzanie pozostaje neutralne wobec silnika — każdy gość opisuje
kształt odczytywanych ustawień, a host egzekwuje dokładnie ten kształt i
nic więcej.
Dołączenie, które nie deklaruje ustawień, jest walidowane jako JSON null. To pozwala gościowi uczynić ustawienia obowiązkowymi: schemat dopuszczający tylko obiekt odrzuca dołączenie, które ich nie dostarcza, i kompilacja zostaje zatrzymana. Konsekwencja działa też w drugą stronę i to ją należy świadomie uwzględnić: gość, którego ustawienia są naprawdę opcjonalne, musi zadeklarować schemat dopuszczający null oraz obiekt, w przeciwnym razie nie da się go dołączyć bez ustawień. Dwa silniki polityk wbudowane w kompilator deklarują "type": ["object", "null"] właśnie z tego powodu — po dołączeniu bez bloku with: działają na wartościach domyślnych. Gość, który deklaruje samo "type": "object", uczynił swoje ustawienia wymaganymi, niezależnie od tego, czy taki był zamiar.
ABI należy do Aggrega
Kontrakt gniazda to własne ABI Aggrega, a nie ABI któregokolwiek silnika polityk. Dzięki temu dowolna technologia polityk skompilowana do Wasm może posłużyć jako gość, który można podłączyć bez zmian: gość udostępnia na zewnątrz powierzchnię Aggrega — describe() oraz eksport wywoływany przez rolę, którą obsługuje — a silnik, którego używa, jest szczegółem implementacyjnym ukrytym za tą powierzchnią.
Gość opakowujący obcy silnik polityk wchłania ABI tego silnika w sobie. Jeśli silnik ma własne ABI Wasm, własne punkty wejścia lub własny protokół wywołań zwrotnych hosta, opakowujący gość tworzy jego instancję i steruje nim wewnętrznie, a decyzję silnika odwzorowuje z powrotem na kształt werdyktu gniazda. Host kompilatora widzi wyłącznie standardową powierzchnię werdyktów zarządzania; nigdy nie dowiaduje się, jakiego silnika użyto, i nie zawiera kodu specyficznego dla silnika. Przeniesienie polityki z jednego silnika na inny to zmiana podłączenia, a nie zmiana hosta.
Dwa silniki polityk wbudowane w kompilator
Dwa silniki polityk są wkompilowane w plik binarny CLI, a operator dołącza dowolny z nich — lub oba — w ten sam sposób, w jaki dołącza się każdy plugin zarządczy:
| Współrzędna | Język polityk | Dołączane źródło |
|---|---|---|
governance/rego | Rego | Pliki .rego lub zakodowane w base64 archiwum całego zestawu polityk |
governance/cel | Common Expression Language (CEL) | Pliki wyrażeń .cel lub dokumenty reguł .yaml / .yml |
Wszystko wokół języka jest wspólne. Oba obsługują wszystkie cztery role, oba odczytują
ten sam ładunek danej roli pod tymi samymi nazwami pól, oba odwzorowują swoje decyzje na
te same trzy poziomy ważności werdyktu za pomocą tego samego ustawienia translation i oba kończą się
wyraźnym błędem, zamiast dopuścić kompilację, której nie mogły ocenić. Każdy z nich ma jako wersję
wydanie kompilatora, z którym jest dostarczany, i żaden nie potrzebuje zewnętrznego
łańcucha narzędzi ani niczego nie pobiera w czasie kompilacji. Wspólne nie jest to, co każdy język potrafi wyrazić:
reguła, która w Rego składa się z kilku reguł pomocniczych, w CEL może wymagać ustawień i powtórzeń
— przed napisaniem reguły przechodzącej po trasie należy zapoznać się z sekcją What an expression can say.
Różni je język, w którym pisze się reguły, i to jest jedyna podstawa wyboru. Środowisko, które ma już zbiór polityk Rego — lub zespół, który pisze w Rego kontrolę dopuszczania w innym miejscu — dołącza silnik Rego, a jego polityki działają bez zmian. Zespół, który wyraża swoje reguły jako pojedyncze wyrażenia nad dokumentem, tak jak robi to polityka validating-admission w Kubernetes, dołącza silnik CEL. Oba dołącza się osobno dla każdej roli, więc obszar roboczy może używać Rego w jednej roli, a CEL w innej, albo obu w tej samej roli jako dwóch dołączeń.
Host jest agnostyczny wobec tego, z którego z nich pochodzi decyzja: przekazuje ładunek, odczytuje werdykt lub zmianę i na tej podstawie działa. Przeniesienie polityki z jednego języka na drugi to zmiana dołączenia i przepisanie reguł — nigdy zmiana hosta.
Polityki Rego: dwie drogi
Rego jest popularnym językiem polityk, a do jego uruchamiania prowadzą dwie drogi — niewymagający wysiłku silnik dostarczany wewnątrz kompilatora oraz furtka o pełnej wierności.
Silnik Rego w kompilatorze to droga niewymagająca wysiłku. Zawiera natywny dla Wasm ewaluator Rego, więc operator umieszcza plik .rego w sources i dołącza plugin — bez zewnętrznego zestawu narzędzi i bez pobierania czegokolwiek w czasie budowania. Obsługuje wszystkie cztery role: ten sam plugin ocenia graf budowania, ocenia wyrenderowane wyjście, kształtuje etykiety lub wstrzykuje adnotacje, zależnie od roli, w której został dołączony. Jego tożsamość w katalogu to sama nazwa rego pod pluginType: governance — koordynata governance/rego — a jego wersją jest wydanie kompilatora, które go dostarcza. Pisaniu polityki dla niego poświęcona jest następna sekcja.
Ewaluator implementuje Rego niezależnie, zamiast osadzać implementację referencyjną, i nie implementuje wszystkich wbudowanych funkcji Rego. Gdy polityka wywołuje wbudowaną funkcję, której ewaluator nie implementuje, dołączenie kończy się głośnym błędem: zwraca błąd, a nie zezwolenie. Budowanie zostaje wtedy zatrzymane z błędem wskazującym plugin — celowo odróżnionym od werdyktu halt, aby „silnik nie może ocenić tej polityki” nigdy nie zostało pomylone z „polityka zezwala na budowanie”. Polityka, której nie da się ocenić, zatrzymuje budowanie; nigdy nie przechodzi po cichu.
Furtka opa build -t wasm to droga o pełnej wierności. Gdy polityka potrzebuje pełnego zestawu funkcji wbudowanych lub dokładnej semantyki silnika referencyjnego, należy ją skompilować własnym zestawem narzędzi OPA do modułu Wasm i uruchomić ten moduł za cienkim gościem-adapterem. Adapter w całości obsługuje u siebie ABI Wasm OPA (zgodnie z sekcją ABI jest własnym ABI Aggrega powyżej): tworzy instancję modułu zbudowanego przez OPA, ustawia dane wejściowe, wywołuje ewaluację i odwzorowuje decyzję z powrotem na kształt werdyktu. Host widzi wyłącznie standardową powierzchnię werdyktów zarządzania.
Jako działający przykład dostarczany jest referencyjny gość-adapter. Osadza on politykę napisaną w Rego i wstępnie skompilowaną za pomocą opa build -t wasm do modułu WebAssembly — przypiętego artefaktu zapisanego w repozytorium, dzięki czemu ewaluacja przebiega w całości w gościu, bez procesu OPA i bez pobierania czegokolwiek. Przy każdym budowaniu adapter tworzy u siebie instancję tego wypieczonego modułu za pomocą osadzonego interpretera Wasm, zaspokaja własne importy modułu (jego pamięć liniową i wywołania zwrotne funkcji wbudowanych), odczytuje ładunek jako dokument OPA input, a settings dołączenia jako dokument OPA data, ocenia każdy skompilowany punkt wejścia i odwzorowuje nazwę punktu wejścia deny / warn / audit na ważność werdyktu — odpowiednio halt, warn i info. Jeśli wypieczona polityka potrzebuje wbudowanej funkcji dostarczanej przez hosta, której adapter nie implementuje, adapter kończy się głośnym błędem — odrzuca moduł, zamiast zwrócić zezwolenie — więc polityka, której nie da się ocenić, zatrzymuje budowanie, zamiast przejść po cichu. Ponowne wygenerowanie wypieczonego modułu z jego źródła Rego to krok autorski wykonywany za pomocą CLI OPA, a nie zależność czasu budowania. ../examples/policy-data-class-route/ buduje ten adapter wokół własnego modułu i podaje polecenia, które ponownie generują oba.
Obie drogi współdzielą ten sam kontrakt z hostem, więc przeniesienie polityki z silnika w kompilatorze do pełnego silnika jest zmianą dołączenia.
Pisanie polityki dla silnika Rego
Silnik ewaluuje kod Rego napisany przez operatora w całości wewnątrz gościa, w tej z czterech ról, w której został dołączony. Dołączenie go dwukrotnie, w dwóch rolach, z dwoma różnymi plikami polityk, pozwala jednemu silnikowi objąć dwa momenty tej samej kompilacji.
Ładunek dla roli dołączenia jest dokumentem input polityki, a obiekt settings dołączenia jest dokumentem data polityki — dlatego polityka odczytuje próg podany przez operatora jako data.max_replicas. Każdy plik, który dołączenie deklaruje w sources, staje się modułem polityki, a każdy pakiet zadeklarowany w tych plikach jest ewaluowany.
W jakiej składni reguł napisana jest polityka
Rego zapisuje się w dwóch składniach reguł, a silnik akceptuje obie, moduł po module. Zestaw polityk utworzony, zanim powstała obecna składnia, jest więc ewaluowany obok zestawu napisanego dziś, w tym samym dołączeniu.
W obecnej składni ciało reguły jest poprzedzone słowem if, reguła zbierająca wartości do zbioru wyraża to przez contains, a moduł określa, w jakiej składni jest napisany, deklarując import rego.v1 w osobnym wierszu pod deklaracją pakietu:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}W starszej składni z nawiasami w nagłówku wartość zbierana przez regułę znajduje się w nawiasach w nagłówku reguły, a ciało następuje bezpośrednio po nim. Moduł w tej składni niczego nie deklaruje, ponieważ rozpoznaje się go po tym, że nie parsuje się jako składnia obecna:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Moduł, który parsuje się jako obecna składnia, a niczego nie deklaruje, jest odrzucany z podaniem nazwy. To deklaracja ustala sposób odczytania, a bez niej ten sam tekst reguły może prowadzić do przeciwnej decyzji: ciało reguły, które nigdy nie jest spełnione, nie wnosi żadnej decyzji w obecnej składni, a w starszej składni wnosi jedną — więc polityka, która powinna milczeć, zatrzymuje kompilację, a w przypadku odwrotnym przepuszcza kompilację, którą reguła miała zatrzymać. Zamiast wybierać sposób odczytania takiego modułu, silnik go odrzuca i podaje, co należy dodać:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.Odrzucenie jest błędem kompilacji wskazującym plugin, a nie werdyktem, więc zatrzymuje kompilację tak samo jak polityka, której nie da się ewaluować, i nigdy nie wygląda jak polityka, która ją dopuściła.
Warto znać dwa przypadki brzegowe, zanim zaskoczą. Moduł bez żadnych ciał reguł — taki, który deklaruje tylko dane — parsuje się jako obecna składnia, więc także od niego wymagana jest deklaracja, choć oba sposoby odczytania nie mogłyby się w jego przypadku różnić. Natomiast moduł napisany w starszej składni nigdy nie jest odrzucany, ponieważ nie parsuje się jako obecna składnia: to sam silnik odróżnia jedną od drugiej, więc celowo napisana polityka z nawiasami w nagłówku nigdy nie zostanie wzięta za politykę w obecnej składni, która zapomniała tego zadeklarować.
Polityka zbiera swoje decyzje pod kluczem decyzji
Każda rola odczytuje decyzje polityki z klucza decyzji — nazwanej reguły, do której polityka zbiera wartości. To, które klucze są odczytywane i co oznacza decyzja pod danym kluczem, ustala rola.
W roli werdyktu decyzja jest komunikatem, a klucz, pod którym została zebrana, ustala poziom ważności, z jakim komunikat jest zgłaszany. Domyślnie kluczami są konwencjonalne nazwy kolekcji Rego:
| Zebrane pod | Zgłaszane jako | Wpływ na kompilację |
|---|---|---|
deny | halt | zatrzymuje kompilację |
warn | warn | pojawia się obok kompilacji, która się kończy |
audit | info | zapisywane; wynik kompilacji się nie zmienia |
Należy rozdzielać te dwa słowniki, bo są to dwa różne słowniki: deny, warn i audit to nazwy w polityce, a halt, warn i info to poziomy ważności, z którymi zgłasza gniazdo. Nazwy w lewej kolumnie można zmienić; prawa kolumna to zamknięty zbiór wspólny dla wszystkich gniazd.
Polityka, która nazywa swoje decyzje inaczej, deklaruje mapowanie w ustawieniach dołączenia:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnZadeklarowane mapowanie zastępuje domyślne, a nie je rozszerza: odczytywane są dokładnie te klucze, które wymienia, więc polityka nadal zbierająca do deny nie osiąga żadnego werdyktu, gdy zadeklarowano powyższe mapowanie. Kolejność deklaracji reguł jest kolejnością zgłaszania werdyktów. Klucz, którego polityka nie deklaruje, oznacza brak decyzji, a nie błąd, więc jeden plik polityki może obsługiwać kilka dołączeń.
Poziom ważności spoza tych trzech oraz mapowanie zadeklarowane jako puste są odrzucane przez schemat ustawień deklarowany przez plugin — host waliduje względem niego ustawienia dołączenia przed wywołaniem. Ten sam klucz zmapowany dwukrotnie jest odrzucany podczas odczytu mapowania, co również następuje przed uruchomieniem jakiejkolwiek polityki. W obu przypadkach kompilacja zatrzymuje się przed podjęciem decyzji, nigdy z mapowaniem zastosowanym częściowo.
Poza tym ustawienia są danymi samej polityki: mapowanie jest odczytywane z obiektu, a obiekt trafia do dokumentu data polityki bez zmian, więc polityka napisana dla kluczy domyślnych widzi dokładnie ten sam dokument danych, który widziałaby bez skonfigurowanego mapowania.
W roli transformacji decyzja jest zmianą do wprowadzenia, a nie komunikatem, więc nie ma poziomu ważności do ustalenia, a zamiast tego ustalony jest klucz: labels w roli kształtowania etykiet, annotations w roli wstrzykiwania adnotacji. Ustawienie translation jest odczytywane tylko tam, gdzie zgłaszane są werdykty, więc dołączenie transformacji, które je deklaruje, zawiera ustawienie nieużywane przez jego rolę.
Klucz decyzji jest odczytywany z każdego pakietu ładowanego przez dołączenie, więc zestaw polityk może rozłożyć reguły na pakiety, a każdy z nich wnosi to, co zebrał. Drugą stronę tego warto znać, zanim da się we znaki: w obrębie jednego dołączenia klucz decyzji jest zarezerwowaną nazwą reguły w każdym pakiecie, więc pakiet pomocniczy, który na własny użytek zbiera do labels, ma swoje wpisy odczytywane jako decyzje dotyczące etykiet. Kończy się to głośnym, a nie cichym błędem — dołączenie zgłasza, że coś zebranego pod kluczem nie jest decyzją o tym kształcie — ale taki komunikat najszybciej odczytać jako kolizję nazw, dlatego klucz należy zachować dla decyzji, a regule pomocniczej nadać inną nazwę.
Co udostępnia ładunek każdej roli
Ładunek jest dokumentem input polityki, więc polityka odczytuje go pod nazwami,
które nadaje mu protokół.
Graf kompilacji znajduje się pod inną ścieżką w każdej z dwóch ról, które go przenoszą. Werdykt nad grafem otrzymuje cały dokument grafu, więc jego węzły znajdują się pod input.graph.spec.nodes; rola kształtująca etykiety otrzymuje projekcję węzłów, więc jej węzły znajdują się pod input.graph.nodes. Regułę przenoszoną między tymi dwiema rolami należy zatem zmodyfikować, a nie skopiować — a objawem pominięcia tego jest reguła, która nigdy się nie uruchamia, a nie błąd, ponieważ nieistniejąca ścieżka jest po prostu niezdefiniowana.
| Rola | Co odczytuje polityka |
|---|---|
ir-verdict | input.graph — cały dokument grafu kompilacji: węzły pod input.graph.spec.nodes z kluczami będącymi identyfikatorami węzłów, krawędzie pod input.graph.spec.edges. Wartość, którą autor zadeklarował jako wrażliwą, odczytywana jest jako {"aggrega_withheld": "declared"}. input.precalculated_paths — wyliczone ścieżki routingu, z których każda zawiera uporządkowaną listę nodes oraz attached_features, czyli typy Feature dołączone w dowolnym miejscu ścieżki (zob. niżej). Lista jest zawsze obecna: kompilacja bez trasy między komponentami zawiera pustą listę. |
render-verdict | input.artifacts — jeden wpis na każdy wygenerowany plik, każdy z polami path, content, format oraz documents, czyli sparsowanymi dokumentami pliku. format to format, który zadeklarował dla pliku dostawca, który go wyrenderował — dostawca Terraform deklaruje hcl dla każdego emitowanego pliku .tf i json dla każdego pliku .tf.json, łącznie z plikami modułu dołączonego do repozytorium (vendored) — albo pusty ciąg znaków, gdy żaden dostawca go nie zadeklarował, jak w przypadku pliku, który encja Recipe wnosi do współdzielonego wyjścia granicy. Taki plik jest mimo to parsowany według rozszerzenia, więc jego documents są obecne w obu przypadkach. Artefakt, którego nie udało się odczytać strukturalnie, zawiera parse_error i nie zawiera dokumentów, dzięki czemu polityka może odrzucić sam błąd, zamiast przepuścić niezbadany nieczytelny plik. |
label-transform | input.graph.nodes — węzły kompilacji z kluczami będącymi identyfikatorami węzłów, każdy z polami component, resolved_version, labels i values: wartościami, które instancja węzła deklaruje w encji Aggregate, z szablonami ewaluowanymi względem jej parametrów; pole jest nieobecne, gdy instancja niczego nie deklaruje. Wartość, którą encja Component węzła deklaruje jako wrażliwą, odczytuje się jako {"aggrega_withheld": "declared"}, tak jak w ir-verdict, a sąsiednie niezadeklarowane wartości odczytuje się tak, jak zostały zapisane. Reguła odczytuje input.graph.nodes[id].values, aby zdecydować o etykiecie; nie może zmienić wartości. input.compilation_context — pola release_name i environment encji Release, dzięki czemu polityka może podejmować różne decyzje w zależności od środowiska. |
annotation-transform | input.targets — każdy komponent, który dołączenie może opatrzyć adnotacjami, każdy z polami boundary_path, component_name — dla komponentu umieszczanego przez wpis routingu jest to jego identyfikator w grafie buildu, np. metrics.query — i annotations, które encja Release zapisuje na samym komponencie, przy czym każda wartość jest taka, jak została zapisana: ciąg znaków, obiekt podkluczy lub null, gdy komponent rezygnuje z adnotacji, którą by odziedziczył. Każdy klucz, który niesie komponent, jest obecny niezależnie od wartości, więc reguła może pozostawić bez zmian klucz, który ktoś już zapisał. input.binding_keys — klucze adnotacji, dla których encja Manifest rejestruje powiązanie. |
Zasób Terraform odczytuje się pod inną ścieżką w każdej z dwóch form Terraform. W documents natywnego pliku .tf blok jest zagnieżdżony pod swoim typem, a następnie pod każdą ze swoich etykiet, a ostatnia etykieta zawiera listę bloków, ponieważ bloki o tym samym typie i etykietach są zbierane w jedną listę w kolejności źródłowej. Atrybut zasobu odczytuje się zatem pod input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — dla instancji RDS o dowolnej nazwie jest to input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Plik .tf.json jest odczytywany tak, jak zapisała go encja Recipe, więc jego zwyczajowa forma obiektowa, w której nazwa zawiera sam blok, odczytuje się pod resource.<type>.<name>.<attr>, a polityka przeznaczona dla obu form odczytuje obie ścieżki. Dotyczy to obu silników polityk wewnątrz kompilatora. Dla reguły Rego napisanej dla drugiej formy wskazana ścieżka jest niezdefiniowana: reguła sprawdzająca tam wartość nigdy się nie uruchamia, a reguła odrzucająca przy braku wartości, za pomocą not, uruchamia się dla każdego zasobu; wyrażenie CEL, które indeksuje lub wybiera w drugiej formie, zatrzymuje kompilację błędem ewaluacji wskazującym jego plik polityki. Referencyjny adapter renderowania Rego, opisany poniżej w sekcji Adaptery polityk etapu renderowania, sam parsuje natywny plik .tf i odczytuje pojedynczy blok jako obiekt, więc gdy polityka przechodzi między tym adapterem a silnikiem wewnątrz kompilatora, ścieżkę Terraform należy zmodyfikować, a nie skopiować.
Każda rola zawiera dodatkowo input.sources — własne pliki dołączenia, każdy z path będącym nazwą bazową i swoim content. Polityka działa wyłącznie jako jeden z tych plików, więc wszędzie tam, gdzie reguła odczytuje tę listę, zawiera ona co najmniej ten plik.
input.settings to obiekt ustawień dołączenia, ten sam obiekt co dokument data polityki, obecny wtedy, gdy dołączenie deklaruje ustawienia. Gdy dołączenie żadnych nie deklaruje, to, co znajdzie reguła, zależy od roli: w ir-verdict, label-transform i annotation-transform pole jest nieobecne, więc input.settings jest niezdefiniowane jak każda ścieżka, której ładunek nie zawiera, a w render-verdict jest pustym obiektem. Dlatego reguła zależna od tego, czy ustawienie zostało skonfigurowane, sprawdza odczytywane ustawienie, a nie obiekt, co działa tak samo w każdej roli — skonfigurowane max_nodes zostaje odczytane, a nieskonfigurowane pozostawia input.settings.max_nodes niezdefiniowane i regułę milczącą:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}Silnik CEL traktuje niezadeklarowany obiekt ustawień inaczej i opisuje to w swojej własnej sekcji poniżej.
attached_features i binding_keys są listami, a nie obiektami, więc polityka
sprawdza przynależność za pomocą in:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features jest sumą typów Feature wszystkich dołączeń dowolnego węzła na
ścieżce — łącznie z dołączeniem zapisanym na jednym z połączeń tego węzła, niezależnie
od tego, na którym połączeniu je zapisano — więc regułę spełnia dołączenie
core/data-masking na samej bramie, czyli tam, gdzie ta Feature się dołącza: wybiera
ona zdolność maskowania treści, którą deklaruje brama. Dołączenie maskuje tekst czatu
i uzupełnień przechodzący przez tę bramę; reguła sprawdza, czy dołączenie istnieje,
a nie, co wymienia.
Ponieważ jest to suma po całej ścieżce, lista mówi, że Feature jest dołączona gdzieś na trasie, ale nigdy gdzie. Reguła, która musi wiedzieć, czy Feature znajduje się pomiędzy dwoma konkretnymi komponentami trasy — tym, który przechowuje dane zastrzeżone, i tym, do którego one docierają — odczytuje kolejno nodes trasy oraz własne dołączenia każdego węzła pod input.graph.spec.feature_values_mapping[<node>]; to samo pytanie zadane attached_features przepuszcza trasę, na której Feature znajduje się za drugim komponentem. ../examples/policy-data-class-route/ jest napisany w ten sposób dla silnika Rego, silnika CEL i OPA.
Obiekt węzła nie zawiera własnego identyfikatora: identyfikatorem jest klucz, pod którym
się znajduje w input.graph.spec.nodes, dlatego powyższa reguła przenosi do komunikatu
identyfikatory odczytane z path.nodes, zamiast odczytywać pole id.
Kolejność, w jakiej polityka napotyka klucze mapy
Graf zachowuje kolejność zapisaną przez autora: węzły w kolejności deklaracji komponentów, a etykiety każdego węzła w kolejności, w jakiej węzeł je zawiera. Ta kolejność trafia do gościa nienaruszona — ładunek przenosi oba jako uporządkowane wpisy (zob. mapy zachowujące kolejność). To, czy polityka ją napotka, zależy od tego, jak silnik oceniający politykę przechowuje obiekt, a nie od ładunku:
- Silnik Rego przechowuje klucze obiektu posortowane. Reguła iterująca po
input.graph.spec.nodes,labelswęzła lub dowolnym innym obiekcie — łącznie z obiektem zapisanym w samej polityce — napotyka klucze w kolejności posortowanej: komponenty zadeklarowane jakoweb,api,metricssą napotykane jakoapi,metrics,web. - Silnik CEL nie ustala kolejności mapy. Wyrażenie składane po
input.graph.spec.nodeslub polabelswęzła może napotkać klucze w innej kolejności w dwóch kompilacjach identycznych danych wejściowych, a dwa przejścia tej samej mapy w jednym wyrażeniu mogą się od siebie różnić. Dlatego komunikaty pod jednym kluczem decyzji są sortowane: należy pisać reguły, których decyzja nie zależy od pozycji klucza. - Gość napisany z użyciem zestawu do tworzenia wtyczek napotyka kolejność autora. Po zdekodowaniu przez zestaw węzły i etykiety każdego węzła trafiają do zachowującego kolejność kontenera zestawu w kolejności, w jakiej przenosi je ładunek, a szkielet adaptera zarządczego dostarczany z każdym zestawem przekazuje swojemu silnikowi dokument JSON zapisany w tej samej kolejności. Silnik, który konwertuje ten dokument na własny typ wartości, napotyka zamiast tego kolejność tego typu, jak opisano w mapach zachowujących kolejność.
Kształtowanie etykiet: polityka nazywa etykietę, a silnik ją adresuje
W roli kształtującej etykiety polityka zbiera jedną decyzję na etykietę pod labels,
wskazując węzeł, klucz etykiety i wartość, którą etykieta przyjmuje:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Ustawienie klucza, który już istnieje, zastępuje jego wartość. Decyzja może zamiast tego zażądać usunięcia klucza:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Polityka nazywa etykietę, zamiast zapisywać instrukcję edycji stosowaną przez kompilację,
a powód warto znać: instrukcja adresuje etykietę ścieżką, a klucz etykiety w Aggrega
często zawiera /, który jest separatorem ścieżki — więc ręcznie zapisana ścieżka
adresowałaby zagnieżdżoną lokalizację zamiast jednej etykiety. Silnik adresuje etykietę
wskazaną w decyzji, więc znaki ucieczki są zapisane raz, a nie w każdej polityce,
a polityka pozostaje czytelna jako stwierdzenie o etykietach, a nie o ścieżkach.
Decyzja może zmienić wyłącznie etykietę. Każda instrukcja emitowana przez silnik adresuje jedną etykietę jednego węzła, więc polityka nie ma możliwości wyrażenia zmiany encji Component węzła, jego rozwiązanej wersji, zbioru węzłów ani wartości etykiety, która nie jest ciągiem znaków. Decyzja wskazująca węzeł, którego kompilacja nie ma, lub usuwająca etykietę, której węzeł nie zawiera, jest odrzucana przez kompilację z komunikatem wskazującym instrukcję — nigdy nie jest po cichu ignorowana.
../examples/policy-label-transform/ dołącza taką politykę obok dwóch wbudowanych pluginów tagujących, a także werdykt nad grafem, który odczytuje zapisywane przez nie etykiety. Co każdy z tych pluginów odczytuje i zapisuje, opisano na stronie Wbudowane pluginy tagujące.
Wstrzykiwanie adnotacji
W roli wstrzykującej adnotacje polityka zbiera jedną decyzję na adnotację pod
annotations, wskazując cel za pomocą współrzędnej, którą zawiera sam cel, oraz
klucz i jego wartość:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}Nazwy pól zapisywane przez decyzję są nazwami pól, pod którymi odczytała swoje cele, więc konwencję można poznać z samego ładunku. Odczyt input.binding_keys pozwala polityce wstrzykiwać tylko klucze, dla których encja Manifest zarejestrowała znaczenie — to one rozwijają się w dołączenie Feature.
Wartość decyzji to taka, którą można by samodzielnie zapisać w tej adnotacji: ciąg znaków lub obiekt podkluczy. Powiązanie kierujące jeden podklucz przyjmuje ciąg znaków; powiązanie kierujące kilka przyjmuje obiekt wskazujący każdy z nich, dokładnie tak, jak operator zapisuje go w encji Release:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}Kompilacja odczytuje wstrzykniętą wartość dokładnie tak, jak tę samą wartość zapisaną w encji Release, więc rozwija się ona w ten sam sposób i w ten sam sposób jest sprawdzana względem powiązanej encji Feature. Silnik przechowuje klucze obiektu posortowane, więc podklucze docierają do kompilacji w posortowanej kolejności. Wartość o jakimkolwiek innym kształcie — null, lista, liczba, wartość logiczna lub obiekt bez podkluczy — jest odrzucana przez kompilację ze wskazaniem wstrzyknięcia: rola dodaje adnotacje, a null lub pusty obiekt odczytuje się jako rezygnację, którą autor zapisuje, aby usunąć adnotację. Decyzja wskazująca komponent, którego ładunek nie zawiera, jest odrzucana w ten sam sposób, z podaniem współrzędnej i adnotacji.
Gdy kompilacja odrzuca wstrzykniętą adnotację ze względu na sposób jej kierowania lub jej zawartość — ciąg znaków przekazany do powiązania kierującego kilka podkluczy, wartość podklucza, której schemat powiązanej encji Feature nie dopuszcza, lub podklucz kierowany przez filar values, którego adnotacja po stronie encji Release nie może używać — odmowa wskazuje plugin, który ją wstrzyknął, i rolę zarządzania, w której jest on dołączony, dzięki czemu wartość da się prześledzić do polityki, która o niej zdecydowała, a nie do wiersza encji Release, którego nikt nie napisał.
../examples/policy-annotation-transform/ dołącza taką politykę, wstrzykując ciąg znaków pod jednym powiązaniem i obiekt podkluczy pod innym, i buduje te same pliki co encja Release zapisująca te adnotacje ręcznie.
Dołączanie całego zestawu polityk jako jednego archiwum
Zestaw polityk dołącza się plik po pliku albo jako jedno archiwum zawierające razem jego pliki polityk i dokumenty danych — w kształcie, jaki buduje zestaw narzędzi Rego. Zawartość dołączonego pliku trafia do gościa jako tekst, a skompresowane archiwum to dowolne bajty, a nie tekst, dlatego archiwum dołącza się zakodowane w base64, z nazwą kończącą się na .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64To nazwa oznacza plik jako archiwum, a nie jako tekst polityki, dzięki czemu wybór pozostaje wyraźną deklaracją operatora: uszkodzone archiwum jest wtedy zgłaszane jako uszkodzone archiwum, ze wskazaniem pliku i kroku, który się nie powiódł, zamiast być odczytywane jako plik polityki, którego nie da się sparsować. Zakodowanie archiwum to krok, który operator dodaje po zbudowaniu go przez swój zestaw narzędzi.
Wewnątrz archiwum każdy element .rego jest modułem polityki, a każdy element data.json lub data.yaml jest dokumentem danych zagnieżdżonym pod katalogiem, w którym się znajduje — limits/data.json zawierający {"max": 3} polityka odczytuje jako data.limits.max. Elementy każdego innego rodzaju archiwum przenosi na potrzeby własnego zestawu narzędzi i nie stanowią one wejścia polityki.
Archiwum, którego nie da się otworzyć, powoduje błąd wskazujący dołączony plik: kodowanie, którego nie da się zdekodować, strumień, którego nie da się zdekompresować, obcięte archiwum, plik danych, którego nie da się odczytać, albo archiwum niezawierające żadnej polityki. Żaden z tych przypadków nie daje pustego zestawu polityk, ponieważ pusty zestaw polityk nie podejmuje żadnej decyzji — a „archiwum było nieczytelne” nigdy nie może być nieodróżnialne od „polityka dopuściła build”.
Pisanie polityki dla silnika CEL
Silnik wykonuje napisany przez operatora kod CEL w całości wewnątrz gościa, w tej z czterech ról, w której został dołączony. Jego tożsamość w katalogu to sama nazwa cel
pod pluginType: governance — współrzędna governance/cel — a jego wersja to
wydanie kompilatora, które go dostarcza. Dołączenie go dwukrotnie, w dwóch rolach, z dwoma
różnymi plikami polityk, pozwala jednemu silnikowi objąć dwa momenty tego samego budowania.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Polityka odwołuje się do całego ładunku przez jedną nazwę, input, więc nazwy, które odczytuje,
to nazwy nadane im w protokole: graf budowania pod input.graph, wyliczone
ścieżki routingu pod input.precalculated_paths, wyrenderowane pliki pod
input.artifacts, cele adnotacji pod input.targets. Te ścieżki dla poszczególnych ról to
te zestawione w tabeli Co udostępnia ładunek każdej roli
powyżej i są identyczne dla obu silników — jeden protokół, odczytywany pod jedną nazwą główną.
Własne pliki dołączenia znajdują się pod input.sources, a jego ustawienia pod input.settings, więc próg podany przez operatora odczytuje się jako input.settings.max_nodes. Nie ma drugiego dokumentu do poznania: ustawienia są częścią input jak wszystko inne. Oba są zawsze obecne jako wartość — gdy dołączenie żadnych nie deklaruje, ustawienia są pustym obiektem w każdej roli — więc wyrażenie odwołujące się do nich nie musi zabezpieczać się przed ich brakiem, a to, czy dane ustawienie zostało skonfigurowane, sprawdza się testem na jego kluczu: has(input.settings.max_nodes).
Dwie formy zapisu i nazwa pliku, która decyduje między nimi
Politykę dołącza się w jednej z dwóch form, a o tym, w której, mówi nazwa pliku:
| Nazwa pliku kończy się na | Odczytywany jako |
|---|---|
.cel | jedno wyrażenie, wykonywane w niezmienionej postaci |
.yaml lub .yml | dokument reguł — lista reguł |
| cokolwiek innego | jedno wyrażenie |
Nazwa to cała reguła. Żadne ustawienie nie wybiera formy, a tekst pliku nie jest badany, by ją odgadnąć — i tak nie mógłby rozstrzygnąć tej kwestii, ponieważ najbardziej zewnętrzna wartość wyrażenia jest mapą, podobnie jak dokumentu reguł, co sprawia, że obu form nie da się odróżnić po kształcie.
Reguła działa więc w obie strony, a oba błędy są odrzucane, a nie
błędnie odczytywane. Dokument reguł nazwany policy.cel zostaje odrzucony, ponieważ lista reguł
YAML nie jest wyrażeniem; wyrażenie nazwane policy.yaml zostaje odrzucone, ponieważ
wyrażenie nie jest listą reguł. Każde odrzucenie wskazuje plik. Zmiana nazwy pliku jest
rozwiązaniem w obu kierunkach.
Zestaw polityk składa się z tylu plików, ilu potrzebuje, a obie formy można dowolnie łączyć w jednym dołączeniu.
Wyrażenie w pliku o nazwie .cel
Język wyrażeń nie ma nazw reguł, pod którymi można by zbierać decyzje, więc decyzje są wartością, którą wyrażenie zwraca: mapą z klucza decyzji na to, co ten klucz zbiera. W roli werdyktu klucz zbiera komunikaty osiągnięte pod nim; w roli, która kształtuje budowanie, zbiera decyzje do zastosowania.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Klucz pominięty w pliku nie osiągnął tam żadnej decyzji, więc plik nie musi wymieniać każdego klucza — a każda rola odczytuje tylko klucz, którego dotyczy, więc jeden zestaw polityk może obsłużyć rolę werdyktu i rolę kształtującą budowanie z tych samych plików. Klucz zawiera listę tego, co zbiera, pojedynczy element albo wartość null oznaczającą brak.
Wyrażenie, które zwraca cokolwiek innego niż mapę, zostaje odrzucone, a komunikat wskazuje kształt,
który należy zapisać. Samo size(input.graph.spec.nodes) <= 5 to błąd, którego warto się spodziewać:
jest to wartość logiczna, a odczytanie false jako zatrzymania oznaczałoby wymyślenie komunikatu, którego
autor nigdy nie napisał.
Dokument reguł w pliku o nazwie .yaml lub .yml
Dokument reguł to lista reguł, z których każda wskazuje osiągany klucz decyzji, wyrażenie rozstrzygające, czy zostaje on osiągnięty, oraz to, co jest zgłaszane, gdy tak się stanie:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentTo, co zgłasza reguła, zależy od osiąganego klucza decyzji, dokładnie tak jak w wyrażeniu. Tekst to komunikat, który niesie werdykt. Mapowanie to pola jedynej decyzji, którą odczytuje rola kształtująca budowanie:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldTo, którą z tych dwóch rzeczy zapisuje reguła, rozstrzyga wyłącznie sama reguła — nie ma ustawienia, które by ją wybierało — a reguła zapisująca niewłaściwą dla swojego klucza zostaje odrzucona z podaniem nazwy.
Jeden szczegół YAML, który warto znać, zanim da o sobie znać: wyrażenie zaczynające się od cudzysłowu
musi zostać ujęte w cudzysłów dla czytnika dokumentu, ponieważ wartość zaczynająca się od " jest
odczytywana jako skalar w cudzysłowie, a nie jako tekst zaczynający się od cudzysłowu.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyDokument reguł jest odczytywany jako wyrażenie, któremu odpowiada, zanim cokolwiek zostanie wykonane. Każda reguła staje się swoim kluczem decyzji, niosącym jej zgłoszenie, gdy wyrażenie jest spełnione, i nic, gdy nie jest, a reguły o wspólnym kluczu są łączone. Tak więc jeden ewaluator wykonuje obie formy, a dokument reguł rozstrzyga dokładnie to, co odpowiadające mu wyrażenie — w każdej roli, zarówno werdykty, jak i decyzje kształtujące budowanie. Wynikają z tego dwie konsekwencje. Dokument i odpowiadające mu wyrażenie napisane ręcznie osiągają te same decyzje, ponieważ są tą samą ewaluacją. A opisane poniżej reguły kolejności dotyczą formy wykonywanej, a nie dokumentu — reguły dokumentu nie są zgłaszane w kolejności, w jakiej je zapisano.
Która forma pasuje — nie są wymienne
Obie formy przechodzą przez jeden ewaluator, więc żadna nie jest szybsza ani bardziej godna zaufania od drugiej. Różni je to, co każda potrafi wyrazić, a ponieważ dwie formy to dwie rzeczy do nauczenia się, warto jasno określić podział, zamiast zostawiać go gustowi. Należy wybierać według tego, co reguła zgłasza.
- Dokument reguł, gdy zgłoszenie jest stałe. Komunikat lub decyzję zapisuje się raz, obok wyrażenia, które ją osiąga, a plik czyta się jak listę warunków. To krótsza forma dla „jeśli to jest prawdą, powiedz dokładnie to”.
- Wyrażenie, gdy zgłoszenie wskazuje to, co znalazło. Jedno wyrażenie filtruje
komponenty budowania i tworzy komunikat — lub decyzję — dla każdego komponentu, więc
czytelnik otrzymuje
component payments tracks the latest version; pin itdla każdego naruszającego komponentu zamiast jednego zdania o liczbie.
Tego drugiego zadania dokument reguł wykonać nie może: każda z jego reguł niesie jedno zgłoszenie, zapisane z góry, więc nie może nic powiedzieć o tym, który komponent ją wyzwolił. Sięgnięcie po formę dokumentu, a potem chęć umieszczenia nazwy naruszającego komponentu w komunikacie, to droga kończąca się przepisaniem reguły jako wyrażenia, dlatego warto rozstrzygnąć tę kwestię od początku.
Co może wyrazić wyrażenie
Wyrażenia wykonywane przez ten silnik korzystają z komprehensji filter, map i exists,
+ na ciągach znaków i listach, size, in, startsWith, string(),
operatora warunkowego oraz listy indeksowanej obliczoną liczbą całkowitą. Nie
oferują funkcji rozszerzeń dodawanych przez niektóre środowiska CEL: join, split,
substring, indexOf, flatten, cel.bind i lists.range są każda odrzucane jako
niezadeklarowane odwołanie, a komprehensja przyjmuje jedną zmienną, więc forma dwuzmiennowa,
taka jak exists(i, v, …), jest odrzucana w ten sam sposób. Odrzucenie to błąd budowania wskazujący
plik i odwołanie:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Trzy konsekwencje kształtują regułę, która przechodzi trasę:
- Nie ma sposobu, by nazwać wartość pośrednią. Podwyrażenie użyte dwukrotnie
zapisuje się dwukrotnie albo wiąże przez mapowanie listy jednoelementowej:
[value].map(name, …)[0]wykonuje swoje ciało raz, znamepowiązanym zvalue. - Nie ma sposobu, by przejść po pozycjach listy. Reguła porównująca komponenty trasy
według pozycji pobiera pozycje ze swoich ustawień — listę
positions, taką jak[0, 1, 2, …]— i indeksuje trasę w każdej z nich, więc musi zabezpieczyć się przed trasą dłuższą niż sama lista, zatrzymując się na takiej, zamiast odczytywać ją częściowo. - Klucz decyzji zbiera komunikaty, a nie ich listy. Wyrażenie tworzące jedną listę komunikatów na trasę jest odrzucane pod kluczem decyzji — błąd informuje, że zebrano wartość typu lista zamiast komunikatu — więc reguła tworzy jeden rekord na trasę i z niego buduje komunikat. Komunikat, który wyrażenie utworzy dwukrotnie, jest zgłaszany dwukrotnie: opisane poniżej sortowanie porządkuje to, co klucz zebrał, i nie usuwa powtórzeń.
../examples/policy-data-class-route/ zawiera regułę CEL napisaną z uwzględnieniem wszystkich trzech, obok tej samej reguły dla silnika Rego.
Klucze decyzji i poziomy ważności
Klucze decyzji, domyślne mapowanie na poziomy ważności oraz ustawienie translation, które zmienia ich nazwy, są takie same jak w silniku Rego — zob.
Polityka zbiera swoje decyzje pod kluczem decyzji
powyżej. Domyślnie deny raportuje na poziomie halt, warn na poziomie warn, a audit na poziomie info; zadeklarowane translation zastępuje to ustawienie domyślne, a nie je rozszerza, a zadeklarowana w nim kolejność jest kolejnością raportowania werdyktów.
Oba silniki deklarują dla niego ten sam schemat ustawień, więc blok translation oznacza
to samo niezależnie od języka, w którym wyrażono decyzje, a blok o błędnej postaci jest
odrzucany, zanim uruchomi się jakakolwiek polityka.
W roli kształtującej build klucz jest stały, a nie mapowany: labels w roli
kształtującej etykiety, annotations w roli wstrzykującej adnotacje.
Kolejność: sortowanie w obrębie klucza i porządek całkowity decyzji
Komunikaty pod jednym kluczem decyzji są raportowane w kolejności posortowanej. Jest to część
kontraktu, a nie wybór sposobu prezentacji, a powód warto zapamiętać: wyrażenie
listowe (comprehension) nad mapą — .filter(...) i .map(...) nad input.graph.spec.nodes,
co jest najbardziej naturalnym sposobem pisania reguły dla każdego komponentu — przechodzi tę mapę w
kolejności, której ewaluator nie ustala. Bez sortowania identyczne dane wejściowe raportowałyby te same
komunikaty w innej kolejności przy każdym buildzie. Sortowanie to eliminuje.
Wynikają z tego dwie rzeczy, które łatwo wziąć za błędy, choć nimi nie są:
- Reguły dokumentu reguł również są raportowane posortowane, a nie w kolejności, w jakiej je zapisano — ponieważ dokument jest ewaluowany jako wyrażenie, któremu odpowiada, a sortowanie dotyczy tego, co zebrał klucz.
- Ręcznie zapisana lista także jest sortowana. Klucz zawierający
["second", "first"]raportujefirstprzedsecond. Nic w wyniku ewaluacji nie odróżnia listy wpisanej przez autora od listy utworzonej przez wyrażenie listowe, więc nie ma autorskiej kolejności do zachowania.
Między kluczami obowiązuje kolejność zadeklarowana w translation. Między plikami jest to
kolejność nazw plików, ponieważ źródła dołączenia docierają posortowane według nazwy,
a nie w kolejności, w jakiej wymienia je dołączenie.
W roli kształtującej build to samo rozumowanie dotyczy samych decyzji, a kolejność jest silniejsza: decyzje są raportowane w porządku rosnącym wszystkiego, co nazywają, co stanowi porządek całkowity tego, co decyzja może wyrazić — węzeł, potem klucz etykiety, potem to, czy etykieta jest dodawana czy usuwana, potem wartość; a dla wstrzyknięcia: granica, potem komponent, potem klucz adnotacji, potem jego wartość. Zmiana etykiet lub adnotacji trafia do wyrenderowanego wyniku, więc dowolna kolejność oznaczałaby, że identyczne dane wejściowe renderują się inaczej w kolejnych buildach.
Kształtowanie etykiet
W roli kształtującej etykiety polityka zbiera jedną decyzję na etykietę pod labels,
wskazując węzeł, klucz etykiety i wartość, którą etykieta przyjmuje:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Ustawienie klucza, który już istnieje, zastępuje jego wartość. Decyzja może zamiast tego zażądać
usunięcia klucza, podając op jako remove:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Pojedyncza decyzja nie wymaga otaczającej listy, a plik, który nie podaje klucza labels, nie decyduje o żadnych
etykietach.
Polityka nazywa etykietę, zamiast zapisywać instrukcję edycji, którą stosuje build,
z powodu podanego w
sekcji o kształtowaniu etykiet silnika Rego:
klucz etykiety w Aggrega często zawiera /, a ręcznie zapisana ścieżka wskazywałaby
zagnieżdżone miejsce zamiast jednej etykiety. Silnik adresuje etykietę, którą nazywa
decyzja.
Odczyt etykiety, której węzeł może nie mieć, jest błędem, a nie pustą wartością, dlatego drugi przykład sprawdza, czy klucz istnieje, zanim go odczyta. Jest to własna reguła języka wyrażeń dotycząca odczytu nieobecnego klucza i jest ona głośna: polityka sięgająca po etykietę, której nie ma żaden węzeł, zgłasza, że nie mogła zostać obliczona, zamiast po cichu niczego nie decydować.
Decyzja może jedynie zmienić etykietę. Decyzja wskazująca węzeł, którego build nie zawiera, lub usuwająca etykietę, której węzeł nie ma, jest odrzucana przez build z komunikatem wskazującym instrukcję — nigdy nie jest po cichu ignorowana.
Należy osiągać jedną decyzję na węzeł i klucz etykiety. Reguła, która może wygenerować dwie różne wartości dla tej samej etykiety tego samego węzła, jest niedookreślona: wartość należy rozstrzygnąć wewnątrz wyrażenia — za pomocą operatora warunkowego lub filtra przepuszczającego jedną gałąź — zamiast emitować obie decyzje.
../examples/policy-label-transform/ pokazuje rolę kształtującą etykiety od początku do końca, z polityką napisaną dla silnika Rego.
Wstrzykiwanie adnotacji pod zarejestrowanym kluczem
W roli wstrzykującej adnotacje polityka zbiera jedną decyzję na adnotację pod
annotations, wskazując cel za pomocą współrzędnej, którą nosi sam cel, a także
klucz i jego wartość:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}Nazwy pól zapisywane przez decyzję są nazwami pól, pod którymi odczytała ona swoje cele, więc
konwencję można poznać z samego ładunku. Odczyt input.binding_keys pozwala
polityce wstrzykiwać tylko klucze, dla których Manifest zarejestrował znaczenie — to
te, które rozwijają się w dołączenie Feature. Każde pole jest wymagane: adnotacja z
pustym kluczem lub pustą nazwą komponentu nie jest czymś, o co polityka chciała poprosić.
Granica, pod którą znajduje się komponent, może zasadnie być nazwana pustym ciągiem, więc to
pole musi być obecne, ale może być puste.
Wartość to taka, którą można by samodzielnie zapisać w tej adnotacji: ciąg znaków lub mapa podkluczy, która zasila powiązanie kierujące kilka podkluczy naraz — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Silnik zapisuje podklucze mapy w posortowanej kolejności, ponieważ język wyrażeń nie ustala kolejności dla mapy, i przekazuje wartość dalej tak, jak wyprodukowało ją wyrażenie; wartość, której model JSON nie może przechować — bajty, znacznik czasu, czas trwania — jest odrzucana, a nie zamieniana na tekst. Kompilacja odczytuje następnie wartość dokładnie tak, jak tę samą wartość zapisaną w encji Release, i odrzuca null, listę, liczbę, wartość logiczną lub pustą mapę, wskazując wstrzyknięcie. Dwie decyzje dla jednego komponentu i klucza z różnymi wartościami są porządkowane według JSON wartości. annotations celu niosą każdą istniejącą wartość tak, jak została zapisana — ciąg znaków, mapę lub null oznaczający rezygnację — więc test "feature.aggrega.ai/monitoring" in t.annotations znajduje klucz niezależnie od jego wartości.
Decyzja wskazująca komponent, którego ładunek nie zawiera, jest odrzucana przez build, z podaniem współrzędnej i adnotacji. Gdy build odrzuca wstrzykniętą adnotację ze względu na jej kierowanie, wartości jej podkluczy lub jej filar, odmowa wskazuje plugin, który ją wstrzyknął, i rolę, w której jest on dołączony. Podobnie jak w przypadku etykiet, należy osiągać jedną decyzję na komponent i klucz adnotacji, rozstrzygając wartość wewnątrz wyrażenia, zamiast emitować dwie decyzje dla jednego klucza.
../examples/policy-annotation-transform/ pokazuje rolę wstrzykującą adnotacje od początku do końca, z polityką napisaną dla obu silników.
Gdy polityki lub decyzji nie da się odczytać
Polityka, której silnik nie może odczytać ani obliczyć lub która generuje coś innego
niż decyzje w udokumentowanej postaci, powoduje, że build kończy się niepowodzeniem, zamiast zwrócić
werdykt lub zmianę. Niepowodzenie jest zgłaszane jako błąd builda wskazujący plik oraz,
gdy błąd dotyczy jednej części pliku, pozycję w nim — celowo
odrębnie od werdyktu halt, aby „tej polityki nie dało się obliczyć” nigdy nie zostało
wzięte za „ta polityka dopuszcza build”.
Dla wyrażenia obejmuje to źródło, którego nie da się sparsować — zgłaszane z własnym wierszem i kolumną parsera oraz znakiem ^ pod błędną pozycją — oraz źródło, które daje w wyniku coś innego niż mapę z klucza decyzji na to, co ten klucz zbiera.
Dla dokumentu reguł obejmuje to tekst, który nie jest listą reguł, listę bez reguł, regułę bez pola lub z pustym polem, pole, którego forma nie definiuje, raport, który nie jest ani tekstem, ani mapowaniem tekstu na tekst, oraz wyrażenie, którego nie da się odczytać. Błąd dotyczący jednej reguły wskazuje pozycję tej reguły — liczoną od jednego, tak jak autor liczy we własnym pliku — oraz jej klucz decyzji. Reguła, której wyrażenia nie da się sparsować, jest odrzucana przed ewaluacją, więc znak ^ trafia do wyrażenia napisanego przez autora, a nie na pozycję w przetłumaczonym tekście, którego autor nigdy nie widział.
Dla decyzji w roli kształtującej build obejmuje to komunikat w miejscu, gdzie powinna
być decyzja, brakującą współrzędną oraz pole, którego forma decyzji tego silnika nie
definiuje. Ten ostatni przypadek warto podkreślić osobno: błędnie zapisane annotation_valu
jest odrzucane, a nie ignorowane, więc pomyłka zostaje zgłoszona, zamiast po cichu wstrzyknąć
pustą wartość i zostawić build, który kończy się bez zmiany. Każde takie
odrzucenie wskazuje plik i kończy się informacją, co musi nazywać decyzja tego rodzaju.
Adaptery polityk etapu renderowania
Adapter etapu renderowania analizuje wyrenderowane wyjście kompilacji zamiast jej grafu IR. Ładunek renderowania zawiera wyemitowane artefakty — każdy z jego ścieżką wyjściową i wyrenderowaną treścią, a tam, gdzie ma to zastosowanie, także z formatem, w którym został wyrenderowany, i sparsowanym widokiem strukturalnym — oraz własne źródła i ustawienia dołączenia, każde tam, gdzie dołączenie je deklaruje. Adapter odczytuje tę treść pod kątem docelowego kształtu wyjścia, ewaluuje politykę na wyniku strukturalnym i mapuje rezultat na werdykty halt / warn / info. Ponieważ ładunek nie nazywa żadnego własnego kształtu wyjścia, jeden wzorzec adaptera obsługuje dowolny cel renderowania; nowy kształt wyjścia to nowy adapter, a nie zmiana hosta.
Każdy adapter etapu renderowania jest adapterem w powyższym sensie: na zewnątrz posługuje się ABI Aggrega, a do wewnątrz wchłania format specyficzny dla celu lub kontrakt obcego silnika polityk, dzięki czemu kompilator pozostaje wolny od jakiejkolwiek logiki formatów wyjścia czy polityk. Silniki Rego i CEL w kompilatorze obsługują rolę render-verdict bezpośrednio; poza nimi wśród przykładów w Rust z zestawu deweloperskiego pluginów dostarczane są dwa referencyjne adaptery etapu renderowania jako przykłady, po jednym na każdy typowy kształt wyjścia.
../examples/policy-render-verdict/ dołącza jedną regułę w render-verdict do wyjścia czterech celów — obiektów Kubernetes, pliku Docker Compose, głównej konfiguracji Terraform i szablonu CloudFormation — napisaną raz dla każdego silnika w kompilatorze, i sprawdza, że podłożone w każdym celu naruszenie zatrzymuje kompilację, a jego wariant kontrolny przechodzi.
Aby napisać własny adapter, w tej roli lub dowolnej innej, należy zacząć od szkieletu adaptera zarządzania dostarczanego z każdym zestawem deweloperskim pluginów: Pisanie własnego pluginu zarządzania prowadzi od tego szkieletu do kompilacji, którą adapter odrzuca.
Wyjście YAML, JSON i Terraform HCL — referencyjny adapter renderowania Rego
Referencyjny adapter renderowania Rego uruchamia dostarczone przez operatora polityki Rego na dowolnym wyjściu
renderowania YAML lub JSON oraz na natywnym wyjściu HCL Terraform. Jest przykładem
kształtu etapu renderowania: ten sam natywny dla Wasm ewaluator Rego co silnik w
kompilatorze i ta sama konwencja zbierania deny / warn / audit mapowana na
te same trzy poziomy ważności werdyktów, przy czym analiza dotyczy wyrenderowanych plików, a nie
grafu kompilacji.
Jest niezależny od kształtu wyjścia w obrębie celów YAML/JSON. Adapter parsuje
treść każdego artefaktu jako jeden lub więcej dokumentów YAML lub JSON — YAML jest
nadzbiorem JSON, więc szablon JSON, taki jak stos CloudFormation, jest parsowany
tym samym parserem — i udostępnia sparsowane dokumenty polityce
obok surowej treści. Polityka analizuje strukturalne wyjście renderowania
dowolnego takiego celu za pomocą zwykłego Rego: input.artifacts[_].documents[_] zwraca
sparsowane dokumenty (services pliku Docker Compose, Resources szablonu
CloudFormation), input.artifacts[_].content zwraca surowy tekst, a
obiekt settings dołączenia jest dokumentem data Rego. Na przykład polityka
wymagająca zatwierdzonego rejestru dla wyjścia Docker Compose odrzuca każdą usługę,
której obraz nie ma prefiksu rejestru.
Adapter analizuje także natywne wyjście HCL Terraform. Natywny
plik .tf nie jest ani YAML, ani JSON, więc adapter rzutuje go na ten sam
kanoniczny obiekt, do którego parsowany jest plik Terraform-JSON (.tf.json): polityka
odczytuje atrybut zasobu pod
input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — dla instancji
RDS input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage
— w ten sam sposób niezależnie od tego, którą formę Terraform wyemitował kompilator. Typy atrybutów są
zachowywane (liczba pozostaje liczbą, wartość logiczna wartością logiczną), a nierozwiązane
wyrażenie Terraform pozostaje ciągiem znaków w postaci ${ ... }. Treści Terraform-JSON
(.tf.json, .auto.tfvars.json) są parsowane ścieżką YAML/JSON bez zmian, a
plik szablonu Terraform (.tftpl) — tekst szablonu, a nie samodzielna
konfiguracja — nie jest rzutowany i zgłasza parse_error jak każda
niestrukturalna treść.
Ta lista mówi, co akceptuje parser adaptera, a nie co emituje kompilator. Te dwa zbiory nie są takie same, a automatycznie ładowany plik zmiennych jest przypadkiem, w którym się różnią: kompilator nie emituje takiej nakładki na żadnej ścieżce — wejścia modułu ze źródła to argumenty bloku modułu danego komponentu w głównej konfiguracji granicy — więc ten kształt trafia do widoku polityki tylko wtedy, gdy dołączony moduł dostarcza własny taki plik, który ścieżka źródłowa kopiuje do wyjścia dosłownie. Polityka napisana z założeniem, że kompilator go wygeneruje, nigdy nie zadziała.
Gdy treści artefaktu nie da się sparsować, adapter nie przepuszcza jej po cichu: zachowuje surową treść, nie udostępnia sparsowanych dokumentów dla tego artefaktu i zapisuje komunikat parsera pod input.artifacts[_].parse_error, dzięki czemu polityka może jawnie zatrzymać kompilację na błędnie sformatowanym artefakcie. Podobnie jak w przypadku silnika Rego w kompilatorze, polityka wywołująca funkcję wbudowaną, której osadzony ewaluator nie implementuje, kończy się głośnym błędem — błędem wskazującym plugin, nigdy cichym przepuszczeniem.
Wyjście Kubernetes — adapter renderowania Kubewarden
Adapter renderowania Kubewarden uruchamia polityki dopuszczenia w stylu Kubewarden na
wyrenderowanych manifestach Kubernetes. Wchłania do wewnątrz kontrakt admission-review
Kubernetes: polityka Kubewarden otrzymuje żądanie opakowujące pojedynczy obiekt
i zwraca odpowiedź akceptującą lub odrzucającą. Na etapie renderowania wyjście kompilacji
jest już zbiorem zasobów Kubernetes, co czyni ten etap naturalnym
miejscem do uruchomienia polityki w kształcie dopuszczenia. Dla każdego wyrenderowanego obiektu adapter
wyprowadza pola dopuszczenia z samego sparsowanego obiektu, opakowuje obiekt w
żądanie w kształcie admission-review wewnątrz gościa, uruchamia politykę i mapuje
odpowiedź na werdykt: odrzucenie staje się jednym werdyktem; akceptacja nie emituje
niczego. Dołączona polityka referencyjna to reguła wymagająca etykiety — każdy obiekt musi
mieć klucz etykiety wskazany przez settings — typowy wzorzec Kubewarden.
Zakres wspólny dla adapterów etapu renderowania
- Etap renderowania, jeden kształt wyjścia na adapter. Adapter etapu renderowania analizuje wyrenderowane artefakty, a nie graf IR, i jest ukierunkowany na kształt wyjścia, który parsuje — YAML/JSON i natywny HCL Terraform w przypadku referencyjnego adaptera renderowania Rego, obiekty Kubernetes w przypadku adaptera Kubewarden. Polityka etapu grafu lub polityka dla kształtu wyjścia, którego nie parsuje żaden dostarczany adapter, to inny gość.
- Tylko walidacja. Adapter etapu renderowania akceptuje lub odrzuca; nigdy nie zwraca zmodyfikowanego obiektu. Zmodyfikowany obiekt polityki mutującej jest ignorowany — kompilator nigdy nie przepisuje wyrenderowanego wyjścia na podstawie werdyktu polityki. Polityka decyduje; nie edytuje.
Dołączanie polityki
Operator dołącza plugin nadzoru za pomocą listy plugins.governance w
konfiguracji obszaru roboczego (.aggrega-config.yaml). Każdy wpis wskazuje plugin,
rolę (role), w której jest dołączony, oraz opcjonalnie kanał with, który dostarcza jego
reguły i parametry dostrajające:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3Wartość uri wskazuje plugin. Host odczytuje każdy plik z sources w czasie budowania
i przekazuje jego bajty do gościa, a settings przekazuje bez zmian. Budowanie
bez dołączonego pluginu nadzoru uruchamia gniazdo jako operację pustą, więc dołączanie
jest dla obszaru roboczego wyłącznie addytywne.
Plugin obsługujący kilka ról dołącza się raz dla każdej roli, a każde dołączenie ma własne reguły i własne ustawienia:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltKtórą wersję wskazuje dołączenie. uri wskazuje encję Plugin — współrzędną <pluginType>/<name> i, po dwukropku, wersję — a wersja bierze udział w rozwiązywaniu. W przypadku dwóch silników wkompilowanych w CLI encja pochodzi z jednego z dwóch miejsc. Każde wydanie kompilatora publikuje encje Plugin dla governance/rego i governance/cel we własnej wersji, a katalog biblioteki standardowej je zawiera, każdą w wersji wydania, które ją opublikowało; obszar roboczy odczytuje je z wymienianych przez siebie katalogów. Plik binarny aggrega zawiera po jednej encji każdego silnika, w wersji własnego wydania i żadnej innej. Dołączenie wskazujące wersję, której nie zawiera żadne z nich i której żaden pull nie pobrał do pamięci podręcznej treści, zatrzymuje kompilację z E0137, wskazując odwołanie.
Dołączenie wskazuje więc wersję, którą zawiera katalog odczytywany przez obszar roboczy. Taka wersja rozwiązuje się z katalogu również w wydaniu aggrega innym niż jej własne, natomiast wersja, którą zawiera wyłącznie plik binarny — wersja jego własnego wydania — rozwiązuje się tylko z tym wydaniem, zarówno w roli werdyktu, jak i w roli transformacji. W roli transformacji pull przypina rozwiązaną wersję w pliku blokady i odrzuca z E0103 wersję, której nie zawiera ani katalog odczytywany przez obszar roboczy, ani plik binarny. Wersja wybiera encję Plugin, która zapisuje eksporty pluginu i limity czasu wykonania, a nie silnik: gdy odwołanie zostanie rozwiązane, uruchamiany jest silnik wkompilowany w plik binarny wykonujący kompilację, ponieważ pluginy wbudowane w plik binarny są pierwszym miejscem, z którego odczytywany jest moduł pluginu. Plugin zarządzania, który obszar roboczy deklaruje sam — encja Plugin we własnym katalogu, z jej .wasm obok — jest wskazywany w wersji, którą zapisuje ta encja.
Każda rola wybiera domyślną funkcję wejściową — verdict_ir dla roli oceniającej
graf, verdict_render dla roli oceniającej wyrenderowane artefakty,
mutate dla roli kształtującej etykiety, transform_annotations dla
roli wstrzykującej adnotacje — a dołączenie może skierować rolę na inny eksport
za pomocą function:. Host odmawia wywołania eksportu, którego gość nie zadeklarował
w swoim samoopisie describe(), więc dołączenie wskazujące rolę, której gość nie
obsługuje, jest zgłaszane z nazwy, zanim gość zostanie uruchomiony, zamiast po cichu nic nie robić.
function: wskazuje eksport wtyczki wskazanej przez uri. Dołączenie w roli werdyktu — ir-verdict lub render-verdict — które podaje function:, a nie podaje uri:, wskazuje funkcję, która nie należy do żadnej wtyczki, więc konfiguracja jest odrzucana już przy odczycie, z kodem E0224, ze wskazaniem pliku i miejsca wpisu na liście: należy dodać uri wtyczki, która eksportuje tę funkcję.
Lista plugins.governance ma addytywny odpowiednik, plugins.governance_append:
wpisy odpowiednika są dołączane na koniec rozstrzygniętej listy governance na każdej
warstwie konfiguracji, więc obszar roboczy lub konfiguracja globalna składa dołączenia
polityk, zamiast przesłaniać listę bazową.
Nakładka należąca do CI
Obok pisanego ręcznie pliku .aggrega-config.yaml zautomatyzowany potok może posiadać
osobny plik nakładki, .aggrega-config-append-ci.yaml. Istnieje on po to, aby potok
mógł dołączać kontrolowane przez siebie polityki (lub inną konfigurację o wartościach listowych)
bez edytowania pisanej ręcznie konfiguracji bazowej programisty — potok może w całości
nadpisywać własny plik nakładki.
Nakładka jest ściśle addytywna. Jest walidowana względem tego samego schematu
konfiguracji co plik bazowy, a w każdym polu o wartości listowej jej wpisy są
dołączane na koniec rozstrzygniętej listy. Może jedynie dodawać: nie może usunąć wpisu
bazowego ani nadpisać wartości skalarnej z bazy — zawarty w niej klucz skalarny lub mapy
nie ma znaczenia addytywnego i jest ignorowany (oraz wymieniany w ostrzeżeniu z rozstrzygania),
zamiast zostać zastosowany. Nigdy też nie wyznacza korzenia obszaru roboczego: robi to tylko
plik .aggrega-config.yaml zawierający blok workspace:, więc umieszczenie
nakładki w katalogu dodaje dołączenia bez zmiany miejsca, w którym zaczyna się obszar
roboczy.
Daje to potokowi czysty punkt styku do egzekwowania polityki obowiązującej w całej organizacji:
potok umieszcza plik .aggrega-config-append-ci.yaml wskazujący obowiązkowe pluginy
polityk, a te dołączenia są scalane ponad tym, co napisał programista,
nigdy zamiast tego.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ buduje jeden obszar roboczy z dołączeniem zespołu, dołączeniem organizacji dodanym przez governance_append globalnego pliku konfiguracji oraz dołączeniem potoku dodanym przez tę nakładkę, i sprawdza, co wypisuje każda kombinacja i czy się kończy.
Testowanie polityki, zanim zacznie blokować kompilację
Reguła Rego wskazująca ścieżkę, której ładunek jej roli nie zawiera, nie jest błędem: ścieżka jest niezdefiniowana, reguła nigdy nie jest spełniona, a kompilacja kończy się tak, jakby polityka na nią zezwoliła. Dlatego nowa polityka zasługuje na halt w trzech krokach: należy dołączyć ją z poziomem ważności, który raportuje bez zatrzymywania, sprawdzić każdą wskazaną przez nią ścieżkę względem ładunku otrzymywanego przez jej rolę i przeczytać, co raportuje na kompilacjach, które będzie oceniać.
Poniższe polecenia działają w kopii examples/policy-org-overlay/, której .aggrega-config.yaml dołącza jedną nową politykę w miejsce polityki zespołu. Ma ona odrzucać magazyn danych działający z wyłączoną wysoką dostępnością, a jej reguła została skopiowana z polityki kształtującej etykiety:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Należy ją dołączyć tak, aby raportowała. Polityka zbiera decyzje pod deny, co domyślnie zatrzymuje kompilację. translation wskazujący tylko deny, na poziomie warn, raportuje każdą jej decyzję jako ostrzeżenie i pozwala kompilacji się zakończyć; info zamiast tego je rejestruje. Sama polityka pozostaje taka, jaka będzie egzekwowana:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnNależy zapisać ładunek i odszukać w nim ścieżki. Gdy kompilacja wypełni plik blokady encji Release,
aggrega build --release release.yaml --dry-run --policy-input payloadszapisuje ładunek, który każda rola przekazuje swoim dołączeniom, do payloads/ i nic poza tym, raportując (gdzie <workspace> oznacza katalog, w którym uruchomiono kompilację):
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]Te cztery pliki to annotation-transform.json, ir-verdict.json, label-transform.json i render-verdict.json; plik roli bez żadnego dołączenia również jest zapisywany, więc politykę można sprawdzić względem jej roli, zanim zostanie gdziekolwiek dołączona. W ir-verdict, label-transform i annotation-transform plik jest dokumentem input, który odczytuje polityka, więc każdą ścieżkę wskazaną przez regułę można z niego odczytać dowolnym narzędziem JSON, zanim zaufa się regule:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}Węzłów reguły tam nie ma: input.graph.nodes to miejsce, w którym przenosi je rola kształtująca etykiety, a w ir-verdict znajdują się one pod input.graph.spec.nodes (zob. Co udostępnia ładunek każdej roli). Plik mówi też, o czym musi zdecydować poprawiona reguła: db jest magazynem danych, jego wysoka dostępność jest wyłączona i należy go zgłosić.
Tam, gdzie zainstalowano OPA, politykę Rego można ewaluować bezpośrednio względem tego samego pliku: opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Silnik Rego w kompilatorze jest niezależną implementacją, więc rozstrzygająca pozostaje ewaluacja w kompilacji: funkcja wbudowana, której nie implementuje, zatrzymuje kompilację, zamiast zostać ewaluowana.
W render-verdict plik nie jest dokumentem input polityki. Każdy artefakt w nim niesie swoje path, content i format; documents, które odczytuje reguła, są parsowane z treści przez silnik polityk po otrzymaniu ładunku, więc reguła nad documents niczego w pliku nie znajduje. Politykę w tej roli testuje się tam, gdzie silnik je parsuje: w kompilacji, jak pokazuje następny krok.
Należy uruchomić kompilację i porównać to, co raportuje, z tym, co mówi ładunek. Ze skopiowaną ścieżką
aggrega build --release release.yaml --auto-pullkończy się i niczego nie raportuje:
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]Ładunek zawiera magazyn danych z wyłączoną wysoką dostępnością, a polityka nic o nim nie powiedziała: to milczenie jest błędem i nic innego w kompilacji na niego nie wskazuje. Gdy reguła odczytuje input.graph.spec.nodes, to samo polecenie raportuje db i się kończy:
policy plugin "rego" warning: db is a datastore running with high availability offPull 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]Dodanie --dry-run raportuje te same werdykty i nie zapisuje dist/, więc pętla działa na obszarze roboczym bez naruszania jego wyjścia.
Ta sama reguła napisana dla silnika CEL nie zawodzi po cichu. Odczyt klucza, którego ładunek nie zawiera, jest tam błędem ewaluacji, więc ze skopiowaną ścieżką w policies/datastore-ha.cel, dołączonym z tym samym translation,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}zatrzymuje kompilację nawet na poziomie warn. Kończy się kodem 1, a jego ostatni wiersz wskazuje plik polityki i klucz:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesPolitykę render-verdict testuje się w ten sam sposób. Dołączona w render-verdict w tym samym obszarze roboczym, z tym samym translation, reguła odrzucająca usługę Compose publikującą port na hoście
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}raportuje jedyną usługę, która to robi:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Następnie należy ją egzekwować. Usunięcie translation przywraca deny do halt, a kompilacja, która zgłosiła db, teraz się na nim zatrzymuje, kończy się kodem 1 i nie zapisuje dist/:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationDołączenia raportującego nie trzeba usuwać wszędzie naraz. Jeden plik konfiguracji może zachować translation swojego dołączenia na warn, podczas gdy nakładka potoku dołącza tę samą politykę z deny na halt — w ten sposób examples/policy-org-overlay/ wdraża regułę organizacji: ostrzeżenie w kompilacji dewelopera i powód, dla którego zatrzymuje się kompilacja potoku.
Uruchamianie polityk w CI na wynikach budowania
Wszystko, co opisano powyżej, dołącza politykę wewnątrz budowania. Istnieje druga droga, która niczego nie wymaga od gniazda: uruchomienie własnego narzędzia w potoku na plikach zapisanych przez budowanie.
Działa to dzięki temu, co emituje budowanie. Cele Kubernetes i Compose zapisują
YAML; cel Terraform zapisuje natywny HCL lub JSON w postaci .tf.json.
Są to formaty, które narzędzia konfiguracyjne ekosystemu już odczytują — a
aggrega build zapisuje zwykłe pliki do katalogu, bez formatu opakowującego, bez
indeksu i bez niczego do rozpakowania. Narzędzie czytające YAML, JSON lub HCL działa więc na
wynikach budowania tak samo jak na konfiguracji napisanej ręcznie przez człowieka,
a Aggrega nie potrzebuje do tego żadnego gniazda, rodzaju wtyczki ani klucza konfiguracji.
Istniejący zbiór reguł nie wymaga więc przenoszenia. Jeśli reguły są już utrzymywane w Conftest, Kyverno CLI, kubeconform, Checkov lub OPA, działają one na wynikach budowania Aggrega w obecnej postaci, a narzędzie, które je ewaluuje, jest tym, które potok już instaluje.
Dwa gotowe do użycia skrypty reguł, każdy z wywołującym go krokiem potoku i obiema odmowami, które zwróciły na rzeczywistych budowaniach, znajdują się w examples/policy-in-ci/. Używają one yq i niczego więcej, więc działają bez zainstalowanego zestawu narzędzi do polityk; pokazany przez nie schemat — odczytaj katalog wyjściowy, podejmij decyzję, zakończ z niezerowym kodem, wskazując problematyczne artefakty — to schemat, który przyjmuje każde narzędzie na tej pozycji.
Do której drogi należy reguła
Obie drogi są pełnoprawne, a przestrzeń robocza często używa obu. O wyborze decyduje to, co reguła musi widzieć i kiedy musi zadziałać.
Należy dołączyć ją do gniazda, gdy:
- budowanie w ogóle nie może wytworzyć artefaktu. Polityka
ir-verdictdziała na bramce analizy statycznej, zanim cokolwiek zostanie wyrenderowane, więc zatrzymanie w tym miejscu nie pozostawia niczego zapisanego — żadnego pliku wyjściowego do przeglądu, kwarantanny czy przypadkowego zastosowania. Kontrola w potoku z konieczności działa dopiero wtedy, gdy pliki już istnieją. - reguła potrzebuje faktów, które ma tylko budowanie. Rola
ir-verdictodczytuje złożony graf: węzły, krawędzie i ich gniazda, każde dołączenie wraz ze slotem, który wypełniło, wartości zadeklarowane przez autora jako wrażliwe, ścieżki routingu. Nic z tego nie przetrwa w wyrenderowanym wyniku — manifest Kubernetes nie zapisuje, które gniazdo dostarczyło wartość ani która encja Feature dodała zasób — więc reguła dotycząca topologii lub pochodzenia ma jedno miejsce i jest nim gniazdo. - reguła musi obowiązywać wszędzie, gdzie działa budowanie. Dołączenie zarządzania znajduje się w konfiguracji przestrzeni roboczej, więc dotyczy lokalnego budowania programisty w takim samym stopniu jak budowania w potoku. Kontrola w potoku działa tam, gdzie działa potok.
- reguła ma kształtować budowanie, a nie je oceniać. Robi to tylko rola transformacji i tylko dlatego, że operator ją dołączył.
Należy uruchomić ją w CI, gdy:
- reguła już istnieje w narzędziu, które zespół uruchamia i przegląda, dla formatu, który to narzędzie już parsuje. Ponowne wyrażenie jej jako treści polityki gniazda to praca, która na końcu nie daje nowego pokrycia.
- reguła dotyczy artefaktów w postaci, w jakiej otrzyma je cel — ostatecznego
zestawu plików, po każdej transformacji, w formie, która zostaje zastosowana. To jest
także przedmiot roli
render-verdict, więc w tym jednym punkcie obie drogi widzą to samo, a wybór zależy od pozostałych. - ustalenie jest przeznaczone dla recenzenta, a nie dla budowania. Potok, który publikuje artefakty i ustalenia obok siebie, daje recenzentowi jedno i drugie; zatrzymane budowanie daje mu komunikat.
- kontrola wykracza poza jedno budowanie — porównuje wynik tego budowania z poprzednim, z bieżącym stanem klastra lub z inwentarzem, którego nie zawiera żaden ładunek budowania. Polityka w dowolnej z ról werdyktu widzi budowanie, do którego jest dołączona, i tylko to widzi.
Drogi się uzupełniają, a nie konkurują: niezmiennik topologii zatrzymuje budowanie z
ir-verdict, a ten sam potok uruchamia następnie istniejące reguły artefaktów
środowiska na tym, co to budowanie zapisało.
Odsyłacze
plugin-contract.md— miejsce gniazda w potoku, typowane kształty danych, które przenosi, oraz piaskownica, w której działa każda wtyczka.plugin-developer-guide.md— tworzenie wtyczki, samoopisdescribe()oraz cykl życia publish → pull → build.../entities/plugin.md— encjaPlugin, która wprowadza wtyczkę do katalogu.../cli/aggrega-build.md— polecenie budowania, które wywołuje gniazdo.../schema/other/aggrega-config.md— schemat konfiguracji obszaru roboczego, w tym powierzchnia dołączaniaplugins.governance.../examples/policy-in-ci/— dwa gotowe do uruchomienia skrypty reguł działające na wyniku budowania, każdy z odpowiadającym mu krokiem potoku.../examples/policy-data-class-route/— jedna regułair-verdictdotycząca tras, napisana dla silnika Rego, silnika CEL i OPA za referencyjnym gościem adaptera, dołączana do każdego budowania przez jeden plik--configna silnik, wraz ze skryptem sprawdzającym, że wszystkie trzy dają ten sam wynik dla każdej encji Release.