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

Sieć między granicami — jedna intencja, dwa wdrożenia

Stos z dwóch komponentów — interfejsu bazy danych Adminer i bazy danych PostgreSQL — podzielony między dwie granice, przy czym Adminer musi sięgać do bazy danych przez szew granicy. Ta sama intencja programisty wdraża się na dwa sposoby, a lekcją jest kontrast:

  • Lokalnie (Docker Compose): każda granica jest osobną siecią compose, a usługa w jednej nie może sięgnąć do usługi w drugiej po nazwie. FeatureRecipe dla compose encji Feature core/compose-bridge z biblioteki standardowej generuje bramę aggrega-gw, która przekracza ten szew.
  • Kubernetes (Helm): każda granica jest osobną przestrzenią nazw, a pod w jednej sięga do obiektu Service w innej przez natywny DNS między przestrzeniami nazw (db-default.backend) — bez mostu. Baza danych publikuje samą nazwę usługi; funkcja routingu core/k8s-dns-resolver po stronie konsumenta kwalifikuje ją docelową przestrzenią nazw.

Most compose to to, co przestrzenie nazw Kubernetes wraz z DNS między przestrzeniami nazw zapewniają natywnie. Przekraczanie szwu to kwestia Ops/operatora, która zależy od celu; intencja programisty się nie zmienia. Ta sama adnotacja granicy aggrega.ai/namespace steruje umieszczaniem w sieci compose w jednym wariancie i w przestrzeni nazw Kubernetes w drugim.

Wspólna intencja dewelopera

aggregate.yaml jest identyczny dla obu wariantów:

components:
adminer:
type: core/devtool/adminer
uses:
databases:
primary:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant
from: host # ← the target db's provides.host
db:
type: core/datastore/postgres

Jedyna krawędź uses wstrzykuje host bazy danych do ADMINER_DEFAULT_SERVER. To, na co rozwiązuje się ten host, jest kwestią Ops rozstrzyganą poniżej encji Aggregate — dlatego ta sama krawędź daje aggrega-gw:5432 w compose i db-default.backend w helm, bez żadnej zmiany intencji dewelopera.

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:

Terminal window
aggrega scaffold --example cross-boundary-networking

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd cross-boundary-networking

Kompilacja

Każdy wariant to jedna encja Release, budowana względem własnego folderu katalogu, jedna encja Release na uruchomienie:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

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 `cross-boundary-networking`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `cross-boundary-networking` i bez `dir`: zapisuje ono przykład w nowym folderze `cross-boundary-networking`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `cross-boundary-networking`, `release` ustawionym na `release-compose.yaml`, `catalog_dirs` ustawionym na listę zawierającą `catalog-compose`, `auto_pull` ustawionym na true i `write` ustawionym na true. Następnie wywołaj narzędzie `build` w ten sam sposób z `release` ustawionym na `release-helm.yaml` i `catalog_dirs` ustawionym na listę zawierającą `catalog-helm`. Podaj mi, które pliki zapisała każda kompilacja; znajdują się w `cross-boundary-networking/dist/`.

Wariant A — lokalnie (Docker Compose): mostek

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

Nadrzędna granica bridge zawiera dwie granice podrzędne, frontend (adminer) i backend (db), które współdzielą jeden katalog, dzięki czemu scalają się w jeden plik dist/bridge/compose/docker-compose.yaml. Adnotacja aggrega.ai/namespace każdej granicy podrzędnej staje się siecią compose. core/compose-bridge, dołączony na poziomie granicy nadrzędnej (zakres granicy), wyprowadza bramę aggrega-gw z krawędzi uses przekraczającej granicę sieci. Jego FeatureRecipe z biblioteki standardowej oblicza raz dla granicy tabelę krawędzi do zmostkowania — oba końce w tym jednym pliku compose, w różnych sieciach — a wszystko, co opisano poniżej, jego własne szablony odczytują z tej tabeli:

  • jego valuesMapping zapisuje konfigurację nginx stream bramy, dostarczaną jako zamontowany config compose (najwyższego poziomu configs:, zamontowany w /etc/nginx/nginx.conf); zawiera ona resolver oraz zmienną proxy_pass dla każdej krawędzi, dzięki czemu upstream jest rozwiązywany w chwili nawiązania połączenia (znak $ jest escapowany jako $$, aby interpolacja Compose pozostawiła go nietkniętym dla nginx);
  • ten sam valuesMapping wskazuje oba końce w x-aggrega-networks-of bramy, które rozwiązuje dostawca compose, więc brama dołącza do obu mostkowanych sieci;
  • jego injectMapping, uruchamiany dla adminera, przepisuje zmienną ADMINER_DEFAULT_SERVER konsumenta na aggrega-gw:5432. Przepisanie zastępuje wartość dostarczoną przez własne połączenie databases adminera; gdyby tę zmienną dostarczała inna encja Feature dołączona do adminera, kompilacja zostałaby zatrzymana ze wskazaniem obu, zamiast ją zastąpić.

