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

Aggregate

Koncepcyjna rola encji Aggregate (Domena 1 — deklaratywny plan topologii tworzony przez programistę) jest opisana w architecture/04-entity-taxonomy.md. Wzorce kompozycji (podsystemy, zagnieżdżone agregaty, Zero-Port Convention, Parameter Hoisting) są opisane w architecture/06-data-taxonomy-and-composition.md. Ta strona omawia sposób tworzenia encji Aggregate na potrzeby katalogu — w szczególności tworzenie wielokrotnego użytku modułów Aggregate przeznaczonych do dystrybucji w katalogu.

Zakres encji Component: domyślny podsystem

Encja Aggregate organizuje komponenty w podsystemy — nazwane grupy dla zagadnień przekrojowych (warstwa danych, warstwa brzegowa), które mają własną kaskadę adnotacji. Większość encji Aggregates ma jedną grupę, więc nie wymaga ona żadnej ceremonii.

Pojedynczy zakres (domyślnie). Komponenty należy definiować bezpośrednio pod spec.components: i pominąć blok subsystems::

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Kompilator włącza je do syntetyzowanego podsystemu default. Tożsamość węzłów się nie zmienia — api pozostaje api, nigdy default.api — dlatego encja Aggregate zdefiniowana w ten sposób jest wymienna z jawną postacią z jednym podsystemem, a odwołania do niej (w celach uses:, w diagnostyce) używają samej ścieżki spec.components.<name>. Syntetyzowany zakres jest rzetelnie zapisywany w eksportowanym IR (ze znacznikiem syntetyzowanego podsystemu), ale nigdy nie pojawia się w ścieżkach, które autor zapisuje lub odczytuje.

Wiele zakresów. Gdy komponenty dzielą się na odrębne grupy przekrojowe, należy zadeklarować nazwane podsystemy pod subsystems:. Każdy podsystem ma własne komponenty i kaskadę adnotacji oraz może zawierać kolejne zagnieżdżone podsystemy.

Wzajemne wykluczanie. spec.components: i spec.subsystems: wykluczają się wzajemnie na poziomie głównym encji Aggregate — należy użyć jednego albo drugiego, nigdy obu. Dokument deklarujący oba zatrzymuje się przy wczytywaniu z błędem koperty. (Podsystem, któremu programista jawnie nada nazwę default, jest zwykłym zadeklarowanym podsystemem, adresowanym pełną ścieżką spec.subsystems.default.components.<name> — pomijanie syntetyzowanego zakresu zależy od pochodzenia, a nie od nazwy.)

Moduły Aggregate wielokrotnego użytku

Encje Aggregates pełnią zarówno rolę głównej encji Aggregate budowanej przez encję Release, jak i modułów wielokrotnego użytku. Nadrzędna encja Aggregate może zadeklarować podrzędną encję Aggregate dokładnie tak jak komponent, przekazując do niej parameters. Aby uniknąć ścisłego powiązania, podrzędne encje Aggregates udostępniają kontrakt exportedComponents:, ustanawiający stabilną nazwę interfejsu publicznego. Element nadrzędny dociera do komponentów modułu wyłącznie przez ten interfejs: cel uses: to nazwa modułu, kropka i jeden z jego wyeksportowanych aliasów, a kompilator podłącza krawędź do wewnętrznego komponentu wskazanego przez alias. Cel, który sięga do modułu pod jakąkolwiek inną nazwą — nazwą komponentu wewnątrz modułu albo ścieżką do modułu zagnieżdżonego w nim — zatrzymuje kompilację, wskazując moduł i eksportowane przez niego aliasy; zob. A uses target names a module’s component the module does not export (Cel wskazuje komponent modułu, którego moduł nie eksportuje).

Dlaczego jawna lista exportedComponents:. Autorzy modułu decydują, które z jego komponentów tworzą interfejs publiczny, a które pozostają szczegółem implementacji. Ponieważ element nadrzędny może wskazać tylko to, co lista publikuje, wnętrze modułu można refaktoryzować — zmienić nazwę komponentu, podzielić jeden komponent na dwa, zastąpić workera usługą zarządzaną — nie psując żadnego elementu nadrzędnego, o ile każda opublikowana nazwa nadal wskazuje komponent. Lista kosztuje jeden wpis na każdy publikowany komponent, a komponent można opublikować pod jego własną nazwą (store: store), jeśli to tej nazwy mają używać importujący. Ta sama reguła obowiązuje wewnątrz kompozycji: moduł dociera do importowanego modułu przez wyeksportowane aliasy tego modułu. Encja Release może połączyć ze sobą dwa komponenty jednego modułu, ponieważ takie połączenie nie przekracza interfejsu żadnego modułu.

