Opublikowana nakładka obsługiwana przez encję Recipe swojej bazy
Ten przykład uczy jednego: encja Component, która extends inną, dziedziczy cały kontrakt danych tej bazy, więc każda encja Recipe napisana dla bazy już
implementuje rozszerzającą encję Component. Opublikowanie wyspecjalizowanego wariantu
komponentu z biblioteki standardowej kosztuje zatem jedną encję katalogu i jedną linię w encji Manifest
— bez własnej encji Recipe i bez zmian w bazie.
Nakładką jest tu example/gateway/nginx-reviewed. Jest dostarczana w katalogu
obok core/gateway/nginx, komponentu, który rozszerza.
Co nakładka dodaje, a co dziedziczy
Cała napisana przez autora powierzchnia nakładki to metadane i jedno gniazdo:
metadata: name: example/gateway/nginx-reviewed labels: component.aggrega.ai/type: server component.aggrega.ai/category: gateway gateway.example.com/audit-tier: reviewed # added gateway.example.com/data-zone: eu-west # added annotations: governance.example.com/review-board: platform-architecture # added governance.example.com/contact: platform-architecture@example.comspec: extends: core/gateway/nginx:1.0.0 schema: inherited usesSchema: reviewed_upstream: # added selector: "gateway.example.com/audit-tier=reviewed" inject: [env]schema: inherited to dosłowny znacznik, który rozszerzająca encja Component zapisuje w miejscu
bloku schema:. Stwierdza, że trzy filary danych — values, infra
i provides — należą do bazy, dokładnie w takiej postaci, w jakiej baza je zdefiniowała. Nakładka
nie deklaruje własnego klucza filaru i nie może tego zrobić: kontrakt należy do bazy,
na każdej głębokości łańcucha.
Wszystko, czego nakładka nie wymienia, dziedziczy. aggrega inspect example/gateway/nginx-reviewed --resolved pokazuje scaloną encję, a dwie
rzeczy w niej warto przeczytać uważnie:
- Trzy gniazda
uses, a nie jedno:upstreamiguard(gniazda bazy, przy czymupstreamwybieracomponent.aggrega.ai/type=server) orazreviewed_upstream(gniazdo nakładki). Rozszerzanie dodaje gniazdo; nie zastępuje zbioru. - Trzy filary bazy, dosłownie —
values.upstream_path,infra.port/engine_version/compute/overridesorazprovides.host/port/protocol, każdy z własnymi opisami bazy.
Co zapisuje konsumująca encja Aggregate
aggregate-reviewed.yaml deklaruje dwie warstwy bramy jako nakładkę, stojące przed
konsolą bazy danych:
components: edge: type: example/gateway/nginx-reviewed values: upstream_path: /api/ # declared by the base; the wrapper never mentions it uses: reviewed_upstream: # the socket the wrapper ADDS internal: { target: internal, inject: { env: [ ... ] } } internal: type: example/gateway/nginx-reviewed values: upstream_path: / uses: upstream: # the socket the wrapper INHERITS console: { target: console, inject: { env: [ ... ] } } console: type: core/devtool/adminerKluczem, na który warto zwrócić uwagę, jest upstream_path. Jest zadeklarowany w filarze values komponentu core/gateway/nginx
i nie pojawia się nigdzie w pliku nakładki, a mimo to autor
zapisuje go w instancji nakładki i trafia on do wyrenderowanej konfiguracji
bramy. Tak w praktyce wygląda dziedziczenie filarów w całości.
Drugą połową jest encja Manifest, w której na każdy typ przypada jedna linia:
mappings: components: type: example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0 core/gateway/nginx:1.0.0: compose/nginx:1.0.0 core/devtool/adminer:1.0.0: compose/adminer:1.0.0Obie linie bramy wskazują tę samą encję Recipe. compose/nginx deklaruje
implements: core/gateway/nginx:1.0.0, a encja Recipe wskazująca bazę jest
implementacją dla każdej encji Component rozszerzającej tę bazę — więc nakładka
jest przez nią obsługiwana bez zmian. Zachodzą tu jednocześnie dwa fakty i są one odrębne:
- Encja Recipe pasuje. Nie istnieje żadna encja Recipe implementująca własny typ nakładki i żadna nie jest potrzebna.
- Mapowanie jest nadal wymagane. Wybór encji Recipe odbywa się według dokładnego klucza mapowania, więc
nakładka potrzebuje własnego wpisu
type; nie dziedziczy wpisu bazy. Instancja nakładki bez własnego wpisu zatrzymuje kompilację diagnostyką niezmapowanej instancji nawet wtedy, gdy jej baza jest zmapowana.
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example extends-wrapperNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd extends-wrapperKompilacja
aggrega build --release release-reviewed.yaml --auto-pullWyrenderowane wyjście i plik blokady są generowane, a nie dostarczane: ten przykład
zatwierdza swoje dane wejściowe i generuje wszystko inne na nowo. --auto-pull rozwiązuje
plik blokady podczas kompilacji; jednorazowe uruchomienie aggrega pull --release release-reviewed.yaml
wcześniej robi to samo i pozwala kolejnym kompilacjom działać w ogóle bez flagi.
Zarówno nakładka, jak i rozszerzana przez nią baza znajdują się we wspólnym katalogu, który jest rozwiązywany z hub.aggrega.ai, domyślnego rejestru deklarowanego w .aggrega-config.yaml. Polecenie kompilacji nie wymaga flagi --catalog, podobnie jak aggrega inspect uruchamiane z tego katalogu.
Operacja pull pobiera core/gateway/nginx, ponieważ wrapper go rozszerza: baza jest zależnością wszystkiego, co ją rozszerza, więc operacja pull podąża za extends: wrappera i przypina bazę w pliku blokady niezależnie od tego, czy encja Manifest ją wymienia. Encja Manifest mapuje tu bazę z innego powodu — kontrolne wydanie poniżej deklaruje instancję samej bazy.
Wyrenderowany plik dist/compose/docker-compose.yaml zawiera dowody:
edge: image: nginx:1.27.5-alpine entrypoint: - /bin/sh - -c - echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;' [… omitted: the published port] labels: [… omitted: the other provenance labels every rendered document carries] aggrega.ai/recipe-uri: nginx:1.0.0 [… omitted: the service's network, its depends_on naming internal, and its healthcheck]Trzy odczyty, w kolejności tego, czego dowodzą:
aggrega.ai/recipe-uri: nginx:1.0.0— tę usługę ukształtowała encja Recipe bazy. Etykieta pochodzenia na instancji nakładki wskazuje encję Recipe bazy, ponieważ to ta encja Recipe ją wyrenderowała.location /api/—values.upstream_path, klucz deklarowany wyłącznie przez bazę, zapisany w instancji nakładki i wyrenderowany.proxy_pass http://internal:8081— krawędźreviewed_upstreamzostała rozwiązana.provides.hostiprovides.portcelu trafiły do kontekstu wstrzykiwania pod kluczami dostarczania, które odczytuje encja Recipe bazy, więc gniazdo dodane przez nakładkę przepływa przez encję Recipe, która nigdy o nim nie słyszała.
Plik blokady rozwiązywany przez kompilację odnotowuje ten sam fakt od strony resolvera:
jeden wpis compose/nginx:1.0.0 z jednym skrótem, do którego odwołują się oba klucze
mapowania — typ bazy i typ nakładki.
Etykiety i adnotacje nakładki przemieszczają się wraz z rozwiązaną krawędzią: kontekst renderowania
węzła konsumującego zawiera provides, labels i adnotacje każdego celu,
więc kontekst edge wie, że jego upstream to audit-tier=reviewed i kto go
przejrzał. To, czy cokolwiek z tego pojawi się w wyrenderowanym artefakcie, jest wyborem encji Recipe —
te etykiety i adnotacje stanowią tożsamość komponentu do odczytu przez selektory i polityki,
a nie wyjście, które kompilator nanosi.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `extends-wrapper`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `extends-wrapper` i bez `dir`: zapisuje ono przykład w nowym folderze `extends-wrapper`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `extends-wrapper`, `release` ustawionym na `release-reviewed.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj mi, które pliki zapisała kompilacja; znajdują się w `extends-wrapper/dist/`.Próba kontrolna: do czego służy dodana etykieta
aggregate-unreviewed.yaml to aggregate-reviewed.yaml z jedną zmianą —
warstwa wewnętrzna jest zadeklarowana jako sama baza core/gateway/nginx zamiast
nakładki — i oczekuje się, że zakończy się niepowodzeniem:
aggrega build --release release-negative-unreviewed.yaml --auto-pull# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.Zatrzymanie jest lekcją. Baza spełnia swoje własne gniazdo upstream — jest
component.aggrega.ai/type=server, a warstwa wewnętrzna jest podłączona przez to
gniazdo dokładnie w ten sam sposób — ale nie ma etykiety audit-tier, więc
ostrzejsze gniazdo nakładki ją odrzuca. Etykieta dodawana przez nakładkę sprawia, że
jej instancję można wybrać, a widać to w selektorze.
Warto znać jeszcze dwa zatrzymania; w obu przypadkach schemat wykonuje swoje zadanie:
- Encja Component, która deklaruje
extendsi zapisuje zawartość filarów podschema:, jest odrzucana podczas wczytywania dokumentu, z nazwaniem ograniczenia. Tak samo encja, która całkowicie pomijaschema:.schema: inheritedto jedyna akceptowana forma; jest zapisywana jawnie, a nie domniemywana, aby czytelnik nigdy nie pomylił odziedziczonego bloku filarów z zapomnianym. - Klucz
values, którego baza nie deklaruje, jest odrzucany w instancji nakładki, w zapisanej ścieżce, ponieważ egzekwowany kontrakt należy do bazy.
Dlaczego to jest przydatne
Organizacja, która ustaliła przejrzany kształt komponentu z biblioteki standardowej,
potrzebuje miejsca, w którym go przechowa. Opisane prozą etykiety, adnotacje i
gniazda są powtarzane w każdej encji Aggregate, która ich potrzebuje, i z czasem
się rozjeżdżają. Opublikowany jako encja Component rozszerzająca bazę kształt staje się
wersjonowaną, podlegającą przeglądowi encją katalogu z nazwą: zespół, który z niej korzysta, zapisuje
type: example/gateway/nginx-reviewed i jedną linię w encji Manifest, a dziedziczy
cały kontrakt bazy wraz z każdą encją Recipe już dla niej napisaną, na
każdym celu obsługiwanym przez bazę.
To, ile kosztuje nakładka, sprawia, że to działa: dodaje strukturę i metadane i nic więcej. Ponieważ nie deklaruje filarów, instancja nakładki i instancja bazy są walidowane względem jednego kontraktu, a encja Recipe napisana dla bazy nigdy nie zostanie zaskoczona jej specjalizacją.