Ruch płynie więc adminer → aggrega-gw:5432 → proxy_pass db:5432, przekraczając styk sieci przez bramę.

Uruchomienie

Terminal window
cd dist/bridge/compose
docker compose up

Należy otworzyć http://localhost:8080 (serwer wstępnie wypełniony jako aggrega-gw:5432) i zalogować się:

PoleWartość
SystemPostgreSQL
Serweraggrega-gw:5432 (wstępnie wypełnione)
Nazwa użytkownikaappuser
Hasłoapppass
Baza danychappdb

Dane uwierzytelniające służą wyłącznie do demonstracji (ustawione bezpośrednio w recepturze db, aby stos działał od razu); rzeczywiste wdrożenie korzysta z podsystemu danych uwierzytelniających.

Wariant B — Kubernetes (Helm): przestrzenie nazw + DNS między przestrzeniami nazw

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Ta sama encja Aggregate, wdrożona w Kubernetes. Dwie granice równorzędne, każda z odrębną adnotacją aggrega.ai/namespace, która kaskadowo trafia do każdego zasobu jako metadata.namespace:

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

Nie ma żadnego aggrega-gw. Recipe helm db publikuje w provides.host samą nazwę usługi — provider helm nadaje syntetyzowanej usłudze Service nazwę <rendered_name>-<service-key> (db-default), bez przestrzeni nazw. Konsument dołącza funkcję routingu core/k8s-dns-resolver (encja Release kieruje ją na ADMINER_DEFAULT_SERVER), a funkcja ta uzupełnia samą nazwę hosta o przestrzeń nazw celu po stronie samego konsumenta — tworząc nazwę DNS między przestrzeniami nazw db-default.backend, zanim Adminer zostanie wyrenderowany. Host jest wyprowadzany, a nie wpisywany ręcznie w producencie:

dist/frontend/helm/adminer-deployment.yaml
- name: ADMINER_DEFAULT_SERVER
value: db-default.backend # == the rendered db Service <name>.<namespace>

Ta wartość co do bajtu odpowiada wartościom metadata.name + metadata.namespace wyrenderowanej usługi Service bazy db, i to jest cały dowód: DNS między przestrzeniami nazw w Kubernetes jest deterministycznym kontraktem, więc jeśli wyrenderowany host jest równy wyrenderowanej tożsamości usługi Service, zostanie rozwiązany w czasie działania — bez bramy i bez działającego klastra potrzebnego do weryfikacji połączeń.

Dwoistość

compose (wariant A)helm (wariant B)
styk granicoddzielne sieci composeoddzielne przestrzenie nazw
mechanizm przekraczaniabrama core/compose-bridge (aggrega-gw)natywny DNS między przestrzeniami nazw
ADMINER_DEFAULT_SERVER rozwiązuje się doaggrega-gw:5432 (przepisane)db-default.backend (kwalifikowane po stronie wywołującego)
dodatkowy zasóbusługa aggrega-gw wraz z jej konfiguracjąbrak
ta sama adnotacja aggrega.ai/namespace sterujeumieszczeniem w sieci composeumieszczeniem w przestrzeni nazw k8s

Jedna intencja dewelopera; przekraczanie styku to mechanizm Ops/Operator specyficzny dla dostawcy. Most compose istnieje, ponieważ płaska sieć compose nie ma DNS ograniczonego do przestrzeni nazw; Kubernetes zapewnia to natywnie.

Gdy oba końce są renderowane przez różnych dostawców

Oba powyższe warianty zachowują jedną intencję programisty i pozwalają, by przejście opierało się na deterministycznym ciągu wskaźnika: wartość provides.host bazy danych przechodzi przez szew granicy jako stabilny wskaźnik, a każdy cel rozwiązuje ten wskaźnik na swój sposób — jako adres bramy compose albo jako nazwę DNS między przestrzeniami nazw. Wskaźnik zawsze przechodzi, ponieważ kompilator przekazuje ciągi znaków między producentem a konsumentem, nie interpretując ich.

