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

aggrega inspect

aggrega inspect wyświetla czytelny dla człowieka widok dowolnej encji Aggrega — encji Component z katalogu, pliku encji napisanego przez autora, encji opublikowanej w rejestrze lub w pełni rozwiązanej encji Release. Jest to kanoniczne narzędzie diagnostyczne do zrozumienia, co wygeneruje kompilator: które encje Components rozszerzają które bazy, który Recipe jest mapowany na każdy typ, które Features są dołączane do każdego węzła i skąd dokładnie pochodzą wkłady każdej encji Feature.

Każdy rodzaj encji ma naturalny widok „kontraktu”. inspect pokazuje ten kontrakt — schemat publikowany przez encję Component, mapowania deklarowane przez encję Manifest, topologię budowaną przez encję Aggregate, dołączenia encji Feature do poszczególnych węzłów, do których rozwiązuje się encja Release. Materiały samouczkowe i koncepcyjne znajdują się gdzie indziej; inspect odpowiada na pytanie „do czego ta encja faktycznie się rozwiązuje?”

Pojedynczy argument pozycyjny jest kierowany na podstawie kształtu treści; podpolecenie nie jest potrzebne. Polecenie wybiera gałąź według następującej heurystyki:

Kształt identyfikatoraGałąźWynik
Zaczyna się od ./, ../ lub / albo kończy się na .yaml / .ymlGałąź plikuInspekcja pliku zależna od nagłówka kind: pliku.
Zaczyna się od oci://Gałąź rejestruEncja opublikowana pod tą współrzędną, odczytana z jej rejestru i wyświetlona w widoku, jaki otrzymuje plik jej rodzaju. Zob. Odczyt opublikowanej encji.
Cokolwiek innegoGałąź kataloguWyszukanie identyfikatora w stosie wyszukiwania katalogu we wszystkich rodzajach encji; rozwiązanie łańcuchów extends:; wyświetlenie własnego widoku dopasowanego rodzaju.

Trzy poziomy szczegółowości

--list, poziom domyślny i --detail tworzą jednolity, trzypoziomowy schemat szczegółowości, którego przestrzega każdy rodzaj encji. --list i --detail wzajemnie się wykluczają — podanie obu jest odrzucane, a nie rozstrzygane po cichu.

  • --list — tylko identyfikatory. Encja Component wypisuje swoją nazwę i nazwy gniazd uses; encja MappingLibrary wypisuje nazwy swoich mapowań; encja Aggregate wypisuje nazwy swoich komponentów wraz z ich typami.
  • poziom domyślny — ustrukturyzowany przegląd dostosowany do pracy interaktywnej. Zaczyna się od tożsamości encji oraz — dla każdego rodzaju poza encjami Manifest i Release — jej opisu, jeśli encja go definiuje; encja bez opisu nie wypisuje go wcale, zamiast wypisywać pustą linię. Reszta kształtu zależy od rodzaju: encja Component pokazuje swój schemat i gniazda; encja Aggregate pokazuje komponenty, ich wartości i krawędzie wraz z dołączeniami, które niesie każde połączenie, oraz graf zależności; encja Release pokazuje drzewo węzłów dla każdej granicy z dołączeniami encji Feature, przy czym każde dołączenie zapisane na połączeniu jest wymienione pod tym połączeniem.
  • --detail — pełne treści pól. Wszystko, co zawiera dany rodzaj: encja Component dodaje swoje mechanizmy self-inject, wymagane encje Features i etykiety; encja MappingLibrary rozwija pełną treść szablonu każdego mapowania; encja Recipe dodaje treść workloadu, provides i asercje.

Niektóre rodzaje wykorzystują poziomy do stopniowego ujawniania coraz większej części zdefiniowanej treści. Encja MappingLibrary na poziomie --list pokazuje nazwy mapowań; na poziomie domyślnym dodaje dla każdego mapowania wygenerowany przykład użycia; na poziomie --detail rozwija pełną treść szablonu.

Rozwiązywanie: --raw i --resolved

Każdy rodzaj ma naturalną domyślną głębokość rozwiązywania (zob. tabela poniżej). --raw i --resolved to zawsze dostępne nadpisania, które wzajemnie się wykluczają — podanie obu jest odrzucane, a nie po cichu rozstrzygane:

  • --raw wyłącza całe rozwiązywanie — encja jest emitowana w postaci, w jakiej została napisana, prosto z pliku.
  • --resolved włącza pełną głębokość rozwiązywania danego rodzaju.

Dla rodzajów, które domyślnie są wyświetlane w postaci źródłowej, --raw nic nie zmienia, a --resolved uruchamia takie rozwiązywanie, jakie dany rodzaj obsługuje. Dla rodzajów domyślnie rozwiązywanych --raw pozwala ominąć rozwiązywanie i zobaczyć postać źródłową.

--raw odtwarza plik, więc wartość, którą autor zadeklarował jako wrażliwą, pojawia się w nim dokładnie tak, jak została napisana. Taka jest umowa, a nie luka — widok źródłowy, który po cichu ukrywałby część siebie, nie byłby widokiem źródłowym. Z wynikiem --raw należy obchodzić się tak samo jak z plikiem encji, z którego pochodzi. --output yaml odtwarza plik w ten sam sposób, dla każdego rodzaju, w tym dla encji Release.

Encja Release odpowiada na dwa dalsze pytania, a każde z nich to osobny dokument z własną flagą. Skompilowany graf, do którego rozwiązuje się encja Release, to --ir-graph; jej domknięcie zależności to --closure. Zob. Wynik do odczytu maszynowego oraz Domknięcie zależności: --closure poniżej.

Wartości domyślne dla poszczególnych rodzajów

inspect zna rodzaje, które można sprawdzać samodzielnie, wymienione w poniższej tabeli. Rodzaje katalogowe są domyślnie renderowane w postaci autorskiej — ich pliki są samowystarczalnymi kontraktami. Rodzaje instancyjne domyślnie pokazują widok rozwiązany, ponieważ ich autorski YAML jest jedynie punktem wyjścia dla kaskady lub potoku.

RodzajDomyślnieCo oznacza „rozwiązany”
Componentw postaci autorskiejPlik jest samowystarczalnym kontraktem; rozwiązywanie odbywa się względem powiązania w encji Manifest i jest pokazywane za pomocą --show-implements.
Featurew postaci autorskiejTak samo jak w przypadku encji Component.
Recipew postaci autorskiej--show-implements rozwiązuje odwołanie spec.implements do encji Component.
FeatureRecipew postaci autorskiej--show-implements rozwiązuje odwołanie spec.implements do encji Feature.
MappingLibraryw postaci autorskiejWpisy są nieprzezroczystymi ciągami szablonów Go; renderowanie następuje w momencie użycia.
SchemaLibraryw postaci autorskiejWpisy są wielokrotnego użytku definicjami schematów i szablonów, rozwiązywanymi w momencie użycia.
WorkloadLibraryw postaci autorskiejWpisy to wielokrotnego użytku treści Workload importowane przez encję Recipe, obliczane w momencie użycia.
ArtifactLibraryw postaci autorskiejWpisy to wielokrotnego użytku pakiety artefaktów importowane przez encję Recipe, renderowane w momencie użycia.
Pluginw postaci autorskiejPlik jest samowystarczalnym kontraktem pluginu: typy gniazd, uprawnienia dla poszczególnych eksportów, ograniczenia środowiska uruchomieniowego i wskaźnik podpisu. Można go wskazać ścieżką pliku lub jego współrzędną <pluginType>/<name> w katalogu.
ManifestrozwiązanyStosowany jest łańcuch extends:; przedstawiane są rozwiązane mapowania komponentów i funkcji.
AggregaterozwiązanyBudowana jest topologia — obliczane są graf użyć i kolejność.
ReleaserozwiązanyUruchamiany jest pełny potok: rozwiązanie, rozwinięcie adnotacji, uruchomienie strażników, zbudowanie topologii, zbudowanie IR.