Ponowny eksport interfejsu zagnieżdżonego modułu. Wpis exportedComponents: może wskazywać na eksportowany alias zagnieżdżonego podagregatu zamiast na bezpośrednio zadeklarowany komponent — moduł ponownie publikuje wtedy część importowanego modułu pod nazwą własnego interfejsu, opcjonalnie pod nową nazwą. Krawędź uses: kierowana na taki ponownie eksportowany alias rozwiązuje się przechodnio przez łańcuch aż do konkretnego węzła wewnętrznego, dzięki czemu moduł włącza głębsze moduły do własnego interfejsu publicznego bez ujawniania ich wewnętrznego układu, a konsument nigdy nie musi wiedzieć, jak głęboko zagnieżdżony jest cel. Dyscyplina stabilnego interfejsu obowiązuje na każdym kroku: każdy moduł ponownie eksportuje tylko to, co sam zdecyduje się opublikować. Ponownie eksportowany cel, który nie rozwiązuje się do żadnego węzła wewnętrznego, zatrzymuje kompilację z wyraźnym błędem tak samo jak bezpośredni wiszący cel, a łańcuch ponownych eksportów zamykający się na sobie jest odrzucany, a nie śledzony w nieskończoność.

Deklaracje modułu są sprawdzane tak samo jak deklaracje encji Aggregate. Dokument modułu jest odczytywany dopiero wtedy, gdy budowana jest kompozycja, która go importuje, a jego deklaracje są od tego momentu sprawdzane na dowolnej głębokości zagnieżdżenia. Własny blok inject: komponentu modułu podlega liście dozwolonych spec.inject jego typu oraz regułom zakazującym dwukrotnego zajęcia jednego klucza dostarczania i odczytywania klucza, którego typ nie publikuje. Dołączenie zapisane w jednym z własnych podsystemów modułu może wskazywać tylko gniazdo deklarowane przez jego encję Feature; to samo dotyczy dołączenia, które encja Release zapisuje względem komponentu wniesionego przez moduł.

Dołączenia podsystemów modułu docierają do jego komponentów. Encja Feature, którą moduł dołącza w jednym z własnych podsystemów, kaskadowo obejmuje każdy komponent deklarowany przez moduł pod tym podsystemem, łącznie z zagnieżdżonymi podsystemami, dokładnie tak jak dołączenie podsystemu w encji Aggregate — i tylko te komponenty, nigdy komponent importującej encji Aggregate znajdujący się pod podsystemem o tej samej nazwie. Jest ono wartościowane bezpośrednio po własnych dołączeniach komponentu, podsystemy zewnętrzne przed wewnętrznymi. W polu zapisanym przez oba wygrywa własne dołączenie komponentu o tej samej nazwie, a pola, które ono pomija, zachowują wartości podsystemu. Każdy komponent, do którego dociera, sprawdza je względem appliesTo encji Feature. Ustalenie dotyczące własnych deklaracji modułu wskazuje moduł i klucz w jego dokumencie — na przykład .spec.subsystems.<subsystem>.features.<attachment> — więc poprawkę wprowadza się w module, w którym znajduje się deklaracja, a nie w importującej go encji Aggregate.

Położenie w katalogu

Moduł Aggregate wielokrotnego użytku znajduje się w katalogu rodzaju aggregate/ pod ścieżką, którą segment po segmencie wyznacza jego metadata.name, z katalogiem wersji na końcu:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Nazwa modułu może zaczynać się od segmentu {publisher} określającego dostawcę lub autora — core dla biblioteki standardowej, acme dla przedsiębiorstwa — i tak właśnie nazwane są opublikowane moduły biblioteki standardowej: core/agenta znajduje się w aggregate/core/agenta/1.0.0/aggregate.yaml. Nazwa złożona z jednego tokenu leży o jeden poziom płycej, w aggregate/{module-name}/{version}/aggregate.yaml. Obie formy są poprawne; nazwę zapisuje autor, a katalog ją odzwierciedla. To odzwierciedlenie jest konwencją katalogu, a nie czymś, co sprawdza kompilator — moduł jest odnajdywany po deklarowanej nazwie, a nie po położeniu pliku.

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, małymi literami — moduł o nazwie core/agenta jest więc publikowany pod hub.aggrega.ai/aggregate/core/agenta:1.0.0, a moduł o nazwie db-module pod hub.aggrega.ai/aggregate/db-module:1.0.0.

Wzorzec modułu