Dostawca może pójść dalej i połączyć natywne odwołanie krzyżowe między dwoma swoimi własnymi złożonymi artefaktami po obu stronach szwu — odwołanie w słownictwie tego dostawcy, które platforma docelowa rozwiązuje w czasie wdrożenia. Dostawca CloudFormation robi tak dla krawędzi uses, która przecina stosy: stos producenta publikuje Export, a stos konsumenta odczytuje go za pomocą Fn::ImportValue (zob. providers/cloudformation.md). Natywne odwołanie krzyżowe jest ulepszeniem w obrębie tego samego dostawcy — działa, ponieważ oba końce posługują się tym samym słownictwem artefaktów, więc jedna strona może opublikować odwołanie, które druga strona potrafi rozwiązać.

Gdy krawędź uses przecina granicę między dwoma różnymi dostawcami — producent jest składany przez jednego dostawcę, a konsument przez innego — natywne odwołanie krzyżowe nie jest możliwe. Odwołanie utworzone w słownictwie jednego dostawcy nic nie znaczy dla drugiego, a kompilator nie tłumaczy między nimi: przekazuje ciągi znaków, nie wnioskuje o znaczeniu ani nie przepisuje odwołania jednego dostawcy na postać innego. Dlatego deterministyczny wskaźnik producenta przechodzi przez szew bez zmian; tam, gdzie którykolwiek z dwóch dostawców sam łączy natywne odwołania krzyżowe, jak robi to CloudFormation, kompilator emituje ostrzeżenie wskazujące oba punkty końcowe, nazwy obu dostawców i gniazdo; a kompilacja kończy się z tym wskaźnikiem. Kompilator ufa autorowi i nie przerywa działania: deterministyczny wskaźnik podany przez autora może z powodzeniem dać się rozwiązać po drugiej stronie szwu — stabilna nazwa DNS lub ciąg interpolacji infrastruktury — a tylko autor zna topologię docelową.

Dzięki temu przechodzenie przez szew pozostaje tam, gdzie jego miejsce. To, czy wskaźnik między dostawcami jest użyteczny, jest kwestią wdrożenia, za którą odpowiada autor; tłumaczenie natywnego odwołania jednego dostawcy na postać konsumenta innego dostawcy jest pracą z własnym zdaniem, specyficzną dla dostawcy, która znajduje się poza neutralnym rdzeniem.

Struktura

cross-boundary-networking/
├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry
├── aggregate.yaml # SHARED developer intent (both variants)
├── release-compose.yaml # Variant A: parent bridge boundary + two networks
├── manifest-compose.yaml
├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)
├── release-helm.yaml # Variant B: two namespace boundaries, no bridge
├── manifest-helm.yaml
└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)

Ten przykład korzysta z biblioteki standardowej. Każdy wariant buduje się z --catalog catalog-<variant>, czyli z własnym katalogiem lokalnym, a to, czego ten katalog nie deklaruje, rozwiązuje z hub.aggrega.ai, domyślnego rejestru wskazanego w .aggrega-config.yaml, dzięki czemu encje lokalne są rozwiązywane przed współdzielonymi. core/datastore/postgres, współdzielony komponent interfejsu core/devtool/adminer, encje Features core/compose-bridge i core/k8s-dns-resolver wraz z ich encjami FeatureRecipes dla compose i helm oraz dostawcy compose/helm pochodzą z katalogu standardowego. Lokalnie pozostaje treść dydaktyczna specyficzna dla przykładu: receptury Adminer dla poszczególnych celów. Receptura helm db to helm/postgres z biblioteki standardowej, której provides.host jest samą, samodzielną nazwą usługi. Konsument kwalifikuje ją przestrzenią nazw celu po stronie wywołującego za pomocą funkcji routingu core/k8s-dns-resolver z biblioteki standardowej, więc receptura nie koduje na sztywno przestrzeni nazw granicy.

W zbudowanym wariancie spotykają się dwie kategorie plików: dane wejściowe tworzone przez autora (wszystko powyżej) oraz dane wyjściowe generowane przez kompilator w dist/ (scalony docker-compose.yaml lub manifesty helm dla poszczególnych przestrzeni nazw) — żadnego z tych ostatnich nie tworzy się ręcznie. dist/ jest generowany ponownie przez aggrega build i ignorowany przez git.