Plik, którego kind: to Workload, jest odrzucany: encja Workload istnieje wyłącznie osadzona w encji Recipe i nie jest samodzielną encją, którą można sprawdzić. Aby zobaczyć jej Workload, należy sprawdzić encję Recipe.

Głębokość rozwiązywania dla poszczególnych rodzajów

Większość rodzajów nie ma potoku — inspect odczytuje plik i go renderuje. Trzy rodzaje instancji są rozwiązywane w znaczący sposób:

  • Manifest stosuje swój łańcuch extends: — podążając za importami plików — i renderuje scalone mapowania komponentów i funkcji. --raw pokazuje plik w postaci, w jakiej został napisany.
  • Aggregate buduje swoją topologię: konstruowany jest graf użyć (uses-graph) i obliczana jest kolejność zależności. Widok domyślny pokazuje komponenty z ich wartościami i krawędziami, a po nich graf zależności. --raw pokazuje napisane drzewo podsystemów.
  • Release uruchamia cały potok kompilacji aż do IR — rozwiązanie, rozwinięcie adnotacji, uruchomienie strażników, zbudowanie topologii, zbudowanie IR — i renderuje drzewo węzłów dla każdej granicy wraz z dołączeniami Feature każdego węzła i ich pochodzeniem. Dołączenia zarządcze, które kształtują graf, działają w tym potoku, a nie są pomijane na potrzeby widoku, więc odczytany wynik odzwierciedla to, co zdecydowały: etykiety dołączenia label-transform są na miejscu, zanim cokolwiek zostanie z nimi dopasowane, a adnotacje wstrzyknięte przez dołączenie annotation-transform rozwijają się w dołączenia Feature dokładnie tak samo jak adnotacja napisana samodzielnie. Dołączenie, którego wtyczki to polecenie nie może rozwiązać, zatrzymuje je, zamiast pozostawiać graf narysowany bez decyzji tej wtyczki. Encja Release rozszerzająca inną jest rysowana — w tym widoku i w --ir-graph — jako Release, do którego składa się jej łańcuch extends:, czyli ten, który odczytuje jej kompilacja, więc Release wskazujący tylko swojego rodzica pokazuje Aggregate, Manifest i granice tego rodzica pod własną nazwą. Manifest wskazywany przez encję Release jest również składany przez swój własny łańcuch extends:, niezależnie od tego, czy Release cokolwiek rozszerza, więc dołączenie, którego mapowanie ten Manifest dziedziczy, pokazuje realizację używaną przez kompilację. --raw emituje plik Release dosłownie, bez potoku. --closure zadaje inne pytanie o ten sam Release i nie uruchamia żadnego potoku; zob. Domknięcie zależności: --closure.

Nie ma osobnej flagi głębokości; przełącznik --raw / --resolved jest jedyną kontrolą rozwiązywania, nałożoną na naturalne ustawienie domyślne każdego rodzaju.

Zachowanie w przypadku błędów

Plik sąsiedni, do którego istnieje odwołanie i którego nie udało się wczytać, natychmiast zatrzymuje polecenie — na przykład encja Release wskazująca na brakującą encję Aggregate albo uszkodzona encja katalogu w stosie wyszukiwania. Polecenie zatrzymuje się z czytelnym komunikatem zamiast renderować częściowe wyniki i nie ma trybu kontynuowania po błędzie wczytywania: gdy dokument potrzebny do rozwiązania jest nieczytelny, nie ma już czego rozwiązywać. Gdy rozwiązywanie nazwy zatrzymuje się na jednym dokumencie katalogu, który wczytywanie odrzuca, komunikat podaje to odrzucenie jeden raz: nagłówek z kategorią oraz, jeśli odrzucenie wskazuje warunek, jego krótkim kodem, następnie dokument, a potem opis problemu — w przypadku dokumentu odrzuconego przez schemat jego rodzaju jest to wiersz i naruszone ograniczenie. Komunikat nie zawiera sugestii przeniesienia pliku — katalog go odczytał i właśnie dlatego został on odrzucony.

Encja Release, której kompozycję odrzucają kontrole kompilatora, jest odrzucana zamiast renderowana. Rozwiązywanie encji Release buduje graf, a kontrole wykonywane przez kompilację na gotowym grafie — krawędź uses:, której cel nie spełnia selector: jej gniazda, encja Feature dołączona do komponentu, którego jej appliesTo: nie dopuszcza, i pozostałe — są wykonywane również tutaj, z tą samą diagnostyką, którą wypisuje kompilacja tych samych dokumentów. Odrzucenie wymienia wszystkie wykryte problemy w jednym przebiegu, zamiast zatrzymywać się na pierwszym, więc jeden przebieg pokazuje całą listę do poprawienia, a nie tylko jej pierwszą pozycję. Dzięki temu polecenie rzetelnie opisuje wdrożenie: widok renderujący kompozycję, którą kompilacja odrzuca, zgłaszałby obszar roboczy jako poprawny, choć taki nie jest. Nie dotyczy to wyborów, które niczego nie rozwiązują — --raw, --output yaml i --closure odtwarzają lub rozwiązują to, co zostało napisane, bez budowania grafu.

Encja Release, której plik lockfile nie odpowiada już temu, do czego się rozwiązuje, jest odrzucana z zatrzymaniem, które wypisuje aggrega build. Gdy obok encji Release znajduje się plik lockfile, każdy wybór, który rozwiązuje encję Release — widok domyślny, --resolved, --ir-graph i --closure — porównuje go z tym, do czego rozwiązuje się encja Release, za pomocą porównania dryfu, które kompilacja wykonuje przed renderowaniem. Plik lockfile, który już nie pasuje, zatrzymuje polecenie odmową E0130 kompilacji: każdy wpis, który uległ dryfowi, a następnie aggrega pull --release <release>, które to naprawia. Nic nie jest zapisywane na standardowe wyjście, a polecenie kończy się niezerowym kodem wyjścia, ponieważ obraz sporządzony na podstawie katalogu w jego obecnym stanie pokazywałby to, czego nie renderuje żadna kompilacja tej encji Release. --raw i --output yaml same w sobie nie odczytują ani pliku lockfile, ani katalogu, i nie podlegają mu. Encja Release bez pliku lockfile obok jest rozwiązywana względem katalogu w jego obecnym stanie.

Plik, którego kind: nie jest rozpoznawany, zgłasza nieznany rodzaj i plik, z którego pochodzi. Plik Workload zgłasza, że ten rodzaj może być tylko osadzony, i podaje encję, w której jest osadzany. Identyfikator oci://, którego nie można odczytać, jest odrzucany z warunkiem wskazującym przyczynę; warunki te wymienia sekcja Odczytywanie opublikowanej encji.

Rozwiązywanie katalogu

Stos wyszukiwania katalogu jest składany według warstwowego pierwszeństwa: najpierw flagi --catalog (dodawane na początku, w podanej kolejności), następnie catalog_dirs obszaru roboczego z pliku .aggrega-config.yaml — dla encji Release, której konfiguracja podaje własne katalogi w workspace.releases, na ich miejscu stoją katalogi tej encji Release — a potem katalog catalog w katalogu głównym obszaru roboczego, odczytywany niezależnie od tego, czy cokolwiek go wskazuje. Obszar roboczy, którego catalog_dirs zapisano jako pustą listę, nie odczytuje żadnego lokalnego katalogu. Stos działa na zasadzie „pierwszy wygrywa” — tożsamość encji należy do najwcześniejszego katalogu, który ją deklaruje; kopia z późniejszego katalogu zostaje przesłonięta. Gałąź katalogu rozwiązuje identyfikator względem tego stosu we wszystkich rodzajach encji, w ustalonej kolejności pierwszeństwa, i renderuje pierwsze dopasowanie za pomocą widoku właściwego dla danego rodzaju; gałęzie pliku i wydania wczytują z niego przywoływane encje katalogowe, gdy trzeba rozwiązać mapowanie encji Manifest lub rodzica wskazanego przez extends:. Rodzic wskazany przez extends:, którego stos nie zawiera, jest odczytywany tam, gdzie odczytuje go kompilacja: z pamięci podręcznej artefaktów, pod przypięciem, które plik blokady encji Release rejestruje dla niego — wskazanej encji Release albo, gdy żadna nie jest wskazana, każdej encji Release w obszarze roboczym. Bazę opublikowaną w rejestrze można więc tu rozwiązać, gdy tylko aggrega pull ją pobierze i przypnie, a wcześniej polecenie jest odrzucane ze wskazaniem aggrega pull --release <release>. Nic nie jest pobierane.

