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 build

aggrega build kompiluje parę encji Aggregate + Release do artefaktów natywnych dla dostawców (manifesty Helm, redystrybuowalne charty Helm, YAML dla docker-compose) w katalogu dist/ w katalogu głównym obszaru roboczego, jak opisano w sekcji Dane wyjściowe. Encja Release jest jedynym punktem wejścia: wskazuje encje Aggregate i Manifest, deklaruje granice i kieruje komponenty do dostawców.

Typowe flagi

Dwie flagi mają zachowanie, którego poniższy opis flag nie jest w stanie sam oddać:

  • --catalog <dir> — katalog zawierający encje katalogu — rodzaje autorskie Component, Feature, Recipe i FeatureRecipe wraz z rodzajami bibliotek, Aggregates i Plugins — wczytywany rekurencyjnie. Każdy katalog --catalog jest przeszukiwany przed katalogami skonfigurowanymi, w podanej kolejności. Aby przeszukać katalog lokalny projektu obok współdzielonego, należy przekazać oba (--catalog ./catalog --catalog ../shared-catalog) lub wymienić je w catalog_dirs. Z flagą --detail każda encja przesłonięta przez katalog o wyższym priorytecie jest zgłaszana na stderr wraz z pozostałymi ostrzeżeniami kompilacji. Katalog --catalog, który nie istnieje, zatrzymuje kompilację, a komunikat podaje jego nazwę. Tak samo dzieje się z katalogiem wymienionym w catalog_dirs, który nie jest katalogiem: kompilacja zatrzymuje się, zanim cokolwiek zostanie odczytane lub zapisane, a komunikat podaje ten wpis oraz plik konfiguracyjny i wiersz, w którym go wymieniono — zob. Skąd wczytywane są encje lokalne. Kompilacja zatrzymana dlatego, że odwołanie nie rozwiązało się do niczego, wymienia w notatce pod komunikatem o zatrzymaniu każdy plik w tych katalogach, który deklaruje apiVersion Aggrega — wiersz zaczynający się bez wcięcia od apiVersion: z wartością rozpoczynającą się od aggrega.ai/ — i nie mógł zostać wczytany, na przykład taki, który nie parsuje się jako YAML, wraz z powodem podanym przez sam parser, wśród plików katalogu pominiętych przy wczytywaniu; plik YAML deklarujący inną apiVersion albo żadnej nie jest dokumentem Aggrega i nigdy nie jest tam wymieniany.
  • --detail — raportuje, co zrobił krok pull, czyli tę samą przejściową diagnostykę zdarzeń pull, którą emituje aggrega pull --detail. O tym, czy jest cokolwiek do zgłoszenia, decyduje to, czy krok pull został zażądany — przez --auto-pull lub przez włączenie auto_pull — a nie to, czy plik blokady już istnieje: zażądany krok pull uruchamia się w obu przypadkach, wypełniając brakujący plik blokady i respektując przypięcia w istniejącym. Gdy żaden krok pull nie jest uruchamiany, flaga wypisuje jednowierszową uwagę na stdout i kontynuuje — nigdy nie fabrykuje poziomu rozwiązania, którego zatwierdzony plik blokady nie zawiera. Aby poznać stan rozwiązania zależności encji Release po kroku pull, należy użyć aggrega inspect.

--dry-run opisano w sekcji Podgląd kompilacji bez jej zapisywania, a --trace i --trace-unredacted w sekcjach Wyjście śledzenia i Wyświetlanie ukrytych wartości poniżej.

Wypełnianie pliku blokady w ramach kompilacji

Domyślnie kompilacja tylko odczytuje zależności: wymaga pliku blokady i żadnego nie zapisuje. --auto-pull oraz ustawienie obszaru roboczego auto_pull dodają do kompilacji krok pobierania, dzięki czemu jedno polecenie rozwiązuje zależności encji Release i kompiluje względem tego, co rozwiązało.

Plik blokady wykrywa zmianę w encji Release. Plik blokady zapisuje encję Release — oraz każdą encję Release, którą ona rozszerza — za pomocą skrótu jej zawartości, więc kompilacja tylko do odczytu na encji Release zmienionej od czasu pobrania zatrzymuje się, zanim cokolwiek zostanie wyrenderowane, podając nazwę pliku i wskazując, że należy uruchomić aggrega pull --release <release>, co zapisuje zmianę, honorując wszystkie pozostałe przypięcia. Liczy się także zmiana komentarza lub białych znaków, ponieważ skrót obejmuje bajty w ich dokładnej postaci. Kompilacja z automatycznym pobieraniem sama wykonuje ten krok pobierania, więc zapisuje zmianę i kompiluje.

Encja Release jest renderowana raz. To, jakie dane zewnętrzne zużywa encja Release, wynika z jej wyrenderowania, a nie z czegokolwiek, co deklarują jej dokumenty, więc krok pobierania renderuje encję Release, aby to ustalić — i ten render jest renderem kompilacji. Kompilacja z automatycznym pobieraniem kosztuje zatem jeden render, tyle samo co zwykła kompilacja z już istniejącym plikiem blokady.

Flagi kształtujące render mają do niego zastosowanie. --trace, --verify-determinism, --disable-plugin-cache i --no-unsupported-field-warnings działają na render wykonywany przez kompilację z automatycznym pobieraniem na tych samych zasadach co na render zwykłej kompilacji, więc zażądanie śladu lub sprawdzenia determinizmu w kompilacji jednym poleceniem daje ten wynik. Wyjątkiem jest --dry-run, i jest to odmowa, a nie przemilczenie: przebieg próbny niczego nie zapisuje, podczas gdy krok pobierania zapisuje, więc takie połączenie zatrzymuje się przed rozpoczęciem jakiejkolwiek pracy (zob. Podgląd kompilacji bez jej zapisywania).

Jak kompilacja odczytuje to, co przypina plik blokady

Przypięcie w pliku blokady wskazuje treść — skrót (digest) — a nie miejsce. W przypadku encji jest to skrót tego, co zawiera jej publikacja, czyli jej dokumentu i plików, które on wskazuje, dlatego kopia encji w katalogu i wpis w pamięci podręcznej zawierający jej publikację mają to samo przypięcie, jak opisuje Plik blokady. Kompilacja odczytuje każdą przypiętą zależność ze źródeł dostępnych już na maszynie: najpierw z katalogów, jak wszędzie indziej, a następnie z pamięci podręcznej treści w .aggrega/cache. Ich odczyt nie odpytuje żadnego rejestru; pobiera wyłącznie krok pull, jeśli kompilacja go wykonuje.

Wpis w pamięci podręcznej, który nie zawiera już swojego przypięcia, jest pomijany. Encja edytowana w miejscu — nowa treść pod tą samą wartością version — pozostawia w pamięci podręcznej treści wcześniejszą treść pod tą nazwą i wersją. Jeśli katalog zawiera kopię, której skrót treści odpowiada przypięciu, kompilacja odczytuje tę kopię i nigdy nie odczytuje wpisu, informując o tym na standardowym wyjściu błędów i podając wpis oraz oba skróty:

reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes

Jeśli żaden katalog nie zawiera encji, kompletny wpis w pamięci podręcznej zawierający dokładnie przypięte bajty jest odczytywany jako zależność, dzięki czemu encja usunięta ze swojego katalogu po pobraniu jej opublikowanej kopii nadal kompiluje się z tej kopii.

