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

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 w parameters: lub przez parameters: { $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: 2 na workers: 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ę inline parameters:. Nakładanie wielu plików wyraża się łańcuchami extends: encji Release.
  • values (intencja poznawcza - własność dewelopera)
    • Zakres: używane jednolicie w components i ich dołączeniach features w encji Aggregate, łą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).
  • uses (topologia strukturalna - stan deklaratywny)
    • Zakres: używane jednolicie w components i ich dołączeniach features w encji Aggregate, łą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ę usesSchema katalogu w celu wymuszenia bezpieczeństwa typów między węzłami.
  • infra (rzeczywistość fizyczna - własność Ops)
    • Zakres: używane jednolicie w components granicy i ich dołączeniach features w encji Release.
    • Znaczenie: fizyczny ślad i mechaniczne wymiarowanie wstrzykiwane podczas Late Binding (np. cpu_limit: "4", port: 5432). Instancje komponentów encji Aggregate i ich dołączenia features nie zawierają pola infra i w połączeniu z additionalProperties: false odrzucają infra podczas walidacji schematu. Walidowane przez ujednoliconą deklarację schema: katalogu.
  • inject (kontrakt dostarczenia - polecenie imperatywne)
    • Zakres: używane na instancji komponentu, w jawnych definicjach celów w uses oraz na dołączonych features, łą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, arg lub 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 z from: lub value:.
  • .context (ogólny potok metadanych)
    • Zakres: wstrzykiwany po cichu przez kompilator do szablonów encji Recipe Ops.
    • 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.

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 kontraktu parameters:, a następnie interpoluje rozwiązane zmienne szablonów Go przed uruchomieniem dalszej walidacji schematu values:.
    • Zalecane użycie: parameters są 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 blok infra encji Release i nakładki granic, dzięki czemu encja Aggregate dewelopera 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, parameters mogą 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.
  • Przepływ 2: poznawcza intencja aplikacji (values w encjach Components): definiuje wewnętrzną logikę aplikacji. Deklaracja schema: 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 (values w 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 ma values dewelopera: zespół operacyjny dołącza ją w encji Release, wraz z jej infra (przepływ 4).
  • Przepływ 4: wymiarowanie fizycznej infrastruktury (infra): z całkowitym pominięciem dewelopera fizyczne wymiarowanie infra jest jawnie rzutowane ze specyficznej dla środowiska encji Release bezpoś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, wymiarowanie infra jest ś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ól infra za 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ów values komponentu (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 port w deklaracji schema:. 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 deklaracji schema: 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 versa

Zachowanie 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, | quote i | 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ą subsystems deweloperzy 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ąc annotations w dół do zasobnika .context.annotations.aggregate i 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ąc type, 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.
aggregate.yaml
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ą kontrakt exportedComponents:, ustanawiający stabilną nazwę interfejsu publicznego. Element nadrzędny dociera do komponentów modułu wyłącznie przez ten interfejs: cel uses: 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ść.
child-database-module.yaml
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type nazywa 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 — wzorcem spec.aggregates + exportedComponents pokazanym 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, bez subsystems. Kompilator włącza je przy ładowaniu do zsyntetyzowanego podsystemu default. 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, bez boundaries. Kompilator włącza je do zsyntetyzowanej granicy default, której wynik jest płaski — artefakty trafiają bezpośrednio do dist/ (dla każdego dostawcy: dist/compose/, dist/helm/, …), bez segmentu z nazwą granicy. To najprostszy przypadek: aggrega build dla płaskiego celu Compose lub jednoklastrowego, bez nazywania granic. (Granica, którą programista deklaruje i nazywa default, jest zwykłą nazwaną granicą i, bez własnego directory:, emituje do dist/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 subsystems albo Ops wprowadza jawne boundaries. 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.

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 bloku values, bez cudzysłowów, aby wartość dotarła jako liczba całkowita, za jaką została zadeklarowana.
    • Dlaczego: jeśli encja Aggregate deklaruje env_workers jako 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 schematu values:. Zachowuje to możliwość ponownego użycia encji Aggregate: Ops dostarcza liczbę całkowitą przez parameters: encji Release, kompilator waliduje ją względem typowanej deklaracji parameters:, podstawia rozwiązaną wartość do dokumentu, a deklaracja schema: encji Component pomyślnie waliduje wynikową liczbę całkowitą.
  • 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ąc type encji Feature dla poświadczeń (oznaczony etykietą feature.aggrega.ai/kind: secret) i używając własnych values tego załącznika do opisania zapytania do magazynu sekretów. To konwencja, a nie kontrola kompilatora — kompilator nie interpretuje znaczenia liścia values i przeniesie literał inline dosłownie. To powierzchnia załączników sprawia, że poprawnie napisana forma jest dostępna i typowana.
  • Ograniczenie 2: Components agnostyczne wobec możliwości

    • Nieobsługiwany wzorzec: architekt pisze aws_instance_type: string w deklaracji schema: 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.
  • Ograniczenie 3: logika warunkowa na metadanych

    • Nieobsługiwany wzorzec: Ops pisze {{ if eq .context.labels.gpu "true" }} w encji Recipe, aby zasadniczo zmienić strategię wdrożenia.
    • Dlaczego: kanał .context omija walidację schema: poszczególnych filarów. Poleganie na niezwalidowanych etykietach w podstawowej logice infrastruktury czyni platformę kruchą. Obiekt .context przenosi tagi metadanych (np. rozliczenia, SOC2); routing strukturalny należy do filarów walidowanych schematem.
  • Ograniczenie 4: encja Release nie może nadpisywać wartości programisty

    • Nieobsługiwany wzorzec: Ops próbuje z poziomu encji Release nadpisać logikę poznawczą programisty (np. zmieniając workers: 4 na workers: 10).
    • Dlaczego: encja Aggregate jest jedynym źródłem prawdy o intencji programisty. Jeśli wartość jest zakodowana na stałe w encji Aggregate, jest niezmienna we wszystkich środowiskach. Jeśli wartość musi się zmieniać zależnie od środowiska, programista stosuje wynoszenie parametrów. Schemat encji Release egzekwuje to, zakazując bloków values i ograniczając Ops do spełnienia kontraktu parameters oraz zdefiniowania fizycznej infra.
  • Ograniczenie 5: etykiety na poziomie instancji w encji Aggregate

    • Nieobsługiwany wzorzec: programista pisze labels: {} w instancji komponentu wewnątrz encji Aggregate.
    • 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żania infra i nadpisań funkcji dla każdego komponentu bez mieszania autorstwa etykiet z encją Aggregate programisty.

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 tablicy parameters.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 na helm po jednym Kubernetes NetworkPolicy na 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ędzi uses na 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; na compose, 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-external w 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Wykonanie przez kompilator podczas renderowania (przekazanie)

  1. Kompilator ewaluuje encję Recipe dla legacy-oracle. Dla encji Release dostarczającej legacy_oracle_ip: "10.0.4.55" jej primary_endpoint to oracle://10.0.4.55:1521/PROD_DB.
  2. Na helm referencyjna encja Workload renderuje jeden ExternalName Service, legacy-oracle, z externalName: 10.0.4.55 i portem 1521; na compose nie renderuje niczego.
  3. Następnie kompilator renderuje encję Recipe dla my-agent. Jej kanał .context.uses przenosi provides węzła Oracle, a kontrakt inject już rozwiązał względem nich ORACLE_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.

  1. Platformowa encja Aggregate: zespół infrastruktury pisze standardowy plik Aggregate.yaml, w którym komponentami są core/aws-vpc, core/eks-cluster i core/istio-base.
  2. Platformowa encja Release: zespół wdraża ten agregat. Renderer powiązany z tymi komponentami platformy generuje artefakty potrzebne do postawienia infrastruktury bazowej.
  3. 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 Release aplikacji.