Wyszukiwanie nazwy w kontekście encji Release

Nazwa podana samodzielnie jest wyszukiwana we własnym stosie obszaru roboczego. Po dodaniu obok niej --release <release-path> nazwa jest wyszukiwana zamiast tego w stosie tej encji Release — w katalogach, które konfiguracja obszaru roboczego przypisuje tej encji Release, z dodanymi na początku ewentualnymi --catalog — czyli w tym, co odczytuje kompilacja tej encji Release. Obszar roboczy, który przechowuje po jednym wariancie katalogu na każdą encję Release, z których każdy deklaruje tę samą encję, odpowiada więc na nazwę wariantem, z którym kompilowana jest dana encja Release:

aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml

Nazwa, której stos tej encji Release nie rozwiązuje, zostaje odrzucona, a informacja o tym, skąd odczytywane są encje lokalne, wskazuje wpis tej encji Release w workspace.releases, ponieważ to właśnie ten wpis odczytało wyszukiwanie. --release wybiera stos, w którym wyszukiwana jest nazwa, więc dotyczy wyłącznie samej nazwy: ścieżka pliku i odwołanie do rejestru są odczytywane takie, jakie są, i odrzucają tę flagę. --release wskazujące nieistniejący plik lub katalog zostaje odrzucone, zanim cokolwiek zostanie wyszukane.

Odczyt opublikowanej encji

aggrega inspect oci://<host>/<repository>:<tag> odczytuje encję opublikowaną pod tą współrzędną; @<digest> zamiast :<tag> wskazuje dokładnie jeden manifest. W ten sposób można obejrzeć encję, która istnieje wyłącznie w rejestrze — repozytorium to segment rodzaju, po którym następuje tożsamość encji, zgodnie z opisem w Catalog and Registry §6, a aggrega push wypisuje referencję, pod którą opublikował encję; tutaj odczytuje się ją z przedrostkiem oci://.

Widoczna jest encja w takiej postaci, w jakiej została opublikowana. Encja opublikowana wraz z deklarowanymi przez nią plikami — encja Recipe z lokalnym chartem lub plikiem blokady, encja Component z importowanym schematem — jest dostarczana jako archiwum, z którego encja zostaje rozpakowana: jest to dokument w katalogu głównym archiwum deklarujący rodzaj podlegający publikacji, dzięki czemu szablon chartu ani fragment compose dostarczony obok nie zostanie z nią pomylony. Encja, która nie deklaruje żadnego pliku, jest dostarczana jako niezmieniony dokument, a encja Plugin jest odczytywana ze swojego manifestu, a nie z opublikowanego wraz z nią pliku wykonywalnego. Dokument jest następnie renderowany tym samym widokiem, który otrzymuje plik danego rodzaju, z tymi samymi poziomami szczegółowości oraz tymi samymi --raw i --output yaml. Dziedziczenie nie jest stosowane: widok pokazuje to, co wydawca umieścił pod tą współrzędną. Czytelne układy kończą się informacją o tym, co odczytano: współrzędną, tym, czy zawierała encję jako archiwum czy jako sam dokument, typem nośnika deklarowanym przez jej manifest oraz skrótem tego manifestu, który po zapisaniu jako @<digest> zamiast :<tag> ponownie odczytuje te same bajty; --output yaml wypisuje dokument i nic po nim.

Co jest sprawdzane, a co nie. Pobrane bajty są porównywane ze skrótem, który zapisuje dla nich manifest samego artefaktu, co potwierdza, że są to bajty wskazywane przez ten manifest. Jest to sprawdzenie względem tego, co zwrócił rejestr, a nie względem czegokolwiek zapisanego wcześniej: żaden podpis dołączony do artefaktu nie jest weryfikowany i żadne wycofanie zapisane dla niego nie jest zgłaszane. Nic nie jest zapisywane — ani wpis w pamięci podręcznej, ani plik blokady — więc odczyt współrzędnej nie zmienia niczego, co rozwiąże późniejsza kompilacja.

Polecenie korzysta z sieci. Połączenie z rejestrem odbywa się przy użyciu poświadczeń, które ta maszyna przechowuje dla niego, z tego samego magazynu, który odczytują aggrega push i aggrega pull, a z rejestrem na tej maszynie łączy się przez zwykły HTTP. Obszar roboczy w trybie offline odrzuca odczyt, zanim nastąpi jakiekolwiek połączenie.

Odczyt, który nie może zwrócić wyniku, kończy się niezerowym kodem wyjścia i nie wypisuje niczego na standardowe wyjście. Każdy z poniższych błędów podaje swój warunek wraz z informacją, co należy zrobić; rejestr, z którym w ogóle nie można się połączyć, jest zgłaszany z błędem sieci, który przerwał odczyt:

Co się stałoWarunek
Pod referencją nic nie opublikowanoE0137
Rejestr odrzucił poświadczenie lub nie przechowuje się dla niego żadnegoE0138
Obszar roboczy jest w trybie offlineE0125
Artefakt jest archiwum, którego nie można rozpakowaćE0300
Archiwum nie zawiera w katalogu głównym żadnego dokumentu encjiE0298
Archiwum zawiera w katalogu głównym więcej niż jeden dokument encjiE0299
Dokument nie jest encją rodzaju publikowanego przez rejestrE0301

Każdy kod jest wymieniony w opisie błędów. Referencja, która nie wskazuje repozytorium albo nie zawiera ani tagu, ani skrótu, jest odrzucana wraz z postacią, którą należy zapisać zamiast niej. --ir-graph i --closure są odrzucane, zanim cokolwiek zostanie pobrane, ponieważ żaden rodzaj publikowany przez rejestr nie jest encją Release.

Powiadomienia o wycofaniu z użycia i wycofaniu publikacji

Wydawca może po opublikowaniu artefaktu zapisać przy nim znacznik stwierdzający, że opublikowana wersja jest przestarzała lub wycofana. Gdy gałąź katalogu rozwiązuje encję, inspect zgłasza każdy taki znacznik pod widokiem samej encji — dla każdego rodzaju rozwiązywanego po nazwie, nie tylko dla encji Component.

Powiadomienie podaje poziom ważności zapisany przez wydawcę — warning, error lub retracted — wraz z wersją, przy której zapisano znacznik, powodem, zamiennikiem, jeśli został wskazany, oraz datą wydania. Zgłaszane są wszystkie trzy poziomy. To szerszy zbiór niż ten, który zmienia wynik rozwiązywania w kompilacji: wersja oznaczona jako retracted jest wykluczana z wyboru wersji, natomiast warning i error mają charakter doradczy i nadal są wybierane. inspect pokazuje, co powiedział wydawca; nie decyduje, co zostanie otrzymane.

Powiadomienie jest odczytywane z lokalnego indeksu rejestru, z którego rozwiązywana jest encja, budowanego przez aggrega registry update — nie wymaga więc sieci i działa w obszarze roboczym offline. Ponieważ indeks jest migawką, powiadomienie kończy się informacją, kiedy wykonano tę migawkę, i podaje polecenie, które ją odświeża. Obszar roboczy bez zbudowanego indeksu nie zgłasza niczego, a brak powiadomienia oznacza zatem „nic nie zapisano w tej migawce”, a nie „nic nie zapisano”.

Znacznik jest zgłaszany tylko wtedy, gdy jego własny podpis weryfikuje się względem podpisujących uznawanych przez politykę zaufania rejestru. Znacznik niepodpisany lub taki, którego podpis się nie weryfikuje, nie jest zgłaszany: twierdzenie, którego nie można uwierzytelnić, nie jest przedstawiane jako fakt.