Jeśli żadne źródło nie zawiera przypiętych bajtów, kompilacja zatrzymuje się, zanim cokolwiek zostanie wyrenderowane, z błędem E0135 — lub E0133, jeśli manifest wpisu w pamięci podręcznej nie jest tym, który przypina plik blokady. Komunikat zatrzymania podaje przypięcie, wpis w pamięci podręcznej i zawarty w nim skrót oraz każdą kopię encji w katalogu wraz z jej skrótem albo informację, że żaden katalog jej nie zawiera. Rozwiązaniem jest wykonanie pull przy dostępnym rejestrze, który ponownie pobiera przypiętą wersję i sprawdza pobraną treść względem przypięcia; w sekcji Honorowanie a aktualizacja opisano, co robi pull, gdy rejestr nie udostępnia już tych bajtów.

Renderowanie, które aggrega pull wykonuje w celu wykrycia wejść zewnętrznych, oraz kompilacja lub podgląd przez aggrega serve lub aggrega mcp odczytują swoje przypięcia w ten sam sposób.

Zewnętrzne dane wejściowe w czasie kompilacji

Renderowanie może zażądać treści spod zdalnego adresu URL — na przykład schematu wartości wykresu ze zdalnym odwołaniem — a kompilacja nigdy jej nie pobiera po to, by dodać ją do tego, co renderowanie może odczytać. Żądanie adresu URL, który plik blokady już przypina, jest obsługiwane z magazynu danych wejściowych obszaru roboczego i weryfikowane względem zapisanego skrótu, zanim jakikolwiek bajt trafi do renderowania. Żądanie nieprzypiętego adresu URL zatrzymuje kompilację, wskazując ten adres URL oraz krok, który go przypina; nie ma ustawienia, które zamieniałoby to zatrzymanie w pobranie, ponieważ ciche poszerzanie zbioru danych wejściowych odczytywanych przez kompilację jest właśnie tym, czego odtwarzalna kompilacja robić nie może.

Jeśli kopia przypiętych danych wejściowych zniknęła z magazynu, tylko te jedne dane wejściowe są pobierane ponownie według skrótu, który plik blokady już zapisuje, i sprawdzane względem niego, zanim cokolwiek zostanie zapisane lub zwrócone. Nie może to zmienić tego, co widzi renderowanie — skrót został ustalony w chwili przypięcia danych wejściowych — więc naprawia to magazyn, a nie rozszerza domknięcia, a plik blokady pozostaje niezmieniony co do bajtu. W trybie offline nie ma transportu nawet do tego, więc brakująca kopia zamiast tego zatrzymuje kompilację, wskazując ten tryb.

Przypinanie następuje podczas rozwiązywania zależności encji Release, więc to, co kompilacja może odczytać, jest ustalone przed jej rozpoczęciem. aggrega pull jest tym krokiem i jest to jedyny taki krok.

Rejestr zaufania do pluginów

Kilka zachowań kompilacji zależy od plugins-trust.yaml, zatwierdzonego w repozytorium pliku obok pliku blokady encji Release, który zapisuje, do jakiego pluginu rozwiązało się każde dołączenie zwracające werdykt — dołączenie plugins.governance w roli ir-verdict lub render-verdict oraz każde dołączenie plugins.linter. Zapisuje go aggrega pull, a jego pola opisuje schemat rejestru zaufania do pluginów; poniżej opisano wyłącznie to, co robi z nim sama kompilacja.

Kompilacja jest sprawdzana względem rejestru, zanim uruchomi się którykolwiek z tych pluginów. Plugin dostarczony z pamięci podręcznej, którego skrót artefaktu nie jest skrótem zapisanym, zostaje odrzucony zamiast uruchomiony — tak zwykle rozwiązuje się takie dołączenie, a aggrega pull opisuje, których innych sposobów rozwiązania zapisany skrót nie obejmuje. Ponadto zapisany wpis, któremu nie odpowiada już żadne dołączenie w .aggrega-config.yaml, zatrzymuje kompilację: usunięcie bramki nie zmienia żadnego wyrenderowanego bajtu, więc wynik wytworzony bez sprawdzonej bramki wygląda dokładnie tak samo jak wynik przez nią zatwierdzony. Komunikat zatrzymania podaje nazwę pluginu i proponuje dwa rozwiązania zależne od zamiaru — ponowne dołączenie pluginu, jeśli jego usunięcie było pomyłką, albo jawne zażądanie usunięcia, jeśli nie było — i wypisuje gotowe do uruchomienia polecenie. Dołączenie, którego rejestr jeszcze nie zawiera, jest widziane po raz pierwszy i żadne z tych porównań nie zatrzymuje się na nim.

Kompilacja sprawdza każdy z tych pluginów względem podpisu zapisanego w jego wpisie, dokładnie tak, jak sprawdza wpis pliku blokady względem tego, co ten wpis zapisuje. Gdy wpis zapisuje zweryfikowany signature, kompilacja przed jakimkolwiek renderowaniem ponownie oblicza skrót pakietu podpisu, który ten fakt wskazuje w pamięci podręcznej, i zatrzymuje się z E0144, jeśli pakietu brakuje lub się różni. W przypadku pluginu odczytywanego z pamięci podręcznej treści kompilacja odczytuje też z tego pakietu, dla którego artefaktu złożono podpis, i zatrzymuje się z E0332, jeśli złożono go dla innego pluginu niż ten, który kompilacja odczytała — tak wygląda signature skopiowany z innego wpisu — niezależnie od tego, co mówi wymóg podpisu. W przypadku pluginu dostarczonego z pamięci podręcznej treści każda z tych odmów wskazuje aggrega pull --release <release>: następne pobranie ponownie weryfikuje podpis pluginu, zapisuje własny podpis pluginu i umieszcza w pamięci podręcznej wskazany przez niego pakiet, nadpisując zbuforowaną kopię, która nie odpowiada już swojemu skrótowi. Gdy konfiguracja zaufania obszaru roboczego wymaga podpisu dla pluginu odczytywanego przez kompilację z pamięci podręcznej treści — przy tych samych ustawieniach, przy których aggrega pull odrzuciłoby go jako niepodpisany, więc skip_signature_verification i rejestr advisory pozwalają kompilacji kontynuować tak samo, jak pozwalają pobraniu — wpis niezapisujący podpisu lub całkowity brak wpisu dla pluginu zatrzymuje kompilację z E0331, podając nazwę pluginu, plugins-trust.yaml oraz ustawienia wymagające podpisu. Rozwiązaniem jest aggrega pull --release <release>, które przy każdym uruchomieniu weryfikuje podpis pluginu w jego rejestrze i go zapisuje. Plugin dostarczony z jednego z własnych katalogów albo z kopii wbudowanej w plik binarny kompilatora nigdy nie podlega temu wymogowi. Podobnie jak reszta kompilacji, ten krok odczytuje pliki już obecne na maszynie i o nic nie pyta żadnego rejestru.

Kompilacja wymienia każde wycofanie zapisane w rejestrze, obok każdego zapisanego w pliku blokady. Znacznik, który aggrega pull zapisał dla jednego z tych pluginów, jest zgłaszany jako wiersz deprecation: podający plugin, zapisany poziom i komunikat wydawcy, przy każdym poziomie, a build.halt_on_deprecated_severity decyduje, czy dodatkowo zatrzymuje on kompilację, według tej samej reguły, którą stosuje do przypiętego odwołania. Każda inna powierzchnia raportująca o encji Release wymienia ten sam zbiór tymi samymi słowami i żadna z nich się na nim nie zatrzymuje: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, odpowiedź serwera językowego dotycząca walidacji i domknięcia oraz describe i validate narzędzi asystenta. Rejestr, który istnieje, ale nie da się go odczytać, zatrzymuje kompilację, zamiast przejść jako rejestr, który niczego nie zapisuje.