Moduł podrzędny (aggregate/child-database-module/1.0.0/aggregate.yaml, opublikowany jako hub.aggrega.ai/aggregate/child-database-module:1.0.0):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"

Nadrzędna encja Aggregate:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Etykiety modułu

Gdy encja Aggregate jest publikowana w katalogu jako moduł wielokrotnego użytku, może nosić metadata.labels w swojej kopercie YAML — na przykład aggregate.aggrega.ai/tier: infrastructure lub aggregate.aggrega.ai/compliance: pci-dss. Etykiety te opisują tożsamość modułu i są przenoszone w opublikowanym dokumencie modułu; żadne polecenie jeszcze ich nie odczytuje. Wyszukiwanie w katalogu nie indeksuje encji Aggregates, a graf kompilacji nie przenosi ani etykiet modułu, ani jego nazwy katalogowej, więc polityka zarządcza nie może wybierać komponentów według modułu, z którego pochodzą.

Kluczowe rozróżnienie. Etykiety encji Aggregate opisują tożsamość modułu wielokrotnego użytku w katalogu. Nie przechodzą kaskadowo na podrzędne węzły komponentów. Etykiety komponentów pochodzą wyłącznie z encji katalogowej Component w Domenie 2. Jeśli programista importuje moduł oznaczony aggregate.aggrega.ai/tier: infrastructure, poszczególne komponenty w tym module zachowują tylko własne etykiety zdefiniowane w katalogu (np. component.aggrega.ai/type: stateful-server). Etykieta encji Aggregate nigdy nie jest wstawiana do słownika labels węzła IR.

Pełne omówienie złożonych Aggregates i wzorca modułu (w tym zasady braku podkomponentów dla Components) oraz mechanizmu przekrojowego grupowania subsystems zawiera architecture/06-data-taxonomy-and-composition.md §6. Powierzchnię tworzenia typowanego kontraktu parameters opisuje vocabulary/data-pillars.

Typowane kontrakty parametrów

Blok spec.parameters: encji Aggregate deklaruje typowany kontrakt dla parametrów, które wypełnia encja Release. Każdy slot parametru ma zadeklarowany type, opcjonalny description, opcjonalny default, opcjonalne ograniczenia przestrzeni wartości oraz (w slotach typu obiektowego) zagnieżdżoną strukturę. Kompilator podczas rozwiązywania sprawdza każdą wartość dostarczoną przez encję Release względem kontraktu, zanim nastąpi interpolacja parametrów.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Cudzysłowy w każdym odwołaniu są celowe: to one decydują o typie, z jakim dociera wyniesiona wartość. Zob. templates/parameters-context.md.

Słownik slotów parametrów

Typowany blok parameters: przyjmuje słownik formy kompaktowej: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate i validateMessage (niestandardowe sprawdzenie i komunikat, który zgłasza), items (dla tablic), properties (dla obiektów), valuesType (dla map wartości typowanych) oraz required: true (znacznik na poziomie slotu). Trzy z tych słów kluczowych przyjmują jako wartość kontrakt, a nie zwykłe ustawienie — items, valuesType i każdy wpis w properties — a w slocie parametru taki zagnieżdżony kontrakt zapisuje się w tej samej typowanej formie co otaczający go slot: valuesType: { type: boolean }, a nie valuesType: boolean. Przed interpolacją kompilator sprawdza scaloną mapę parametrów bezpośrednio względem tych deklaracji: parametr niezadeklarowany w żadnym slocie jest odrzucany, slot oznaczony required: true, którego nie wypełnia encja Release ani nie dostarcza default, zatrzymuje kompilację, a każda dostarczona wartość jest sprawdzana względem zadeklarowanego type slotu, przynależności do enum, granic minLength i maxLength, wyrażenia regularnego pattern i format w slocie tekstowym oraz granic min i max — wartości slotu liczbowego, długości slotu tekstowego i liczby elementów slotu tablicowego. Sloty obiektowe i tablicowe są sprawdzane rekurencyjnie: każdy wpis w properties i każdy element względem items sprawdza się tak samo, kontrakt valuesType obejmuje klucze, których properties nie wymienia, a zagnieżdżony klucz niewymieniony w żadnej deklaracji jest odrzucany. Pełny słownik słów kluczowych, w tym miejsca, w których filar schema: zapisuje te słowa kluczowe inaczej, opisuje vocabulary/compact-form-authoring.md.