Powiadomienie towarzyszy widokom czytelnym dla człowieka. Ani --output yaml, ani --ir-graph go nie dołącza, więc konsument parsujący którykolwiek z nich otrzymuje dokument i nic więcej.

Przykłady

Wyszukiwanie encji Component w katalogu

$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0
Schema:
|
values: { port?: int | *8080 }
Uses sockets:
db: selector="component.aggrega.ai/type=stateful-server"

Widok domyślny pokazuje opis encji Component, jeśli go ona zawiera, następnie rozwiązany schemat (po ewentualnym scaleniu extends:) oraz zadeklarowane gniazda uses. Powyższa encja Component nie zawiera opisu, dlatego zapis zaczyna się od razu od schematu. --detail dodaje mechanizmy self-inject, wymagane Features i etykiety; --list pokazuje tylko identyfikator encji Component i nazwy jej gniazd.

Feature

$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0
Schema:
|
values: { port?: int | *9090 }
Uses sockets:
backend: selector="component.aggrega.ai/type=stateful-server"
inject: [env]
Secret slots:
token (required)
Targeting:
appliesTo: component.aggrega.ai/type=server
Labels:
feature.aggrega.ai/category: observability

Recipe z --show-implements

Widok domyślny encji Recipe pokazuje po jednej sekcji dla każdego zadeklarowanego trybu wejścia, jej capability oraz mapowanie wartości. --show-implements rozwiązuje odwołanie spec.implements względem katalogu i wyświetla powiązaną encję Component wraz z załącznikami, których ta encja Component wymaga:

$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Synthesized
workload: inline
valuesMapping: (none)
Implements Component: core/api-server:1.0.0
requires attachment (observability): core/metrics

Recipe deklarujący kilka trybów wejścia

Tryby wejścia encji Recipe składają się przez dodawanie: source: do wyrenderowania, workload: do syntezy i mapa artifacts: wnoszą każdy własne wyjście, a encja Recipe może zadeklarować dowolną ich kombinację. inspect raportuje każdy tryb zadeklarowany w encji Recipe, zamiast wybierać jeden, więc widoczny jest dokładnie zestaw, który został napisany:

$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Sourced
source: oci://charts.example.com/api-server:2.1.0
## Synthesized
workload: inline
valuesMapping: inline template
Artifacts: 2
- servicemonitor.yaml
- networkpolicy.yaml

Sekcje są uporządkowane source: → workload: → artifacts:, w tej samej kolejności, którą stosuje build, gdy sprowadza encję Recipe do nazwy jednego trybu i gdy raportuje, którego zadeklarowanego trybu powiązany provider nie obsługuje — dzięki temu ten widok i diagnostyka buildu wymieniają tryby w jednej kolejności. Encja Recipe, która nie deklaruje ani source:, ani workload:, jest raportowana jako artifacts-only; to jedyny przypadek, w którym widok podaje nazwę jednego trybu.

Manifest (domyślnie rozwiązany)

$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings:
Type → Recipe
core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0
core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0
core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings:
Type → FeatureRecipe
core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings:
(none)

Widok domyślny stosuje łańcuch extends: encji Manifest i przedstawia rozwiązane mapowania komponentów i funkcji oraz powiązania adnotacji. --raw pokazuje plik w postaci napisanej, przed rozwiązaniem extends.

Aggregate (domyślnie rozwiązany)

$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components:
backend (type: core/compute/api-server)
Values: (none)
Uses:
databases:
- data.main-db
frontend (type: core/compute/web-ui)
Values: (none)
Uses:
apis:
- my-api → backend
main-db (type: core/datastore/postgres)
Values:
database_name: app_production
Uses: (none)
Dependency Graph:
data.main-db
↑ backend
backend
↑ frontend

Widok domyślny buduje topologię i pokazuje każdy komponent z jego wartościami i krawędziami uses, a następnie obliczony graf zależności. Drzewo podsystemów jest renderowane z zagnieżdżeniem; --flat renderuje po jednej sekcji na węzeł, każdą oznaczoną pełną ścieżką z kropkami.

Po połączeniu zapisanym w formie długiej następują przenoszone przez nie załączniki, każdy pod nazwą, jaką przyjmuje w komponencie konsumującym — alias połączenia i slot połączone kropką — z typem Feature, który wskazuje, oraz klauzulą podającą slot, który wypełnia, i informację, czy obsługuje materiał zadeklarowany jako wrażliwy:

gateway (type: conn/gateway)
Values:
region: eu
Uses:
models:
- gpt → model
- gpt.credential (feature.conn/token) [slot: credential, sensitive]

Slot i oznaczenie to fakty, które build encji Release wdrażającej ten Aggregate zapisuje dla załącznika, odczytywane tak samo jak w widoku Release (zob. Połączenie załącznika, slot i klauzula wrażliwości); pochodzą z deklaracji slotu gniazda i z deklaracji samej encji Feature, więc nie zależą od tego, która encja Release wdraża ten Aggregate. Aggregate nie wskazuje żadnego Manifest, więc realizacja, którą Manifest danej encji Release wybiera dla załącznika, nie jest tu pokazywana. Ten widok wymienia połączenia komponentu i to, co przenoszą; załączniki własnego bloku komponentu pojawiają się w widoku Release.

Release (domyślnie rozwiązany)

Widok Release to inspekcja o najwyższej stawce. Uruchamia pełny potok i renderuje, dla każdej granicy, każdy węzeł Component, jego krawędzie uses oraz każdy Feature dołączony do tego węzła — ten zapisany na połączeniu pod krawędzią tego połączenia — każdy ze slotem załącznika, który wypełnia, informacją, czy obsługuje materiał zadeklarowany jako wrażliwy, i FeatureRecipe, który go realizuje, a także nawiasem pochodzenia ujawniającym, skąd pochodzi załącznik:

$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns
Directory: ./dist/backend
Annotations (provider-consumed):
aggrega.ai/namespace: backend-zone
Component: backend (type: core/compute/api-server:1.0.0)
Uses:
data.main-db → data.main-db [cross-boundary]
Features: (none)
Boundary: frontend-ns
Directory: ./dist/frontend
Annotations (provider-consumed):
aggrega.ai/namespace: frontend-zone
Component: frontend (type: core/compute/web-ui:1.0.0)
Uses:
my-api → backend [cross-boundary]
Features:
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns
Directory: ./dist/data
Annotations (provider-consumed):
aggrega.ai/namespace: database-zone
Component: data.main-db (type: core/datastore/postgres:1.0.0)
Features: (none)

Każda granica zawiera swój katalog wyjściowy i adnotacje konsumowane przez providera; każdy komponent w granicy zawiera swój typ komponentu z Aggregate, krawędzie uses (z oznaczonymi krawędziami między granicami), po każdej z nich załączniki przenoszone przez to połączenie, oraz własne załączniki Feature, każdy załącznik z klauzulą faktów i nawiasem pochodzenia. --flat spłaszcza drzewo granic do jednej sekcji na granicę, oznaczonej jej pełną ścieżką. --raw wypisuje plik Release dosłownie, bez potoku.

Wyjście YAML

$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
db:
selector: component.aggrega.ai/type=stateful-server
schema:
values:
port: {type: integer, default: 8080}

Encja Component wskazana z katalogu jest wypisywana jako encja, do której rozwiązał ją katalog, więc po scaleniu extends: widać scaloną encję, a nie plik w postaci napisanej przez autora; plik encji Component jest wypisywany w postaci napisanej przez autora.

Wyjście czytelne maszynowo

Dwie flagi generują wyjście czytelne maszynowo i odpowiadają na różne pytania. --output wybiera format dokumentu, który to polecenie już renderuje; --ir-graph żąda innego dokumentu — skompilowanego grafu, do którego rozwiązuje się encja Release — dodatkowo. Są niezależne: podanie obu daje graf i YAML w postaci napisanej przez autora, każde jeden raz.

