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

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

instancjaencja Component z kataloguco zawiera w release.yaml
apiexample/compute/servicenic
workerexample/compute/servicenic
gatewayexample/compute/servicewł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_arn

Powią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.targets wymienia każdy komponent, który może opatrzyć adnotacjami. Każdy cel ma boundary_path, component_name oraz annotations, które encja Release zapisuje na tym komponencie, każdą wartość w postaci, w jakiej została zapisana.
  • input.binding_keys wymienia 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:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

zapisuje 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: /metrics

Ten 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: v1
kind: ServiceAccount
metadata:
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,

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

zapisuje 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

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

zatrzymuje 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

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

zatrzymuje 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.rego

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

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

Terminal window
aggrega scaffold --example policy-annotation-transform

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

Terminal window
cd policy-annotation-transform

Kompilacja

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

Katalog 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.

Terminal window
./check.sh

check.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.yaml bez polityki jest wzorcem. Musi wyrenderować sześć plików, w które rozwijają się adnotacje.
  • release.yaml bez polityki musi zatrzymać się z E0162 dla api i worker i dla żadnego innego komponentu.
  • release.yaml z 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.yaml z 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' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string 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; tylko gateway zapisuje 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 na annotation-transform przez 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 polecenie aggrega build.
  • check.sh — wykonuje pięć kompilacji i sprawdza każdy wynik.