Poniższe słowa kluczowe są sprawdzane także w samej deklaracji, zanim zostanie odczytana jakakolwiek wartość encji Release, więc slot, który nie mógłby niczego ograniczać, zatrzymuje kompilację nawet wtedy, gdy żadna encja Release go nie wypełnia:

  • Granice długości są równe zero lub większe. Ujemny minLength lub maxLength we własnej deklaracji parametru jest odrzucany przez schemat encji Aggregate podczas jej ładowania, z podaniem parametru i klucza. Wewnątrz zagnieżdżonego kontraktu — w items, properties lub valuesType — granica długości jest odczytywana tak, jak ją zapisano, i podczas ładowania encji Aggregate nie jest sprawdzana względem tego minimum, dlatego również tam należy zapisywać ją jako zero lub więcej: ujemny minLength niczego nie narzuca, a ujemny maxLength odrzuca każdą wartość.
  • min i max muszą coś ograniczać. W slocie logicznym lub obiektowym ta para niczego nie ogranicza, więc min lub max zapisane w nim są odrzucane podczas wczytywania encji Aggregate, ze wskazaniem parametru i klucza.
  • Wzorzec musi się kompilować. Każdy pattern jest kompilowany jako wyrażenie regularne podczas odczytu kontraktu parametrów — w samym slocie i w każdym zagnieżdżonym kontrakcie, na dowolnej głębokości — a taki, który się nie kompiluje, jest odrzucany z podaniem parametru, wzorca i przyczyny. Kontrakt jest odczytywany przy każdej kompilacji, pobraniu i walidacji encji Release, która dociera do encji Aggregate, niezależnie od tego, czy jest to własna encja Aggregate tej encji Release, czy moduł przez nią importowany. Sprawdzenie wartości dopasowuje następnie każdą dostarczoną wartość do tego samego skompilowanego wyrażenia.
  • Format musi być jednym z tych, które sprawdza kompilator. format wskazuje jedną z nazw email, uri, hostname, ipv4, ipv6, uuid, date-time i date, zapisanych tak jak w JSON Schema. Każda inna nazwa — literówka, np. emial, lub nazwa niezdefiniowana w JSON Schema, np. password — jest odrzucana podczas ładowania encji Aggregate, z podaniem parametru i listy obsługiwanych nazw: w samym slocie przez schemat encji Aggregate, a wewnątrz zagnieżdżonego kontraktu, na dowolnej głębokości, podczas odczytu kontraktu parametrów. Dostarczony ciąg, który nie ma wskazanego formatu, jest następnie odrzucany z podaniem parametru, wartości i formatu. Co sprawdza każda nazwa, opisuje vocabulary/compact-form-authoring.md.

Parametry typu obiektowego i tablicowego

Sloty parametrów przyjmują każdy typ obsługiwany przez formę kompaktową, w tym zagnieżdżone obiekty i tablice typowanych elementów:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

Encja Release wypełnia parametry typu obiektowego strukturalnym YAML; kompilator przed interpolacją sprawdza strukturę względem zadeklarowanego schematu. Szablony odwołujące się do pól obiektu używają standardowej składni szablonów Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} itd.

Walidacja kontraktu parametrów