--output yaml emituje encję w postaci napisanej przez autora, nadającą się do przekazywania potokiem i porównywania. To wyjście jest dosłowne, łącznie z wartościami, które autor zadeklarował jako wrażliwe — wyjście, które deklaruje odtworzenie wejścia, nie może ukryć jego części i nadal je odtwarzać. Należy przekazywać, przechowywać i udostępniać je tak samo jak plik encji, z którego pochodzi.

Skompilowany graf: --ir-graph

aggrega inspect <release> --ir-graph zapisuje graf, do którego rozwiązało się uruchomienie, na standardowe wyjście jako JSON, przed widokiem, który polecenie i tak renderuje. Jeden dokument JSON, jeden końcowy znak nowej linii, więc odbiorca dekodujący strumień odczytuje graf i kończy.

Dotyczy encji Release, jedynego rodzaju, który rozwiązuje się do grafu. Zapytane o dowolny inny rodzaj lub o encję katalogu po nazwie, polecenie odmawia i to komunikuje, zamiast renderować własny widok tej encji i po cichu porzucać żądanie.

Kompozycja odrzucona przez sprawdzenia kompilatora nie daje grafu. Odmowa opisana w sekcji Zachowanie w przypadku błędów następuje, zanim cokolwiek zostanie zapisane do tego strumienia, więc potok, który go czyta, nigdy nie otrzyma grafu, którego odmówiłby build tych samych dokumentów — otrzymuje te same ustalenia, które zgłosiłby build, oraz niezerowy kod wyjścia.

Ta sama flaga, w tym samym znaczeniu, występuje w aggrega build i aggrega validate: każde z nich zwraca graf obliczony przez dane uruchomienie, oprócz wszystkiego innego, co produkuje dane polecenie. Integracja z edytorem odczytuje ten sam graf przez protokół demona.

--output yaml nie emituje grafu. Odtwarza napisaną przez autora encję Release, dokładnie tak jak dla każdego innego rodzaju. Potok, który potrzebuje grafu, odczytuje go zamiast tego z --ir-graph i otrzymuje JSON, a nie YAML.

Graf ukrywa wartości. Nie jest plikiem, który ktoś napisał — to wynik obliczony przez kompilację z encji Aggregate, encji Release i katalogu — więc nie ma kontraktu zachowania postaci autorskiej, a te same deklaracje, które rządzą czytelnymi układami, rządzą także nim. Wszędzie tam, gdzie graf zawiera liść zadeklarowany przez autora jako wrażliwy, wartość jest zastępowana obiektem z jednym kluczem, oznaczającym ją jako ukrytą:

"values": {
"secretName": "db-creds",
"vault": {
"token": { "aggrega_withheld": "declared" }
}
}

Klucz pozostaje, więc graf nadal informuje, jakie liście zawiera węzeł i jego załączniki; znika tylko wartość. Niezadeklarowany sąsiedni element w tym samym ładunku jest emitowany w postaci autorskiej — secretName powyżej to publiczny lokalizator, którego autor nie zadeklarował, i zostaje wypisany. Powód dołączony do znacznika wyjaśnia, dlaczego wartości brakuje: declared dla liścia objętego deklaracją oraz unreadable, gdy ładunek dotarł w kształcie, którego to polecenie nie mogło odczytać — wtedy ukrywany jest cały ładunek, zamiast zgadywać którąkolwiek jego część.

Własna konfiguracja połączenia jest ukrywana w ten sam sposób. values dla danego połączenia, które Aggregate zapisuje we wpisie uses, oraz infra dla danego połączenia, które zapisuje w nim Release, podlegają gniazdu komponentu konsumującego — valueSchema i infraSchema, które ono deklaruje, czyli kontraktom, względem których ta konfiguracja jest walidowana — a nigdy deklaracjom celu. Liść, który którykolwiek z kontraktów deklaruje jako sensitive: true, jest zastępowany znacznikiem w values i infra krawędzi oraz we wpisie uses węzła konsumującego, który zawiera wartości w postaci zapisanej przez autora; każda krawędź wymienia ukrywane przez siebie liście w sensitive_payload_leaves, polu, którego węzeł używa dla własnych. Liść o tej samej nazwie na połączeniu, którego gniazdo deklaruje go jako czytelny, jest emitowany w postaci zapisanej.

Gdy potok rzeczywiście potrzebuje wartości, należy podać --unredacted i traktować wynik tak samo jak same pliki encji. aggrega build i aggrega validate przyjmują tę samą flagę obok --ir-graph, na tych samych zasadach: zwracany przez nie graf ukrywa wartości, jeśli flaga nie zostanie podana.

Protokół demona udostępnia ten sam graf według tej samej zasady. aggrega/irGraph odpowiada z ukrytymi wartościami i zwraca je jawnie tylko na żądanie, które ustawia pole unredacted — odpowiednik tej flagi w protokole. Tak więc to, co rysuje panel edytora, podlega tym samym deklaracjom, a klient pokazujący wartości robi to, ponieważ o nie poprosił.

Domknięcie zależności: --closure

aggrega inspect <release> --closure raportuje domknięcie zależności encji Release: każdą osiąganą encję katalogu w wersji, do której została rozwiązana, wraz z tożsamościami encji Aggregate i Manifest, do których rozwiązały się jej dwa wskaźniki, oraz współdzielonymi dokumentami, z których te encje korzystają. Nic nie jest renderowane i nie powstaje żaden artefakt — domknięcie jest rozwiązywane, a nie budowane, więc do udzielenia odpowiedzi nie jest ładowany żaden provider.

Domknięcie i widok rozwiązany to różne dokumenty i żadnego z nich nie da się odtworzyć z drugiego. Widok rozwiązany — to, co to polecenie domyślnie renderuje dla encji Release — mówi, jak wygląda wdrożenie: jego granice, węzły komponentów, co jest z czym połączone i co jest dołączone do każdego węzła. Domknięcie mówi, co zostało pobrane, aby je zbudować, i w jakich wersjach. Encja może zostać osiągnięta, nigdy nie pojawiając się jako węzeł — encja Recipe, na którą Manifest mapuje typ komponentu, jest osiągana przez każdą kompilację i nie jest węzłem w żadnej z nich — a węzeł zapisuje typ komponentu, jako który został zadeklarowany, a nie wersję, do której ten typ został rozwiązany. Czytelnik pytający więc „dlaczego ta wersja się zmieniła?”, „na co wpłynęłaby zmiana tego współdzielonego dokumentu?” lub „od czego to wdrożenie faktycznie zależy?” pyta o domknięcie, a czytelnik mający widok rozwiązany nie uzyska go, czytając uważniej.

To samo słowo oznacza ten sam dokument na każdej powierzchni. --closure tutaj, aggrega/releaseClosure w protokole demona (zob. aggrega serve „Domknięcie to nie graf”) oraz tryb release narzędzia describe w protokole narzędzi asystenta odpowiadają na to samo pytanie o encję Release; nazwa encji Release podana w dowolnym z nich prowadzi do tego samego rozwiązania, więc te trzy nie mogą się rozejść co do tego, od czego zależy Release. Gdy plik blokady nie odpowiada już temu, do czego rozwiązuje się Release, to polecenie i narzędzie describe odmawiają z zatrzymaniem kompilacji z powodu rozbieżności; demon, który obsługuje edytor w trakcie edycji, odpowiada.

To jeden dokument, więc żąda się go osobno. --closure wybiera domknięcie zamiast widoku rozwiązanego i nie można go łączyć z --raw, --resolved, --output ani --ir-graph — każda z tych flag żąda innego dokumentu o tej samej encji Release, a polecenie przyjmujące dwa żądania musiałoby po cichu odpowiedzieć tylko na jedno z nich. Połączenie ich jest odrzucane z podaniem tej pary.

