Polityka dołączająca encje Features, których nikt nie napisał: adnotacje wstrzykiwane na etapie `annotation-transform`
Polityka zarządzania zapewnia każdemu komponentowi sklepu monitoring platformy i rolę AWS IAM. Robi to, dodając adnotacje. Encja Manifest wiąże dwa klucze adnotacji z dwiema encjami Features, a adnotacja pod powiązanym kluczem rozwija się w załącznik encji Feature. Adnotacje dodawane przez politykę wnoszą więc do każdego komponentu Prometheus ServiceMonitor i Kubernetes ServiceAccount, a ani encja Aggregate, ani encja Release nie zapisują żadnego z nich.
Polityka jest dołączana w roli annotation-transform, raz dla każdego silnika polityk wkompilowanego w CLI: Rego i CEL. Głównym dowodem jest kontrolna encja Release, która zapisuje te same adnotacje ręcznie. Zbudowana bez polityki renderuje te same pliki, bajt w bajt, co encja Release, którą polityka opatruje adnotacjami.
Co powstaje
| instancja | encja Component z katalogu | co zawiera w release.yaml |
|---|---|---|
api | example/compute/service | nic |
worker | example/compute/service | nic |
gateway | example/compute/service | własna adnotacja monitorowania z interwałem 10 sekund |
Wszystkie trzy są kompilowane do Kubernetes za pomocą Helm, do dist/shop/helm/. example/compute/service to demonstracyjna encja Component w katalogu biblioteki standardowej. Każda jej instancja musi mieć załącznik core/prometheus-exporter — wymóg, który określa encja Component, a sprawdza kompilacja.
Dwa powiązania adnotacji
manifest.yaml nadaje znaczenie dwóm kluczom adnotacji:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnPowiązanie, które kieruje kilka podkluczy, przyjmuje jako wartość obiekt wymieniający każdy z nich, więc feature.aggrega.ai/monitoring przyjmuje {interval: …, port: …, path: …}. Powiązanie, które kieruje jeden podklucz, przyjmuje ciąg znaków, więc aws-role przyjmuje ARN roli. Dołączenie, w które rozwija się adnotacja, otrzymuje nazwę od swojego klucza. core/aws-irsa nadaje swojemu ServiceAccount nazwę dołączenia, dlatego ten klucz nie zawiera kropki ani ukośnika.
Dołączanie polityki
.aggrega-config.yaml wskazuje hub jako swój rejestr, nie wskazuje żadnego katalogu z katalogiem encji i nie zawiera dołączenia zarządzania. Politykę dołącza plik, który kompilacja wskazuje przez --config: governance-rego.yaml dla silnika Rego, governance-cel.yaml dla silnika CEL. Plik dla Rego wygląda tak:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config wskazuje globalny plik konfiguracji dla tego uruchomienia, zamiast tego, który maszyna odczytałaby w innym przypadku, a .aggrega-config.yaml tego obszaru roboczego nadal nakłada się na niego.
0.9.0 to wersja, w której hub publikuje encję Plugin każdego silnika, więc dołączenie rozwiązuje się z rejestru odczytywanego przez obszar roboczy albo z pliku binarnego aggrega tego wydania, który ją zawiera. Działa ten silnik, który jest wkompilowany w plik binarny aggrega wykonujący kompilację, niezależnie od wersji wskazanej przez dołączenie. Obiekt przyjmowany przez adnotację monitorowania wymaga silnika, który wstrzykuje obiekt podkluczy, a silniki z wydań wcześniejszych niż 0.8.7 tego nie robią.
Co odczytuje polityka annotation-transform
Polityka na annotation-transform odczytuje dwie rzeczy:
input.targetswymienia każdy komponent, który może opatrzyć adnotacjami. Każdy cel maboundary_path,component_nameorazannotations, które encja Release zapisuje na tym komponencie, każdą wartość w postaci, w jakiej została zapisana.input.binding_keyswymienia klucze adnotacji, które wiąże encja Manifest.
aggrega build --release <release> --dry-run --policy-input <dir> zapisuje ładunek otrzymywany przez każdą rolę do <dir> i nie zapisuje nic więcej. Po tym, jak kompilacja release.yaml wypełniła swój plik blokady:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}annotations celu zawierają to, co encja Release zapisuje na samym komponencie. aggrega.ai/namespace granicy nie należy do nich.
Polityka
policies/platform-defaults.rego zbiera jedną decyzję na adnotację w annotations. Każda decyzja wskazuje cel za pomocą dwóch pól, pod którymi został odczytany, a następnie klucz i wartość:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Każda reguła uruchamia się tylko dla klucza z input.binding_keys, więc polityka nie dodaje niczego, czemu encja Manifest nie nadała znaczenia. Każda reguła pomija też cel, który już ma dany klucz. Decyzja dotycząca klucza, który komponent już ma, zastępuje wartość zapisaną w encji Release. Bez tego sprawdzenia gateway straciłby swój 10-sekundowy interwał na rzecz 30 sekund z polityki.
policies/platform-defaults.cel wyraża te same dwie decyzje jednym wyrażeniem, łącząc dwie listy za pomocą +. Klucz mapy sprawdza się przez in, a nie object.keys, a ARN roli łączy się przez +, ponieważ język wyrażeń nie ma sprintf. Część wyrażenia dotycząca roli wygląda tak:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),Co renderuje kompilacja
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullzapisuje dwanaście plików w dist/shop/helm/: Deployment i Service dla każdego komponentu, ServiceMonitor, w który rozwija się jego adnotacja monitorowania, oraz ServiceAccount, w który rozwija się jego adnotacja aws-role. spec ServiceMonitor komponentu api, z adnotacji wstrzykniętej przez politykę:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsTen należący do gateway zawiera interval: 10s, wartość zapisaną przez jego wpis w encji Release. ServiceAccount, na którym działa api, z wstrzykniętej aws-role:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Wstrzyknięte czy zapisane ręcznie: te same pliki
release-by-hand.yaml to release.yaml z adnotacjami, które wstrzykuje polityka, zapisanymi ręcznie na każdym komponencie. Skompilowany bez dołączonej polityki,
aggrega build --release release-by-hand.yaml --auto-pullzapisuje te same dwanaście plików, bajt w bajt, co release.yaml z polityką dołączoną na dowolnym z silników. Z tego porównania nic nie jest wyłączone: to, czy adnotacja została wstrzyknięta, nie jest zapisywane w żadnym wyrenderowanym pliku. check.sh porównuje drzewa przy każdym uruchomieniu.
Kompilacja odczytuje wstrzykniętą wartość dokładnie tak samo jak tę samą wartość zapisaną w encji Release, więc wartość rozwija się w to samo dołączenie.
Gdzie zapisywane jest wstrzyknięcie
Zapisuje je graf kompilacji, a --ir-graph wypisuje graf. Każdy komponent, który otrzymał wstrzykniętą adnotację, ma wśród swoich adnotacji Release aggrega.ai/injected-by z nazwą wtyczki. Po aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph komponent api wygląda tak:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},Zapis jest prowadzony per komponent, a nie per klucz: gateway też go ma, ze względu na swoją aws-role. Każde dołączenie, w które rozwinęły się adnotacje, ma w grafie "origin": "annotation", tak jak w przypadku adnotacji zapisanej ręcznie.
Cel Helm nie renderuje adnotacji aggrega.ai/injected-by i informuje o tym. W tej kompilacji każdy komponent, który otrzymał wstrzyknięcie, dodaje do wyjścia trzy ostrzeżenia. Pierwsze z ostrzeżeń dla api:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings wycisza tę klasę ostrzeżeń i nie zmienia niczego, co zapisuje kompilacja.
Rola dodaje adnotacje i nic więcej
Decyzja wskazuje jeden komponent, jeden klucz adnotacji i jego wartość. Nic w decyzji nie dodaje komponentu, nie zmienia etykiety ani nie dołącza bezpośrednio encji Feature. Polityka dociera do encji Feature tylko przez klucz, który wiąże encja Manifest, i to Manifest decyduje, która to Feature.
Decyzja nie może też usunąć adnotacji. Jej wartość to ciąg znaków lub obiekt podkluczy, a null jest odrzucany ze wskazaniem wstrzyknięcia, ponieważ null to sposób, w jaki autor wyłącza komponent z adnotacji, którą w przeciwnym razie by odziedziczył.
Ciąg znaków tam, gdzie powiązanie kieruje trzy podklucze
governance-monitoring-as-string.yaml dołącza policies/monitoring-as-string.rego, która wstrzykuje ciąg "30s" pod kluczem monitorowania. To powiązanie kieruje trzy podklucze, a ciąg znaków nie wskazuje żadnego z nich, więc
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullzatrzymuje się, kończy z kodem 1 i nie zapisuje dist/. Polityka wstrzyknęła ten ciąg do api i do worker i każde z tych wstrzyknięć zostaje odrzucone. Każda odmowa wskazuje wtyczkę, która wstrzyknęła wartość, i rolę, do której jest dołączona, więc wartość daje się prześledzić do polityki, która o niej zdecydowała, a nie do wiersza encji Release, którego nikt nie napisał:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Bez polityki
release.yaml skompilowany bez dołączenia zarządzania
aggrega build --release release.yaml --auto-pullzatrzymuje się. Jego encja Component wymaga dołączenia core/prometheus-exporter, a nic nie zapewnia go ani api, ani worker:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway nie jest wymieniony, ponieważ jego wpis w encji Release zapisuje własne monitorowanie. Z dołączoną polityką ta sama encja Release się kompiluje: dołączenie, w które rozwija się wstrzyknięta adnotacja, spełnia wymaganie tak samo jak zapisane ręcznie.
Co zapisuje plik blokady
Dołączenie annotation-transform zmienia to, co renderuje kompilacja, więc plik blokady je przypina. Po kompilacji z Rego release.lock zawiera dołączenie w mutators:, wraz z jego wtyczką, rolą oraz treścią i skrótem pliku polityki:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoPrzypina też wtyczkę w plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0Dołączenie wskazuje wersję, którą publikuje hub, więc przypięcie rozwiązuje się przez rejestr odczytywany przez obszar roboczy albo z pliku binarnego aggrega tego wydania.
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-annotation-transformNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd policy-annotation-transformKompilacja
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullKatalog biblioteki standardowej dostarcza każdą encję Component, Feature, Recipe i FeatureRecipe użytą tutaj oraz 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 wyrenderowane wyjście są generowane, a nie dostarczane.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `policy-annotation-transform`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `policy-annotation-transform` i bez `dir`: zapisuje ono przykład w nowym folderze `policy-annotation-transform`. Następnie wywołaj narzędzie `cli-build`, które uruchamia `aggrega build` i przyjmuje jego flagę `--config`, z `workspace_root` ustawionym na `policy-annotation-transform`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `config` ustawionym na `governance-rego.yaml`; potem wywołaj je ponownie w ten sam sposób z `config` ustawionym na `governance-cel.yaml`. Na koniec wywołaj narzędzie `build` z `workspace_root` ustawionym na `policy-annotation-transform`, `release` ustawionym na `release-by-hand.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, jakie pliki zapisała każda kompilacja; znajdują się w `policy-annotation-transform/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 wykonuje pięć kompilacji za pomocą pomocnika build-release i porównuje każdy wynik z tym, który opisuje ta strona:
release-by-hand.yamlbez polityki jest wzorcem. Musi wyrenderować sześć plików, w które rozwijają się adnotacje.release.yamlbez polityki musi zatrzymać się zE0162dlaapiiworkeri dla żadnego innego komponentu.release.yamlz polityką jest kompilowany raz na każdym silniku. Każda kompilacja musi zapisać pliki wzorca bajt w bajt, przypiąć wtyczkę w swoim pliku blokady i zapisać wszystkie trzy komponenty jako wstrzyknięte przez tę wtyczkę.release.yamlz podłożonym ciągiem znaków musi zatrzymać się z odmową podaną powyżej.
Wypisuje jeden wiersz na kompilację, następnie pliki wyrenderowane przez oba powiązania, i kończy z kodem 1, jeśli którykolwiek wynik się różni, wypisując wyjście tej kompilacji:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Każda kompilacja działa we własnej kopii tego obszaru roboczego, utworzonej w katalogu tymczasowym, ze ścieżką katalogu encji w jej .aggrega-config.yaml zamienioną na bezwzględną, aby nadal rozwiązywała się stamtąd. W tym katalogu nic nie jest zapisywane. Używa pliku binarnego, który wskazuje pomocnik build-release, więc wybiera go AGGREGA_BIN, a argumenty po -- trafiają do każdej kompilacji. Jego kod wyjścia stanowi cały werdykt.
Gdzie kompilator nie interpretuje
Kompilator przekazuje polityce komponenty i powiązane klucze. Dodaje adnotacje, o których decyduje polityka, i rozwija je przez powiązania encji Manifest, tak jak rozwija każdą adnotację. Nie wie, że usługa powinna być monitorowana, czym jest interwał zbierania metryk ani w jakiej roli IAM komponent powinien działać: te znaczenia należą do polityki i encji Manifest. Role, ładunki i klucze decyzji opisuje gniazdo zarządzania. Rozwijanie adnotacji bez polityki opisuje annotation-driven-monitoring.
Pliki
aggregate.yaml— trzy usługi, bez adnotacji.manifest.yaml— wiąże typ komponentu i dwie encje Features z ich Helm Recipes, a dwa klucze adnotacji z dwiema Features.release.yaml— encja Release, którą polityka opatruje adnotacjami; tylkogatewayzapisuje adnotację.release-by-hand.yaml— próba kontrolna: każda adnotacja zapisana ręcznie..aggrega-config.yaml— domyślny rejestr; bez dołączenia zarządzania.governance-rego.yaml,governance-cel.yaml— polityka dołączona naannotation-transformprzez każdy z silników, każdy plik wskazywany przez--config.governance-monitoring-as-string.yaml— podłożony błąd, wskazywany przez--config.policies/platform-defaults.rego,policies/platform-defaults.cel— polityka, po jednej na silnik.policies/monitoring-as-string.rego— podłożony błąd.build-release.sh— buduje jedną encję Release, wypisując równoważne polecenieaggrega build.check.sh— wykonuje pięć kompilacji i sprawdza każdy wynik.