Jaringan lintas batas — satu intensi, dua deployment
Sebuah stack dua komponen — UI basis data Adminer dan basis data PostgreSQL — yang terbagi di dua batas, dengan Adminer harus menjangkau basis data melintasi sambungan batas. Intensi developer yang sama di-deploy dengan dua cara, dan kontras inilah pelajarannya:
- Lokal (Docker Compose): setiap batas adalah jaringan compose tersendiri, dan sebuah layanan di satu batas tidak dapat menjangkau layanan di batas lain berdasarkan nama. FeatureRecipe compose milik Feature pustaka standar
core/compose-bridgemenghasilkan gatewayaggrega-gwuntuk melintasi sambungan tersebut. - Kubernetes (Helm): setiap batas adalah namespace tersendiri, dan sebuah pod di
satu namespace menjangkau Service di namespace lain melalui DNS lintas namespace bawaan
(
db-default.backend) — tanpa bridge. Basis data memublikasikan nama layanan polos; fitur peruteancore/k8s-dns-resolvermilik konsumen mengkualifikasinya dengan namespace target.
Compose-bridge adalah apa yang diberikan secara bawaan oleh namespace Kubernetes + DNS lintas namespace
kepada Anda. Pelintasan sambungan adalah urusan Ops/Operator yang berbeda menurut target;
intensi developer tidak berubah. Anotasi batas aggrega.ai/namespace
yang sama persis mengarahkan penempatan jaringan compose di satu varian dan
penempatan namespace Kubernetes di varian lainnya.
Intent pengembang bersama
aggregate.yaml identik untuk kedua varian:
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/postgresSatu-satunya edge uses menyuntikkan host milik database ke dalam ADMINER_DEFAULT_SERVER.
Ke mana host tersebut di-resolve adalah urusan Ops yang diputuskan di bawah Aggregate — sehingga
edge yang sama menghasilkan aggrega-gw:5432 di bawah compose dan db-default.backend
di bawah helm, tanpa perubahan pada intent pengembang.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example cross-boundary-networkingKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd cross-boundary-networkingBuild
Setiap varian adalah satu Release, di-build terhadap direktori katalognya sendiri, satu Release per eksekusi:
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-helmDengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `cross-boundary-networking`, panggil alat `scaffold` sekali dengan `example` diatur ke `cross-boundary-networking` dan tanpa `dir`: alat ini menulis contoh ke dalam folder `cross-boundary-networking` yang baru. Lalu panggil alat `build` dengan `workspace_root` diatur ke `cross-boundary-networking`, `release` diatur ke `release-compose.yaml`, `catalog_dirs` diatur ke daftar yang berisi `catalog-compose`, `auto_pull` diatur ke true, dan `write` diatur ke true. Lalu panggil alat `build` dengan cara yang sama dengan `release` diatur ke `release-helm.yaml` dan `catalog_dirs` diatur ke daftar yang berisi `catalog-helm`. Beri tahu saya file mana yang ditulis oleh setiap build; file tersebut berada di bawah `cross-boundary-networking/dist/`.Varian A — lokal (Docker Compose): bridge
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeBoundary induk bridge memuat dua anak, frontend (adminer) dan backend (db), yang berbagi satu direktori sehingga keduanya digabung menjadi satu dist/bridge/compose/docker-compose.yaml. Anotasi aggrega.ai/namespace setiap anak menjadi sebuah network compose. core/compose-bridge, yang dipasang pada induk (cakupan boundary), menurunkan gateway aggrega-gw dari edge uses lintas network. FeatureRecipe pustaka standarnya menghitung, sekali untuk boundary tersebut, tabel edge yang perlu dijembatani — kedua ujungnya ada di satu file compose ini, pada network yang berbeda — dan semua yang ada di bawah ini dibaca dari tabel itu oleh templatnya sendiri:
valuesMapping-nya menulis konfigurasistreamnginx milik gateway, yang dikirimkan sebagai config compose yang di-mount (configs:tingkat atas, di-mount pada/etc/nginx/nginx.conf); konfigurasi ini memuatresolverdan variabel per edgeproxy_passsehingga upstream di-resolve saat koneksi dibuat ($di-escape menjadi$$agar interpolasi Compose membiarkannya utuh untuk nginx);valuesMappingyang sama menyebut kedua ujung di bawahx-aggrega-networks-ofmilik gateway, yang di-resolve oleh provider compose, sehingga gateway bergabung ke kedua network yang dijembatani;injectMapping-nya, yang dijalankan untuk adminer, menulis ulangADMINER_DEFAULT_SERVERmilik konsumen menjadiaggrega-gw:5432. Penulisan ulang ini menggantikan nilai yang dikirimkan oleh koneksidatabasesmilik adminer sendiri; seandainya Feature lain yang dipasang pada adminer mengirimkan variabel tersebut, build akan berhenti dengan menyebut keduanya alih-alih menggantinya.
Dengan demikian, lalu lintas mengalir adminer → aggrega-gw:5432 → proxy_pass db:5432, melintasi
batas network melalui gateway.
Menjalankannya
cd dist/bridge/composedocker compose upBuka http://localhost:8080 (server sudah terisi aggrega-gw:5432) lalu masuk:
| Field | Nilai |
|---|---|
| System | PostgreSQL |
| Server | aggrega-gw:5432 (sudah terisi) |
| Username | appuser |
| Password | apppass |
| Database | appdb |
Kredensial ini hanya untuk demo (ditetapkan secara inline pada recipe db agar stack dapat langsung berjalan); deployment sungguhan menggunakan subsistem kredensial.
Varian B — Kubernetes (Helm): namespace + DNS lintas namespace
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmAggregate yang sama, di-deploy ke Kubernetes. Dua boundary bersaudara, masing-masing dengan
anotasi aggrega.ai/namespace berbeda yang diturunkan ke setiap resource sebagai
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: backendTidak ada aggrega-gw. Recipe helm db memublikasikan nama service polos
di provides.host — provider helm menamai Service yang disintesis
<rendered_name>-<service-key> (db-default), tanpa namespace. Konsumen
melampirkan feature routing core/k8s-dns-resolver (Release mengarahkannya ke
ADMINER_DEFAULT_SERVER), dan feature tersebut mengualifikasi host polos itu dengan
namespace target di sisi konsumen sendiri — menghasilkan nama DNS lintas namespace
db-default.backend sebelum Adminer di-render. Host tersebut diturunkan, bukan
ditulis tangan ke dalam produsen:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>Nilai itu cocok byte demi byte dengan metadata.name +
metadata.namespace dari Service db yang di-render, dan itulah seluruh buktinya: DNS lintas namespace Kubernetes adalah
kontrak yang deterministik, sehingga jika host yang di-render sama dengan identitas Service
yang di-render, host tersebut ter-resolve saat runtime — tanpa gateway, tanpa perlu cluster aktif untuk memverifikasi
pengkabelannya.
Dualitas
| compose (Varian A) | helm (Varian B) | |
|---|---|---|
| sambungan batas | jaringan compose terpisah | namespace terpisah |
| mekanisme penyeberangan | gateway core/compose-bridge (aggrega-gw) | DNS lintas namespace bawaan |
ADMINER_DEFAULT_SERVER diresolusi menjadi | aggrega-gw:5432 (ditulis ulang) | db-default.backend (dikualifikasi di sisi pemanggil) |
| resource tambahan | service aggrega-gw + konfigurasinya | tidak ada |
aggrega.ai/namespace yang sama menentukan | penempatan jaringan compose | penempatan namespace k8s |
Satu intent pengembang; penyeberangan sambungan adalah mekanisme Ops/Operator yang spesifik untuk provider. Bridge compose ada karena jaringan compose yang datar tidak memiliki DNS yang dibatasi namespace; Kubernetes menyediakannya untuk Anda secara bawaan.
Ketika kedua ujung dirender di bawah provider yang berbeda
Kedua varian di atas mempertahankan satu maksud pengembang dan membiarkan penyeberangan berjalan di atas
string penunjuk deterministik: provides.host milik basis data mengalir melintasi
sambungan batas sebagai penunjuk yang stabil, dan setiap target me-resolve penunjuk itu dengan caranya
sendiri — sebuah alamat gateway compose, atau sebuah nama DNS lintas namespace. Penunjuk itu
selalu menyeberang, karena compiler menyalurkan string antara produsen dan
konsumen tanpa menafsirkannya.
Sebuah provider dapat melangkah lebih jauh dan menyambungkan referensi silang native antara dua artefak
rakitannya sendiri di kedua sisi sambungan — sebuah referensi dalam kosakata provider
itu sendiri yang di-resolve oleh platform target pada saat deploy. Provider
CloudFormation melakukan ini untuk edge uses yang melintasi stack: stack
produsen menerbitkan sebuah Export dan stack konsumen membacanya dengan
Fn::ImportValue (lihat providers/cloudformation.md).
Referensi silang native adalah peningkatan sesama provider — ini berfungsi karena kedua
ujung menggunakan kosakata artefak yang sama, sehingga satu sisi dapat menerbitkan referensi yang
diketahui cara me-resolve-nya oleh sisi lain.
Ketika sebuah edge uses melintasi batas antara dua provider yang berbeda — produsen dirakit di bawah satu provider dan konsumen di bawah provider lain — tidak ada referensi silang native yang mungkin. Referensi yang dibuat dalam kosakata satu provider tidak bermakna bagi provider lain, dan compiler tidak menerjemahkan di antara keduanya: compiler menyalurkan string, tidak menyimpulkan makna atau menulis ulang referensi satu provider ke dalam bentuk provider lain. Jadi penunjuk deterministik milik produsen melintasi sambungan tanpa diubah; jika salah satu dari kedua provider menghubungkan referensi silang native-nya sendiri, seperti yang dilakukan CloudFormation, compiler mengeluarkan peringatan yang menyebutkan kedua endpoint, kedua nama provider, dan socket-nya; dan build selesai dengan penunjuk itu. Compiler memercayai penulis dan tidak berhenti: penunjuk deterministik yang diberikan penulis bisa saja dapat di-resolve melintasi sambungan — sebuah nama DNS yang stabil atau string interpolasi infrastruktur — dan hanya penulis yang mengetahui topologi target.
Hal ini menjaga penyeberangan sambungan tetap di tempat yang semestinya. Apakah penunjuk lintas provider dapat digunakan adalah urusan deployment yang menjadi tanggung jawab penulis; menerjemahkan referensi native satu provider ke bentuk konsumen provider lain adalah pekerjaan yang beropini dan spesifik provider yang berada di luar inti yang netral.
Tata letak
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)Contoh ini menggunakan pustaka standar. Setiap varian dibangun dengan --catalog catalog-<variant>, direktori lokalnya sendiri, dan me-resolve apa yang tidak dideklarasikan direktori itu dari hub.aggrega.ai, registry default yang disebut .aggrega-config.yaml, sehingga entitas lokal di-resolve sebelum entitas bersama. core/datastore/postgres, komponen UI bersama core/devtool/adminer, Features core/compose-bridge dan core/k8s-dns-resolver beserta FeatureRecipes compose dan helm-nya, serta provider compose/helm berasal dari katalog standar. Yang tetap lokal adalah konten pengajaran khusus contoh ini: recipe Adminer per target. Recipe helm db adalah helm/postgres dari pustaka standar, yang provides.host-nya berupa nama layanan yang polos dan mandiri. Konsumen mengkualifikasinya dengan namespace target di sisi pemanggil melalui feature perutean pustaka standar core/k8s-dns-resolver, sehingga recipe tersebut tidak meng-hardcode namespace batas apa pun.
Dua kategori file bertemu dalam varian yang telah dibangun: input yang ditulis (semua
yang di atas) dan output yang dihasilkan kompiler di bawah dist/ (
docker-compose.yaml yang digabungkan, atau manifest helm per namespace) — Anda tidak menulis satu pun
dari yang terakhir. dist/ dibuat ulang oleh aggrega build dan diabaikan oleh git (gitignored).