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

Release

Koncepcyjna rola encji Release (Domena 4 — router wdrożeniowy wiążący encję Aggregate z encją Manifest i mapujący komponenty na fizyczne granice) jest opisana w architecture/04-entity-taxonomy.md. Mechanizm sekwencjonowania czasowego (syncWave dla każdej granicy), Dynamic Addressing Polyfill oraz wzorzec Parameter Hoisting są opisane w architecture/12-day-two-lifecycles.md. Ta strona omawia sposób tworzenia encji Release.

Rola encji Release

Encja Release wiąże aggregate z manifest i przypisuje komponenty do fizycznych granic wdrożenia (np. aws-eks-production). Jest jedynym punktem wejścia kompilacji: aggrega build --release release.yaml.

Encja Release realizuje abstrakcyjny kontrakt agregatu, wstrzykując fizyczne realia wyłącznie do bloku parameters, a fizyczne wymiarowanie (np. liczbę CPU czy porty) wstrzykuje przez równoległą przestrzeń nazw infra.

Każda encja Release deklaruje pole manifest: wskazujące jej encję Manifest (chyba że encja Release używa extends:, które dziedziczy wskaźnik na manifest z encji nadrzędnej). CLI aggrega build odczytuje to pole bezpośrednio; flaga CLI --manifest nie istnieje, więc specyfikacja zależności pozostaje zatwierdzona w Git razem z samą encją Release, dzięki czemu historię wdrożeń można audytować przez własną historię Git encji Release.

Pola aggregate: i manifest: są rozwiązywane przez tożsamość lub przez plik o ścieżce względnej, tak samo jak reszta języka rozwiązuje odwołania — nigdy jako rdzeń nazwy pliku względny wobec encji Release. Wartość ./ lub ../ to jawny plik lokalny, odczytywany bezpośrednio względem encji Release. Samodzielny token to tożsamość — metadata.name wskazywanej encji. Tożsamość w manifest: jest rozwiązywana przez przeszukanie katalogu samej encji Release (encja Manifest to konfiguracja operatora po stronie wdrożenia, więc nie ma poziomu katalogu ani rejestru). Tożsamość w aggregate: jest rozwiązywana przez pełną kaskadę — katalog encji Release, następnie katalog (catalog), następnie rejestr — dzięki czemu encja Release może wskazać opublikowaną encję Aggregate przez tożsamość, a ten sam opublikowany moduł zostanie rozwiązany niezależnie od tego, czy jest to spec.aggregate najwyższego poziomu encji Release, czy podagregat wewnątrz innej encji Aggregate. Ten model tożsamości lub ścieżki pozwala, by jedna współdzielona encja Aggregate obsługiwała wiele wariantów encji Release bez wiązania odwołania z nazwą pliku, a opublikowaną encję Aggregate można było wdrożyć bezpośrednio po nazwie.

Ścieżka pozostaje wewnątrz obszaru roboczego. Wartość ./ lub ../ wskazuje plik znajdujący się w obszarze roboczym, podobnie jak każda inna ścieżka zapisana w encji Release — jej extends: oraz $import: w parametrach, opisane niżej. Ścieżka, która w zapisanej postaci wychodzi poza obszar roboczy lub którą wyprowadza z niego dowiązanie symboliczne po drodze, jest odrzucana, zanim cokolwiek zostanie odczytane ze wskazanego pliku. Aby wdrożyć encję Aggregate przechowywaną poza obszarem roboczym, należy wskazać ją przez tożsamość i wpisać zawierający ją katalog jako katalog katalogu (catalog) w konfiguracji obszaru roboczego; encja Manifest, encja Release wskazana przez extends: oraz plik parametrów są odczytywane obok encji Release i nigdy nie są wyszukiwane po nazwie, dlatego przechowuje się je wewnątrz obszaru roboczego. Encja Release wskazana w wierszu poleceń lub w konfiguracji obszaru roboczego, leżąca poza obszarem roboczym, jest odrębnym korzeniem: każda zapisana w niej ścieżka — i każda ścieżka zapisana w encji Release, do której prowadzi jej łańcuch extends: — musi prowadzić do pliku wewnątrz katalogu zawierającego tę encję Release, a ścieżka wychodząca poza ten katalog lub wyprowadzana z niego przez dowiązanie jest odrzucana w ten sam sposób. Wszystko, co taka encja Release wskazuje, należy trzymać obok niej albo budować ją w obszarze roboczym, który zawiera oba elementy. Zob. errors/fatal-halts.md §„A reference to another file leads out of the directory it must stay inside (Odwołanie do innego pliku wychodzi poza katalog, w którym musi pozostać)”.

Encja Release określa miejsce docelowe skompilowanych artefaktów; przydział do dostawców należy do encji Manifest, na którą wskazuje encja Release (podział ról opisuje Manifest a Release: rozdzielenie odpowiedzialności).

Metadane środowiska

Każdy blok metadanych encji Release przyjmuje pole environment: — dowolny ciąg znaków identyfikujący środowisko, do którego wdrażana jest encja Release (typowe wartości: production, staging, dev). Pole ma charakter informacyjny: nie ma wyliczenia, wzorca na poziomie schematu ani walidacji między encjami poza type: string. Kompilator emituje jego wartość jako etykietę aggrega.ai/environment na każdym manifeście Kubernetes renderowanym przez provider helm, obok pozostałych etykiet pochodzenia Aggrega — w postaci, w jakiej ją zapisano, gdy jest prawidłową wartością etykiety Kubernetes, a w przeciwnym razie przepisaną na prawidłową wartość, przy czym dokładna wartość jest przenoszona w adnotacji aggrega.ai/environment (zatem eu/prod otrzymuje etykietę eu-prod); provider helm-chart dodaje te same etykiety do każdego artefaktu ładowanego przez $import:, który umieszcza w sub-charcie, natomiast własne szablony sub-chartu zawierają to, co napisał ich autor. Provider compose przenosi tę samą wartość jako etykietę aggrega.ai/environment na każdej emitowanej przez siebie usłudze.