Dotyczy encji Release i niczego innego. Encja katalogu, plik encji Aggregate, Manifest — żadne z nich nie rozwiązuje domknięcia, więc żądanie jest odrzucane, zamiast odpowiadać na nie wyrenderowaniem własnego widoku danego obiektu i pominięciem żądania. Pominięte żądanie wyglądałoby dla wywołującego dokładnie tak samo jak obiekt, którego domknięcie jest puste.

Każdy wynik jest rozróżniany. Na encję Release, która się rozwiązuje, odpowiedzią jest lista. Ścieżka encji Release niewskazująca żadnego pliku jest odrzucana z informacją, że pliku nie ma. Encja Release, która istnieje, ale jej domknięcia nie da się rozwiązać, jest odrzucana z podaniem, czego nie udało się rozwiązać i skąd pochodziło odwołanie, a następnie wszelkich plików odrzuconych przy ładowaniu katalogu — ponieważ odrzucony plik jest zwykle przyczyną zniknięcia encji osiąganej przez Release. Rejestr zaufania do pluginów obok encji Release, który istnieje, ale nie da się go odczytać, jest odrzucany z podaniem, czego nie udało się odczytać, ponieważ lista, która by go pominęła, nie zgłaszałaby żadnego wycofanego pluginu tam, gdzie żadnego nie dało się sprawdzić. Encja Release, której plik blokady nie odpowiada już temu, do czego się ona rozwiązuje, jest odrzucana z zatrzymaniem z powodu rozbieżności, które wypisuje kompilacja, jak opisuje Zachowanie w przypadku błędów, ponieważ wymienione wersje byłyby takimi, których nie używa żadna kompilacja tej encji Release. Pusta lista nigdy nie jest odpowiedzią w żadnym z tych przypadków: przedstawiałaby błędnie wpisaną ścieżkę lub uszkodzony obszar roboczy jako Release, który od niczego nie zależy.

Trzy poziomy szczegółowości działają tak jak dla każdego rodzaju. --list wypisuje same odwołania, po jednym w wierszu, do potokowania. Poziom domyślny dodaje rozwiązane tożsamości, wersję, do której rozwiązało się każde odwołanie, wykorzystane dokumenty współdzielone, każde mapowanie w encji Manifest, którego cel nie implementuje typu, na który jest mapowany, oraz każde powiadomienie o wycofaniu z użycia lub wycofaniu zapisane dla tego, od czego zależy Release — w jego pliku blokady dla przypiętego odwołania, a w rejestrze zaufania do pluginów obok niego dla pluginu dołączonego w roli zwracającej werdykt akceptacji lub odrzucenia — tymi samymi słowami, którymi aggrega build wypisuje ten sam znacznik. --detail dodaje rodzaj każdego odwołania tam, gdzie miejsce odwołania go zapisało — niektóre pozycje w dokumencie określają, na jaki rodzaj wskazują, a inne nie, więc jest on raportowany tam, gdzie jest znany, a nie zgadywany na podstawie kształtu nazwy.

$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0
Aggregate: fullstack-app
Manifest: prod-manifest
Environment: production
Entities (11):
./aggregate.yaml
./manifest.yaml
core/compute/api-server (1.0.0)
core/compute/web-ui (1.0.0)
core/datastore/postgres (1.0.0)
core/k8s-dns-resolver (1.0.0)
db-module (1.0.0)
helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0)
k8s-dns-patcher:1.0.0 (1.0.0)

Jeśli obszar roboczy zapisał, do jakich wersji rozwiązuje się encja Release, ten zapis stanowi punkt wyjścia rozwiązywania, więc raportowane wersje to te, z których to wdrożenie jest budowane, a nie te, które katalog akurat dziś zawiera. Obszar roboczy bez takiego zapisu jest rozwiązywany względem katalogu w jego bieżącym stanie.

Klauzula połączenia, slotu i wrażliwości załącznika

Każdy załącznik Feature w widoku encji Release zawiera klauzulę wymieniającą fakty, które kompilator rejestruje o samym załączniku: który slot załącznika wypełnia, czy obsługuje materiał zadeklarowany jako wrażliwy, oraz encję FeatureRecipe, która go realizuje — a w przypadku załącznika zapisanego na jednym z połączeń komponentu także połączenie, na którym go zapisano. Klauzula znajduje się między nazwą załącznika a jego nawiasem pochodzenia i brzmi identycznie w obu opisanych niżej formach pochodzenia.

Załącznik zapisany na połączeniu jest wymieniony pod wierszem tego połączenia w Uses:, a nie pod Features:, dzięki czemu Features: zawiera wyłącznie własne załączniki komponentu. Wiersz nad nim określa połączenie przez jego alias i komponent, do którego prowadzi, a resztę mówi jego własna klauzula:

  • [socket: <socket>] — gniazdo, przez które połączenie jest podłączone, czego wiersz połączenia nie podaje. Otwiera klauzulę, ponieważ zmienia sposób odczytania reszty: następująca po nim część dotycząca slotu wskazuje slot zadeklarowany przez gniazdo połączenia, a nie slot, który komponent deklaruje dla własnych załączników.
  • [connection: <alias> through socket <socket>] — ten sam fakt dla załącznika, którego połączenie nie ma wiersza w bloku Uses:; taki załącznik jest wtedy wymieniony pod Features: i w tym miejscu wskazuje swoje połączenie. W obu przypadkach połączenie jest podane raz na załącznik, nigdy dwukrotnie.
  • [slot: <name>] — załącznik wypełnia slot o nazwie <name>. Slot wypełnia się, dołączając Feature pod własną nazwą slotu, więc <name> to nazwa, pod którą zapisano załącznik, dopasowana do zadeklarowanych slotów: featuresSchema encji Component będącej hostem w przypadku jej własnych załączników oraz featuresSchema zadeklarowane przez gniazdo połączenia w przypadku załącznika zapisanego na połączeniu.
  • [free] — załącznik nie wypełnia żadnego zadeklarowanego slotu: rozwiązana encja Component nie deklaruje slotu featuresSchema o tej nazwie. Jest to ustalenie, a nie diagnostyka. Załącznik swobodny jest akceptowany, a operator, który chce go zabronić, wyraża to jako politykę zarządzania, zamiast polegać na tym, że narzędzie go odrzuci.
  • [sensitive] — załącznik obsługuje materiał, który autor zadeklarował jako wrażliwy, ponieważ dołączona encja Feature deklaruje wrażliwy liść, ponieważ wypełniany przez niego slot deklaruje sensitive: true, albo z obu powodów.
  • [realization: <name>:<version>] — encja FeatureRecipe, którą Manifest encji Release wiąże z załącznikiem: według własnej nazwy załącznika, jeśli Manifest mapuje tę nazwę — dla załącznika zapisanego na połączeniu jest to alias i slot połączone kropką — a w przeciwnym razie według jego typu Feature. Jest to realizacja, z którą kompilacja tych samych dokumentów renderuje załącznik, i ta sama wartość, którą skompilowany graf przechowuje przy załączniku jako realization (zob. --ir-graph), więc ten widok i graf nie mogą wskazać różnych realizacji. Występuje w klauzuli jako ostatnia.

Gdy dotyczy kilka faktów, dzielą one jedną klauzulę. core/storage/s3-object-store deklaruje slot secret_access_key oznaczony sensitive: true, więc poświadczenie dołączone pod tą nazwą zgłasza oba fakty, natomiast Feature dołączona pod nazwą, dla której encja Component nie deklaruje slotu, nie zgłasza ani slotu, ani wrażliwości. Przy encji Manifest, która mapuje każdy typ Feature na FeatureRecipe, każdy wiersz podaje także swoją realizację:

Features:
- secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit]
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]

Komponent, którego gniazdo models deklaruje slot credential oznaczony sensitive: true i który podłącza wypełniające go połączenie pod aliasem gpt, wymienia ten załącznik pod połączeniem — obok własnego poświadczenia, które pozostaje pod Features::

Uses:
gpt → model
- gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit]
Features:
- db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]

