Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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-bridge menghasilkan gateway aggrega-gw untuk 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 perutean core/k8s-dns-resolver milik 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/postgres

Satu-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:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd cross-boundary-networking

Build

Setiap varian adalah satu Release, di-build terhadap direktori katalognya sendiri, satu Release per eksekusi:

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

Dengan 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

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

Boundary 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 konfigurasi stream nginx milik gateway, yang dikirimkan sebagai config compose yang di-mount (configs: tingkat atas, di-mount pada /etc/nginx/nginx.conf); konfigurasi ini memuat resolver dan variabel per edge proxy_pass sehingga upstream di-resolve saat koneksi dibuat ($ di-escape menjadi $$ agar interpolasi Compose membiarkannya utuh untuk nginx);
  • valuesMapping yang sama menyebut kedua ujung di bawah x-aggrega-networks-of milik gateway, yang di-resolve oleh provider compose, sehingga gateway bergabung ke kedua network yang dijembatani;
  • injectMapping-nya, yang dijalankan untuk adminer, menulis ulang ADMINER_DEFAULT_SERVER milik konsumen menjadi aggrega-gw:5432. Penulisan ulang ini menggantikan nilai yang dikirimkan oleh koneksi databases milik 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

Terminal window
cd dist/bridge/compose
docker compose up

Buka http://localhost:8080 (server sudah terisi aggrega-gw:5432) lalu masuk:

FieldNilai
SystemPostgreSQL
Serveraggrega-gw:5432 (sudah terisi)
Usernameappuser
Passwordapppass
Databaseappdb

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

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

Aggregate 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: 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

Tidak 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:

dist/frontend/helm/adminer-deployment.yaml
- 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 batasjaringan compose terpisahnamespace terpisah
mekanisme penyeberangangateway core/compose-bridge (aggrega-gw)DNS lintas namespace bawaan
ADMINER_DEFAULT_SERVER diresolusi menjadiaggrega-gw:5432 (ditulis ulang)db-default.backend (dikualifikasi di sisi pemanggil)
resource tambahanservice aggrega-gw + konfigurasinyatidak ada
aggrega.ai/namespace yang sama menentukanpenempatan jaringan composepenempatan 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).