aggrega build --upgrade nadpisuje ten plik. Implikuje --auto-pull i wykonuje gołe pełne odświeżenie, które ponownie rozwiązuje każdą zależność, a zatem ponownie rozwiązuje i nadpisuje każdą zapisaną tożsamość oraz usuwa każdy wpis, któremu nie odpowiada żadne dołączenie. Jeśli więc ten plik okaże się zmodyfikowany po kompilacji z aktualizacją, właśnie dlatego: zasięg flagi obejmuje każdą zależność, a zapisane tożsamości należą do tego, co jest ponownie rozwiązywane, choć nie są przypięciami pliku blokady. W odróżnieniu od aggrega pull --upgrade flaga kompilacji nie przyjmuje celu, więc nie można jej zawęzić do jednego pluginu: aby przyjąć lub usunąć pojedynczą tożsamość, należy zamiast tego uruchomić aggrega pull --upgrade --release <release> <plugin>, które pozostawia nietknięte wszystkie inne przypięcia i wszystkie inne zapisane tożsamości.

Ponieważ jej zasięg obejmuje wszystko, przed rozpoczęciem prosi o potwierdzenie. aggrega build --upgrade potwierdza odświeżenie na tych samych zasadach co gołe aggrega pull --upgrade — to ta sama czynność, więc zadają to samo pytanie. Aby odpowiedzieć z góry w użyciu nieinteraktywnym, należy przekazać --yes; gdy standardowe wejście nie jest terminalem i brak --yes, kompilacja odmawia, zamiast czekać na odpowiedź, której nikt nie może udzielić. Kompilacja, która nie odświeża, o nic nie pyta.

Rozwiązywanie obszaru roboczego i determinizm