Załącznik zapisany na połączeniu nigdy nie zgłasza [free]: gniazdo dopuszcza tylko sloty, które deklaruje, a połączenie o innej nazwie jest odrzucane podczas ładowania kompilacji.

Klauzula jest całkowicie pomijana, gdy nie dotyczy żaden z faktów, a każda jej część jest pomijana niezależnie:

  • Brak części gniazda lub połączenia oznacza, że załącznik zapisano we własnym bloku komponentu albo dotarł do niego z szerszego zakresu lub przez rozwinięcie sterowane adnotacjami.
  • Brak części slotu oznacza, że nie udało się rozwiązać zbioru slotów zadeklarowanych przez encję Component będącą hostem — na przykład jej typ nie odpowiada żadnej encji katalogu. Jest to celowo odróżnione od [free]: [free] odpowiada „nie zadeklarowano slotu o tej nazwie”, a brak części oznacza, że na to pytanie w ogóle nie dało się odpowiedzieć.
  • Brak sensitive oznacza, że żadna deklaracja nie oznaczyła załącznika. To mniej niż orzeczenie, że załącznik nie zawiera nic tajnego; ta oś zgłasza deklaracje i nic nie jest wnioskowane z nazwy pola ani jego wartości.
  • Brak części realizacji oznacza, że Manifest nie wiąże załącznika z żadną encją FeatureRecipe znajdującą się w katalogu.

Slot, którego zadeklarowana nazwa to dosłownie free, również jest renderowany jako [free], nie do odróżnienia od załącznika swobodnego — nic nie rezerwuje tego słowa w przestrzeni nazw slotów.

Gramatyka nawiasów pochodzenia w IR

Każde dołączenie encji Feature w widoku encji Release ma nawias pochodzenia. Nawias może przyjąć formę zwartą (jeden nawias na Feature, gdy pochodzenie dołączenia jest jednolite dla wszystkich liści) albo formę per liść (jeden nawias na liść, gdy liście dołączenia pochodzą z różnych źródeł). Istnieją trzy treści nawiasów; stosują się one identycznie do obu form.

Trzy treści nawiasów

  • [explicit] — dołączenie encji Feature jest zadeklarowane przez autora. Encja Aggregate lub Release jawnie nazwała Feature w danym węźle. Jawne dołączenia są źródłem o najwyższym priorytecie; zawsze wygrywają z wkładami sterowanymi adnotacjami w tym samym liściu.

  • [annotation: <key> from <source>] — dołączenie encji Feature jest sterowane adnotacją. Kompilator utworzył je, ponieważ adnotacja na <source> dopasowała powiązanie w encji Manifest deklarujące tę Feature. <key> to klucz adnotacji, który uruchomił powiązanie (np. business.aggrega.ai/team); <source> to encja, która niosła adnotację (aggregate, release, component lub manifest). Utworzone dołączenie jest strukturalnie identyczne z jawnym — dalsze renderowanie traktuje oba tak samo — ale nawias pochodzenia je rozróżnia, aby debugowanie pozostało rozstrzygalne.

  • [explicit; overrides annotation: <key> from <source>] — forma per liść, występująca, gdy jawna deklaracja autora w jednym liściu wypiera wkład adnotacji, który w przeciwnym razie ustawiłby ten sam liść. Taki przypadek powstaje przy kompozycji międzystronnej: adnotacja encji Aggregate może dostarczać filar values: encji Feature, adnotacja encji Release dostarcza jej filar infra:, a jawna deklaracja w encji Release na tej samej Feature nadpisuje jeden liść infra. Nawias liścia zapisuje zarówno jawnego autora, jak i wypartą adnotację; wyparta adnotacja nie wnosi nic do renderowanego wyniku, ale jej obecność widać w widoku inspect, dzięki czemu operator może sprawdzić, która adnotacja została nadpisana i gdzie.

Forma zwarta a forma per liść

Kompilator wybiera między renderowaniem zwartym a per liść, przechodząc po pochodzeniu poszczególnych liści dołączenia i sprawdzając jednolitość. Pochodzenie dołączenia jest jednolite, gdy każdy wypełniony liść (w filarach values: i infra: encji Feature) ma to samo źródło (jawne lub adnotacja), ten sam klucz adnotacji w przypadku sterowania adnotacją, tę samą encję źródłową i żaden liść nie ma znacznika „overrides annotation”. Gdy pochodzenie jest jednolite, kompilator emituje jeden nawias na dołączenie:

- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]

Gdy pochodzenie się rozchodzi — typowym przypadkiem jest kompozycja międzystronna, w której adnotacja encji Aggregate dostarcza values:, a adnotacja encji Release dostarcza infra: tej samej Feature — kompilator emituje jeden nawias na każdy wypełniony liść:

- core/pii-redaction
values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate]
values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate]
infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]

Kolejność przechodzenia: najpierw filar values (w kolejności autora), potem filar infra (według tej samej zasady). Prefiks filaru (values. / infra.) i ścieżka z kropkami wewnątrz filaru wskazują dokładnie, który liść opisuje każdy nawias.

Wartości zadeklarowane jako wrażliwe

Liść, którego schemat deklaruje sensitive: true, wyświetla w miejscu swojej wartości stały tekst <redacted>. Klucz, prefiks filaru i nawias pochodzenia są zachowywane — zastępowana jest tylko wartość — dzięki czemu układ nadal pokazuje, jakie liście zawiera encja i skąd pochodzi każdy z nich. Dotyczy to dwóch czytelnych widoków: bloku Values: poszczególnych węzłów encji Aggregate oraz bloku dołączeń z podziałem na liście w rozwiązanej encji Release — w tym dołączenia zapisanego na połączeniu, wyświetlanego pod wierszem tego połączenia, które wstrzymuje dokładnie te liście, które wstrzymuje ta sama encja Feature, gdy komponent przechowuje ją sam. Skompilowany graf encji Release w trybie --ir-graph wstrzymuje te same liście w formie strukturalnej opisanej w sekcji Dane wyjściowe do odczytu maszynowego.

Components:
app (type: core/app)
Values:
appName: demo
dbPassword: <redacted>
tuning.poolSize: 25
tuning.adminToken: <redacted>

Wstrzymywany jest tylko zadeklarowany liść, a klauzula [sensitive] na poziomie dołączenia nie jest instrukcją wstrzymania: informuje, że dołączenie obsługuje materiał poufny, a nie to, które z jego liści go zawierają. Publikowane lokalizatory encji Feature z poświadczeniami — nazwa zasobu i klucz danych — są publiczne i celowo pozostawiono je niezadeklarowane w katalogu biblioteki standardowej, dlatego są wyświetlane jawnie obok materiału, który taki nie jest:

- credentials (feature.test/db-credential)
values.secretName: db-creds [explicit]
values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]

Nic nie jest wnioskowane z nazwy pola: pole o nazwie password bez deklaracji wyświetla swoją wartość, a zadeklarowane pole o nazwie key — nie. Redakcja obejmuje to, co wyświetla narzędzie; nigdy nie dotyczy wyrenderowanego artefaktu, a dist/ jest emitowany dokładnie w takiej postaci, w jakiej utworzyło go renderowanie. Słowo kluczowe i pełny zakres tego, co daje jego zadeklarowanie, opisano w vocabulary/compact-form-authoring.md w sekcji „Declaring a leaf sensitive”.

Wyświetlanie wstrzymanych wartości

--unredacted wyświetla wartości zadeklarowane jako wrażliwe zamiast je wstrzymywać, jednocześnie we wszystkich widokach inspect — zarówno w opisanych wyżej czytelnych układach, jak i w skompilowanym grafie encji Release. Opcja istnieje, ponieważ wstrzymana wartość bywa właśnie tą, którą się bada: poświadczenie pochodzące z niewłaściwego dołączenia wygląda identycznie jak właściwe, gdy oba są wyświetlane jako wstrzymane.