Pięć praktycznych wzorców kieruje tworzeniem pola environment::

  1. Przypisywanie kosztów OTel/FinOps. Pulpity kosztów chmury (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtrują pody Kubernetes według środowiska na podstawie tagów. Etykieta aggrega.ai/environment: production trafia do etykiet podów poprzez wstrzykiwanie etykiet przez provider Helm; raporty kosztów grupują wydatki według aggrega.ai/environment bez ręcznego tagowania poszczególnych zasobów.

  2. Filtrowanie śladów i logów OTel. Pulpity obserwowalności (Datadog, New Relic, Honeycomb, Grafana Tempo) filtrują telemetrię według etykiety środowiska. aggrega.ai/environment: staging pozwala operatorom ograniczyć zapytania o logi i wyszukiwanie śladów do środowiska staging bez filtrowania według konwencji przestrzeni nazw czy nazw chartów — jedna kanoniczna etykieta w całej wyrenderowanej powierzchni.

  3. Kierowanie operatorów Kubernetes. Kontrolery GitOps (ArgoCD, Flux) i operatory polityk (Kyverno, OPA Gatekeeper) czasem filtrują zasoby według etykiety środowiska na potrzeby polityk specyficznych dla środowiska (na przykład „zasoby wyłącznie produkcyjne wymagają etykiety zatwierdzonego źródła obrazu”). Etykieta aggrega.ai/environment zapewnia stabilny selektor, niezależny od konwencji przestrzeni nazw czy wzorców nazewnictwa.

  4. Rozróżnianie produkcji w wielu regionach. Zespół uruchamiający encję Release production-us-east obok encji Release production-eu-west — obie z metadata.environment: production — otrzymuje tę samą etykietę aggrega.ai/environment: production we wszystkich regionach. W połączeniu z osobną etykietą regionu umożliwia to zbiorcze zestawienie kosztów między regionami („łączne wydatki produkcyjne”) i szczegółową analizę dla każdego regionu.

  5. Zakres zgodności. Zbieranie dowodów dla SOC 2, PCI i HIPAA jest zawężane według środowiska (audyt wyłącznie produkcji itp.). Etykieta aggrega.ai/environment jest wykorzystywana przez narzędzia do gromadzenia dowodów zgodności (Vanta, Drata) do filtrowania zasobów według zakresu audytu.

Schemat wymaga environment: w każdej encji Release; wartość ma charakter informacyjny, a kompilator odczytuje ją wyłącznie po to, by zapisać etykietę aggrega.ai/environment.

Ograniczenia na poziomie schematu

Dwie gwarancje strukturalne chronią encję Aggregate jako jedyne źródło prawdy (Single Source of Truth):

  • values: jest zabronione. Aby chronić encję Aggregate jako jedyne źródło prawdy, schemat encji Release mechanicznie zabrania bloku values: — operator nie może deklarować values dla żadnej encji Component ani Feature z poziomu encji Release. Zakaz obejmuje również krawędzie uses: wpis uses dla pojedynczej krawędzi w encji Release zawiera infra oraz załączniki, które zapisuje na połączeniu, a te również zawierają infra — nigdy values (wartości dla pojedynczych krawędzi przeznaczone dla programisty oraz wartości załącznika na połączeniu pozostają w encji Aggregate). Zróżnicowanie wartości przeznaczonych dla programisty w zależności od środowiska odbywa się poprzez wynoszenie parametrów (Parameter Hoisting): programista udostępnia typowane pole parameters.* w encji Aggregate, szablon values encji Component odwołuje się do niego, a encja Release wypełnia parametr dla swojego środowiska. Zakaz na poziomie schematu jest wprost opisany w architecture/06-data-taxonomy-and-composition.md §8 Constraint 4. Zakres krawędzi uses w encji Release — co można w nich konfigurować i łączyć — opisano poniżej w sekcji Konfiguracja połączeń dla pojedynczych krawędzi.
  • extends + aggregate: jest odrzucane. Aby zapobiec niemożliwym do prześledzenia encjom Releases „modyfikującym agregat”, gdy encja Release używa extends, zadeklarowanie wskaźnika aggregate jest odrzucane przez schemat encji Release. Wydanie potomne musi odpowiadać dokładnie tej samej intencji programisty co jego rodzic. Pole manifest staje się natomiast opcjonalne, co umożliwia „późne wiązanie” (Late Binding) — operator może odziedziczyć całą fizyczną topologię, a jednocześnie precyzyjnie podmienić encję Manifest.

Blok parameters:

Encja Release realizuje typowany kontrakt parametrów, który deklaruje encja Aggregate. spec.parameters: to powierzchnia tworzenia — mapa YAML, której klucze odpowiadają deklaracjom parameters.* w encji Aggregate, a wartości dostarczają realizację dla danego środowiska.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Każda wartość przechodzi kontrolę względem schematu zadeklarowanego w encji Aggregate na warstwie kontraktu parametrów, a kompilacja zatrzymuje się, gdy encja Release pomija wymagany parametr (E0165, parameter-missing) lub dostarcza wartość odrzucaną przez kontrakt danego miejsca (E0164, parameter-contract-violation). Parametry zadeklarowane z default: otrzymują wartość domyślną, gdy encja Release pomija dane miejsce; typowany kontrakt jest jedynym słownikiem tworzenia.

Dwa tryby tworzenia — rozróżnianie według kształtu treści. parameters: przyjmuje albo wbudowaną mapę YAML (tryb 1, pokazany powyżej), albo pojedynczy klucz $import: wskazujący lokalny plik (tryb 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Względna ścieżka $import: jest rozwiązywana względem katalogu zawierającego encję Release, która ją zapisuje, niezależnie od tego, skąd uruchomiono polecenie, dzięki czemu wiersz poleceń i edytor odczytują ten sam plik; ścieżka bezwzględna wskazuje własne miejsce, a każda z nich musi prowadzić do pliku wewnątrz obszaru roboczego — lub, w przypadku encji Release wskazanej spoza obszaru roboczego, wewnątrz katalogu, który ją zawiera. Oba tryby wzajemnie się w tym miejscu wykluczają i można zaimportować tylko jeden plik. Wielowarstwowe nakładanie parametrów z wielu plików to domena łańcuchów extends: encji Release: nadrzędna encja Release dostarcza bazowy zestaw parametrów, a podrzędna rozszerza go i nadpisuje dla każdego środowiska. Wzorzec opisano dalej w sekcji Composite Release / extends: inheritance.

Granica między parametrami a infra. Parametry niosą poznawczą intencję programisty wyrażoną jako typowane miejsca, które deklaruje encja Aggregate; encja Release je realizuje. infra: w encji Release niesie fizyczne wymiarowanie operatora (liczby replik, limity CPU/pamięci, klasy pamięci masowej) przypisane do konkretnych komponentów lub dołączeń encji Feature. Parametry trafiają do szablonów values: encji Aggregate przez .parameters.X; infra: trafia do szablonu valuesMapping: encji Recipe przez .infra.X. Taksonomię filarów danych opisano w architecture/06-data-taxonomy-and-composition.md §3, a cykl życia parametrów w potoku — w templates/parameters-context.md.

Granice i zakres domyślny

Encja Release grupuje komponenty w granice — fizyczne jednostki wdrożenia, z których każda ma własny katalog wyjściowy i kaskadę adnotacji. Przypadek z jedną granicą jest najczęstszy, dlatego nie wymaga żadnej ceremonii.

Pojedynczy zakres (domyślny). Komponenty należy zapisać bezpośrednio pod spec.components: i pominąć blok boundaries:. Kompilator łączy je w syntetyzowaną granicę default, której wyjście jest płaskie — artefakty trafiają bezpośrednio do dist/ (osobno dla każdego dostawcy, dzięki bezpiecznej wartości domyślnej subDirectory opisanej poniżej: dist/compose/, dist/helm/, …), bez segmentu z nazwą granicy w ścieżce. To najprostsze wdrożenie: aggrega build dla płaskiego celu Compose lub pojedynczego klastra bez nazywania granic.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Wiele zakresów. Gdy encja Release obejmuje więcej niż jedno fizyczne zgrupowanie — osobne klastry, regiony lub fale synchronizacji — należy zadeklarować nazwane granice pod boundaries:. Każda granica ma własne directory:, kaskadę adnotacji i syncWave:, a komponenty są adresowane w obrębie swojej granicy.

Wzajemne wykluczanie. spec.components: i spec.boundaries: wzajemnie się wykluczają na poziomie głównym encji Release — encja Release zawiera jedno albo drugie, nigdy oba. Dokument deklarujący oba zatrzymuje się przy wczytywaniu z błędem koperty. Powierzchnia components najwyższego poziomu ma ten sam kształt operatorski dla każdego komponentu co components granicy (infra:, annotations:, uses:).

Zadeklarowana granica o nazwie default. Płaskie wyjście jest właściwością syntetyzowanej granicy domyślnej, a nie nazwy. W encji Release, która jawnie deklaruje pod boundaries: granicę o nazwie default, jest to zwykła nazwana granica: jej wyjście wynika z jej directory: (domyślnie dist/boundaries/default/), dokładnie tak jak w przypadku każdej innej zadeklarowanej granicy.

Wzorzec zakresu domyślnego opisano w architecture/06-data-taxonomy-and-composition.md §7.

Segregacja przestrzenna i ścieżki wyjściowe

Każda granica deklaruje fizyczny katalog wyjściowy directory dla swoich skompilowanych artefaktów; komponenty w obrębie granicy mogą go nadpisać za pomocą subDirectory ustawianego dla każdego komponentu. Kompilator oblicza ostateczną ścieżkę artefaktu, łącząc je, w postaci rozdzielanej ukośnikami na każdej platformie: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Jeden katalog, jedna pisownia. Obliczona ścieżka jest normalizowana jednokrotnie, więc out/a, out//a, ./out/a i out/a/ to jeden katalog. Granice, których ścieżki po normalizacji wskazują ten sam katalog i które są renderowane przez tego samego dostawcę, są składane razem, dokładnie tak jak granice zapisane z identycznymi ścieżkami.
  • Ścieżka pozostaje poniżej katalogu głównego wyjścia. Ścieżka, która wychodzi poza katalog główny wyjścia (.., ../escape, a/../..), ścieżka bezwzględna albo taka, która nie wskazuje żadnego katalogu — pusta lub po normalizacji równa samemu katalogowi głównemu wyjścia — zatrzymuje kompilację, zanim cokolwiek zostanie zapisane. Komunikat podaje encję Release, granicę, błędne pole (directory: lub subDirectory:) oraz wartość, do której zostało obliczone, ponieważ ta wartość jest często wynikiem szablonu.
  • Bezpieczna wartość domyślna. Jeśli subDirectory zostanie pominięte lub jest puste, kompilator automatycznie stosuje subDirectory: "{{ .capability }}" — artefakty każdej możliwości renderowania (Helm, Helm-chart, Compose, Terraform, CloudFormation) trafiają do osobnego podfolderu, co zapobiega kolizjom mieszanych artefaktów w dalszych narzędziach CI/CD. Jawnie zapisane subDirectory: "" jest odczytywane dokładnie tak jak pominięte, więc również otrzymuje tę wartość domyślną.
  • Płaskie nadpisanie. Aby całkowicie wyłączyć podkatalogi (wszystkie artefakty bezpośrednio w directory), należy ustawić subDirectory: ".". Szablon subDirectory, który zostaje obliczony do pustego ciągu — na przykład "{{ .parameters.sub }}" z sub ustawionym na "" — również je wyłącza.
  • Zmienne szablonu. directory jest obliczane z użyciem {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }} oraz {{ .parent_boundary.* }} do kaskadowania danych z granicy nadrzędnej. subDirectory jest obliczane z tym samym zestawem oraz {{ .component_id }} (tylko w nadpisaniach dla poszczególnych komponentów). Kompilator oblicza szablony ścieżek z missingkey=error — odwołanie do niezadeklarowanej zmiennej zatrzymuje kompilację z precyzyjną diagnostyką. Macierz dla poszczególnych kontekstów i zasady kaskadowania z granicy nadrzędnej opisano w zmiennych szablonów ścieżek.

Adnotacje granicy kaskadują w dół do każdego zawartego komponentu; infra pozostaje ściśle lokalne dla komponentu, którego dotyczy. Rekurencyjna mapa boundaries pozwala na dowolne zagnieżdżanie (granica w granicy w granicy), a niezmienniki kaskady adnotacji i lokalności infra obowiązują na każdym poziomie.

Przykład:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Adnotacje kaskadowane przez ten mechanizm są dostępne w dalszych szablonach encji Recipe przez .context.annotations.release; sposób, w jaki renderery z nich korzystają, opisano w tworzeniu encji Recipe oraz w macierzy rozwijania szablonów.

Ustrukturyzowane wartości adnotacji. Gdy powiązanie w encji Manifest deklaruje wiele ścieżek routingu do filaru infra dla jednego klucza adnotacji, wartość adnotacji po stronie encji Release może być ustrukturyzowanym obiektem, który w jednej deklaracji niesie wartości dla kilku pól schematu encji Feature:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

Wartości ustrukturyzowane kaskadują z głębokim scalaniem na poziomie podkluczy; podklucze z bliższego poziomu nadpisują podklucze nadrzędne. null ustawione dla podklucza wyłącza ten jeden podklucz, a sąsiednie podklucze pozostają. Strona encji Release uruchamia tylko podklucze, których filar w mapie powiązań to infra; podklucze kierowane do values należą do adnotacji po stronie encji Aggregate. Pełne omówienie wartości ustrukturyzowanych — składanie między stronami, walidację typów podkluczy, dyscyplinę złagodzonych wartości domyślnych — zawiera providers/well-known-annotations.md §„Structured annotation values”.

Dobrze znane adnotacje. Poza kluczami ad hoc biblioteka standardowa Aggrega definiuje zestaw dobrze znanych adnotacji w przestrzeniach nazw aggrega.ai/ i feature.aggrega.ai/, pogrupowanych w kategorie rozmieszczenia, sieci, bezpieczeństwa i obserwowalności. Autorzy dodający adnotacje do granicy encji Release powinni zapoznać się z providers/well-known-annotations.md, gdzie znajduje się pełna macierz wraz z zasadami użycia przez poszczególnych dostawców — strona dokumentuje, którzy dostawcy stosują każdy dobrze znany klucz i jakie zachowanie generują, gdy klucz jest obecny.

Konfiguracja połączeń dla poszczególnych krawędzi

Komponent granicy może zawierać blok uses:, który konfiguruje lub łączy krawędzie topologii w obrębie gniazd deklarowanych przez usesSchema w katalogu encji Component. Jest to powierzchnia konfiguracji poszczególnych połączeń dostępna dla operatora, ograniczona tak, aby deweloper zachował własność architektury, którą utworzył:

  • Konfiguracja istniejącej krawędzi. Ustawia się infra dla krawędzi, którą deweloper już zadeklarował. Wpis podaje alias dewelopera i dostarcza infra; albo wskazuje ten sam cel, który połączył deweloper, albo pomija cel. infra jest walidowane względem infraSchema gniazda.
  • Połączenie niepowiązanego gniazda. Tworzy się krawędź do gniazda, które deklaruje usesSchema encji Component, ale deweloper pozostawił je niepołączone, wskazującą na istniejący komponent. Utworzona krawędź może również zawierać infra dla danej krawędzi.
  • Dołączenie na połączeniu. Dołączenia umieszcza się pod features: wpisu, z kluczem będącym slotem deklarowanym przez gniazdo w jego featuresSchema — tymi samymi slotami, które wypełnia wpis połączenia dewelopera. Każde zawiera type, opcjonalny description oraz infra, a nigdy values. W slocie, który deweloper już wypełnił na tym samym połączeniu, wpis określa rozmiar tego dołączenia: należy zapisać tylko infra, ponieważ typ i wartości pochodzą z encji Aggregate (zapisany tu type musi być zgodny z typem w encji Aggregate, w przeciwnym razie kompilacja zatrzymuje się na tym wpisie, wskazując oba). W slocie, który deweloper pozostawił pusty, dołączenie należy do encji Release, a type jest wymagany. W obu przypadkach wypełnienie podlega selector slotu i wlicza się do slotu required, dokładnie tak jak wypełnienie dewelopera.

Ta powierzchnia działa na zasadzie tworzenia bez przekierowywania: encja Release może dodać krawędź do niepowiązanego gniazda, ale nie może przekierować krawędzi, którą deweloper już zadeklarował. Wpis dla krawędzi wskazujący inny cel niż krawędź dewelopera zatrzymuje kompilację; wpis wskazujący ten sam cel (lub go pomijający) konfiguruje tę krawędź. Encja Release nie może też deklarować values na krawędzi ani na dołączeniu, które tam zapisuje (wartości przeznaczone dla dewelopera pozostają w encji Aggregate), wiązać gniazda, którego usesSchema nie deklaruje, ani kierować krawędzi do nieistniejącego komponentu — każdy z tych przypadków to krytyczne zatrzymanie. Tak samo jest z wpisem ustawiającym infra lub features na połączeniu, które nie istnieje po narysowaniu wszystkich krawędzi, chyba że komponent konsumujący jest wyłączony przez active: false. Zob. errors/fatal-halts.md §„When building the topology”.

Trzy kolejne zatrzymania utrzymują dołączenia połączenia na tym połączeniu:

  • Nazwa, dla której gniazdo nie deklaruje slotu, zatrzymuje kompilację, dokładnie tak jak we wpisie połączenia encji Aggregate, na tym wpisie w encji Release, wskazując sloty deklarowane przez gniazdo oraz te z nich, od których nazwa różni się o jedną edycję.
  • Dołączenie tworzone wyłącznie przez encję Release, zapisane bez type, zatrzymuje kompilację na wpisie połączenia, wskazując slot. Dołączenie tworzone przez encję Release nie zawiera values, więc pasuje do encji Feature, której values niczego nie wymagają; takie, którego schemat wymaga wartości, zatrzymuje kompilację na brakującej wartości w tym samym wpisie. Encje Features poświadczeń z biblioteki standardowej, które przenoszą lokalizator wywołującego, nie wymagają niczego w values: każda przyjmuje go również w infra (zob. niżej).
  • Złożona nazwa zapisana gdziekolwiek poza połączeniem zatrzymuje kompilację. Dołączenie połączenia staje się dołączeniem komponentu konsumującego o nazwie <alias>.<slot> (zob. wpis połączenia encji Aggregate), a zarówno własne klucze features: wpisu komponentu, jak i klucze granicy dopuszczają kropkę. Wpis komponentu zapisujący tę nazwę lub granica zapisująca ją tak, że dociera do komponentu, którego połączenie ją przenosi — komponentu umieszczonego w tej granicy lub w granicy w niej zagnieżdżonej, w tym komponentów kierowanego podmodułu — zatrzymuje kompilację, wskazując obie pisownie, raz dla każdego komponentu, do którego dociera. Slot gniazda wypełnia się na każdym połączeniu, a nigdy przez dołączenie kaskadujące z szerszego zakresu.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Poświadczenie na połączeniu tworzonym przez encję Release wskazuje swój sekret w infra. Połączenie tworzone przez encję Release nie ma wpisu w encji Aggregate, więc nic tam nie zapisuje values poświadczenia, a encja Release nigdzie nie zapisuje values. Każda encja Feature poświadczeń z biblioteki standardowej, która przenosi lokalizator wywołującego — core/referenced-secret, core/referenced-secret-set, core/secret-value i core/secret-provided — przyjmuje go więc zarówno w infra, jak i w values: origin lub entries dla core/referenced-secret-set, o tym samym kształcie i z tą samą deklaracją sensitive: true w obu filarach. Każda realizacja odczytuje ten filar, który go przenosi.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Lokalizator zapisuje się w dokładnie jednym filarze na dołączenie. Dołączenie, które przenosi go w obu — values encji Aggregate i infra encji Release dla tego samego slotu — lub w żadnym, zatrzymuje kompilację na własnej asercji encji Feature (E0033), wskazując encję Feature, dołączenie i komponent oraz podając, który z dwóch przypadków wystąpił. Reguła należy do encji katalogowych tych Features, a nie do kompilatora, który ocenia ich asercję tak, jak ocenia asercję każdej encji Feature. Pola inne niż lokalizator zachowują swój filar: key pozostaje liściem values, więc dołączenie tworzone wyłącznie przez encję Release odczytuje domyślny klucz danych encji Feature, value. Zakaz values: pozostaje bez zmian — lokalizator operatora to infra.

core/secret-provided jako jedyna nie pasuje do połączenia: publikuje swoją wartość, aby dostarczył ją własny blok inject: dołączenia, a dołączenie połączenia nie ma bloku inject: w żadnym z dokumentów, więc na połączeniu żaden blok inject: jej nie dostarcza. Należy tam użyć core/referenced-secret lub core/secret-value.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

Rozstrzygnięte infra krawędzi trafia do kontekstu renderowania komponentu konsumującego pod .context.uses.<alias>.infra.<key>; nigdy nie pojawia się w kontekście komponentu docelowego, więc renderowany wynik celu jest niezmienny względem konsumentów konfigurujących prowadzące do niego krawędzie. Dołączenie na połączeniu również trafia do komponentu konsumującego, jako jedno z jego dołączeń: jego infra łączy się z values encji Aggregate dla tego samego slotu, a jego FeatureRecipe renderuje się względem obu. Encja Recipe komponentu konsumującego odczytuje je pod jego połączeniem, w .context.uses.<alias>.features.<slot>, a jego Workload dostarcza je, wskazując połączenie obok slotu — zob. Dostarczanie poświadczenia przenoszonego przez połączenie.

Pole aggregates: — kierowanie zagnieżdżonych podmodułów do granic

Gdy encja Aggregate deklaruje zagnieżdżone podmoduły przez spec.aggregates:, encja Release decyduje, w której granicy trafiają komponenty każdego podmodułu, deklarując aggregates: obok components: wewnątrz docelowej granicy:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Każdy podagregat wymieniony w Aggregate.spec.aggregates: należy umieścić w dokładnie jednej granicy.

Kierowanie umieszcza komponenty. Każdy komponent skierowanego podmodułu trafia do granicy, która go kieruje, i przejmuje jej directory, subDirectory, syncWave oraz kaskadę adnotacji — ten sam kontekst, który otrzymuje komponent nazwany bezpośrednio w components:, łącznie z pochodzeniem aggrega.ai/boundary-path umieszczanym na emitowanych artefaktach. Skierowanie podmodułu i zaadresowanie każdego z jego komponentów kwalifikowaną ścieżką z kropkami z pustą treścią dają zatem identyczne artefakty; kierowanie jest krótszym sposobem wyrażenia tego samego i jedynym, który nie wymaga znajomości zawartości podmodułu.

Komponent należy do dokładnie jednej granicy, a budowanie zostaje przerwane, gdy dokument umieszcza go dwukrotnie — ten sam podmoduł skierowany do dwóch granic, podmoduł skierowany do jednej granicy, podczas gdy jeden z jego komponentów jest nazwany w innej, albo komponent nazwany zarówno bezpośrednio, jak i przez wpis kierujący. Diagnostyka wskazuje oba miejsca, ponieważ to autor decyduje, które zachować. Skierowanie podmodułu do granicy i nazwanie jednego z jego komponentów w tej samej granicy nie jest konfliktem: kierowanie umieszcza komponent, a nazwany wpis go konfiguruje.

Podagregat, którego encja Release nigdzie nie umieszcza, przerywa budowanie. Umieszczenie jest odczytywane z obu zapisów, więc budowanie zostaje przerwane tylko wtedy, gdy żaden nie obejmuje podmodułu: żadna granica nie kieruje go w aggregates: i żadna granica nie nazywa żadnego z jego komponentów w components: kwalifikowaną ścieżką z kropkami. Każdy z zapisów sam w sobie go umieszcza, a podmoduł, którego wszystkie komponenty są nazwane indywidualnie, nie potrzebuje wpisu kierującego. Poprawka należy do bloku aggregates: encji Aggregate, która zaimportowała podmoduł — dla podmodułu importowanego bezpośrednio jest to Aggregate wdrażany przez encję Release, a dla zagnieżdżonego własny dokument importującego podmodułu. Diagnostyka nazywa ten wpis kluczem, którym zapisuje go dokument importujący, więc dla zagnieżdżonego podmodułu jest to nazwa lokalna, a nie ścieżka z kropkami.

Dwa przypadki celowo nie przerywają budowania. Podmoduł niewnoszący żadnych komponentów nie ma czego umieszczać. Podmoduł, którego przełącznik active: rozwiązuje się do false, nigdy nie został złożony, więc nie istnieje żaden jego komponent do umieszczenia.

Częściowe umieszczenie nie przerywa budowania według tej reguły: podmoduł jest umieszczony, gdy którykolwiek z jego komponentów trafi do granicy, więc nazwanie jednego z nich spełnia warunek dla podmodułu. Nie wynika z tego, że resztę można pominąć. Każdy komponent, którego granica nie nazwała, nie jest wtedy umieszczony przez nic, a reguła dla komponentów poniżej zgłasza go pod jego własnym kluczem — więc częściowo umieszczony podmoduł przerywa budowanie raz dla każdego pominiętego komponentu, a nie na poziomie podmodułu. Dwa zapisy umieszczające cały podmoduł w jednej linii to wpis kierujący i nazwanie każdego komponentu; wszystko pomiędzy umieszcza to, co nazywa, i nic więcej.

Komponent, którego encja Release nigdzie nie umieszcza, również przerywa budowanie, o jeden poziom głębiej. Powyższa reguła sprawdza, czy podmoduł trafił do granicy; ta sprawdza to samo dla każdego komponentu w kompozycji. Komponent trafia do granicy, gdy jest nazwany w components: tej granicy albo znajduje się w podmodule, który granica kieruje do siebie. Komponent nieosiągający żadnej z tych dróg byłby renderowany poza każdą granicą zadeklarowaną przez encję Release, przejmując directory, subDirectory, syncWave, kaskadę adnotacji i infra: dla komponentu znikąd — więc budowanie zostaje zatrzymane i nazywa komponent, zamiast emitować artefakty, do których konfiguracja granic nigdy nie dotarła.

Obie reguły dzielą obszar, pytając o podmoduł komponentu, a nie jedynie o to, czy komponent go ma. Komponent podmodułu, którego encja Release nigdzie nie umieściła, podlega regule dla podmodułów, która zgłasza ten jeden błąd autorski raz, przy wpisie aggregates:, a nie raz na każdy komponent modułu. Komponent podmodułu umieszczonego częściowo podlega tej regule, ponieważ reguła dla podmodułów traktuje taki moduł jako umieszczony i nic o nim nie mówi — więc każdy komponent, którego granica nie nazwała, jest zgłaszany tutaj, pod jego własnym kluczem w dokumencie, który go deklaruje. Częściowe umieszczenie podmodułu nazywa zatem dokładnie to, co zamierzano nazwać, i informuje o każdym komponencie, którego nie nazwano.

Również wpis granicy nazywający komponent, którego wdrażany Aggregate nie zawiera, przerywa budowanie. Dwie powyższe reguły odczytują umieszczenie od strony komponentu — czy coś go umieściło. Ta odczytuje je od strony encji Release: czy nazwa się rozwiązuje. Wpis, który rozwiązuje się do niczego, niczego nie umieszcza, więc jego subDirectory, adnotacje, infra: dla komponentu i uses: konfigurują komponent, którego nie ma, a budowanie zostaje zatrzymane, zamiast emitować wdrożenie, do którego wpis nigdy nie dotarł. Sprawdzane są oba zapisy: nazwa w components: granicy jest odczytywana jako identyfikator, który komponent ma po zakończeniu kompozycji, a nazwa w components: wpisu kierującego jako nazwa lokalna, którą ma w tym podmodule. Diagnostyka podaje identyfikator zaadresowany przez wpis, który w zapisie kierującym nie jest nazwą z pliku — plik zapisuje lokalną połowę, a podmoduł dostarcza jej prefiks.

Nazwa jest odrzucana za to, że rozwiązuje się do niczego, a nigdy za swoją postać: nazwa z kropkami jest czymś zwykłym, ponieważ komponent o jeden moduł głębiej nosi prefiks tego modułu. Komponent, którego przełącznik active: rozwiązuje się do false, nadal może być nazywany — wyłączenie komponentu nie wymaga edycji encji Release, która go konfiguruje.

Podsystem nie wnosi niczego do kwalifikowanej ścieżki, więc granica adresuje komponent jego samą nazwą, niezależnie od tego, jak encja Aggregate go grupuje. Tylko kompozycja podmodułów kwalifikuje identyfikator. Komponent wdrażanej encji Aggregate to store niezależnie od tego, czy autor zapisał go na najwyższym poziomie, czy wewnątrz podsystemu o nazwie data; komponent o jeden moduł głębiej to data.store, a data jest tam prefiksem modułu, a nie jakiegokolwiek podsystemu. Wpis granicy zapisany jako data.store dla komponentu znajdującego się w podsystemie o nazwie data niczego więc nie adresuje: sam wpis przerywa budowanie według powyższej reguły, a komponent, dla którego był przeznaczony, również nie trafia do żadnej granicy. Poprawienie wpisu na store rozwiązuje oba problemy.

Umieszczenie podmodułu wymaga więc boundaries:. Forma z jednym zakresem nie ma powierzchni routingu — aggregates: jest kluczem granicy, a nie spec: — a mapa components: najwyższego poziomu przyjmuje tylko nazwy niekwalifikowane, dlatego encja Release wdrażająca encję Aggregate, która importuje podmoduły, deklaruje boundaries:.

Routing rekurencyjny. aggregates: jest rekurencyjne — każdy wpis pod aggregates: granicy może sam zadeklarować zagnieżdżoną mapę aggregates: na potrzeby głęboko zagnieżdżonej kompozycji modułów.

Blok routingu dla poszczególnych agregatów. Wpis routingu przyjmuje dokładnie dwa klucze i nic więcej: components:, służący do konfigurowania poszczególnych komponentów danego podmodułu, oraz zagnieżdżony aggregates: dla modułów zagnieżdżonych głębiej. annotations: należy do granicy, a infra: dla poszczególnych komponentów należy do wpisu pod własnym components: wpisu routingu.

We wpisie kierującym komponent jest kluczowany nazwą, którą nosi wewnątrz swojego podmodułu — consumer, a nie data.consumer — ponieważ to jedyna nazwa, jaką tam ma. Kwalifikowana ścieżka z kropkami to sposób, w jaki własna mapa components: granicy adresuje ten sam komponent; oba zapisy nie są wymienne, a wpis kierujący odrzuca klucz z kropkami.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

Własne komponenty i Features podagregatu nie są ponownie deklarowane w encji Release — Release je kieruje, zamiast je powtarzać, i nazywa któryś z nich tylko po to, by go skonfigurować.

Sekwencjonowanie w czasie — syncWave na poziomie granicy

Każda granica w encji Release może opcjonalnie deklarować pole całkowitoliczbowe syncWave:, które daje operatorowi jawną kontrolę nad kolejnością wdrażania bez ingerowania w encję Aggregate dewelopera. Numer fali jest właściwością samej granicy; każdy komponent zawarty w poddrzewie granicy dziedziczy wartość fali swojej granicy podczas emisji artefaktów.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Semantyka wartości fali. syncWave: jest liczbą całkowitą ze znakiem (dodatnią, zerową lub ujemną). Gdy pole zostanie pominięte, wartością domyślną jest 0. Wartości fali nie są dziedziczone z nadrzędnej granicy — każda granica, która ma mieć falę inną niż domyślna, deklaruje ją jawnie. Components nie mogą nadpisać fali swojej granicy (fala jest właściwością jednostki przestrzennej, a nie poszczególnych komponentów).

Emisja dla poszczególnych dostawców. Kompilator emituje wartość fali granicy do wyrenderowanego wyniku w formie natywnej dla dostawcy. Trzy z tych form omówiono poniżej; działanie fali u każdego dostawcy z biblioteki standardowej, łącznie z terraform, zestawiono w tabeli w providers/reference-matrix.md „What a boundary’s syncWave does on each provider”.

  • Kubernetes (provider helm / helm-chart). Gdy fala jest różna od 0, każdy zasób Kubernetes renderowany dla granicy przez provider helm otrzymuje standardową dla GitOps adnotację argocd.argoproj.io/sync-wave: "<N>"; hooki Helm dodatkowo otrzymują adnotację helm.sh/hook-weight: "<N>", dzięki czemu ta sama wartość fali steruje własną kolejnością pre/post-install w Helm. ArgoCD odczytuje adnotację sync-wave, a Helm wagę hooka, i każde z nich odpowiednio porządkuje stosowanie zasobów. Provider helm-chart kopiuje szablony źródłowego chartu tak, jak napisał je ich autor, więc własne zasoby sub-chartu mają falę tylko tam, gdzie zapisują ją te szablony; dodawany przez niego artefakt ładowany przez $import: ma argocd.argoproj.io/sync-wave, a nie ma helm.sh/hook-weight (zob. providers/helm-chart.md).
  • Compose. Każda usługa w pliku compose, do którego renderuje granica, czeka, poprzez depends_on, na usługi bezpośrednio poprzedzającej fali, które trafiły do tego samego pliku — z warunkiem na stan zdrowia celu, jeśli cel deklaruje healthcheck, a na jego uruchomienie, jeśli nie deklaruje. Fala porządkuje więc usługi jednego pliku i nic poza nim: granice renderujące do osobnych plików docker-compose.yaml są osobnymi projektami compose, a ich sekwencjonowanie należy do operatora. Krawędzie uses: nadal wyrażają kolejność na poziomie krawędzi obok fali. Zobacz providers/compose.md.
  • CloudFormation. Każdy zasób w złożonym szablonie stosu zależy, poprzez DependsOn, od zasobów bezpośrednio poprzedzającej fali, które trafiły do tego samego stosu — fala ustala więc kolejność, w jakiej zasoby są tworzone, a w odwrotnym porządku kolejność, w jakiej są usuwane. Nie jest to porządkowanie według gotowości: szablon stosu nie zna pojęcia zasobu gotowego do obsługi. Własne DependsOn fragmentu jest rozszerzane, a nie zastępowane. Components, które składają się w inny stos, są poza zasięgiem, a sekwencjonowanie dwóch stosów należy do operatora. Zobacz providers/cloudformation.md.

Jednostka definiowania fal a jednostka wdrażalna. Granica jest jednostką definiowania fal. Jednostką wdrażalną jest ścieżka złożenia, do której emitują komponenty — domyślnie 1:1 z granicą, ale dwie granice siostrzane współdzielące directory: łączą się w jeden złożony wynik (jeden Chart.yaml, jeden docker-compose.yaml). W takim przypadku złożony wynik może zawierać zasoby z wielu fal; Application ArgoCD odczytująca go porządkuje w obrębie Application każdy zasób według adnotacji sync-wave, którą ten zasób ma — w helm każdy zasób renderowany dla niezerowej fali, a w helm-chart tylko artefakt ładowany przez $import:, przy czym własne szablony sub-chartu zawierają to, co napisał ich autor. Sekwencjonowanie między aplikacjami na różnych ścieżkach należy do CI operatora.

Przypadki użycia. Kolejność fal ma znaczenie wszędzie tam, gdzie uruchomienie jednej granicy zależy od wcześniejszego zakończenia innej. Wzorzec kanoniczny: granica infra w fali 0 (VPC + baza danych), granica migrations w fali 1 (zadanie migracji schematu) i granica apps w fali 2 (aplikacja korzystająca z zmigrowanego schematu). Bez jawnych fal wszystkie trzy wdrażają się jednocześnie, a aplikacja wpada w pętlę awarii, czekając na zakończenie migracji.

Pełne ujęcie architektoniczne — model wykonania DAG, uzasadnienie umieszczenia sekwencjonowania w czasie w encji Release, a nie w encji Aggregate, oraz rozróżnienie między jednostką definiowania fal a jednostką wdrażalną — opisano w architecture/12-day-two-lifecycles.md §1.

Dołączanie encji Feature

Encja Release może dołączać encje Features zarówno w zakresie granicy (szeroka polityka), jak i w zakresie konkretnego komponentu (precyzyjne wskazanie), a wykonanie przebiega zgodnie z pięciowarstwowym modelem cebuli zdefiniowanym w architecture/10-compilation-pipeline.md. Encje Features zadeklarowane w encji Release wnoszą type, infra i uses; nie mogą deklarować values (zob. Ograniczenia na poziomie schematu powyżej).

Encja Feature dołączona na granicy jest kluczowana wybraną nazwą instancji i ta nazwa nie może być . ani ... W providerze, który daje każdemu współtwórcy własny katalog — terraform w modules/ i helm-chart w charts/ — pliki encji Feature dołączonej na poziomie granicy są zapisywane w katalogu nazwanym wyłącznie nazwą instancji, a żadna z tych dwóch nazw nie jest osobnym katalogiem: kompilacja zatrzymuje się, wskazując encję Release, granicę i instancję. Nazwa, która jedynie zawiera kropki, np. audit.v2, jest zwykłą nazwą.

features: jest jedyną powierzchnią dołączania w encji Release, w obu zakresach — tak samo jak w encji Aggregate. Poświadczenie to encja Feature z etykietą feature.aggrega.ai/kind: secret, więc poświadczenie dołączane przez operatora dołącza się w features: jak każdą inną encję Feature i wskazuje ono swój sekret w infra dokładnie tak jak poświadczenie na połączeniu (zob. Konfiguracja połączenia dla poszczególnych krawędzi) — na komponencie, który encja Aggregate pozostawiła bez niego, albo jako wymiarowanie dołączenia, które encja Aggregate zadeklarowała bez wskazania sekretu. W żadnym zakresie nie ma drugiego słowa kluczowego dołączania; dokument, który je deklaruje, jest odrzucany przy wczytywaniu z błędem koperty wskazującym nieoczekiwaną właściwość.

Funkcja dołączona do całej granicy może zawierać blok uses:, który jest rzutowany na każdy komponent skierowany do tej granicy: każdy komponent zyskuje krawędź zależności do wskazanych celów funkcji i otrzymuje wstrzyknięte provides tych celów. Pozwala to wyrazić wspólną zależność raz, na granicy — „każdy komponent w tej granicy komunikuje się ze wspólnym cache / kolektorem / magistralą komunikatów” — zamiast powtarzać tę samą krawędź uses: w każdym komponencie. Dołączenie encji Feature na poziomie podsystemu w encji Aggregate rzutuje swoje uses: w ten sam sposób na komponenty podsystemu. uses jest deklaracją okablowania topologii, a nie wartością, dlatego jest dozwolone w encji Release. Rzutowanie jest niezależne od zakresu wykonania dołączonej encji Feature: encja Feature, której FeatureRecipe renderuje się raz na granicę, nadal rzutuje swoje uses: na każdy komponent, podczas gdy sam wspólny zasób renderuje się raz.

Funkcja dołączona do pojedynczego komponentu zawiera ten sam blok uses: i tworzy tę samą krawędź z tego jednego komponentu: komponent zyskuje krawędź zależności do każdego wskazanego celu, otrzymuje wstrzyknięte provides tych celów, a krawędź zapisuje dołączenie jako swoje źródło dokładnie tak jak w formie dla całej granicy. Obie formy to jedna deklaracja o dwóch zasięgach — dołączenie na granicy łączy każdy komponent w niej, dołączenie na komponencie łączy tylko ten jeden — a wybór między nimi jest kwestią zasięgu, nigdy tego, co robi okablowanie. Żadna z nich nie tworzy zasobów obliczeniowych: cel musi już wskazywać komponent zadeklarowany przez encję Aggregate, a cel, który tego nie robi, zatrzymuje kompilację. Połączenie utworzone przez encję Feature nie ma własnych dołączeń: jego wpis przyjmuje target i inject, a klucz features: w tym miejscu jest odrzucany przy wczytywaniu encji Release.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Jak zapisuje się cel. Cel krawędzi wskazuje komponent złożonego grafu, dlatego zapisuje się go kwalifikowaną ścieżką z kropkami — data.store, a nie store — zawsze gdy cel należy do skierowanego podmodułu. Dotyczy to także sytuacji, w której samo dołączenie znajduje się pod wpisem routingu, którego klucze components: są lokalne dla modułu: klucz określa, na którym komponencie jest dołączenie, a cel określa, do którego komponentu sięga krawędź, i tylko to drugie jest nazwą obowiązującą w całym grafie. Cel zapisany nazwą lokalną dla modułu nie pasuje do żadnego komponentu i zatrzymuje kompilację z tą samą diagnostyką, jaką daje każda wisząca krawędź.

Złożona encja Release i dziedziczenie przez extends:

Encja Release może zadeklarować spec.extends:, wskazując bazową encję Release, której powierzchnię autorską dziedziczy.

Odwołanie jest ścieżką do pliku obok deklarującej encji Release — ./base-release.yaml lub ../shared/base-release.yaml. Encja Release należy do strony wdrożeniowej i nie jest indeksowana w katalogu, więc odwołanie extends: nigdy nie jest rozwiązywane przez katalog. Ścieżka względna to jedyna akceptowana forma: odwołanie zapisane jako współrzędna rejestru jest odrzucane, podobnie jak sama nazwa, a w obu przypadkach diagnostyka wskazuje formę ścieżki względnej. extends: encji Manifest to bliski odpowiednik, który działa inaczej — przyjmuje ścieżkę względną lub samą wartość metadata.name encji Manifest leżącej obok encji Release — więc obie formy nie są wymienne, a sama nazwa, która zostałaby rozwiązana w encji Manifest, tutaj nie zostanie rozwiązana. Każde ogniwo łańcucha jest odczytywane tak samo: nadrzędna encja Release przechowywana w innym katalogu wskazuje własnego rodzica ścieżką względem siebie, niezależnie od tego, gdzie leży wskazana encja Release, dokładnie tak, jak jej $import: parametrów jest rozwiązywany względem niej. Ścieżka musi prowadzić do encji Release wewnątrz obszaru roboczego, jak każda ścieżka zapisana w encji Release — lub, dla encji Release wskazanej spoza obszaru roboczego, wewnątrz katalogu zawierającego tę encję Release, czego przestrzega każde ogniwo jej łańcucha: ścieżka, która z niego wychodzi lub którą ogniwo wyprowadza na zewnątrz, jest odrzucana przed odczytaniem wskazanego pliku.

Kompilator podąża za łańcuchem podczas ładowania encji Release — odrzucając łańcuch, który wraca do pliku już w nim obecnego, łańcuch przekraczający limit głębokości oraz odwołanie, które niczego nie wskazuje — a następnie składa łańcuch w jedną rozwiązaną encję Release.

To, co odziedziczone, można zastępować klucz po kluczu. Własna wartość wygrywa na każdym poziomie, aż do wartości stanowiącej niepodzielną całość — skalara, listy, szablonu — którą przyjmuje się lub zastępuje w całości. Odziedziczony element usuwa się, zapisując go jako null. Tę samą zasadę stosują rozszerzające encje Component, Feature i Manifest, więc autor, który poznał jedną, poznał wszystkie.

W odniesieniu do encji Release: boundaries składają się według nazwy granicy, a granica według klucza, components według nazwy komponentu, infra głęboko, features według nazwy instancji, a następnie według filaru; uses komponentu według gniazda, a następnie według połączenia, przy czym target zapisany przez potomka zastępuje odziedziczony, infra połączenia składa się klucz po kluczu, a jego features składają się według slotu, a następnie według filaru, zgodnie z tą samą zasadą co własne features komponentu; directory, subDirectory, syncWave oraz wskaźniki Aggregate i Manifest to skalary, które są zastępowane.

Dwie rzeczy nie są przenoszone:

  • Tożsamość i pochodzenie. Żadne pole metadata nie jest dziedziczone. Warto znać metadata.environment: jest wymagane w każdej encji Release i z natury dotyczy pojedynczej encji Release, więc potomek renderuje się z własnym środowiskiem w etykietach pochodzenia, a nie ze środowiskiem rodzica.
  • Wskaźnik Aggregate jest dziedziczony, a nie nadpisywalny. Potomek nie może zadeklarować aggregate: — schemat odrzuca extends: i aggregate: w jednym dokumencie — więc potomek wdraża tę samą intencję dewelopera co jego baza.

Potomek może pominąć manifest:, dziedzicząc go z bazy, lub nadpisać go na potrzeby późnego wiązania.

Jeden kształt routingu w całym łańcuchu. boundaries: i components: wykluczają się wzajemnie w obrębie jednej encji Release i dotyczy to także łańcucha: baza deklarująca nazwane granice i potomek deklarujący komponenty najwyższego poziomu są odrzucane, a diagnostyka wskazuje oba pliki i oba klucze. Należy wybrać jeden kształt routingu i stosować go na całej długości łańcucha.

Wzorzec mostu do lokalnego developmentu. Kanonicznym przypadkiem użycia jest deweloper uruchamiający lokalnie produkcyjną encję Aggregate swojego zespołu bez forkowania encji Aggregate i bez powielania topologii granic. Zespół publikuje produkcyjną encję Release; lokalna encja Release robi na niej extends: i nadpisuje jedynie wskaźnik Manifest, zamieniając encje Recipes przeznaczone dla chmury na lokalne odpowiedniki:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release dziedziczy topologię granic bazy, dołączenia encji Feature i nadpisania komponentów; deweloper utrzymuje jeden plik local-release.yaml i uruchamia aggrega build --release local-release.yaml bez powielania konfiguracji produkcyjnej.

directory: należy zapisywać względem parametru. Ponieważ katalog jest dziedziczony jak każdy inny skalar, potomek dziedziczący katalog bez zmiennej szablonu renderuje się do tej samej ścieżki co jego baza i żadna opcja wiersza poleceń tego nie przekierowuje. Jest to uprawnione, jeśli taki był zamiar — na przykład przy zamianie samych encji Recipes w celu porównania ich wyniku — więc kompilacja to zgłasza i kontynuuje, zamiast odmawiać. Zapisanie katalogu względem parametru, jak powyżej, utrzymuje topologię w jednym miejscu, a mimo to kieruje wynik każdej encji Release w osobne miejsce.

Wieloplikowe warstwowanie parametrów. Dziedziczenie encji Release jest właściwym miejscem na wieloplikowe warstwowanie parametrów. Bazowa encja Release dostarcza wspólny zestaw parametrów; potomkowie dla poszczególnych środowisk robią extends: na bazie i nadpisują różniące się sloty:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Każdy potomek widzi parametry odziedziczone z bazy scalone z własnymi. Parametry o wartościach mapowych są scalane głęboko, przy czym wygrywa klucz potomka; parametry skalarne są zastępowane przez potomka; klucz zapisany przez potomka jako null jest usuwany, a nie ustawiany na pustą wartość.

Baza może importować parametry, a potomek nadal może nadpisywać poszczególne klucze. Dwa tryby autorskie opisane powyżej w parameters: — inline lub pojedynczy $import: — to zasada dotycząca jednego dokumentu, a nie łańcucha: każda encja Release w łańcuchu deklaruje jeden lub drugi tryb, a import każdej z nich jest rozwiązywany względem katalogu zawierającego tę encję Release, zanim łańcuch zostanie złożony. Zatem baza importująca wspólny plik i potomek zapisujący kilka kluczy inline składają się według klucza, dokładnie tak jak dwa bloki inline:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Tryby błędów. Cykliczne łańcuchy extends:, brakujące wskaźniki rodzica i deklaracje aggregate: po stronie potomka zatrzymują ładowanie obszaru roboczego z jawną diagnostyką wskazującą problematyczną encję Release i naruszenie na poziomie schematu. Kształty komunikatów poszczególnych błędów opisano w errors/fatal-halts.md.