Polityka dla wyrenderowanego wyniku: jedna reguła wewnętrzna, cztery cele, dwa silniki
Jedna reguła wewnętrzna, dołączona w roli render-verdict, ocenia pliki, które kompilacja zapisuje dla czterech celów, i odrzuca naruszenie podłożone w każdym z nich. Reguła ma dwie klauzule:
Każdy obraz kontenera wskazuje stałą wersję — tag inny niż
latestalbo skrót. Każda instancja bazy danych przechowuje dane w postaci zaszyfrowanej.
Ten obszar roboczy kompiluje jeden Aggregate dla czterech celów — Kubernetes przez Helm, Docker Compose, Terraform i CloudFormation. Rola render-verdict ocenia pliki zapisywane przez kompilację, po tym jak wszystkie cele je wyrenderowały, a reguła odczytuje własny kształt wyniku każdego celu: obrazy w obiektach Kubernetes i w pliku Compose, instancję RDS w pliku Terraform i w szablonie CloudFormation. Każdy cel ma encję Release, która przechodzi, oraz encję Release z podłożonym naruszeniem, którą reguła odrzuca.
Reguła jest napisana dwa razy, raz dla każdego silnika polityk wkompilowanego w CLI — Rego i CEL — a obie kopie zgadzają się w każdej kompilacji tutaj. Skrypt obok encji Releases kompiluje wszystkie szesnaście kombinacji i sprawdza każdy wynik.
aggrega buildwłasna polityka
podłączona do kompilatora
wynik pozytywny
pliki zapisane
gotowe do przeglądu i wdrożenia
wynik negatywny
kompilacja zatrzymana
Polityka może zatrzymać kompilację i wskazać, co poprawić. Nigdy nie zmienia plików, aby przeszły.
Co powstaje
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
db | core/datastore/postgres | baza danych zamówień |
report | core/compute/task | zadanie raportowe odczytujące db, uruchamiane ręcznie: zawiera core/manual-trigger, więc żadne uruchomienie nie startuje przy wdrażaniu encji Release |
report odczytuje adres, port i nazwę bazy danych przez swoje połączenie database, jako DB_HOST, DB_PORT i DB_NAME. Aggregate to ten sam plik dla każdej kompilacji; każda encja Release wskazuje Manifest, który wybiera cel:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, StatefulSet | helm/task, CronJob utrzymywany w stanie wstrzymanym |
manifest-compose.yaml | compose/postgres, usługa | compose/task, usługa za profilem |
manifest-terraform.yaml | terraform/postgres-rds, instancja RDS | terraform/task-ecs, definicja zadania Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, instancja RDS | cloudformation/task-ecs, definicja zadania Amazon ECS |
Każdy Recipe tutaj renderuje wyłącznie z katalogu: baza danych Kubernetes jest syntetyzowana, a nie pobierana jako chart, treść bazy danych Terraform zapisuje jej Recipe, a moduł zadania Terraform jest przechowywany obok jego Recipe. Dlatego każda kompilacja działa offline.
Osiem encji Releases
| Release | cel | co znajduje reguła | budowanie |
|---|---|---|---|
release-helm.yaml | Kubernetes | report uruchamia registry.example.com/orders-report:1.4.2 | kończy się powodzeniem |
release-helm-unpinned.yaml | Kubernetes | report uruchamia ten sam obraz z tagiem latest | zostaje zatrzymane |
release-compose.yaml | Docker Compose | report uruchamia registry.example.com/orders-report:1.4.2 | kończy się powodzeniem |
release-compose-unpinned.yaml | Docker Compose | report uruchamia obraz bez tagu | zostaje zatrzymane |
release-terraform.yaml | Terraform | instancja jest szyfrowana kluczem wskazanym przez encję Release | kończy się powodzeniem |
release-terraform-unencrypted.yaml | Terraform | encja Release nie wskazuje klucza, więc instancja nie jest szyfrowana | zostaje zatrzymane |
release-cloudformation.yaml | CloudFormation | encja Release włącza StorageEncrypted | kończy się powodzeniem |
release-cloudformation-unencrypted.yaml | CloudFormation | encja Release pozostawia je wyłączone | zostaje zatrzymane |
Obraz należy do encji Release: core/compute/task nie pakuje żadnego oprogramowania, więc Release wskazuje obraz wykonywany przez uruchomienie pod infra.image, łącznie z tagiem. Na dwóch celach AWS szyfrowanie bazy danych również należy do encji Release. Terraform Recipe odczytuje infra.overrides.kms_key_id i, gdy jest ustawione, renderuje storage_encrypted = true obok klucza; CloudFormation Recipe odczytuje infra.overrides.StorageEncrypted i KmsKeyId pod własnymi nazwami właściwości zasobu. Encja Release, która nie ustawia żadnego z nich, renderuje instancję w ogóle bez atrybutu szyfrowania — tak właśnie robią encje Releases z podłożonym naruszeniem.
Bazy danych Kubernetes i Compose uruchamiają obraz postgres:16 ze stałym tagiem, więc reguła ocenia je i przepuszcza w każdej encji Release.
Dołączanie reguły
.aggrega-config.yaml wskazuje hub jako swój rejestr i nie wskazuje żadnego katalogu z encjami ani żadnego dołączenia nadzoru. Regułę dołącza plik, który kompilacja wskazuje przez --config: governance-rego.yaml dla silnika Rego, governance-cel.yaml dla silnika CEL. Plik dla Rego brzmi:
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config wskazuje globalny plik konfiguracyjny dla danego uruchomienia, zamiast tego, który maszyna odczytałaby w innym przypadku, a .aggrega-config.yaml tego obszaru roboczego nadal jest nakładany na jego wierzch. Lista plugins.governance w pliku obszaru roboczego zastąpiłaby listę z wskazanego pliku, dlatego plik obszaru roboczego jej nie deklaruje. 0.9.0 to wersja encji Plugin każdego silnika w katalogu biblioteki standardowej. Oba silniki są wkompilowane w CLI — aggrega plugin list wymienia governance/rego i governance/cel wśród osadzonych wbudowanych pluginów — więc żadna kompilacja tutaj nie pobiera pluginu.
Co odczytuje polityka render-verdict
Polityka w roli render-verdict odczytuje pliki zapisywane przez kompilację w input.artifacts, po jednym wpisie na plik, posortowane według ścieżki. Każdy wpis zawiera:
path— ścieżkę pliku wdist/, na przykładterraform/modules/db/main.tf;content— tekst pliku, w postaci zapisanej;format— format, który dostawca celu zadeklarował dla pliku:yamldla pliku Compose,jsondla szablonu CloudFormation,hcldla każdego pliku Terraform, łącznie z treścią bazy danych zapisywaną przez jej Recipe. Tam, gdzie nic go nie zadeklarowało, jest to pusty ciąg, tak jak w przypadku plików Kubernetes tutaj;documents— treść pliku przetworzona do struktury, jako lista dokumentów: tutaj po jednym na plik;parse_error— obecne tylko w pliku, którego nie udało się przetworzyć, zamiastdocuments.
Oprócz plików input.sources przechowuje własny plik polityki dołączenia, a input.settings jego ustawienia — tutaj pusty obiekt, ponieważ to dołączenie żadnych nie deklaruje.
aggrega build --release <release> --dry-run --policy-input <dir> zapisuje ładunek, który otrzymuje każda rola, do <dir> i nie zapisuje niczego innego. W roli render-verdict ten plik jest tym, co otrzymuje silnik, a nie tym, co odczytuje polityka: każdy plik w nim zawiera swoje path i content oraz format zadeklarowany przez jego dostawcę, a silnik przetwarza documents z treści po otrzymaniu ładunku. Plik wymienia więc pliki, które zostaną pokazane regule, ale nie ich dokumenty. Po tym, jak kompilacja release-terraform.yaml wypełniła swój plik blokady:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Ścieżka, którą reguła odczytuje wewnątrz documents, jest sprawdzana w kompilacji, w której silnik je przetworzył. Żaden plik zapisywany przez te encje Recipes nie kończy się błędem przetwarzania, więc żaden plik tutaj nie zawiera parse_error. Każda klauzula tej reguły odczytuje documents, więc plik, którego nie udało się przetworzyć, przeszedłby ją niesprawdzony; reguła, która nie może na to pozwolić, dodaje klauzulę odrzucającą plik zawierający parse_error.
Jak każda klauzula odczytuje kształt swojego celu
Każda klauzula wskazuje kształt, który odczytuje, a plik o innym kształcie nie zawiera tego, co klauzula wskazuje: w Rego ścieżka jest niezdefiniowana i klauzula nie jest spełniona. Dlatego jedna reguła działa na wyniku każdego celu, a każda klauzula znajduje tylko swój.
Compose zapisuje jeden plik, którego dokument kluczuje każdą usługę według nazwy pod services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Obiekty Kubernetes przechowują swoje kontenery w szablonie poda, który CronJob trzyma o jeden poziom głębiej niż inne obciążenia, pod spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform w natywnym HCL zagnieżdża blok pod jego typem, a następnie pod każdą z jego etykiet, a ostatnia etykieta przechowuje listę bloków, ponieważ bloki o wspólnym typie i etykietach są zbierane w jedną listę. Dlatego atrybuty instancji znajdują się jeden indeks poniżej jej nazwy, a klauzula przechodzi przez tę listę:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}Lista ma tu większe znaczenie niż w przypadku reguły szukającej wartości, ponieważ ta klauzula odrzuca z powodu braku. Gdyby napisać ją dla pojedynczego bloku — some name, block in doc.resource.aws_db_instance — block byłby listą, block.storage_encrypted byłby na niej niezdefiniowany, a not jest spełnione dla wszystkiego, co niezdefiniowane: klauzula odrzuciłaby również release-terraform.yaml, którego instancja jest zaszyfrowana, z tym samym komunikatem co encja Release z podłożonym naruszeniem.
Plik .tf.json jest odczytywany tak, jak zapisał go jego Recipe, z nazwą przechowującą sam blok, więc reguła napisana dla jednej formy nie odczytuje drugiej. Dlatego klauzula najpierw odczytuje format: native_hcl przyjmuje plik o formacie hcl albo o pustym formacie i nazwie kończącej się na .tf — plik, dla którego żaden dostawca nie zadeklarował formatu, jest przetwarzany według nazwy, więc reguła również rozpoznaje go po nazwie, zamiast go pomijać. Każdy plik Terraform kompilowany tutaj jest zadeklarowany jako hcl, więc żaden plik tutaj nie jest rozpoznawany po nazwie. Te encje Recipes nie zapisują pliku .tf.json, więc reguła nie odczytuje innej formy. Co udostępnia ładunek każdej roli opisuje obie formy.
CloudFormation zapisuje jeden szablon, którego zasoby są kluczowane według logicznego ID pod Resources, każdy ze swoimi Type i Properties:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Instancja bez właściwości StorageEncrypted lub z tą właściwością ustawioną na cokolwiek innego niż true jest odrzucana: not … == true jest spełnione w obu przypadkach.
Dlaczego reguła CEL jest napisana inaczej
policies/house-rule.cel wyraża te same dwie klauzule i dochodzi do tego samego werdyktu w każdej kompilacji tutaj. Jest napisana inaczej w trzech miejscach, z których każde wynika z właściwości silnika.
Sprawdza każdy klucz przed jego odczytaniem. Odczytanie klucza, którego wartość nie zawiera, jest w CEL błędem ewaluacji, a nie niezdefiniowaną ścieżką, a błąd zatrzymuje kompilację. Plikom każdego celu brakuje kluczy, które mają pliki innego — obiekt Kubernetes nie ma services, plik Compose nie ma kind — więc każda klauzula najpierw sprawdza odczytywane klucze za pomocą has():
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Bez sprawdzenia has(d.services) polecenie aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull zatrzymuje się, niezależnie od tego, jakie obrazy uruchamiają obiekty Kubernetes, kończy z kodem 1 i nie zapisuje dist/, a wiersz zgłaszający błąd wskazuje plik polityki i klucz:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesZgłasza jednego naruszającego na plik. Klucz decyzji zbiera komunikaty, a wyrażenie CEL nie ma sposobu na połączenie list budowanych dla każdego pliku w jedną listę. Dlatego każda klauzula CEL zgłasza jednego naruszającego w każdym pliku: pierwszy kontener szablonu poda albo, spośród usług, instancji i zasobów kluczowanych przez plik według nazwy, ten, którego nazwa jest pierwsza w kolejności sortowania. Wyrażenie składane przechodzi przez mapę w nieustalonej kolejności, więc to wybór według nazwy sprawia, że komunikat jest taki sam w kolejnych kompilacjach. Reguła Rego zgłasza każdego naruszającego. Przy dwóch nieprzypiętych usługach w jednym pliku Compose silnik Rego zatrzymuje się z dwoma komunikatami, a silnik CEL z jednym, dla usługi, której nazwa jest pierwsza w kolejności sortowania; przy jednej, jak w każdej encji Release tutaj, oba zatrzymują się z tym samym komunikatem.
Powtarza się. CEL nie umożliwia nazwania podwyrażenia, więc test użyty dwukrotnie jest zapisany dwukrotnie, a test obrazu jest rozpisany w każdej klauzuli, zamiast być wywoływany, jak unpinned w Rego.
Te dwa pliki są celowym niemal duplikatem, każdy napisany samodzielnie na podstawie powyższej reguły, a nie wygenerowany jeden z drugiego, tak aby kompilacja, w której silniki się nie zgadzają, ujawniła tę niezgodność.
Werdykt nigdy nie zmienia wyniku
Polityka w roli render-verdict akceptuje kompilację albo ją odrzuca. Otrzymuje pliki zapisane przez kompilację i zwraca werdykty; nic, co zwraca, nie jest do nich stosowane. Dlatego kompilacja kontrolna tworzy te same pliki, bajt w bajt, z dołączoną regułą i bez niej, a check.sh porównuje oba drzewa przy każdym uruchomieniu. Odrzucona kompilacja w ogóle nie zapisuje dist/. Aby usunąć odrzucenie, zmienia się encja Release — przypięty tag, klucz szyfrowania — a następna kompilacja jest oceniana ponownie.
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:
aggrega scaffold --example policy-render-verdictNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd policy-render-verdictKompilacja
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Należy zamienić governance-rego.yaml na governance-cel.yaml, aby uruchomić tę samą regułę w silniku CEL, oraz terraform w nazwie pliku encji Release na helm, compose lub cloudformation, z ich encjami Releases z podłożonym naruszeniem release-helm-unpinned.yaml, release-compose-unpinned.yaml i release-cloudformation-unencrypted.yaml.
Katalog biblioteki standardowej dostarcza każdą encję Component, Recipe, Feature i FeatureRecipe tutaj i zawiera encje Plugin obu silników. 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 wyrenderowany wynik są generowane, a nie dostarczane.
Kompilacja kontrolna Terraform kończy się. Encja Release z podłożonym naruszeniem zatrzymuje się:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationKażdy komunikat wskazuje plik oceniany przez regułę, jako jego ścieżkę w dist/, oraz naruszającego w nim. Pozostałe encje Releases z podłożonym naruszeniem zatrzymują się w ten sam sposób:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedKażdy wiersz to wiersz następujący po [POLICY_ERROR E0005] w wyjściu jego kompilacji, pokazany od lewego marginesu. Pierwszy pochodzi z silnika Rego, a pozostałe dwa z silnika CEL, każdy wskazuje silnik, który go zgłosił; drugi silnik wypisuje ten sam komunikat pod własną nazwą.
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-render-verdict`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `policy-render-verdict` i bez `dir`: zapisuje ono przykład w nowym folderze `policy-render-verdict`. Następnie wywołaj narzędzie `cli-build`, które uruchamia `aggrega build` i przyjmuje jego flagę `--config`, raz dla każdej encji Release, w tej kolejności — `release-terraform.yaml` i `release-terraform-unencrypted.yaml` — za każdym razem z `workspace_root` ustawionym na `policy-render-verdict`, `release` ustawionym na ten plik, `auto_pull` ustawionym na true i `config` ustawionym na `governance-rego.yaml`. Druga kompilacja ma zostać odrzucona, więc odczytaj mi odmowę. Powiedz mi, jakie pliki zapisała pierwsza kompilacja; znajdują się w `policy-render-verdict/dist/`.Sprawdzanie każdej kompilacji
Ten autotest działa w kopii roboczej repozytorium dokumentacji, która zawiera używany przez niego wspólny skrypt pomocniczy budowania; kopia zapisana przez aggrega scaffold --example tego skryptu nie zawiera.
./check.shcheck.sh za pomocą skryptu pomocniczego build-release najpierw kompiluje każdą kompilację kontrolną raz bez dołączonej polityki, jako odniesienie, a następnie wszystkie osiem encji Releases w każdym silniku. Kompilacja kontrolna musi się zakończyć i zapisać te same pliki, bajt w bajt, co jej odniesienie; encja Release z podłożonym naruszeniem musi zatrzymać się z E0005 i oczekiwanym dla niej komunikatem, bez żadnego innego odrzucenia obok, i nie zapisać dist/. Od obu silników wymagany jest ten sam komunikat. Wypisuje jeden wiersz na kompilację i kończy z kodem 1, jeśli którykolwiek wynik się różni, wypisując wyjście tej kompilacji:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.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ż przenosi drzewo każdej kompilacji, aby je porównać, i nie pozostawia żadnego po sobie; kompilacje wypełniają pliki blokady tego katalogu, jak każda kompilacja. Jego kod wyjścia stanowi cały werdykt.
Gdzie kompilator nie interpretuje
Kompilator renderuje pliki każdego celu, przekazuje je dołączonemu silnikowi jako tekst wraz z formatem zadeklarowanym przez ich dostawcę i działa zgodnie z poziomem ważności, jaki niesie każdy werdykt. Nie wie, czym jest tag obrazu, że latest się przesuwa ani że instancja RDS powinna być zaszyfrowana: te znaczenia należą do reguły. Role, ładunki i klucze decyzji opisuje gniazdo nadzoru.
Pliki
aggregate.yaml— baza danych i podłączone do niej zadanie raportowe.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— wiążą każdy typ komponentu oraz encję Feature ręcznego wyzwalacza z ich encjami Recipes na jednym celu.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— wariant kontrolny i podłożone naruszenie dla każdego celu..aggrega-config.yaml— domyślny rejestr; bez dołączenia zarządzania.governance-rego.yaml,governance-cel.yaml— reguła dołączona wrender-verdictprzez każdy silnik, każdy plik wskazywany przez--config.policies/house-rule.rego,policies/house-rule.cel— reguła, raz dla każdego silnika.build-release.sh— buduje jedną encję Release, wypisując równoważne polecenieaggrega build.check.sh— wykonuje dwadzieścia kompilacji i sprawdza wynik każdej z nich.