Jej zasięg ogranicza się do polecenia, któremu ją przekazano. aggrega build i aggrega validate również ją przyjmują, przy czym obejmuje ona tylko graf zwracany przez --ir-graph i nic więcej, a polecenia te odrzucają ją, gdy nie zażądano grafu. aggrega build --trace-unredacted realizuje tę samą ideę dla plików śledzenia kompilacji, a żadna z dwóch flag kompilacji nie wpływa na dane wyjściowe drugiej; żadna z nich nie wpływa na wyrenderowany artefakt w dist/, ponieważ jest on emitowany dokładnie w takiej postaci, w jakiej utworzyło go renderowanie, niezależnie od przekazanych flag.

Wszystko, do czego trafiają wtedy dane wyjściowe, zawiera te wartości jawnie — terminal, potok, plik, nagranie ekranu, wklejone zgłoszenie błędu. W przeciwieństwie do plików śledzenia, z których każdy zaczyna się nagłówkiem informującym, że został zapisany bez redakcji, dane wyjściowe w terminalu nie mają takiego oznaczenia: tylko wiersz polecenia świadczy o tym, że flagę przekazano.

Kiedy sięgać po inspect

  • Debugowanie „skąd tu się wziął ten Feature?” — dołączenia wynikające z adnotacji są niewidoczne w plikach YAML encji Aggregate i Release (adnotacje tam są, ale syntetyzowane przez nie dołączenia Feature istnieją tylko w IR). Inspect pokazuje je wraz z pochodzeniem.
  • Weryfikacja dziedziczenia schematów — aggrega inspect <ComponentName> pokazuje scalony schemat po rozwiązaniu łańcucha extends:; sam napisany plik pokazuje tylko lokalną różnicę.
  • Diagnozowanie niespodzianek przy kompozycji między stronami — gdy adnotacja encji Aggregate i adnotacja encji Release dostarczają ładunki filarów dla tego samego Feature, rozwiązane liście mogą być trudne do odtworzenia w myślach. Forma nawiasów dla każdego liścia czyni rozwiązanie jawnym.
  • Kontrola przed wdrożeniem — aggrega inspect ./prod-release.yaml wyświetla każdy Feature w każdej encji Component, zanim aggrega build wygeneruje artefakty; operator może potwierdzić, że topologia odpowiada zamierzeniom, zanim zatwierdzi wyrenderowane manifesty w GitOps.

Mechanizmy leżące u podstaw — jak adnotacje kaskadują, jak podział strona/filar kieruje wartości adnotacji do filarów Feature i jak zasada pierwszeństwa jawnego dołączenia współdziała z wkładami wynikającymi z adnotacji — opisano w providers/well-known-annotations.md oraz entities/manifest.md „Annotation-Driven Feature Bindings”.

Składnia

aggrega inspect [identifier] [flags]

Opis

Render a readable view of any Aggrega entity — a catalog entity by name, an
authored entity file by path, an entity published in a registry, or a
fully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extend
which bases, which Recipe maps to each type, which Features attach to each node,
and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../
or /, or ending in .yaml or .yml — is read as a file and inspected by its own
kind: header. A registry reference — oci://<host>/<repository>:<tag>, or
@<digest> in place of :<tag> — is read from the registry that publishes it.
Anything else is looked up by name in the catalog search stack: the
workspace's own, or, with --release, the one the workspace configuration
gives that Release, so a name several catalog variants declare, one per
Release, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpacked
from the archive its kind is published as where it is one, and rendered by the
same view a file of that kind gets. Reading it reaches the network, using the
credentials this machine holds for that registry, and an offline workspace
refuses it. The fetched bytes are checked against the digest the artifact's
own manifest records for them, which establishes that they are the bytes that
manifest names and nothing more: no signature attached to the artifact is
verified, no withdrawal recorded against it is reported, and nothing is
written — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, the
default for a structured overview, and --detail for full field bodies. --list
and --detail are mutually exclusive. Resolution depth has its own pair, --raw
for the entity exactly as authored and --resolved for the kind's full depth,
also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declared
sensitive appears as authored. That is what as-authored means; handle such
output as you would the entity file itself. --output yaml reproduces the file
the same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag because
neither answer contains the other. --ir-graph asks for the IR graph a Release
resolves to — what the Release looks like, as JSON on stdout in addition to
whatever else this command produces. --closure asks for the Release's dependency
closure — every catalog entity it reaches and the version each resolved to,
which is what was pulled in to build the Release. An entity can be reached
without appearing as a node, and a node does not carry the version its type
resolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command's
own view. Values an author declared sensitive are withheld from the graph, as
they are from the readable layouts. Pass --unredacted to print them instead.

Flagi

FlagaDomyślnieOpis
--catalog[]Katalog z katalogiem encji; można podać wielokrotnie. Każde —catalog <dir> jest dodawane na początek stosu wyszukiwania katalogów (wygrywa pierwsze dopasowanie): catalog_dirs obszaru roboczego lub — dla encji Release, której konfiguracja obszaru roboczego nadaje własne katalogi w workspace.releases — katalogi tej encji Release; stos kończy się katalogiem o nazwie catalog w katalogu głównym obszaru roboczego, jeśli taki istnieje. Lista catalog_dirs zapisana jako pusta oznacza, że żaden lokalny katalog nie jest odczytywany.
--closurefalseZamiast widoku rozwiązanych węzłów raportuje domknięcie zależności encji Release — każdą osiąganą encję katalogu w wersji, do której została rozwiązana. Dotyczy encji Release, jedynego rodzaju, który rozwiązuje domknięcie; każdy inny rodzaj odrzuca żądanie zamiast po cichu je pomijać.
--colorautoKolorowanie wyjścia: auto|always|never.
--detailfalseRenderuje pełne treści pól.
--flatfalseRenderuje encję o strukturze drzewa (Aggregate, Release) jako płaską listę, w której każdy węzeł poprzedza jego pełna ścieżka z kropkami. Nie ma wpływu na rodzaje tabelaryczne.
--ir-graphfalseDodatkowo zapisuje na stdout, jako JSON, graf IR obliczony w tym uruchomieniu, oprócz wszystkiego, co to polecenie już generuje. Wartości zadeklarowane przez autora jako wrażliwe są w nim wstrzymywane; aby je wyświetlić, należy podać —unredacted. Dotyczy encji Release, jedynego rodzaju rozwiązywanego do grafu; każdy inny rodzaj odrzuca żądanie zamiast po cichu je pomijać
--listfalseRenderuje wyłącznie identyfikatory.
--no-colorfalseWyłącza kolorowanie wyjścia (alias dla —color=never).
--output, -otextFormat wyjścia: text|yaml.
--plugin—Ścieżka w systemie plików do surowego artefaktu <file.wasm>; wyznacza i wyświetla importowane przez niego funkcje hosta, zanim aggrega plugin sync zapisze je w encji Plugin. Nie przyjmuje argumentu identyfikatora.
--rawfalseRenderuje encję w postaci napisanej, bez rozwiązywania.
--release—Wyszukuje nazwę z katalogu na warunkach tego pliku Release: w katalogach, które konfiguracja obszaru roboczego nadaje tej encji Release, z dodanymi na początku —catalog. Dotyczy nazwy; plik lub odwołanie do rejestru jest inspekcjonowane w obecnej postaci i odrzuca tę flagę. Ścieżka względna jest rozwiązywana względem katalogu, w którym uruchamia się polecenie, a nie względem katalogu głównego obszaru roboczego. Gdy ten katalog nie należy do żadnego obszaru roboczego i nie wskazano katalogu głównego, ścieżka bezwzględna znajduje obszar roboczy na podstawie własnego folderu encji Release
--resolvedfalseRenderuje encję w pełni rozwiązaną.
--show-implementsfalseDla encji Recipe lub FeatureRecipe rozwiązuje spec.implements względem katalogu i renderuje powiązany Component lub Feature.
--unredactedfalseWyświetla wartości zadeklarowane przez autora jako wrażliwe zamiast je wstrzymywać. Wszystko, do czego trafia wyjście — terminal, potok, plik, nagranie ekranu — zawiera wtedy te wartości jawnym tekstem.