Taksonomia danych i kompozycja
Ujednolicona taksonomia danych i reguły kompozycji
Aby ustanowić przewidywalny schemat i wyeliminować tarcie poznawcze, platforma używa dokładnie pięciu powszechnie rozumianych słów kluczowych i struktury YAML opartej wyłącznie na mapach (słownikach), z mapami zamiast zagnieżdżonych tablic w korzeniu struktury.
1. Standard map z 5 słowami kluczowymi i całkowita symetria schematów
Bezpośrednie słownictwo strukturalne: podstawową regułą projektowania schematów jest to, że główne struktury danych muszą być pojedynczymi, strukturalnymi słowami kluczowymi. Choć użycie potocznych angielskich wyrażeń (takich jak depends_on czy runs_within) może sprawić, że YAML-owy DSL będzie się czytał bardziej naturalnie, wprowadza to złożoność strukturalną przy mapowaniu tych kluczy na programowe szablony Go. Aby zachować bezpośrednie mapowanie zmiennych 1:1 i zapobiec fragmentacji języka dziedzinowego (DSL), schematy JSON podstawowych encji katalogu (Component, Feature) wykazują niemal całkowitą symetrię strukturalną, opartą na tym samym podstawowym zestawie strukturalnych słów kluczowych używanym we wszystkich tworzonych slotach instancji. Encje Features poświadczeń (oznaczone etykietą feature.aggrega.ai/kind: secret) dzielą dokładnie ten sam paradygmat — nie ma osobnego schematu dla sekretów.
parameters(globalny kontrakt środowiskowy)- Zakres: definiowane w korzeniu encji
Aggregate; wypełniane przez encjęRelease(CI/CD) inline wparameters:lub przezparameters: { $import: <path> }wskazujące zewnętrzny plik parametrów. - Znaczenie: zewnętrzne argumenty, które dynamicznie zmieniają stan poznawczy lub logiczny aplikacji w różnych środowiskach (np. zmiana
workers: 2naworkers: 10). Obsługuje typowany kontrakt (pełną składnię typowanego kontraktu opisuje data-pillars) walidowany przed interpolacją. W przepływach pracy GitOps, które przechowują wartości parametrów w osobnym pliku, encja Release używa formy$import:; kompilator wczytuje zawartość pliku i zastępuje nią mapę inlineparameters:. Nakładanie wielu plików wyraża się łańcuchamiextends:encji Release.
- Zakres: definiowane w korzeniu encji
values(intencja poznawcza - własność dewelopera)- Zakres: używane jednolicie w
componentsi ich dołączeniachfeaturesw encjiAggregate, łącznie z encjami Features poświadczeń. - Znaczenie: podstawowy stan poznawczy, logika biznesowa i konfiguracja operacyjna. Nieprzezroczyste dla kompilatora Go, ale ściśle walidowane przez ujednoliconą deklarację
schema:katalogu (forma kompaktowa lub JSON Schema 2020-12).
- Zakres: używane jednolicie w
uses(topologia strukturalna - stan deklaratywny)- Zakres: używane jednolicie w
componentsi ich dołączeniachfeaturesw encjiAggregate, łącznie z encjami Features poświadczeń. - Znaczenie: deklaratywne stwierdzenie faktu, które definiuje krawędzie sieciowe i zależności (np. „Ten agent używa tej bazy danych”). Natywnie parsowane przez kompilator Go w celu narysowania grafu reprezentacji pośredniej (IR). Walidowane przez ujednoliconą deklarację
usesSchemakatalogu w celu wymuszenia bezpieczeństwa typów między węzłami.
- Zakres: używane jednolicie w
infra(rzeczywistość fizyczna - własność Ops)- Zakres: używane jednolicie w
componentsgranicy i ich dołączeniachfeaturesw encjiRelease. - Znaczenie: fizyczny ślad i mechaniczne wymiarowanie wstrzykiwane podczas Late Binding (np.
cpu_limit: "4",port: 5432). Instancje komponentów encji Aggregate i ich dołączeniafeaturesnie zawierają polainfrai w połączeniu zadditionalProperties: falseodrzucająinfrapodczas walidacji schematu. Walidowane przez ujednoliconą deklaracjęschema:katalogu.
- Zakres: używane jednolicie w
inject(kontrakt dostarczenia - polecenie imperatywne)- Zakres: używane na instancji komponentu, w jawnych definicjach celów w
usesoraz na dołączonychfeatures, łącznie z encjami Features poświadczeń. - Znaczenie: jawne, imperatywne polecenie określające intencję dostarczenia (np. „Kompilatorze, wstrzyknij tę zmapowaną wartość jako zmienną środowiskową”). Ustanawia abstrakcyjny kontrakt (
env,file,arglub mechanizmy niestandardowe) dla fizycznego wyjścia, rozwiązanego punktu końcowego lub pobranego poświadczenia, natomiast fizyczna mechanika tego, jak dokładnie wykonywane jest to zamontowanie, jest w całości delegowana do bazowej Recipe Ops. Każdy mechanizm jest listą wpisów ([{ in: API_HOST, from: "host" }]), z których każdy nazywa swój lokalny identyfikator za pomocąin:i zawiera dokładnie jedno zfrom:lubvalue:.
- Zakres: używane na instancji komponentu, w jawnych definicjach celów w
.context(ogólny potok metadanych)- Zakres: wstrzykiwany po cichu przez kompilator do szablonów encji
RecipeOps. - Znaczenie: przenosi to, co kompilator zebrał dla węzła z reszty grafu (takie jak
.context.uses), przekazywane bezpośrednio do silnika szablonów Ops.
- Zakres: wstrzykiwany po cichu przez kompilator do szablonów encji
Rzeczywistość mapowania 1:1
Zastąpienie potocznych przyimków ścisłymi słowami kluczowymi infrastruktury daje bezpośrednie mapowanie 1:1. Inżynier Ops nie musi tłumaczyć gramatyki; po prostu odwołuje się do dokładnie tych kluczy, które napisał deweloper.
Kształty strukturalne: mapy w korzeniu, tablice w ładunkach. Główne bloki topologii — components, features, aggregates, subsystems, boundaries — to mapy YAML, których klucze, tworzone przez użytkownika, służą jako stabilne identyfikatory instancji. Tablice nie są w tych miejscach dozwolone; klucz mapy jest tożsamością, której kompilator używa do odwołań krzyżowych (target: my-db), budowy węzłów grafu i rozwiązywania encji Manifest. Wewnątrz nieprzezroczystych bloków ładunku (values, infra, parameters) tablice są w pełni dozwolone — deweloperzy mogą pisać tools_allowed: ["sql", "web"] lub hostnames: ["stripe.com", "twilio.com"] w values encji Component. Schemat encji Aggregate deklaruje te bloki ładunku jako additionalProperties: true, więc są one nieprzezroczyste dla kompilatora Go i walidowane w całości przez osadzoną w katalogu deklarację schema:. Dzięki temu zmienność frameworków (nowe kształty API AI, nowe natywne dla chmury formaty ładunków) trafia do domeny katalogu, gdzie może ewoluować niezależnie, a kompilator Go w korzeniu strukturalnym operuje wyłącznie na adresowalnych kluczach.
2. Przepływy informacji: kto, kiedy i po co?
Aby zapobiec kolizjom przestrzeni nazw w szablonach i niezamierzonemu przeciekaniu konfiguracji fizycznej infrastruktury do poznawczej logiki aplikacji, architektura jawnie rozdziela dane na sześć odrębnych strumieni:
- Przepływ 1: wstrzykiwanie środowiskowe (
parameters): potok CI/CD wstrzykuje realia wdrożenia. Kompilator waliduje każdą wartość dostarczoną przez encję Release względem typowanego kontraktuparameters:, a następnie interpoluje rozwiązane zmienne szablonów Go przed uruchomieniem dalszej walidacji schematuvalues:.- Zalecane użycie:
parameterssą zarezerwowane dla poznawczej logiki aplikacji, która różni się między środowiskami (np.LOG_LEVEL=debug,ENABLE_BETA=true). Wymiarowanie operacyjne i kwestie fizycznej infrastruktury — repliki, limity CPU, ARN-y AWS, nazwy hostów ingress — przepływają przez blokinfraencjiReleasei nakładki granic, dzięki czemu encjaAggregatedewelopera pozostaje skupiona na intencji aplikacji. - Pragmatyczna furtka: w mniejszych zespołach, przy szybkim prototypowaniu lub w starszych integracjach CI/CD, gdzie ścisłe rozdzielenie nie jest praktyczne,
parametersmogą przenosić globalne konfiguracje środowiska przez cały stos. Kompilator akceptuje wszystko, co przechodzi walidację schematu; powyższe zalecenie jest umową społeczną, a nie regułą kompilatora.
- Zalecane użycie:
- Przepływ 2: poznawcza intencja aplikacji (
valuesw encjach Components): definiuje wewnętrzną logikę aplikacji. Deklaracjaschema:encji Component (forma kompaktowa lub JSON Schema 2020-12) zapewnia ścisłe sprawdzanie typów i walidację tego ładunku, dając deweloperom natychmiastową informację zwrotną w duchu „Shift-Left” i gwarantując, że żądane konfiguracje odpowiadają API bazowej infrastruktury. - Przepływ 3: operacyjna intencja encji Feature (
valuesw encjach Features): w encji Aggregate deweloper żąda możliwości infrastruktury, których zachowanie jest intencją aplikacji, i odpytuje ściśle typowane poświadczenia bez modyfikowania wewnętrznego kodu. Encja Feature, której wszystkie wejścia są operacyjne, nie mavaluesdewelopera: zespół operacyjny dołącza ją w encji Release, wraz z jejinfra(przepływ 4). - Przepływ 4: wymiarowanie fizycznej infrastruktury (
infra): z całkowitym pominięciem dewelopera fizyczne wymiarowanieinfrajest jawnie rzutowane ze specyficznej dla środowiska encjiReleasebezpośrednio na encje Components o zasięgu lokalnym i dołączone do nich encje Features, w tym encje Features poświadczeń. Aby uniknąć kolizji walidacji zamkniętych schematów wynikających z dosłownego rozgłaszania słowników, wymiarowanieinfrajest ściśle ograniczone do jawnie wskazującego je komponentu. Dzięki temu limity obliczeniowe, repliki i mechaniczne wymagania zasobowe pozostają w domenie Ops. - Przepływ 5: kaskadowe adnotacje (metadane kontekstowe): szerokie dane kontekstowe (takie jak domeny operacyjne, przestrzenie nazw czy kody rozliczeniowe) są obsługiwane przez kaskadowe adnotacje, co zapobiega zanieczyszczeniu przez rozgłaszanie
infra. Są one rozdzielane do zasobników według pochodzenia, a zamierzone zastosowanie każdego zasobnika opisane poniżej jest umową społeczną: szablon encji Recipe może odczytać wszystkie trzy, a kompilator nie wymusza tego rozdzielenia (zob. labels-and-annotations):.context.annotations.release(granice domeny 4): używane wyłącznie do zarządzania realiami fizycznymi. Ops jawnie kieruje te adnotacje do ścisłych lokalnych pólinfraza pomocą szablonów Go (np. mapując regionalną przestrzeń nazw na komponent obliczeniowy)..context.annotations.aggregate(podsystemy domeny 1): używane wyłącznie do zarządzania logiką poznawczą i operacyjną. Te adnotacje są jawnie kierowane do ładunkówvalueskomponentu (np. kaskadowo przekazując kod rozliczeniowy zespołu aż do konfiguracji aplikacji)..context.annotations.catalog(katalog domeny 2): niezmienne cechy wewnętrzne tworzone przez architekta, używane głównie do programowej ewaluacji polityk Wasm.
- Przepływ 6: potok metadanych (
.context): stosuje globalne wymagania przedsiębiorstwa (tagi SOC2) bezpośrednio do szablonów fizycznej infrastruktury.
3. Abstrakcja sieci: konwencja „Zero-Port”
- Dobra praktyka: deweloperzy powinni pomijać porty w encji
Aggregate. Recipe Ops dynamicznie obsługuje wewnętrzne trasowanie. - Furtka: jeśli wewnętrznego kodu aplikacji nie można zmienić, architekt platformy jawnie udostępnia pole
portw deklaracjischema:. Uwaga architektoniczna: konwencja „Zero-Port” jest najbardziej widocznym przykładem szerszego rozdzielenia odpowiedzialności na platformie. Dokładnie ta sama filozofia — oddzielenie fizycznej mechaniki od dewelopera — dotyczy żądań CPU, limitów pamięci, domen operacyjnych i wymiarowania dysków. Ilekroć ograniczenie fizycznej infrastruktury musi przeniknąć do ładunku aplikacji dewelopera (z powodu starszego kodu lub ścisłych wymagań sprzętowych), zawsze musi być regulowane jawną „furtką” w deklaracjischema:architekta, czyli deklaracji, względem której walidowany jest ładunek dewelopera.
Nazwa „Zero-Port” oznacza tę konwencję; zasada uogólnia się na każde ograniczenie fizycznej infrastruktury, które starsza aplikacja ma zakodowane na stałe. Poniższy schemat używa tcp_keepalive_seconds jako przykładu — parametru czasowego jądra/sieci, którego aplikacja oczekuje na warstwie gniazd — ponieważ leży on wyraźnie na osi przeciekania infra.
Schemat (domena 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }YAML dewelopera (domena 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaZachowanie kompilatora: kompilator Go przekazuje tcp_keepalive_seconds: 120 do grafu IR. Następnie Recipe Ops odczytuje {{ .values.tcp_keepalive_seconds }}, aby skonfigurować specyfikację poda Kubernetes lub limit czasu bezczynności load balancera dostawcy chmury, skutecznie wypełniając lukę po starszym kodzie bez naruszania schematu.
4. Kontrakt wstrzykiwania i wstępnie rozwiązana mapa
Spośród pięciu strukturalnych słów kluczowych inject ma inny kształt niż pozostałe. parameters, values, uses i infra to stan deklaratywny — deweloper zapisuje fakty o tym, czym jest aplikacja i od czego zależy. inject to polecenie imperatywne — deweloper określa, jak wartość ma zostać dostarczona do działającego kontenera, mapując abstrakcyjne źródła danych (klucze provides celu, własne wartości komponentu, odpowiedź sejfu encji Feature poświadczeń) na konkretne mechanizmy dostarczania (env, file, arg lub mechanizm niestandardowy zadeklarowany przez encję Component).
To rozdzielenie jest strukturalne. Encja Aggregate dewelopera mówi „wstrzyknij host bazy danych jako zmienną środowiskową DB_HOST”, nie podając fizycznego adresu bazy danych, ścieżki w sejfie magazynu sekretów ani formatu nazw hostów dostawcy chmury. Recipe Ops otrzymuje rozwiązany ciąg znaków przez .context.inject i używa go bez tworzenia łańcucha wyszukiwania.
Wstępnie rozwiązana mapa. Podczas renderowania kompilator rozwiązuje każde źródło wstrzykiwania — literały samowstrzykiwania i odwołania from: do własnych provides komponentu, odwołania między komponentami przez uses[].inject, przechwycenia injectMapping encji FeatureRecipe — do jednego spłaszczonego słownika w .context.inject. Zanim uruchomi się szablon valuesMapping bazowej Recipe, każdy klucz wstrzykiwania ma już swoją ostateczną wartość tekstową. Encje Recipes iterują bezpośrednio po mapie ({{ range $k, $v := .context.inject.env }}) bez przechodzenia łańcucha rozwiązywania.
Nazwy nadawane przez programistę własnym wartościom komponentu. Tam, gdzie encja Component deklaruje spec.inject, własny blok inject: programisty wybiera nazwy, pod którymi własne wartości i provides komponentu trafiają do potoku dostarczania. Kompilator przekazuje encji Recipe, w .context.self_inject, jedną własną wartość odczytywaną przez szablon każdego wpisu — dla każdego mechanizmu każda nazwa jest odwzorowana na provides.<key>, na values.<key> w przypadku szablonu odczytującego dokładnie jedną własną wartość i nic poza nią, albo na pusty ciąg — w postaci, jaką przyjmują nazwy połączenia w .context.uses.<alias>.inject. Konwencja katalogu biblioteki standardowej dla encji Recipe uruchamiającej obraz programisty polega na traktowaniu nazw, które w przeciwnym razie wybrałaby dla własnych wartości komponentu, jako wartości domyślnych i dostarczaniu własnej wartości pod jej domyślną nazwą tylko wtedy, gdy żaden wpis nie jest już na nią odwzorowany. Jest to konwencja katalogu, a nie reguła kompilatora: katalog przedsiębiorstwa może dostarczać własne wartości swoich komponentów w dowolny wybrany sposób. Kompilator odczytuje mapę z tekstu napisanego przez programistę i nie przypisuje nazwom żadnego znaczenia.
Pełna specyfikacja kontraktu wstrzykiwania — semantyka kontekstu o podwójnym stanie, reguły kolizji kluczy, model przechwytywania encji FeatureRecipe i opracowane przykłady — znajduje się w topology-triad.
5. Silnik szablonów (DX dla Ops)
Inżynierowie Platform Ops tworzą szablony tłumaczące i potrzebują pełnej mocy standardowego szablonowania infrastruktury bez zastrzeżonego języka szablonów. Szablony Aggrega to Go text/template:
- Żadnych „magicznych” ciągów: kompilator zachowuje dokładne klucze map dewelopera. Ops bezpiecznie odwołuje się do funkcji przez standardowe indeksowanie map Go:
{{ (index .features "public-route").infra.hostname }}. - Biblioteka Sprig: kompilator natywnie rejestruje standardową dla Helm bibliotekę Sprig, zapewniając natychmiastowy dostęp do potoków takich jak
| default,| quotei| toYaml. - Fragmenty MappingLibrary: fragment mapowania używany ponownie przez kilka encji Recipes znajduje się w MappingLibrary i jest dołączany do każdej encji Recipe za pomocą
$import:. Funkcje pomocnicze szablonów chartów Helm (include,tpl,required,warn) nie są zarejestrowane; listę zarejestrowanych zawiera sprig-functions.
6. Reguły kompozycji: Aggregates, podsystemy i Components
- Grupowanie logiczne (tablica
subsystems): za pomocąsubsystemsdeweloperzy mogą jednocześnie stosować metadane logiczne (własność zespołu, etykiety zgodności) i przekrojowe funkcje do dziesiątek komponentów. Podsystemy działają jak rekurencyjne foldery na płaszczyźnie logicznej/intencji, kaskadowo przekazującannotationsw dół do zasobnika.context.annotations.aggregatei dołączając funkcje do wszystkich zawartych komponentów, bez narzucania granic fizycznych. Funkcje na poziomie podsystemu stosują ten sam schemat co funkcje na poziomie komponentu (obsługująctype,values,uses,inject), ponieważ należą do domeny 1 (intencja dewelopera). Podczas finalizacji grafu kompilator spłaszcza funkcje podsystemu do listy funkcji każdego zawartego komponentu, umieszczając je w kolejności wykonania po własnych funkcjach komponentu i przed wszelkimi funkcjami dołączonymi w encji Release.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Złożone encje Aggregates są OBSŁUGIWANE (wzorzec modułu): 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ą kontraktexportedComponents:, ustanawiający stabilną nazwę interfejsu publicznego. Element nadrzędny dociera do komponentów modułu wyłącznie przez ten interfejs: celuses:wskazuje moduł i jeden z jego wyeksportowanych aliasów, a kompilator łączy krawędź z wewnętrznym komponentem, który wskazuje ten alias, natomiast cel sięgający do wnętrza modułu pod jakąkolwiek inną nazwą zatrzymuje kompilację, podając moduł i aliasy, które eksportuje. Moduł może z kolei ponownie wyeksportować wyeksportowany komponent zagnieżdżonego modułu pod własną nazwą interfejsu — opcjonalnie zmieniając jego nazwę — a kompilator rozwiązuje taki łańcuch ponownych eksportów przechodnio aż do bazowego węzła wewnętrznego, dzięki czemu moduły składają się na dowolną głębokość, a element nadrzędny nie musi wiedzieć, jak głęboko zagnieżdżony jest cel. Cel, który nie rozwiązuje się do żadnego węzła wewnętrznego, nadal głośno zatrzymuje kompilację, a łańcuch ponownych eksportów zamykający się sam na siebie jest odrzucany zamiast śledzony w nieskończoność.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: 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"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Encje Components nie mogą zawierać podkomponentów: encje Components są atomowymi elementami składowymi. Kompozycja odbywa się na poziomie encji Aggregate przez podsystemy i podagregaty. Jeśli aplikacja wymaga wielu fizycznych kontenerów (np. API + sidecar), to fizyczne zagnieżdżenie znajduje się w szablonie Recipe Ops, a nie w definicji encji Component.
-
Jedna spójna usługa na encję Component — granica pojedynczego obciążenia: encja Component modeluje jedną spójną usługę — pojedynczą udostępnianą usługę albo obciążenie lub obciążenia jednej usługi wraz z jej wyłącznie wewnętrznymi obciążeniami pomocniczymi. Jej etykieta
component.aggrega.ai/typenazywa kształt operacyjny tej jednej usługi. Wiele fizycznych obciążeń w jednej encji Component jest w porządku, gdy tworzą jeden spójny produkt bez części użytecznych niezależnie: usługa, której chart uruchamia kontroler plus webhook plus injector, nadal jest jedną encją Component. Kryterium nie jest wiele obciążeń; jest nim niezależna użyteczność.Granicę wyznacza się tam, gdzie pakiet zawiera coś, czego inny komponent mógłby sensownie używać (
use) samodzielnie — zwłaszcza obcą infrastrukturę, taką jak baza danych, pamięć podręczna czy broker komunikatów, którą Aggrega już modeluje jako osobną encję Component. Taki pakiet nie jest jedną encją Component; jest modułem podagregatu — wzorcemspec.aggregates+exportedComponentspokazanym wyżej — który składa jedną encję Component na usługę, tak aby każda usługa była adresowalnym węzłem z własnym typem, własnymi krawędziami i własną powierzchnią polityk i skalowania.Heurystyka sformułowana jako wyraźna reguła: Czy chart zawiera coś, czego inny komponent mógłby sensownie używać samodzielnie, albo coś, dla czego Aggrega ma już encję Component? Jeśli tak, należy modelować to jako stos — moduł podagregatu składający encje Components na usługę. Jeśli służy wyłącznie tej jednej usłudze, należy modelować to jako jedną encję Component.
Opakowanie całego wielousługowego produktu jako jednej nieprzezroczystej encji Component jest udokumentowanym antywzorcem. Kompilator działa bez własnego zdania i to zaakceptuje — renderuje wszystko, co przechodzi walidację schematu — ale biblioteka standardowa zamiast tego składa encje Components na usługę w moduł, ponieważ monolityczne opakowanie ukrywa niezależnie modelowalne usługi przed topologią, selektorem oraz politykami i skalowaniem poszczególnych usług. Ta dyscyplina granularności jest umową społeczną — zobacz
../language-reference/vocabulary/social-contracts.md(granularność encji Component).
7. Zakres domyślny — stopniowe ujawnianie grupowania
subsystems (w encji Aggregate) i boundaries (w encji Release) to konstrukcje grupujące, ale programista nie musi deklarować ich od początku. Każda encja oferuje dwie formy zapisu i wzajemnie się one wykluczają: komponenty zapisuje się pogrupowane w nazwanych zakresach albo bezpośrednio na najwyższym poziomie — nigdy oba sposoby naraz. Dokument, który deklaruje zarówno components najwyższego poziomu, jak i nazwane zakresy, zatrzymuje się przy ładowaniu z błędem koperty.
Dla formy płaskiej (components najwyższego poziomu) kompilator syntetyzuje przy ładowaniu prawdziwy zakres default i włącza do niego komponenty najwyższego poziomu, dzięki czemu każdy kolejny przebieg widzi jednolitą strukturę opartą na zakresach. Zsyntetyzowany zakres nie jest ukrytym kontenerem: to rzeczywisty, oznaczony pochodzeniem węzeł w IR, odróżnialny od zakresu, który programista jawnie nazwie default. Jest ukryty tylko tam, gdzie autor czyta ścieżki — diagnostyka i adresowanie pokazują ścieżkę w kształcie korzenia .spec.components[…], którą programista faktycznie napisał.
- Płaska encja Aggregate (komponenty najwyższego poziomu): komponenty zapisuje się pod
spec.components, bezsubsystems. Kompilator włącza je przy ładowaniu do zsyntetyzowanego podsystemudefault. Adnotacje zakresu podsystemu i funkcje na poziomie podsystemu dotyczą tylko podsystemów zadeklarowanych; forma płaska nie zawiera żadnych. - Płaska encja Release (komponenty najwyższego poziomu): komponenty zapisuje się pod
spec.components, bezboundaries. Kompilator włącza je do zsyntetyzowanej granicydefault, której wynik jest płaski — artefakty trafiają bezpośrednio dodist/(dla każdego dostawcy:dist/compose/,dist/helm/, …), bez segmentu z nazwą granicy. To najprostszy przypadek:aggrega builddla płaskiego celu Compose lub jednoklastrowego, bez nazywania granic. (Granica, którą programista deklaruje i nazywadefault, jest zwykłą nazwaną granicą i, bez własnegodirectory:, emituje dodist/boundaries/default/jak każda inna). - Ścieżka rozbudowy: gdy płaska architektura rozrasta się do takiej, która wymaga grupowania (różne przestrzenie nazw, oddzielne grupy logiczne, wdrożenie w wielu granicach), programista przenosi komponenty najwyższego poziomu do jawnych
subsystemsalbo Ops wprowadza jawneboundaries. Ponieważ obie formy wzajemnie się wykluczają, jest to przejście z formy płaskiej do formy z zakresami — a nie mieszanie obu — a tożsamość węzłów zostaje zachowana podczas tego przejścia.
Uzasadnieniem jest stopniowe ujawnianie: wymaganie obowiązkowego grupowania w trywialnych przypadkach użycia (demo z jedną usługą, szybki lokalny prototyp) tworzy niepotrzebne tarcie. Test wdrożeniowy „od zera do działania w 10 minut” wymaga, aby programista mógł napisać minimalną encję Aggregate z jednym komponentem, jedną encją Manifest i jedną encją Release i uzyskać działający wynik bez wcześniejszego zrozumienia podsystemów czy granic. Zakres domyślny to wjazd; zadeklarowane zakresy to kierunek, w którym architektura podąża, gdy rośnie.
8. Ograniczenia architektoniczne i zalecane wzorce
Poniższe pozycje to jeden zalecany wzorzec i pięć ograniczeń. Schematy wymuszają ograniczenia 4 i 5 — encja Release nie ma bloku values, a instancja komponentu w encji Aggregate nie ma klucza labels; pozostałe to konwencje, których kompilator nie sprawdza.
-
Zalecany wzorzec: wynoszenie parametrów przez ciągi szablonów
- Przykład: programista pisze
workers: {{ .parameters.env_workers }}w swoim blokuvalues, bez cudzysłowów, aby wartość dotarła jako liczba całkowita, za jaką została zadeklarowana. - Dlaczego: jeśli encja Aggregate deklaruje
env_workersjako parametr typowany (type: integer), kompilator najpierw waliduje wartość dostarczoną przez encję Release względem kontraktu. Walidacja kontraktu parametrów następuje przed interpolacją; interpolacja następuje przed walidacją otaczającego schematuvalues:. Zachowuje to możliwość ponownego użycia encji Aggregate: Ops dostarcza liczbę całkowitą przezparameters:encjiRelease, kompilator waliduje ją względem typowanej deklaracjiparameters:, podstawia rozwiązaną wartość do dokumentu, a deklaracjaschema:encji Component pomyślnie waliduje wynikową liczbę całkowitą.
- Przykład: programista pisze
-
Ograniczenie 1: poświadczenia są załącznikami, nie wartościami
- Odradzany wzorzec: programista pisze
values: { password: "123" }w komponencie. - Dlaczego: konwencja biblioteki standardowej polega na tym, że poświadczenie zamawia się jako załącznik w
features:, wskazująctypeencji Feature dla poświadczeń (oznaczony etykietąfeature.aggrega.ai/kind: secret) i używając własnychvaluestego załącznika do opisania zapytania do magazynu sekretów. To konwencja, a nie kontrola kompilatora — kompilator nie interpretuje znaczenia liściavaluesi przeniesie literał inline dosłownie. To powierzchnia załączników sprawia, że poprawnie napisana forma jest dostępna i typowana.
- Odradzany wzorzec: programista pisze
-
Ograniczenie 2: Components agnostyczne wobec możliwości
- Nieobsługiwany wzorzec: architekt pisze
aws_instance_type: stringw deklaracjischema:encji Component. - Dlaczego: zgodnie z konwencją Components są agnostyczne wobec możliwości. Fizyczne cele sprzętowe należą do Recipes zespołu Ops lub do ogólnych adnotacji
.context, a nie do podstawowej logiki poznawczej aplikacji.
- Nieobsługiwany wzorzec: architekt pisze
-
Ograniczenie 3: logika warunkowa na metadanych
- Nieobsługiwany wzorzec: Ops pisze
{{ if eq .context.labels.gpu "true" }}w encjiRecipe, aby zasadniczo zmienić strategię wdrożenia. - Dlaczego: kanał
.contextomija walidacjęschema:poszczególnych filarów. Poleganie na niezwalidowanych etykietach w podstawowej logice infrastruktury czyni platformę kruchą. Obiekt.contextprzenosi tagi metadanych (np. rozliczenia, SOC2); routing strukturalny należy do filarów walidowanych schematem.
- Nieobsługiwany wzorzec: Ops pisze
-
Ograniczenie 4: encja Release nie może nadpisywać wartości programisty
- Nieobsługiwany wzorzec: Ops próbuje z poziomu encji
Releasenadpisać logikę poznawczą programisty (np. zmieniającworkers: 4naworkers: 10). - Dlaczego: encja
Aggregatejest jedynym źródłem prawdy o intencji programisty. Jeśli wartość jest zakodowana na stałe w encjiAggregate, jest niezmienna we wszystkich środowiskach. Jeśli wartość musi się zmieniać zależnie od środowiska, programista stosuje wynoszenie parametrów. Schemat encjiReleaseegzekwuje to, zakazując blokówvaluesi ograniczając Ops do spełnienia kontraktuparametersoraz zdefiniowania fizycznejinfra.
- Nieobsługiwany wzorzec: Ops próbuje z poziomu encji
-
Ograniczenie 5: etykiety na poziomie instancji w encji Aggregate
- Nieobsługiwany wzorzec: programista pisze
labels: {}w instancji komponentu wewnątrz encjiAggregate. - Dlaczego: etykiety to niezmienne cechy na poziomie katalogu, tworzone przez architekta platformy — semantyczna tożsamość, którą odczytują silniki polityk i selektory. Encja Release kieruje komponenty do granic przez jawne wskazywanie po ID oparte na mapach (
components: { "my-agent": {} }), co zachowuje możliwość zagnieżdżaniainfrai nadpisań funkcji dla każdego komponentu bez mieszania autorstwa etykiet z encją Aggregate programisty.
- Nieobsługiwany wzorzec: programista pisze
9. Perymetr bezpieczeństwa & jawne zabezpieczenia ruchu wychodzącego (miejsca docelowe poza perymetrem)
Żadna aplikacja nie istnieje w próżni. Skompilowana architektura Aggrega reprezentuje ściśle odwzorowany graf. Jednak nowoczesne systemy AI nieustannie komunikują się z bytami spoza tego skompilowanego perymetru — takimi jak publiczne modele LLM w modelu SaaS (Anthropic, OpenAI), ogólne publiczne API (Stripe, Twilio) czy starsze bazy danych brownfield (lokalny Oracle).
Aby bezpiecznie zintegrować te systemy zewnętrzne, Aggrega ściśle oddziela granicę bezpieczeństwa od mechaniki wykonania. Granicą bezpieczeństwa rządzą uniwersalna reguła encji Component oraz jawne zabezpieczenie ruchu wychodzącego.
1. Uniwersalna reguła encji Component
Jeśli aplikacja komunikuje się z jakimś bytem — czy to lokalną bazą danych, zarządzanym zasobem chmurowym, modelem LLM w modelu SaaS, czy ogólnym publicznym punktem końcowym API — ten byt MUSI zostać zadeklarowany jako odrębna encja Component w encji Aggregate. Ta reguła jest konwencją: kompilator nie widzi wywołań wykonywanych przez aplikację, więc nic jej nie sprawdza.
Traktując zewnętrzne API SaaS i starsze bazy danych jako pełnoprawne węzły w grafie reprezentacji pośredniej (IR), programiści zyskują możliwość dołączania konfiguracji proxy Zero-Trust bezpośrednio do wywołania wychodzącego. Na przykład modelując API Stripe jako odrębny węzeł, programista może dołączyć do niego funkcję header-injector, dzięki czemu wygenerowana konfiguracja nie pozwoli wywołującemu agentowi przechowywać surowego tokenu API we własnej pamięci.
2. Jawne zabezpieczenie ruchu wychodzącego (zgodność infrastruktury)
Zamiast polegać na zakodowanej na stałe logice kompilatora przy zarządzaniu ruchem wychodzącym z sieci, Aggrega w całości deleguje bezpieczeństwo perymetru do agnostycznych silników polityk przedsiębiorstwa i wtyczek renderujących Wasm. Gwarantuje to, że wygenerowane konfiguracje są ściśle zgodne z jawnymi zatwierdzeniami ruchu wychodzącego.
- Punkt zaczepienia w katalogu (domena 2): gdy architekt definiuje publiczny komponent SaaS (np.
core/external-service), dołącza do niego niezmienną etykietę firmową (np.security.enterprise.com/zone: "untrusted-external"). - Zabezpieczenie polityką (w czasie kompilacji): zanim zostanie wygenerowana jakakolwiek konfiguracja, silnik polityk OPA lub Kyverno ocenia graf. Przedsiębiorstwo tworzy prostą regułę: „Jeśli węzeł wewnętrzny łączy się z węzłem oznaczonym etykietą
untrusted-external, ID tego węzła docelowego musi być jawnie wymienione w tablicyparameters.approved_egressśrodowiska”. Jeśli programista spróbuje skierować dane do niezatwierdzonego zewnętrznego miejsca docelowego, silnik polityk zatrzymuje kompilację. - Generowanie konfiguracji (czas renderowania): jeśli polityka przejdzie, reguła ruchu wychodzącego jest renderowana z tego, co dołączył operator. Encja Feature
core/egress-allowlist, dołączona do wywołującego komponentu w encji Release, renderuje nahelmpo jednym KubernetesNetworkPolicyna każde obciążenie renderowane przez ten komponent, dopuszczając ruch wychodzący tylko do jego własnych podów, do podów celów jego krawędziusesna portach, które te pody deklarują, do DNS klastra oraz do zakresów adresów, które załącznik wymienia dla celu nieuruchomionego w klastrze, takiego jak publiczne API SaaS. Kompilacja zatrzymuje się, chyba że encja Release potwierdzi za pomocąinfra.control_plane_present: true, że wtyczka sieciowa klastra egzekwuje politykę sieciową, a także zatrzymuje się, wskazując każde takie połączenie zewnętrzne bez wymienionego zakresu adresów; nacompose, który nie ma polityki sieciowej, załącznik zatrzymuje kompilację. Programista nigdy nie pisze reguły zapory.
Gwarantuje to — za pośrednictwem roli werdyktu ładu, która ocenia zadeklarowaną topologię — że jawnie zadeklarowana infrastruktura jest zgodna z polityką ruchu wychodzącego, bez potrzeby rozumienia przez podstawowy kompilator Go, co oznacza „zewnętrzny”. (Uwaga: prawdziwy ruch wychodzący zero-trust wymaga, aby klaster docelowy uruchamiał w czasie działania CNI typu Default Deny; wygenerowane konfiguracje jedynie odwzorowują autoryzowane wyjątki).
Jedna encja Component na usługę zewnętrzną
Każda usługa zewnętrzna jest deklarowana jako odrębny komponent, a nie zwijana w tablicę wielu celów. Jeśli aplikacja wywołuje pięć różnych API firm trzecich, programista deklaruje pięć odrębnych komponentów core/external-service. To właśnie deklaracja na poziomie usługi pozwala silnikom polityk i wtyczkom Wasm kierować się do każdego wychodzącego miejsca docelowego osobno — dołączając do każdej zależności zewnętrznej inne polityki ruchu wychodzącego, inne funkcje proxy lub inne punkty zaczepienia obserwowalności.
Oddzielenie bezpieczeństwa od wykonania (scenariusz „brownfield”)
Należy koniecznie zauważyć, że etykieta semantyczna (np. untrusted-external) określa politykę bezpieczeństwa sieci, a nie wykonanie. Jest niezależna od tego, czy Aggrega renderuje artefakty aprowizujące ten zasób.
- Scenariusz A (publiczne API SaaS): oznaczone etykietą
untrusted-externalw katalogu (uruchamia zabezpieczenia ruchu wychodzącego polityki). Realizowane przez obciążenie referencyjne (bez aprowizacji mocy obliczeniowej; zob. §10). - Scenariusz B (wewnętrzna starsza baza danych): oznaczona etykietą
internal-trusted(omija zabezpieczenia ruchu wychodzącego, pozostaje wewnątrz VPC). Realizowana przez obciążenie referencyjne (bez aprowizacji mocy obliczeniowej; zob. §10). - Scenariusz C (samodzielnie hostowana baza danych): oznaczona etykietą
internal-trusted. Wykonywana przez wtyczkę renderującą Helm (fizycznie aprowizowana jako StatefulSet Kubernetes).
10. Usługi, których kompilacja nie aprowizuje: referencyjne Workloads
Gdy aplikacja komunikuje się ze starszą lokalną bazą danych lub publicznym API SaaS (takim jak Stripe), uniwersalna reguła encji Component nakazuje, aby te byty zewnętrzne zostały zadeklarowane jako odrębne komponenty w encji Aggregate. Aggrega nie może jednak próbować generować dla nich fizycznego artefaktu Poda Kubernetes ani instancji AWS RDS.
Encja Recipe realizująca taki komponent deklaruje encję Workload z form: reference: endpoint — host lub URL — opcjonalnie port i żadnych kontenerów. Kompilator przekazuje oba jako deterministyczne ciągi wskaźnikowe i nigdy ich nie rozwiązuje. To, co dostawca renderuje dla referencyjnej encji Workload, zależy od samego dostawcy: helm emituje ExternalName Service z hostem punktu końcowego, dzięki czemu obciążenia w klastrze mogą docierać do usługi, której punkt końcowy jest nazwą DNS, pod stabilną nazwą wewnątrz klastra; compose nic dla niej nie renderuje. Kubernetes traktuje externalName jako nazwę DNS, więc do punktu końcowego zapisanego jako adres IP dociera się pod adresem, który otrzymuje konsument, a nie przez Service.
U obu dostawców provides: encji Recipe docierają do każdego konsumenta przez .context.uses i kontrakt inject dokładnie tak samo jak w przypadku aprowizowanego komponentu. Okablowanie konsumenta nie zmienia się więc, gdy jego cel przechodzi od aprowizowanego do referencyjnego: zmienia się tylko encja Recipe, na którą encja Manifest mapuje cel.
Potok wykonania krok po kroku
1. Domena 1 (encja Aggregate): intencja programisty Programista zamawia starszą bazę danych Oracle. Nie interesuje go, gdzie się znajduje; określa jedynie, że jego wywołujący agent oczekuje dostarczenia ciągu połączenia jako zmiennej środowiskowej. Ponieważ adres IP jest statyczny i znany z góry, przekazuje go przez parametry.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Domena 4 (encja Manifest): routing Ops mapuje typ starszej bazy danych na encję Recipe, która formatuje jej ciąg połączenia. Encja Manifest wskazuje encję Recipe i nic więcej; wskazana encja Recipe deklaruje encję Workload z form: reference i to ta forma sprawia, że węzeł nie aprowizuje mocy obliczeniowej. Routing pozostaje idealnie płaski i przewidywalny, ponieważ mapa ma dokładnie jeden kształt niezależnie od celu.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Domena 3 (referencyjna encja Recipe): strukturyzowanie przekazania Inżynier Ops pisze encję Recipe. Buduje ona ciąg połączenia primary_endpoint z values programisty w swoim bloku locals, publikuje go pod provides i deklaruje referencyjną encję Workload wskazującą na host bazy danych.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Wykonanie przez kompilator podczas renderowania (przekazanie)
- Kompilator ewaluuje encję Recipe dla
legacy-oracle. Dla encji Release dostarczającejlegacy_oracle_ip: "10.0.4.55"jejprimary_endpointtooracle://10.0.4.55:1521/PROD_DB. - Na
helmreferencyjna encja Workload renderuje jeden ExternalName Service,legacy-oracle, zexternalName: 10.0.4.55i portem1521; nacomposenie renderuje niczego. - Następnie kompilator renderuje encję Recipe dla
my-agent. Jej kanał.context.usesprzenosiprovideswęzła Oracle, a kontrakt inject już rozwiązał względem nichORACLE_DSN.
5. Domena 3 (wywołująca encja Recipe): spełnienie kontraktu Standardowy przepis Helm dla workera Python odczytuje otrzymaną mapę inject dokładnie tak, jak zrobiłby to dla bazy danych aprowizowanej przez kompilację.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Przesyłanie między filarami przez schema-bridge: pomost od intencji do infrastruktury
Zobacz inheritance-and-interface, aby poznać wzorzec schema-bridge, który bezpiecznie udostępnia wyspecjalizowane pokrętła infrastruktury przez komponenty potomne — pole values: przeznaczone dla programisty, zadeklarowane w schema: encji Component, które szablon valuesMapping: encji Recipe przekazuje do wyrenderowanego wyniku w kształcie infra:.
12. Aprowizacja greenfield („Aggregates platformowe”)
Powtarzającą się pułapką w inżynierii platform jest zmuszanie routera (pliku Release) do obsługi ciężkiej aprowizacji klastrów w dniu 0 (np. uruchamiania nowego klastra AWS EKS przed wdrożeniem do niego aplikacji). Prowadzi to do długich, trudnych do czytania plików routingu.
Aggrega radzi sobie z tym zgodnie z zasadą „żółwie aż do samego dołu”. Schemat encji Release nie ma bloku do instalowania infrastruktury; aprowizację klastrów modeluje się za pomocą Aggregates platformowych.
Ponieważ klaster AWS EKS, płaszczyzna sterowania Istio i AWS VPC są ostatecznie tylko fizycznymi zasobami chmurowymi, modeluje się je dokładnie tak jak komponenty aplikacji.
- Platformowa encja Aggregate: zespół infrastruktury pisze standardowy plik
Aggregate.yaml, w którym komponentami sącore/aws-vpc,core/eks-clustericore/istio-base. - Platformowa encja Release: zespół wdraża ten agregat. Renderer powiązany z tymi komponentami platformy generuje artefakty potrzebne do postawienia infrastruktury bazowej.
- Aplikacyjna encja Release: gdy programista aplikacji jest gotowy do wdrożenia swojego agenta AI, zespół Ops po prostu wskazuje nowo utworzony klaster granicą we własnym pliku
Releaseaplikacji.