Wymagane przez schemat odwołanie manifest: encji Release jest rozwiązywane względem pliku encji Release. Względny wpis catalog_dirs (oraz względna ścieżka wtyczki w systemie plików) jest rozwiązywany względem katalogu pliku .aggrega-config.yaml, który go zadeklarował — „względny” zawsze oznacza względny wobec pliku, w którym go zapisano, więc ścieżka oznacza to samo niezależnie od tego, skąd wywoływany jest aggrega. Flaga --catalog, która nie ma pliku deklarującego, jest rozwiązywana względem bieżącego katalogu roboczego. Odwołania do rejestrów (oci://…, odwołanie do huba) pozostają bez zmian.

Katalogiem głównym obszaru roboczego jest katalog najbliższego nadrzędnego pliku .aggrega-config.yaml zawierającego blok workspace: albo katalog wskazany przez --workspace-root. Gdy katalog główny jest w ten sposób ustalony, kompilacja jest niezależna od miejsca wywołania: uruchomienie aggrega build z katalogu głównego projektu i z podkatalogu daje identyczne co do bajtu IR i wyrenderowane artefakty, ponieważ przeszukiwany katalog i ścieżki źródłowe zapisane w wyniku nie zmieniają się wraz z katalogiem roboczym. (Bez znacznika workspace: i bez --workspace-root katalogiem głównym jest katalog roboczy, więc wynik jest zakotwiczony tam — chyba że katalog roboczy niczego nie zakotwicza, a --release wskazuje encję Release ścieżką bezwzględną: katalog główny jest wtedy wykrywany ponownie od folderu samej encji Release, więc przeszukiwany katalog i ścieżki zapisane w wyniku należą do projektu, do którego należy encja Release, niezależnie od tego, skąd uruchamia się polecenie. Zob. configuration.md.) Jeśli i w ten sposób nie zostanie znaleziony żaden obszar roboczy, a nic go nie wskazuje, kompilacja ostrzega na standardowym wyjściu błędów, że folder użyty jako katalog główny nie leży w żadnym obszarze roboczym, i podaje polecenie, które czyni go obszarem roboczym; kompilacja, od której zażądano wcześniejszego rozwiązania zależności, jest odrzucana, zanim cokolwiek zostanie pobrane, ponieważ pamięć podręczna wypełniana przez to rozwiązywanie zostałaby zapisana w tym folderze i uczyniłaby go obszarem roboczym. Kompilacja, która niczego wcześniej nie rozwiązuje, nadal renderuje, ale z tego samego powodu zewnętrzne wejście przypięte w pliku blokady, którego pamięć podręczna już nie przechowuje, nie jest pobierane ponownie: wtyczka, która o nie prosi, otrzymuje w jego miejsce zdanie z odmową, tak jak otrzymuje zdanie trybu offline, a kompilacja zgłasza, co ta wtyczka z nim zrobi. --workspace-root lub AGGREGA_WORKSPACE_ROOT wskazujące nieistniejący folder jest odrzucane, zanim kompilacja zrobi cokolwiek innego, z podaniem, które z nich go dostarczyło.

Zmienne środowiskowe

Ustawienia obszaru roboczego odczytywane przez build można nadpisać przez środowisko, z pierwszeństwem przed zatwierdzoną konfiguracją, ale po każdej fladze: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (lista ścieżek rozdzielona separatorem systemu operacyjnego; należy podawać ścieżki bezwzględne), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY oraz AGGREGA_WORKSPACE_ROOT. Pełna lista i model pierwszeństwa znajdują się w environment-variables.md.

Wynik

Wyrenderowane artefakty trafiają do dist/ pod katalogiem głównym obszaru roboczego, niezależnie od folderu, z którego uruchomiono polecenie — samego katalogu głównego, folderu pod nim lub folderu w innym miejscu, gdy katalog główny wskazano przez --workspace-root lub AGGREGA_WORKSPACE_ROOT — a wiersz końcowy podaje pełną ścieżkę tego katalogu:

Build completed: 4 files written to <workspace>/dist

<workspace> oznacza tu katalog główny obszaru roboczego, który wiersz podaje jako pełną ścieżkę. Jeśli nie znaleziono obszaru roboczego i nic go nie wskazuje, katalogiem głównym jest folder, z którego uruchomiono polecenie, więc dist/ jest zapisywany tam. dist będący dowiązaniem prowadzącym poza obszar roboczy jest odrzucany, zanim cokolwiek zostanie w nim usunięte lub zapisane. Encja Release, która nie deklaruje granic, zapisuje wynik osobno dla każdego dostawcy: dist/<provider>/<files>. Zadeklarowana granica bez directory: zapisuje wynik osobno dla każdej granicy i każdego dostawcy: dist/boundaries/<boundary-path>/<provider>/<files>. Nadpisania directory: i subDirectory: zdefiniowane przez operatora na granicach encji Release zmieniają ścieżkę docelową; scalanie według (path, provider) łączy współtwórców, którzy rozwiązują się do tej samej obliczonej ścieżki.

Pliki, których kompilacja nie zapisała

Kompilacja zapisuje własne pliki i nie usuwa niczego, czego sama nie zapisała, z jednym wyjątkiem: dist/boundaries/, który kompilacja generuje w całości od nowa, jest czyszczony przed zapisem, więc plik pozostawiony tam przez kompilację innego wariantu nie przetrwa w drzewie, które już go nie wytwarza. Wszystko inne w dist/ pozostaje bez zmian — zarówno plik zapisany przez wcześniejszą kompilację, którego obecna już nie wytwarza, jak i plik umieszczony tam przez directory: granicy podczas wcześniejszego przebiegu, a także plik umieszczony tam samodzielnie — ponieważ kompilacja nie potrafi odróżnić pozostałości od pliku przechowywanego tam celowo.

Zamiast tego kompilacja o tym informuje. Po zapisaniu swoich plików kompilacja przegląda sam dist/ oraz każdy katalog pod nim, do którego zapisała plik lub przez który przeszła, aby zapisać plik głębiej, i wymienia każdy znajdujący się tam plik, którego nie zapisała w tym przebiegu, w jednym ostrzeżeniu na standardowym wyjściu błędów. Pliki są wymieniane według ścieżek względnych wobec dist/, posortowanych, więc to samo drzewo jest zgłaszane w ten sam sposób przy każdym przebiegu:

warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"

Wiersz końcowy następnie je zlicza:

Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write

Katalog, do którego kompilacja niczego nie zapisała ani pod którym niczego nie zapisała, nie jest przeglądany, więc własny folder przechowywany pod dist/ nie jest wymieniany plik po pliku. Kompilacja, która nie znajdzie żadnego takiego pliku, nie wypisuje ostrzeżenia, a jej wiersz końcowy jest taki, jak pokazano w sekcji Wyjście. W obu przypadkach pliki zapisywane przez kompilację to te same bajty. Aby porównać dwie kompilacje lub zacząć od zera, należy usunąć dist/ przed kompilacją.

Żądanie aggrega/build w aggrega serve oraz narzędzie build asystenta (aggrega mcp) zapisują przez ten sam krok, więc wymieniają te same pliki w tym samym zdaniu: demon jako jedno z notices swojej odpowiedzi, a narzędzie jako ostatnie ze swoich advisories. Przebieg próbny niczego nie zapisuje, więc nie zgłasza niczego z tego.

Wcięcia YAML

Każdy wyrenderowany artefakt YAML — pliki docker-compose, szablony i wartości chartów Helm oraz manifesty Kubernetes — jest emitowany z jednolitą szerokością wcięcia. Szerokość ustawia build.yaml_indent w .aggrega-config.yaml, a jej wartość domyślna to 2 (szerokość zgodna z konwencją dla tych formatów):

build:
yaml_indent: 2 # default; accepts 2 through 9

Szerokość jest stosowana w jednym punkcie serializacji wspólnym dla wszystkich rendererów, więc wynik pozostaje identyczny co do bajtu między uruchomieniami dla tych samych danych wejściowych. Wartości spoza zakresu [2, 9] są odrzucane przez walidację schematu konfiguracji.

Zwracanie skompilowanego grafu

--ir-graph zapisuje graf, do którego rozwiązała się ta kompilacja, na standardowe wyjście w formacie JSON. Działa addytywnie: artefakty nadal są zapisywane do dist/, podsumowanie nadal jest wypisywane, a wyrenderowane bajty pozostają bez zmian. Graf trafia na wyjście przed wszystkim innym, co kompilacja tam wypisuje — jeden dokument JSON i jeden końcowy znak nowego wiersza — więc odbiorca dekodujący strumień odczytuje go i kończy.

Zwracany graf to ten, który wykorzystało renderowanie, więc opisuje dokładnie kompilację, która wytworzyła towarzyszące mu artefakty, a nie drugie rozwiązanie tej samej encji Release. Można go łączyć z --dry-run: graf zostaje wypisany, a po nim raport artefaktów, przy czym nic nie jest zapisywane na dysku.

Wartości, które autor zadeklarował jako wrażliwe, są w nim ukrywane — w tym values i infra połączenia, gdy gniazdo komponentu konsumującego deklaruje liść jako wrażliwy — w ustrukturyzowanej postaci opisanej w aggrega inspect. --unredacted obok --ir-graph wypisuje je zamiast tego, na warunkach określonych przez aggrega inspect --unredacted: dotyczy to wyłącznie grafu — pliki śladu mają własną flagę --trace-unredacted, a wyrenderowane artefakty nigdy nie są ukrywane — i wszystko, do czego trafia wynik, zawiera wtedy te wartości jawnym tekstem. Flaga przekazana bez --ir-graph jest odrzucana, ponieważ nie byłoby nic do ujawnienia.

Ta sama flaga, o tym samym znaczeniu, jest dostępna w aggrega inspect i aggrega validate.

Podgląd kompilacji bez jej zapisywania

--dry-run wykonuje tę samą kompilację co zwykłe budowanie — te same bramki zależności, to samo renderowanie, tych samych dostawców — i wypisuje to, co zostałoby wygenerowane, zamiast to zapisywać. Każdy artefakt jest raportowany wraz ze ścieżką, którą by zajął, i treścią, którą by zawierał:

aggrega build --release releases/production.yaml --dry-run
==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==
apiVersion: v1
kind: ConfigMap
...
Total build time: 2.5s
Dry run: 1 file would be written to <workspace>/dist; nothing was written

Artefakty są raportowane w kolejności, w jakiej zapisuje je budowanie, więc te same dane wejściowe dają te same bajty w tej samej kolejności, a raportowana ścieżka jest ścieżką, pod którą zapisałoby je budowanie — pod katalogiem głównym obszaru roboczego, podaną w całości tam, gdzie powyżej stoi <workspace>.

Co nie jest zapisywane. Katalog wyjściowy pozostaje dokładnie w obecnym stanie — nie jest też czyszczony, więc wynik poprzedniego budowania przetrwa przebieg próbny nienaruszony. Plik blokady nie jest zapisywany. Nic nie jest zapisywane w .trace/.

Zewnętrzne dane wejściowe zachowują się dokładnie tak samo jak przy zwykłym budowaniu, na zasadach opisanych w sekcji Zewnętrzne dane wejściowe podczas budowania. Przebieg próbny odczytuje więc to samo przypięte domknięcie, które odczytałoby zastępowane przez niego budowanie, a to, co pokazuje, jest tym, co to budowanie by zapisało.

Jeśli odwołanie zostało odrzucone, przebieg wymienia każde, do którego nie mógł dotrzeć, i wskazuje polecenie, które je przypina:

note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit:
- https://charts.example.com/values-schema.json
Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run again

Wystarczy raz uruchomić aggrega pull, aby przebieg próbny miał wszystko, czego potrzebuje; nic innego się w nim nie zmienia.

Przebieg próbny wymaga pliku blokady i nigdy go nie wypełnia. Budowanie jest domyślnie tylko do odczytu, a przebieg próbny trzyma się tego niezależnie od tego, w jaki sposób zażądano wypełnienia. --auto-pull i --upgrade są od razu odrzucane (poniżej); ustawienie obszaru roboczego auto_pull jest nadpisywane na to jedno wywołanie, więc obszar roboczy, który domyślnie wypełnia plik blokady, nadal można podejrzeć. Bez pliku blokady przebieg próbny zatrzymuje się z tą samą wskazówką naprawczą, którą daje zwykłe budowanie tylko do odczytu: najpierw należy uruchomić aggrega pull.

Odrzucane flagi. Trzy flagi zapisują, więc łączenie ich z przebiegiem próbnym nie ma uczciwego wyniku — zignorowanie zapisu sprawiłoby, że żądane wypełnienie by zniknęło, a jego wykonanie złamałoby jedyną obietnicę, jaką składa przebieg próbny. Każde takie połączenie zatrzymuje się przed jakąkolwiek pracą, podając przekazaną flagę i krok, który należy wykonać zamiast niej:

W połączeniu zPowód odrzucenia
--auto-pullwypełnia plik blokady; należy uruchomić aggrega pull jako osobny krok
--upgradeponownie rozwiązuje każdą zależność i przepisuje plik blokady; należy uruchomić aggrega pull --upgrade jako osobny krok
--tracezapisuje pliki poszczególnych węzłów w .trace/; należy uruchomić budowanie ze śledzeniem bez --dry-run

Wszystko inne łączy się normalnie. --verify-determinism renderuje każdy węzeł dwukrotnie i porównuje bajty, nie zapisując żadnego z nich, a --catalog, --quiet, --progress, --debug i filtry ostrzeżeń działają dokładnie tak samo jak przy budowaniu, które zapisuje.

Do czego służy, a do czego nie. Przebieg próbny odpowiada na pytanie „co wygenerowałby ten Release”, na które odpowiedzieć może tylko renderowanie — nie zastępuje więc aggrega validate, które sprawdza poprawność bez renderowania, ani aggrega inspect, które odpytuje graf przed renderowaniem. Po przebieg próbny warto sięgnąć, gdy potrzebną odpowiedzią są same artefakty: przy przeglądaniu, jak zmiana encji Release wpływa na wynik, lub przy sprawdzaniu edycji encji Recipe przed zapisaniem czegokolwiek w dist/.

Wyjście śledzenia

Flaga --trace włącza zrzut debugowania dla każdego węzła, rejestrujący każdy pośredni stan kompilatora. Wynik trafia do .trace/ w katalogu głównym obszaru roboczego, obok dist/ (nigdy w nim; układ katalogów równorzędnych jest zgodny z konwencją .git/, .terraform/, node_modules/ i sprawia, że dist/ zawiera wyłącznie to, co jest przeznaczone do wdrożenia).

Układ katalogów jest podzielony według granic i instancji:

.trace/
└── boundaries/
└── <boundary-path>/
└── <instance-id>/
├── 01-pillars-initial.yaml
├── 02-provides-evaluation.yaml
├── 03-inject-hydration.yaml
├── 04-inject-mapping.yaml
├── 05-source-resolution.yaml
├── 06-source-locals.yaml
├── 07-values-mapping.yaml
├── 08-workload-synthesis.yaml
├── 09-artifact-evaluation/
│ └── <per-artifact-file>.yaml
├── 09b-feature-rendering-boundary.yaml
├── 10-engine-synthesis/
│ └── <per-synthesized-file>.yaml
├── 11-engine-emission.log
└── 12-labels-injected.log

Każdy slot rejestruje określony stan kompilatora:

  • 01-pillars-initial.yaml — migawka danego węzła kontekstu odczytywanego przez szablon, wykonana po rozwiązaniu, a przed jakąkolwiek modyfikacją na poszczególnych etapach. Zawiera .values, .infra, .context, .parameters, .metadata.
  • 02-provides-evaluation.yaml — rozwiązane wyjścia provides: po ewaluacji provides.
  • 03-inject-hydration.yaml — scalony potok .context.inject po hydratacji inject (widok po stronie konsumenta na provides z węzłów nadrzędnych).
  • 04-inject-mapping.yaml — potok .context.inject po przepisaniach injectMapping w encji FeatureRecipe.
  • 05-source-resolution.yaml — sparsowana zawartość source:, którą przetworzy provider. Występuje tylko wtedy, gdy encja Recipe deklaruje source:.
  • 06-source-locals.yaml — rozwiązany blok locals:. Rozwiązywanie źródła publikuje .locals przed ewaluacją szablonu source:, dlatego ten slot jest zapisywany niezależnie od tego, czy encja Recipe deklaruje source:.
  • 07-values-mapping.yaml — wyrenderowane wyjście valuesMapping: (słownik, który otrzymuje provider). Występuje tylko wtedy, gdy encja Recipe deklaruje valuesMapping:.
  • 08-workload-synthesis.yaml — kontekst w stanie z chwili, gdy szablon workload: został poddany ewaluacji, a jego wynik sparsowany. Występuje tylko wtedy, gdy encja Recipe deklaruje workload: (inline lub ładowany przez $import:). Sam sparsowany Workload nie znajduje się w tym slocie: pojawia się od 09-artifact-evaluation/ wzwyż, gdy jest już ustalony, a nie w trakcie przetwarzania.
  • 09-artifact-evaluation/ — jeden plik na każdy poddany ewaluacji artefakt. Występuje tylko wtedy, gdy encja Recipe deklaruje artifacts: (z wpisami inline lub ładowanymi przez $import: dla poszczególnych wpisów).
  • 09b-feature-rendering-boundary.yaml — kontekst w chwili zakończenia renderowania węzła, gdy dołączone do niego encje FeatureRecipes wygenerowały już swoje zasoby, z przeanalizowanym workload obok. Zapisywany dla każdego węzła.
  • 10-engine-synthesis/ — jeden plik na każdy syntetyzowany manifest, który provider wytworzył z encji Workload (tryb workload helm/compose). Występuje tylko wtedy, gdy provider wykonał ścieżkę syntezy.
  • 11-engine-emission.log — podsumowanie po emisji (liczba plików, ścieżki wyjściowe) dla danego węzła.
  • 12-labels-injected.log — etykiety i adnotacje pochodzenia zapisane w wyrenderowanym wyjściu dla danego węzła.

Począwszy od 03-inject-hydration.yaml, slot pokazujący kontekst węzła zawiera blok .context.inject zawsze wtedy, gdy przechwytywany przez niego potok dostarcza co najmniej jeden klucz, pod dowolnym mechanizmem: env, file, arg lub mechanizmem o innej nazwie, do którego zapisuje mapowanie inject, injectMapping encji FeatureRecipe albo własny blok inject: komponentu. Węzeł, którego jedynym dostarczaniem jest taki niestandardowy mechanizm, również pokazuje ten blok, z tym mechanizmem pod jego własną nazwą i jego kluczami w all, a wartość zadeklarowana jako wrażliwa ma w obu miejscach postać <redacted>. Slot zapisany w chwili, gdy potok niczego nie dostarcza, nie ma bloku .context.inject.

Zapis śledzenia nie blokuje: śledzenie jest zapisywane na dysk równolegle z kompilacją, a nie na jej ścieżce. Operacje I/O śledzenia nie wpływają na opóźnienie kompilacji — ta sama kompilacja kończy się w tym samym czasie rzeczywistym niezależnie od tego, czy --trace jest włączone, czy wyłączone.

Wartości zadeklarowane jako wrażliwe w śladzie

Dana, którą autor zadeklarował jako wrażliwą — liść schematu z sensitive: true albo klucz dostarczania, którego materiał pochodzi z takiego klucza provides — jest zapisywana w śladzie jako stały tekst <redacted>. Klucz zostaje zachowany, a zastępowana jest tylko wartość, więc slot nadal pokazuje, jakie liście i klucze dostarczania ma węzeł. Niezadeklarowany sąsiedni element w tym samym bloku wypisuje swoją wartość dosłownie; podstawienie wynika z deklaracji i z niczego innego.

Wstrzymywana jest również wartość, którą FeatureRecipe dostarcza przez własne injectMapping. Tę drogę wybiera slot deklarujący pustą listę inject i tę samą drogę obiera realizacja poświadczeń oparta wyłącznie na inject. Klucz dostarczania zapisywany przez takie mapowanie jest sam szablonem, więc żadna deklaracja go nie nazywa; zamiast tego odczytywany jest tekst samego mapowania. Gdy ten tekst odwołuje się do liścia values lub infra, który dołączona encja Feature deklaruje jako sensitive: true, każdy klucz dostarczania wytworzony przez mapowanie ma wartość <redacted> — także klucz, który nie niesie nic wrażliwego, ponieważ odczyt odbywa się per dołączenie, a nie per klucz. Mapowanie, które nie odwołuje się do niczego zadeklarowanego, wypisuje swoje klucze dosłownie.

Wstrzymywana jest też wartość obliczona przez szablon z danej zadeklarowanej jako wrażliwa, mimo że jej własny klucz nie ma deklaracji. Identyfikuje ją odwołanie napisane przez autora: wstrzymywany jest wpis locals:, którego szablon odczytuje liść zadeklarowany jako wrażliwy, i tak samo pole source:, które to robi. Odczyt jest zachowawczy — szablon sięgający całego obiektu sięga każdego zadeklarowanego liścia pod nim, więc {{ range $k, $v := .values.creds }} wstrzymuje swój wynik, gdy cokolwiek pod creds jest zadeklarowane — a wpis locals: odczytujący już wstrzymany sąsiedni wpis jest z kolei również wstrzymywany. Sąsiedni wpis o tym samym kształcie, który nie odczytuje niczego zadeklarowanego, jest wypisywany dosłownie.

Wartość przechodząca przez krawędź uses jest wstrzymywana według deklaracji celu, a nie węzła konsumującego, i jest wstrzymywana na obu powierzchniach, na które krawędź ją przenosi. .context.uses.<alias>.provides odtwarza to, co opublikował komponent docelowy, więc tymi wartościami rządzi schemat celu: klucz provides, który cel zadeklarował jako wrażliwy, ma w slocie konsumenta wartość <redacted>, nawet gdy konsument nie deklaruje niczego. Gdy własny blok inject krawędzi kieruje ten klucz na klucz dostarczania komponentu konsumującego, .context.inject również wstrzymuje ten klucz dostarczania — według tej samej reguły, którą już stosuje mapowanie inject dołączenia, odczytując tę samą deklarację. Wstrzymywanie odbywa się per krawędź, więc dwie krawędzie publikujące klucz provides o tej samej nazwie są rozstrzygane niezależnie: ta, której cel go zadeklarował, jest wstrzymywana, a druga wypisuje się dosłownie. Pozostała część krawędzi — jej cel, gniazdo, etykiety i nazwy kluczy samego mapowania inject — nie podlega deklaracji provides celu i jest wypisywana dosłownie.

Za to values i infra dla danego połączenia, zapisane na samej krawędzi, podlegają gniazdu komponentu konsumującego: valueSchema i infraSchema, które to gniazdo deklaruje i które są kontraktami, względem których ta konfiguracja jest walidowana. Liść, który którykolwiek z kontraktów deklaruje jako sensitive: true, ma postać <redacted> w .context.uses.<alias>.values lub .context.uses.<alias>.infra, z zachowanym kluczem; tak samo liść mający wartość domyślną zadeklarowaną przez kontrakt; niezadeklarowany liść sąsiedni jest wypisywany dosłownie. Deklaracje celu nie odgrywają tu żadnej roli, a wstrzymywanie odbywa się per połączenie, więc liść o tej samej nazwie na połączeniu, którego gniazdo deklaruje go jako czytelny, jest wypisywany dosłownie.

Dołączenia zapisane na połączeniu są pokazywane pod krawędzią tego połączenia, w .context.uses.<alias>.features.<slot>, a każde jest wstrzymywane według deklaracji swojej encji Feature — tych samych, które rządzą tą encją Feature, gdy komponent posiada ją bezpośrednio. Liść values lub infra, który Feature deklaruje jako sensitive: true, ma wartość <redacted>, podobnie jak klucz rozwiązanego provides dołączenia, który Feature deklaruje jako wrażliwy; każdy klucz zostaje zachowany. Typ, wersja i etykiety dołączenia oraz każdy liść i klucz provides, których jego Feature nie deklaruje, są wypisywane dosłownie, więc opublikowany lokalizator pozostaje czytelny obok materiału, który lokalizuje. Wstrzymywanie odbywa się per połączenie i slot, więc ta sama Feature zapisana na dwóch połączeniach jest rozstrzygana na każdym z nich. Slot deklarujący sensitive: true — na komponencie lub na jego gnieździe — oznacza, że dołączenie obsługuje materiał tajny, i sam nie wstrzymuje żadnego liścia: to, które liście są wstrzymywane, deklaruje Feature. Własne dołączenia komponentu nie należą do bloków pokazywanych przez slot, ponieważ ślad nie zawiera bloku .features; to, co szablon workload: z nich odczytuje, obejmuje opisane niżej ponowne renderowanie.

Sparsowany Workload jest ponownym renderowaniem, a nie zapisem dokumentu wyemitowanego przez build, i sloty, które go zawierają — 09-artifact-evaluation/, 10-engine-synthesis/ i 09b-feature-rendering-boundary.yaml — informują o tym we wpisie workload_note obok niego. Wyrenderowany dokument nie zapisuje, z której deklaracji pochodzi dany znak, więc nie ma w nim klucza, pod którym można by dokonać podstawienia. Zamiast tego ślad pokazuje ten sam szablon workload: obliczony drugi raz, względem kontekstu, w którym dane zadeklarowane jako wrażliwe mają już wartość <redacted>. Ponieważ szablon widzi ciąg znaków tam, gdzie był ciąg znaków, wynik zachowuje kształt wyemitowanego dokumentu: te same pola, w tych samych miejscach, z <redacted> w miejscu wstrzymanej danej i niezmienionym tekstem dosłownym wokół niej.

Dwa sposoby, w jakie to ponowne renderowanie różni się od tego, co zostało wyemitowane — oba podaje notatka:

  • Szablon rozgałęziający się według treści wartości renderuje się inaczej. Porównanie eq z konkretną wartością, test długości, skrót lub jej zakodowanie: każde z nich widzi <redacted> i daje inny wynik — inną gałąź, inną długość, inny skrót. Dlatego ślad nigdy nie twierdzi, że pokazuje wyemitowany dokument.
  • Dane, których nie nazywa żadna deklaracja, przechodzą bez zmian. Podstawienie obejmuje to, co nazywa ta oś — zadeklarowany liść values / infra, oznaczony klucz dostarczania, klucz provides, który własna encja Component komponentu deklaruje jako wrażliwy, zadeklarowane provides konsumowanego celu, liść własnych values lub infra połączenia, który jego gniazdo deklaruje jako wrażliwy, zadeklarowany liść lub klucz provides dołączenia, które komponent posiada sam (odczytywanego w .features.<name>), lub dołączenia zapisanego na połączeniu, a także wartość locals: lub source: obliczoną z którejś z nich. To te same dane, według których wstrzymywana jest odmowa zgłoszona przez szablon. Dana docierająca do szablonu jakąkolwiek inną drogą, na przykład klucz provides nienazwany przez żadną deklarację, którego wartość Recipe obliczył z zadeklarowanego liścia, pojawia się w ponownym renderowaniu dokładnie tak, jak w wyemitowanym dokumencie.

Gdy ponownego renderowania nie da się w ogóle wytworzyć, slot zachowuje klucz workload: i zastępuje dokument wierszem, który to stwierdza i wymienia --trace-unredacted. To stwierdzenie jest celowe: projekcja, która po prostu by zniknęła, byłaby nie do odróżnienia od encji Recipe, która w ogóle nie deklaruje workload:.

Zanim uzna się .trace/ za bezpieczny, warto poznać jedno ograniczenie: dist/ nie jest redagowany. Wyrenderowane artefakty są emitowane dokładnie tak, jak wytworzyło je renderowanie, ponieważ to one są wdrażane, a ponowne renderowanie śladu nigdy do nich nie sięga — te same dane wejściowe renderują się identycznie co do bajtu niezależnie od tego, czy --trace jest włączony.

Należy traktować .trace/ jako zawierający materiał wrażliwy i obchodzić się z nim tak, jak z dist/.

Wyświetlanie wstrzymanych wartości

--trace-unredacted, użyta razem z --trace, zapisuje w plikach śladu wartości zadeklarowane jako wrażliwe zamiast tekstu, który je zastępuje. Opcja istnieje, ponieważ debugowana jest czasem właśnie wstrzymana wartość — poświadczenie pochodzące z niewłaściwego dołączenia wygląda identycznie jak właściwe, gdy oba są odczytywane jako wstrzymane.

W ten sposób przechwytuje się też dokument faktycznie wyemitowany przez kompilację: gdy nic nie jest wstrzymane, nie ma czego podstawiać, więc sloty workload: zawierają wyemitowany dokument, a nie jego ponowne renderowanie, a wpis workload_note nie występuje.

Ograniczają ją trzy właściwości:

  • Każdy zapisywany przez nią plik mówi, czym jest. Każdy plik śladu utworzony w danym uruchomieniu zaczyna się komentarzem, który podaje nazwę opcji i stwierdza, że poniżej występują jawnym tekstem wartości zadeklarowane jako wrażliwe, dzięki czemu plik dołączony później do zgłoszenia błędu lub pozostawiony we współdzielonym katalogu niesie własne ostrzeżenie. Komentarz jest poprawny w formacie danego pliku, więc plik nadal daje się sparsować.
  • Wpływa na .trace/ i na nic innego. Renderowane artefakty są identyczne bajt w bajt z nią i bez niej — zmienia ona to, co pokazuje plik debugowania, nigdy to, co tworzy kompilacja — a układy aggrega inspect oraz tekst diagnostyczny wypisywany przez nieudaną kompilację są identyczne w obu stanach.
  • Istnieje tylko w wywołaniu. Nie ma dla niej ustawienia konfiguracyjnego, więc nie można jej włączyć raz i pozostawić włączonej dla wszystkich, którzy później budują przestrzeń roboczą. Użycie jej bez --trace zatrzymuje kompilację z komunikatem wymieniającym obie opcje, zamiast przyjmować żądanie, którego nie da się spełnić.

Niezależnie od śladu kompilacja wypisuje jedno ostrzeżenie dla każdego klucza dostarczania, który zawiera materiał zadeklarowany jako wrażliwy w postaci wartości literalnej, podając komponent, cel, dołączenie i klucz dostarczania. Ostrzeżenie nigdy nie zatrzymuje kompilacji, a --no-unsupported-field-warnings go nie wycisza — ta opcja dotyczy tego, czego z utworzonej treści cel nie może obsłużyć, a to inna kategoria.

Słowo kluczowe, dwa miejsca jego użycia, dokładne brzmienie ostrzeżenia oraz pełny zakres tego, co daje jego zadeklarowanie, opisano w vocabulary/compact-form-authoring.md, w sekcji „Declaring a leaf sensitive”.

Kiedy używać --trace

  • Diagnozowanie, dlaczego wyrenderowany manifest nie zawiera oczekiwanej wartości: należy przejść przez zrzuty z poszczególnych przebiegów, aby znaleźć pierwszy slot, w którym brakuje wartości.
  • Weryfikacja determinizmu po aktualizacji kompilatora: dwie kompilacje tego samego wejścia z --trace dają identyczne bajt w bajt zrzuty śladu; każda różnica w danym slocie lokalizuje regresję.
  • Iteracyjne tworzenie katalogu: porównanie migawek 04-inject-mapping.yaml i 06-source-locals.yaml pokazuje, co widzą szablony encji Recipe w czasie ewaluacji.

Przykłady

Kompilacja encji Release względem lokalnego katalogu:

aggrega build --release releases/production.yaml

Kompilacja z osobnym katalogiem catalog:

aggrega build --release releases/production.yaml --catalog ../platform-catalog/

Podgląd tego, co wygenerowałaby encja Release, bez zapisywania czegokolwiek:

aggrega build --release releases/production.yaml --dry-run

Kompilacja ze zrzutami śledzenia do debugowania:

aggrega build --release releases/production.yaml --trace

Po kompilacji stan po każdym przebiegu można sprawdzić w .trace/boundaries/<boundary>/<instance>/. Katalog .trace/ jest nadpisywany przy każdym uruchomieniu z --trace; poprzedni stan śledzenia nie jest zachowywany między kompilacjami.

Odsyłacze

  • aggrega-pull — pobiera encje katalogu z rejestru OCI do lokalnego katalogu.
  • aggrega-validate — sprawdza poprawność katalogu, domknięcia encji Release lub pojedynczej encji bez emitowania artefaktów; walidacja zależności wykonywana przez build, bez renderowania.
  • aggrega-lint — sprawdza konwencje publikowania katalogu w tych samych trzech zakresach.
  • aggrega-inspect — odpytuje graf IR po finalizacji grafu bez przechodzenia do renderowania.
  • Błędy — skategoryzowany format prezentacji błędów widoczny w CLI.

Składnia

aggrega build [flags]

Opis

Compile an Aggregate and Release pair into provider-native artifacts under each
boundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,
declares the boundaries, and routes each component to a provider. What a
provider emits is the provider's own shape — Helm manifests, a redistributable
Helm chart, docker-compose YAML — so the output directory holds whatever the
providers this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder the
command is run from, and the closing line names it in full. A run that finds no
workspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first to
create one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makes
the rendered tree reviewable as a diff.

Flagi

FlagaDomyślnieOpis
--auto-pullfalseUruchamia krok pull przed budowaniem: rozwiązuje zależności encji Release do pliku blokady i pamięci podręcznej w ramach procesu, a następnie buduje względem nich. Jest to to samo wypełnianie w ramach procesu, które wykonuje ustawienie obszaru roboczego auto_pull, włączone dla pojedynczego buildu bez edytowania konfiguracji obszaru roboczego. Samodzielnie jest to wypełnianie przyrostowe — istniejące przypięcia są respektowane, a odwołania bez przypięcia są rozwiązywane i dodawane
--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.
--debugfalseEmituje czytelne dla człowieka szczegółowe diagnostyki na stderr — czas rzeczywisty każdej fazy oraz liczby encji i zależności. Ma pierwszeństwo przed —quiet: szczegółowe wyjście jest zawsze emitowane. Różni się od —trace, które zapisuje czytelne maszynowo pliki pośrednie dla każdego węzła w .trace/
--detailfalseBuild domyślnie działa tylko do odczytu i nie wypisuje szczegółów rozwiązywania. Gdy uruchamiany jest krok pull — ponieważ przekazano —auto-pull lub obszar roboczy włącza auto_pull — build wypełnia plik blokady w ramach procesu niezależnie od tego, czy już istnieje, a ta flaga wypisuje dla każdej rozwiązanej encji, co zrobiło to wypełnianie: pobrano świeżo z rejestru, ponownie użyto slotu pamięci podręcznej, znaleziono w lokalnym katalogu, dostarczono z wnętrza pliku binarnego kompilatora lub zewnętrzne (własna encja Aggregate lub Manifest encji Release, odczytana z pliku lub wpisu wskazanego przez Release). Gdy krok pull nie jest uruchamiany, zamiast wierszy dla poszczególnych encji wypisuje jedną linię z tą informacją. Tylko stdout; nie jest utrwalane
--disable-plugin-cachefalsePomija trwałą dyskową pamięć podręczną kompilacji pluginów dla tego buildu i kompiluje gości pluginów od nowa w pamięci podręcznej w RAM, odrzucanej po zakończeniu buildu. Domyślnie wyłączone, co oznacza ponowne użycie współdzielonej dyskowej pamięci podręcznej między buildami. Nie zmienia renderowanego wyniku
--dry-runfalseRenderuje Release i wypisuje to, co zostałoby wyemitowane, zamiast to zapisywać: przyszła ścieżka i zawartość każdego artefaktu trafiają na stdout, a katalog wyjściowy i plik blokady pozostają nietknięte. Wejścia zewnętrzne zachowują się dokładnie tak jak w zwykłym buildzie — przypięte wejścia są dostarczane z magazynu adresowanego treścią (i ponownie pobierane według skrótu, gdy brakuje obiektu blob), a renderowanie żądające nieprzypiętego zewnętrznego URL zatrzymuje się, podając go — więc to, co pokazuje przebieg próbny, jest tym, co zapisałby build. Odmawia połączenia z —auto-pull, —upgrade lub —trace, z których każde coś zapisuje — wypełnianie zależności lub build ze śledzeniem należy uruchomić jako osobny krok. Można łączyć z —policy-input, którego pliki są wtedy jedyną rzeczą, jaką zapisuje
--ir-graphfalseDodatkowo zapisuje na stdout graf IR obliczony w tym przebiegu, w formacie JSON, oprócz wszystkiego, co to polecenie już generuje. Wartości zadeklarowane przez autora jako wrażliwe są z niego pomijane; aby je wypisać, należy przekazać —unredacted. Artefakty są nadal zapisywane, a podsumowanie nadal wypisywane; graf jest zapisywany przed nimi
--no-unsupported-field-warningsfalseWycisza klasę ostrzeżeń o nieobsługiwanych polach: powiadomienia, które cel zgłasza dla czegoś, co zostało zdefiniowane, a czego nie może uwzględnić — pola encji Workload, którego nie potrafi wyrazić (jak cel o niższej wierności, np. compose), lub adnotacji aggrega.ai/, na którą nie reaguje dla danego rodzaju wejścia węzła. Pozostałe ostrzeżenia renderowania są nadal wyświetlane. Dotyczy tylko wyświetlania; nie zmienia renderowanego wyniku
--policy-input—Zapisuje do tego katalogu ładunek, który każda rola zarządcza przekazuje dołączonemu tam pluginowi, jako jeden wiersz JSON: dokładnie to, co build przekazuje pluginowi, z ukryciem każdej wartości, którą build przed nim ukrywa. Dla annotation-transform, label-transform i ir-verdict plik jest dokumentem input, który odczytuje polityka w tej roli. Dla render-verdict silnik polityk przekształca ładunek, zanim polityka go odczyta — z niego parsowane są documents każdego artefaktu — więc politykę render-verdict na wbudowanym silniku testuje się w buildzie, dołączoną tak, by raportowała na poziomie warn lub info; dla pluginu, którego .wasm zbudowano samodzielnie, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json uruchamia go na tym pliku. Rola bez dołączeń również jest zapisywana, jako ładunek, który otrzymałoby dołączenie bez źródeł i bez ustawień, więc politykę można napisać przed jej dołączeniem. Każda rola jest zapisywana do <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict); gdy dołączenia jednej roli otrzymują różne ładunki — jedno ma własne źródła lub ustawienia albo transformacja zmienia to, co odczytuje następne — każde jest zamiast tego zapisywane do <role>.<position>.<plugin>.json, gdzie position liczy dołączenia tej roli od 1 w kolejności, w jakiej wymienia je konfiguracja obszaru roboczego, a plugin to ostatni segment odwołania do pluginu bez wersji, z zastąpieniem sekwencją ucieczki każdego znaku, którego nazwa pliku nie może zawierać. Pliki o tych nazwach już obecne w katalogu są zastępowane, a niczego innego w nim się nie dotyka. Pliki są zapisywane niezależnie od tego, czy build się zakończy, czy zatrzyma, a build, który zatrzyma się przed uruchomieniem roli, wymienia każdą rolę, dla której nie zapisał pliku. Żądanie ich nie zmienia żadnego artefaktu ani żadnego werdyktu. Można łączyć z —dry-run, który wtedy zapisuje te pliki i nic poza nimi: katalog wyjściowy i plik blokady pozostają nietknięte
--progressfalseWymusza wyświetlanie postępu buildu nawet wtedy, gdy stderr nie jest terminalem, wypisując jedną zwykłą linię na każdy ukończony krok wraz z jego czasem. Domyślnie auto: interaktywna lista faz jest wyświetlana tylko wtedy, gdy stderr jest terminalem interpretującym sekwencje sterujące, terminal, który ich nie interpretuje, otrzymuje te same zwykłe linie, a wyjście przekierowane lub potokowe nie otrzymuje żadnych. —quiet i —debug nadpisują —progress
--quietfalseWycisza wyświetlanie postępu buildu na stderr. Nie wpływa na stdout. Ma pierwszeństwo przed —progress
--release—Ścieżka do pliku YAML encji Release (wymagana). Ścieżka względna jest rozwiązywana względem katalogu, w którym uruchamiane jest 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 odnajduje obszar roboczy na podstawie własnego folderu encji Release
--tracefalsezapisuje pliki pośrednie dla każdego węzła w .trace/ w katalogu głównym obszaru roboczego, obok dist/, do analizy po fakcie
--trace-unredactedfalseZapisuje wartości zadeklarowane jako wrażliwe w plikach .trace/ zamiast zastępującego je tekstu i oznacza każdy plik zapisywany przez śledzenie nagłówkiem informującym o tym. Wymaga —trace. Dotyczy .trace/ i niczego więcej: renderowane artefakty, wyjście aggrega inspect i tekst diagnostyk są identyczne z tą flagą i bez niej. Tylko przy wywołaniu — nie ma dla niej ustawienia w konfiguracji obszaru roboczego, więc nigdy nie może pozostać włączona dla późniejszego buildu
--unredactedfalseWypisuje wartości zadeklarowane przez autora jako wrażliwe zamiast je pomijać. Wszystko, do czego trafia wyjście — terminal, potok, plik, nagranie ekranu — zawiera wtedy te wartości jawnym tekstem. Dotyczy grafu zapisywanego przez —ir-graph i niczego więcej, dlatego wymaga —ir-graph; pliki .trace/ używają zamiast tego —trace-unredacted
--upgradefalseZmienia krok auto-pull w pełne odświeżenie: odrzuca istniejący plik blokady i ponownie rozwiązuje każdą zależność na podstawie bieżącego stanu rejestru, podnosząc każdą do najwyższej dostępnej wersji zamiast respektować istniejące przypięcia. Implikuje —auto-pull — samodzielnie uruchamia pull z pełnym odświeżeniem przed buildem. Nie przyjmuje celu, więc nie można go zawęzić do jednej zależności: aby przyjąć lub usunąć pojedyncze przypięcie, należy zamiast tego uruchomić aggrega pull —upgrade —release , które pozostawia wszystkie inne przypięcia bez zmian. Ponieważ usuwa wszystkie zapisane przypięcia, najpierw prosi o potwierdzenie; —yes odpowiada z góry, a przy nieinteraktywnym stdin odmawia działania zamiast czekać na odpowiedź, której nikt nie może udzielić
--verify-determinismfalseRenderuje każdy węzeł dwukrotnie i porównuje wyemitowane bajty, zatrzymując build, jeśli dwa renderowania któregokolwiek węzła się różnią. Domyślnie wyłączone. Służy do potwierdzenia, że provider renderuje deterministycznie — identyczne wejście daje bajtowo identyczne wyjście — na czym opierają się gwarancje różnic GitOps i bajtowo identycznego wyjścia
--yesfalseUdziela z góry odpowiedzi na potwierdzenie —upgrade, do użytku nieinteraktywnego. Dotyczy tego jednego monitu i niczego więcej: build, który nie odświeża, o nic nie pyta, więc przekazanie tej flagi nie zmienia tam zachowania