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-bridgez 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 routingucore/k8s-dns-resolverpo 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/postgresJedyna 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:
aggrega scaffold --example cross-boundary-networkingNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd cross-boundary-networkingKompilacja
Każdy wariant to jedna encja Release, budowana względem własnego folderu katalogu, jedna encja Release na uruchomienie:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmZ 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
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeNadrzę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
valuesMappingzapisuje konfigurację nginxstreambramy, dostarczaną jako zamontowany config compose (najwyższego poziomuconfigs:, zamontowany w/etc/nginx/nginx.conf); zawiera onaresolveroraz zmiennąproxy_passdla 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
valuesMappingwskazuje oba końce wx-aggrega-networks-ofbramy, które rozwiązuje dostawca compose, więc brama dołącza do obu mostkowanych sieci; - jego
injectMapping, uruchamiany dla adminera, przepisuje zmiennąADMINER_DEFAULT_SERVERkonsumenta naaggrega-gw:5432. Przepisanie zastępuje wartość dostarczoną przez własne połączeniedatabasesadminera; 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
cd dist/bridge/composedocker compose upNależy otworzyć http://localhost:8080 (serwer wstępnie wypełniony jako aggrega-gw:5432) i zalogować się:
| Pole | Wartość |
|---|---|
| System | PostgreSQL |
| Serwer | aggrega-gw:5432 (wstępnie wypełnione) |
| Nazwa użytkownika | appuser |
| Hasło | apppass |
| Baza danych | appdb |
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
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmTa 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: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendNie 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:
- 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 granic | oddzielne sieci compose | oddzielne przestrzenie nazw |
| mechanizm przekraczania | brama core/compose-bridge (aggrega-gw) | natywny DNS między przestrzeniami nazw |
ADMINER_DEFAULT_SERVER rozwiązuje się do | aggrega-gw:5432 (przepisane) | db-default.backend (kwalifikowane po stronie wywołującego) |
| dodatkowy zasób | usługa aggrega-gw wraz z jej konfiguracją | brak |
ta sama adnotacja aggrega.ai/namespace steruje | umieszczeniem w sieci compose | umieszczeniem 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.