Najpierw, w chwili odczytu, sprawdzany jest sam kontrakt — kontrole ograniczeń długości i wzorców opisane powyżej w sekcji „Parameter slot vocabulary”. Następnie kompilator wykonuje podczas przetwarzania parametrów trzy kroki:

  1. Uzupełnianie wartości domyślnych — sloty ze zdefiniowanym default:, dla których encja Release nie dostarcza wartości, otrzymują wartość domyślną. Parametry będące zagnieżdżonymi obiektami mają trzyprzypadkową semantykę dla pominiętych, jawnie pustych i częściowo wypełnionych slotów nadrzędnych: pominięcie slotu nadrzędnego uzupełnia wartości domyślne slotów podrzędnych, zapisanie slotu nadrzędnego jako {} zachowuje jawną pustą wartość (wyłącza wartości domyślne slotów podrzędnych), a zapisanie slotu nadrzędnego jako niepustej mapy uzupełnia tylko te sloty podrzędne, których encja Release nie dostarczyła. Przykłady YAML i przewodnik „kiedy używać której formy” zawiera templates/parameters-context.md.
  2. Walidacja kontraktu — każda wartość w scalonej mapie, niezależnie od tego, czy dostarczyła ją encja Release, czy uzupełniło ją default:, jest sprawdzana względem zadeklarowanych ograniczeń type / enum / min / max / pattern / struktury zagnieżdżonej. Błędy walidacji zatrzymują kompilację z czytelnym komunikatem wskazującym błędny slot, dostarczoną wartość i naruszone ograniczenie. Brak wymaganego parametru bez default: powoduje podobne zatrzymanie z nazwą slotu.
  3. Interpolacja — kompilator przetwarza cały tekst encji Aggregate jako szablon, zanim odczyta go jako YAML, i zastępuje każde odwołanie {{ .parameters.<slot> }} — zwykle w ciągach values: komponentów / funkcji / podagregatów — rozstrzygniętą wartością; każde inne {{ w tekście również jest odczytywane jako składnia szablonu, więc wartość zawierająca własne podwójne nawiasy klamrowe — na przykład wyeksportowana definicja platformy przepływów — zapisuje każde {{ jako {{"{{"}}, jak opisano w sekcji Tekst zawierający własne podwójne nawiasy klamrowe. Po tym przebiegu powierzchnie szablonów wartości otrzymują już zinterpolowane literały i nie dostają .parameters w swoim kontekście szablonu.

Scalona mapa parametrów pozostaje dostępna przez całe renderowanie, aby umożliwić ewaluację szablonów ścieżek. Tworzone przez operatora szablony directory: i subDirectory: na granicach encji Release odczytują .parameters.<slot> bezpośrednio w czasie renderowania, w ramach zamkniętej listy dozwolonych zmiennych; generowanie ścieżek wymaga słownictwa regionu / środowiska do układu artefaktów per środowisko, a asymetryczne uprawnienie utrzymuje tę kwestię operatora w obrębie powierzchni operatora bez przechodzenia przez values encji Aggregate. Mapa pozostaje czytelna do zakończenia wszystkich faz renderowania i jest osiągalna tylko z kompilacji, dla której została rozstrzygnięta; recepty korzystające z tworzonych przez programistę values: widzą ciągi po interpolacji, natomiast szablony ścieżek widzą bieżące dane .parameters przez całe renderowanie. Macierz dostępności szablonów ścieżek zawiera wiersz 3 w templates/expansion-matrix.md, a listę dozwolonych zmiennych szablonów ścieżek — path-template-variables.md.

Szerszą listę kontrolną przenoszenia parametrów (deklaracja w encji Aggregate → odwołanie w values → wypełnienie w encji Release → użycie w encji Recipe) oraz mechanikę między filarami opisuje vocabulary/data-pillars.md §“Parameters” i §“The parameter-hoisting checklist”. Pola kontekstu szablonu udostępniane podczas interpolacji oraz wyjątek dla szablonów ścieżek opisuje templates/parameters-context.md.

Krawędź uses to wywołanie deklarowane przez encję Aggregate

Krawędź uses to deklaracja encji Aggregate, że jeden komponent wywołuje inny. Kompilator przekazuje do wywołującego wartości publikowane przez cel i niczego nie ogranicza: sama krawędź ani nie wpuszcza wywołującego, ani nie odmawia nikomu innemu, a obciążenie, które dociera pod adres celu bez krawędzi, i tak do niego dociera.

Ograniczenie, kto może wywoływać komponent i co ten komponent może wywoływać, jest decyzją operatora, podejmowaną dla każdego środowiska w encji Release. Gdy encja Release dołącza do komponentu Feature core/caller-allowlist z katalogu biblioteki standardowej, kompilacja zapisuje politykę sieciową wpuszczającą dokładnie te komponenty, których krawędzie uses na niego wskazują, własne pody tego komponentu oraz źródła wskazane w dołączeniu. Jego odpowiednik dla ruchu wychodzącego, core/egress-allowlist, pozwala komponentowi, do którego jest dołączony, docierać wyłącznie do komponentów, na które wskazują jego własne krawędzie uses, do własnych podów, do DNS klastra oraz do zakresów adresów wymienionych w encji Release. Wywołanie, którego encja Aggregate nie deklaruje jako krawędzi, może wtedy zostać odrzucone przez klaster na dowolnym z końców, wszędzie tam, gdzie jego wtyczka sieciowa egzekwuje polityki sieciowe. Dlatego należy zapisać krawędź dla każdego wywołania wykonywanego przez komponenty, także takiego, które nie wstrzykuje żadnej wartości: brakująca krawędź to wywołanie, które odgrodzony komponent może odrzucić. model-server-caller-allowlist pokazuje serwer modelu osiągalny wyłącznie przez stojącą przed nim bramę.

Własne załączniki połączenia: features we wpisie uses

Połączenie, które komponent definiuje w rozwiniętej formie uses:, jest osobnym wpisem i obok target, inject i values może zawierać załączniki w kluczu features:. Każdy z nich jest kluczowany slotem zadeklarowanym przez gniazdo: konsumująca encja Component wymienia w featuresSchema gniazda sloty, które może wypełnić każde połączenie podpięte przez to gniazdo (zob. Gniazda topologii). W ten sposób jeden komponent przechowuje inne poświadczenie dla każdego komponentu, do którego sięga — brama wywołująca dwa modele z dwoma kluczami albo agent przedstawiający modelowi własny klucz.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Załącznik połączenia zawiera type (wymagane), opcjonalny description oraz values dla encji Feature. Nie zawiera uses ani inject: załącznik połączenia nie jest zagnieżdżany, a o tym, jak jego materiał trafia do konsumenta, decyduje encja Recipe konsumującego komponentu, a nie blok inject. Dokument zawierający którykolwiek z tych kluczy jest odrzucany przy wczytywaniu z podaniem nazwy klucza.

Tylko sloty zadeklarowane przez gniazdo. Załącznik pod nazwą, której featuresSchema gniazda nie wymienia, zatrzymuje kompilację przy wczytywaniu, z podaniem połączenia, gniazda, komponentu i slotów, które gniazdo deklaruje — a jeśli nazwa różni się o jedną edycję od któregoś z nich, także tego slotu jako prawdopodobnie zamierzonej pisowni. Wypełniony slot podlega następnie własnej deklaracji slotu na każdym połączeniu: selector, którego etykiety encji Feature nie spełniają, zatrzymuje kompilację na tym wpisie, a slot required pozostawiony pusty na dowolnym połączeniu zatrzymuje ją z podaniem tego połączenia. Gniazdo, które nie deklaruje slotów, nie dopuszcza żadnego załącznika na swoich połączeniach; podobnie gniazdo ad hoc — takie, które encja Aggregate podpina bez deklaracji w encji Component — ponieważ nie deklaruje żadnych slotów. Komponent wniesiony przez podmoduł podlega tej samej regule, a komunikat wskazuje na własny dokument podmodułu. Zob. A connection carries an attachment under a name its socket declares no slot for (Połączenie zawiera załącznik pod nazwą, dla której jego gniazdo nie deklaruje slotu).

Połączenie definiowane przez encję Feature nie zawiera żadnych załączników. Własny blok uses: dołączonej encji Feature — na komponencie lub na podsystemie — ma ten sam kształt, ale przy wczytywaniu dokumentu odrzuca features:. Poświadczenie potrzebne takiemu połączeniu wypełnia slot, który encja Feature deklaruje we własnym featuresSchema, dołączony obok encji Feature; zob. Własne poświadczenie encji Feature.

Nazwa załącznika. Każdy załącznik połączenia staje się załącznikiem komponentu konsumującego o nazwie <alias>.<slot> — alias, pod którym zapisano połączenie, kropka i slot: powyżej gpt.credential. Kropka jest separatorem zarezerwowanym dla nazw składanych przez kompilator, której nie może zawierać żaden alias, slot ani nazwa załącznika w encji Aggregate, więc złożona nazwa nigdy nie jest równa nazwie zapisanej we własnym bloku features: komponentu; encja Release zapisująca ją na komponencie lub granicy jest odrzucana (zob. Konfiguracja połączeń dla poszczególnych krawędzi). Pod tą nazwą warstwa per instancja encji Manifest kluczuje załącznik (zob. Płaskie mapowanie URI), pod nią raportują go diagnostyka i graf IR, i tę wartość FeatureRecipe załącznika odczytuje jako .attachment_name (zob. Nazwy wyprowadzane z załącznika połączenia).

Dalej jest rozwiązywany jak każdy załącznik: encja Manifest wiąże jego typ Feature z encją FeatureRecipe, jego values są walidowane względem schematu encji Feature — błąd jest zgłaszany przy wpisie połączenia, który je zapisał — a jego FeatureRecipe renderuje się względem własnych values i infra załącznika. Od własnych załączników komponentu odróżniają go dwie rzeczy:

  • Nie ma go w .features konsumującej encji Recipe. Ten filar zawiera tylko załączniki zapisane we własnym bloku komponentu, więc encja Recipe przeszukująca .features pod kątem własnych załączników według typu nigdy nie otrzyma poświadczenia połączenia. Encja Recipe odczytuje załącznik połączenia z samego połączenia, pod .context.uses.<alias>.features.<slot>, w kształcie, jaki ma .features — łącznie z rozwiązanym provides (zob. Załączniki połączenia).
  • Trafia wyłącznie do konsumenta. Wyrenderowany wynik celu jest taki sam niezależnie od tego, co zawierają docierające do niego połączenia.

Kopia autorskiego bloku w grafie. Graf IR zachowuje blok uses: każdego komponentu w postaci zapisanej przez autora i tam załącznik połączenia zachowuje swoje type i description, ale żadnej ze swoich values. Wartości pojawiają się raz, w załączniku, który ma konsument, gdzie wartość zadeklarowana przez encję Feature jako wrażliwa jest ukrywana.

Encja Release może określić rozmiar zadeklarowanego tu załącznika za pomocą infra lub dołączyć własny załącznik do połączenia, do którego sięga — zob. Konfiguracja połączeń dla poszczególnych krawędzi.

Wyłączanie komponentu lub modułu: active:

Instancja komponentu i moduł podagregatu przyjmują przełącznik active:, który decyduje, czy dana encja w ogóle należy do skompilowanej topologii. Jeśli go pominąć, encja jest obecna; jest to wartość domyślna i zwykły przypadek.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Można wpisać wartość logiczną bezpośrednio albo szablon nad .parameters, który się do niej rozwiązuje. Forma szablonu jest powodem istnienia przełącznika: pozwala encji Release decydować o obecności encji przez wypełnienie parametru, dzięki czemu jedna encja Aggregate obejmuje środowiska różniące się tym, które elementy wdrażają — bez deklarowania przez encję Release niczego, czego nie zadeklarowała encja Aggregate.

Co usuwa przełącznik o wartości false. Encja jest przycinana przed zbudowaniem grafu, a przycięcie działa kaskadowo: komponent zabiera ze sobą własne krawędzie uses: i dołączone encje Features, a moduł zabiera wszystko, co wniósł — swoje komponenty, ich krawędzie i ich dołączenia. Nic, co wniosła przycięta encja, nie jest renderowane. Przycięcie nie obejmuje natomiast odwołania do niej z miejsca, które przetrwało, o czym mowa w następnym akapicie.

Komponent, który przetrwał i nadal wskazuje na przycięty, zatrzymuje kompilację. Jeśli api deklaruje krawędź uses: do redis, a redis jest wyłączony, kompilacja zatrzymuje się, zamiast pozwolić krawędzi zniknąć, co pozostawiłoby wstrzyknięte wartości api po cichu puste w czasie wdrożenia. Należy zdecydować, który z nich należy do tego środowiska: ponownie włączyć cel, uzależnić konsumenta od tego samego parametru, tak aby para znikała razem, albo usunąć krawędź z bloku uses: konsumenta.

Zapisany przełącznik musi dawać wartość logiczną, a pusta wartość nią nie jest. Przełącznik jest odczytywany ściśle po rozwiązaniu jego szablonu, a literał, którego nie da się sparsować jako wartości logicznej, zatrzymuje kompilację, zamiast przyjmować jakąkolwiek wartość domyślną. Przypadek, na który warto uważać, to przełącznik odczytujący parametr bez wartości: rozwiązuje się on do niczego, a odczytanie niczego jako „obecny” wdrożyłoby właśnie tę encję, którą uzależniono od tego parametru. Dlatego zapisanie active: bez niczego po nim nie jest tym samym co pominięcie klucza — tylko przełącznik, którego nikt nie zapisał, domyślnie oznacza obecność. Należy nadać parametrowi default: w spec.parameters, aby każde środowisko miało odpowiedź, albo wypełnić go w encji Release. Aby encja była obecna bezwarunkowo, należy usunąć klucz active:, a nie opróżniać go. Zatrzymanie opisano pod hasłem „An active: toggle does not resolve to true or false (Przełącznik active: nie rozwiązuje się do true ani false)” w opisie warunków zatrzymania.

Wyłączony komponent nadal można nazwać z encji Release. Encja Release może nadal wymienić go w granicy, i jest to zamierzone: wyłączenie komponentu jest czynnością autorską, a od encji Release, która go konfiguruje, nie oczekuje się przepisania w tej samej edycji.

Adnotacje w podsystemach i komponentach

Zarówno podsystemy, jak i instancje komponentów mają pole annotations:. Adnotacje tworzone przez programistów w encji Aggregate sterują kaskadą adnotacji po stronie Aggregate — adnotacja podsystemu propaguje się do każdego zagnieżdżonego podsystemu i każdego zawartego komponentu, przy czym nadpisania na bliższym poziomie działają z granulacją pojedynczego klucza. Mapa mappings.features.annotations w encji Manifest deklaruje powiązania, które w czasie budowania przekładają klucze adnotacji na syntetyczne dołączenia encji Feature. Niezmiennik Aggregate-as-Authoring-Surface ogranicza te adnotacje do routingu przez ścieżki maps.values powiązania; powiązanie deklarujące wyłącznie ścieżki maps.infra uruchamia się po stronie Release, a nie po stronie Aggregate.

Kształty wartości

Każdy klucz adnotacji przyjmuje jedną z czterech form, odróżniając „milczę” od „deklaruję wartość” — skalarną lub obiekt strukturalny — i od „rezygnuję”:

  • Brak klucza — zakres nie deklaruje wartości dla tej adnotacji. Zagnieżdżone podsystemy i zawarte komponenty dziedziczą powiązanie z zakresu nadrzędnego.
  • Skalarny ciąg znaków — pojedyncza wartość. Powiązanie w encji Manifest musi deklarować łącznie dokładnie jedną ścieżkę; wartość skalarna jest kierowana do tej ścieżki.
  • Obiekt strukturalny — mapa podkluczy na podwartości. Każdy podklucz obiektu jest kierowany przez maps powiązania w encji Manifest do odpowiedniego pola schematu encji Feature w zadeklarowanym filarze.
  • Jawne YAML null — zakres usuwa ze swojego poddrzewa każde odziedziczone powiązanie dla tego klucza. Sąsiednie komponenty i sąsiednie podsystemy zachowują dziedziczenie; powiązanie traci tylko zakres, który zrezygnował.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Wartości strukturalne dla wielopolowych encji Features

Encja Feature z wieloma konfigurowalnymi polami skłania do użycia strukturalnej wartości adnotacji: jeden klucz adnotacji niesie wartości dla kilku pól schematu encji Feature w jednej deklaracji. Strona Aggregate uruchamia tylko te podklucze, których filarem w mapie powiązania jest values; podklucze kierowane do infra należą do adnotacji po stronie Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Wartości strukturalne kaskadują się z głębokim scalaniem na poziomie podkluczy: podklucze z bliższego poziomu nadpisują podklucze nadrzędne; jawne null przy podkluczu wyłącza odziedziczony podklucz dla danego zakresu, a sąsiednie podklucze pozostają. Pełny opis wartości strukturalnych — kompozycja między stronami z podkluczami infra po stronie Release, walidacja typów dla poszczególnych podkluczy, złagodzona dyscyplina wartości domyślnych dla pól schematu bez zadeklarowanego type — znajduje się w providers/well-known-annotations.md §„Structured annotation values”.

Niezależność poszczególnych kluczy

Każdy klucz adnotacji jest dziedziczony, nadpisywany i wyłączany niezależnie. Komponent deklarujący annotations.feature.myco/db-pool: null rezygnuje tylko z tego klucza; pozostałe klucze odziedziczone z otaczającego podsystemu nadal propagują się do tego komponentu. Sąsiednie komponenty w tym samym podsystemie niezależnie zachowują własne mapy adnotacji — rezygnacja jednego komponentu nie wpływa na sąsiednie.

Adnotacje komponentów najwyższego poziomu

Komponenty najwyższego poziomu (zadeklarowane bezpośrednio w spec.components, a nie wewnątrz podsystemu) nie mają odziedziczonej kaskady. Ich pole annotations: deklaruje wartości bezpośrednio w zakresie komponentu; rozwinięcie syntetyzuje dołączenia encji Feature z każdej zadeklarowanej adnotacji, dla której encja Manifest zawiera pasujące powiązanie.

Regułę kaskady po stronie Aggregate stosowaną do powiązań, podział strona–filar oraz kompletny przykład pokazujący, jak powiązania przekładają adnotacje na syntetyczne dołączenia encji Feature, opisano w providers/well-known-annotations.md §„Aggregate-side annotation cascade”.

Wzorce kotwic YAML (blok defs:)

Schemat encji Aggregate akceptuje opcjonalny blok defs: na poziomie głównym — listę ciągów YAML służącą wyłącznie jako miejsce na standardowe kotwice YAML (&anchor) i odwołania (*anchor). Kompilator nigdy nie odczytuje zawartości tego bloku; istnieje on po to, aby autorzy mogli zadeklarować definicje kotwic w jednym miejscu i odwoływać się do nich w pozostałej części encji Aggregate, zachowując powtarzane wartości zgodnie z zasadą DRY bez utraty płaskiego słownika O(1), po którym iteruje kompilator. Mechanizm odpowiada analogicznemu blokowi defs: w encji Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Kotwice są rozwiązywane w czasie parsowania YAML, więc *default_log_level jest już ciągiem "info" w chwili, gdy kompilator odczytuje blok wartości. Blok defs: jest zgodnym z konwencją miejscem na definicje kotwic; YAML pozwala deklarować kotwice w dowolnym miejscu, ale zgrupowanie ich zachowuje czytelność pozostałej części encji Aggregate. Blok jest opcjonalny — encje Aggregates, które nie potrzebują kotwic, całkowicie go pomijają.