Arsitektur Provider
Sebuah provider merender jenis input sebuah Recipe menjadi file manifest bawaan provider. Ketika sebuah Recipe mendeklarasikan capability: helm, capability: compose, atau nama provider lainnya, compiler mendelegasikan perenderan ke provider yang melayani nama tersebut. Bab ini membahas bagaimana sebuah provider diwujudkan sebagai Plugin perenderan provider, bagaimana delegasi bekerja, dan kontrak plugin-socket yang mengikat compiler ke setiap provider.
Yang tidak dibahas dalam bab ini: model komposisi tiga jenis input (source: + valuesMapping:, workload:, artifacts: — masing-masing menerima konten inline atau $import:) yang digunakan sebuah Recipe untuk menghasilkan outputnya. Model tersebut bersifat lintas sektoral di semua provider dan dibahas di ../../architecture/16-recipe-input-composition.md, termasuk Provider Capability Matrix yang memetakan jenis input mana yang didukung oleh setiap provider.
Plugin provider-rendering
Perenderan Provider dilayani oleh sebuah Plugin dengan pluginType: provider. Plugin perenderan provider:
- melayani satu atau beberapa nama provider — dideklarasikan dalam
spec.provider.capabilities. Nama provider yang disebut oleh sebuah Recipe (spec.capability: helm) terikat ke Plugin provider-rendering yang daftarspec.provider.capabilities-nya mencakup nama tersebut. Jika lebih dari satu Plugin melayani target yang sama, workspace memilih di antaranya melalui pengikatan provider dalam.aggrega-config.yaml, yang di-resolve saataggrega pulldan dicatat dalam lockfile; tanpa pengikatan dan dengan tepat satu kandidat, kandidat tersebut digunakan, dan tanpa pengikatan dengan lebih dari satu kandidat, build berhenti secara eksplisit dengan menyebutkan plugin-plugin kandidat. - membawa metadata provider-socket-nya dalam blok yang sama —
spec.providermemuat daftar kapabilitas di atas bersama deklarasi provider lainnya.spec.provider.workloadSchemaadalah deklarasi JSON Schema 2020-12 yang mendokumentasikan bagaimana jenis Workload milik platform diterjemahkan ke dalam output native provider ini; katalog pustaka standar mendeklarasikannya pada provider yang melakukan sintesis, sebagai kontrak terjemahan yang terdokumentasi.spec.provider.wellKnownAnnotationsmenyebutkan anotasi batasaggrega.ai/yang dibaca oleh provider. Dukungan input tersintesis (workload:) adalah properti dari provider, yang ditegakkan saat render — tidak ditentukan oleh keberadaanworkloadSchema.
Lihat ../entities/plugin.md untuk permukaan authoring lengkap tingkat field dari entitas Plugin, termasuk blok spec.provider.
Dispatch per provider
Setiap Recipe mendeklarasikan tepat satu capability: di bagian atas spec-nya. Compiler membaca field ini dan mendelegasikan rendering ke provider yang melayani nama tersebut. Sebuah Recipe tidak dapat menargetkan beberapa provider sekaligus. Komposisi multi-provider terjadi pada tingkat Release: sebuah boundary dapat memuat komponen dengan provider campuran, dan kontributor setiap provider pada jalur perakitan boundary yang telah dievaluasi dirakit secara independen — satu perakitan per tuple (path, provider).
Jalur dispatch untuk satu node:
- Compiler me-resolve URI Recipe untuk node ini melalui pencarian tiga tingkat Manifest di bawah bagian pemetaan provider target. Pengelompokan Manifest berdasarkan sumbu provider itulah yang menjadikan “Component yang sama, Recipes berbeda untuk provider berbeda” sebuah pola yang wajar.
spec.capabilitymilik Recipe yang telah di-resolve mengidentifikasi nama provider tujuan dispatch.- Compiler mengikat provider untuk nama tersebut: compiler me-resolve Plugin provider-rendering yang daftar
spec.provider.capabilities-nya mencakup nama itu dan melakukan rendering melalui guest Plugin tersebut. Rendering hanya berbasis Wasm — tidak ada renderer di dalam host sebagai cadangan, sehingga nama provider yang tidak ter-resolve ke Plugin mana pun yang melayaninya menghentikan build secara eksplisit pada saat routing. - Provider dipanggil dengan konteks render per node (nilai pilar, proyeksi
.context.*, jenis input Recipe). - Provider mengembalikan output yang telah di-render. Compiler meneruskan file hasil render ke assembler per-
(path, provider)yang dikunci padadirectory:boundary yang telah dievaluasi, digabungkan dengansubDirectory:per komponen. Dua boundary yang dievaluasi ke jalur yang sama di bawah provider yang sama berbagi satu assembler — pola kanonisnya adalah satu boundary induk ditambah dua boundary anak dengandirectory: "{{ .parent_boundary.directory }}"yang menyatu menjadi satu perakitan gabungan.
Lihat ../entities/manifest.md untuk bentuk dispatch sumbu provider pada Manifest, dan ../entities/recipe.md untuk deklarasi provider tunggal di sisi Recipe. Model perakitan per-(path, provider) dan allowlist variabel templat jalur yang mengendalikan jalur yang dievaluasi didokumentasikan dalam ../path-template-variables.md.
Kontrak plugin Wasm
Provider rendering berjalan di dalam sandbox WebAssembly. Compiler Go adalah host; Plugin provider-rendering adalah guest. Untuk setiap node, compiler menyerahkan konteks render node tersebut kepada plugin, dan plugin mengembalikan file yang direndernya. Kontrak ini seragam di semua provider:
- Encoding biner kanonis di kedua arah. Kompiler meng-encode konteks render — nilai dan lampiran node,
.workloadyang telah di-parse, entri artefak yang telah dievaluasi, daftar khusus nama dari.sourceyang telah di-resolve, dan metadata boundary — sebagai CBOR kanonis (RFC 8949 §4.2.1) lalu menyerahkannya kepada plugin. Plugin menjawab dalam encoding yang sama dengan daftar file yang di-render-nya — masing-masing berupa path relatif terhadap root output node dan byte persis yang akan ditulis di sana, opsional beserta format file tersebut — di samping diagnostik apa pun. Setiap export dari socket, mulai dari me-render satu node hingga merakit boundary dan menyambungkan tautan lintas boundary, membawa encoding ini di kedua arah, dan kit pengembangan plugin setiap bahasa melakukan decode dan encode untuk plugin. Jawaban yang bukan bentuk output export tersebut dalam encoding ini menghentikan build. Kontrak plugin mendokumentasikan payload setiap export. - Tanpa akses filesystem. Plugins tidak dapat membaca file sembarang dari filesystem host. Sumber yang disebut oleh sebuah Recipe — chart di registry, modul di repositori — di-resolve oleh kompiler sebelum plugin berjalan; plugin menerima daftar khusus nama dari sumber tersebut dan meminta file yang dipilihnya kepada kompiler melalui host function, yang hanya menjawab untuk file di bawah sumber node tersebut.
- Tanpa akses jaringan. Plugins bersifat deterministik dan hermetis, dan tidak membuka koneksi sendiri. Input eksternal yang dibutuhkan plugin saat rendering — skema jarak jauh yang dirujuk oleh nilai sebuah chart — diminta melalui host function input eksternal milik kompiler, yang menjawab dari konten yang di-pin oleh workspace untuk rujukan tersebut.
- Output deterministik. Dengan input yang identik dan versi plugin yang sama, plugin harus menghasilkan output yang identik per byte. Inilah kontrak yang membuat jaminan output identik per byte dari kompiler berlaku secara menyeluruh melalui lapisan plugin. Build yang dijalankan dengan
--verify-determinismme-render setiap node dua kali dan berhenti ketika dua hasil render sebuah node berbeda.
Arsitektur plugin-socket pada tingkat ekstensibilitas yang lebih luas, termasuk socket Wasm lain dalam pipeline kompilasi (peran transform dan verdict dari socket governance), terdapat di ../../architecture/14-extensibility.md.
Provider pustaka standar Aggrega
Provider helm, helm-chart, compose, terraform, dan cloudformation bersama-sama membentuk himpunan provider pustaka standar. Provider tersebut mencakup target deployment yang umum tanpa mengharuskan tim perusahaan menulis provider mereka sendiri.
helm mendukung ketiga jenis input: sourced (chart Helm upstream yang diambil melalui Helm SDK dengan output valuesMapping milik Recipe sebagai override chart), synthesized (YAML Kubernetes datar — objek controller yang dipilih oleh form milik Workload (Deployment, StatefulSet, DaemonSet, Job, atau CronJob) ditambah Services dan PVC — yang dihasilkan dari Workload yang telah di-parse), dan artifacts (file YAML mandiri di samping output chart). Lihat Provider Capability Matrix di ../../architecture/16-recipe-input-composition.md untuk mengetahui jenis mana dari ketiganya yang diterimanya.
helm-chart mendukung mode sourced (komposisi umbrella chart: satu chart per boundary, satu sub-chart per komponen) dan artifacts: yang menyertainya, dalam kedua bentuk penulisan. Entri artifacts: yang dimuat dengan $import: terlebih dahulu diproses dengan template Go oleh Aggrega, lalu disisipkan ke direktori templates/ milik chart sebelum render; entri artifacts: dengan konten inline dievaluasi dengan cara yang sama dan ditempatkan di root sub-chart, tanpa informasi asal-usul yang digabungkan, tempat template milik chart itu sendiri membacanya melalui .Files.Get / .Files.Glob milik Helm. Recipe mandiri yang hanya berisi artifacts bukan salah satu jenis yang dideklarasikannya, begitu pula jenis synthesized: umbrella mengorkestrasi sub-chart, sedangkan jenis Workload adalah konsep daun yang berada di dalam setiap sub-chart (domain provider helm).
compose mendukung sourced (memuat file compose dan melakukan deep-merge terhadap overlay valuesMapping), synthesized (menghasilkan services: + volumes: + networks: compose dari Workload yang telah di-parse untuk bentuk stateless dan stateful, dengan penanganan volume yang terdegradasi untuk persistentTemplate — PVC per replika diciutkan menjadi satu named volume bersama disertai peringatan; bentuk daemon, scheduled, dan task tidak memiliki pemetaan compose dan berhenti secara eksplisit), serta artifacts (fragmen compose yang kunci tingkat atasnya services: / networks: / volumes: / configs: digabungkan ke dalam docker-compose.yaml gabungan per boundary). Artifacts dapat menyertai salah satu dari dua jenis lainnya, dan Recipe mandiri yang hanya berisi artifacts — artifacts: tanpa source: dan tanpa workload: — juga merupakan jenis yang dideklarasikan provider ini: fragmennya digabungkan dengan aturan yang sama, sehingga node menyumbangkan tepat apa yang dideklarasikannya dan tidak memerlukan Workload sebagai pengganti komputasi yang tidak dimilikinya.
terraform mendukung sourced (menyertakan modul Terraform apa adanya dan memberikan output valuesMapping sebagai argumen blok module komponen tersebut dalam konfigurasi root boundary) dan artifacts (menghasilkan body HCL atau .tf.json yang ditulis sebagaimana hasil evaluasi template-nya, tanpa menulis ulang). Provider ini tidak menawarkan jenis input synthesized — tidak ada pemetaan yang setia dari jenis Workload platform ke resource Terraform sembarang. Provider ini menghasilkan konfigurasi dan tidak pernah menjalankan Terraform; nilai yang bergantung pada runtime tetap berupa string interpolasi ${ ... } yang diselesaikan oleh runtime Terraform saat apply.
cloudformation me-render sebuah boundary menjadi satu template stack AWS CloudFormation, dengan merakit fragmen resource yang ditulis komponen-komponennya menjadi satu template JSON murni, menampilkan provides setiap komponen sebagai Outputs stack, dan menghubungkan edge uses sebagai Fn::GetAtt di dalam satu stack serta sebagai Fn::ImportValue / Fn::GetStackOutput antar-stack. Provider ini mendukung input sourced dan artifacts serta menghasilkan konfigurasi tanpa pernah menjalankan CloudFormation; nilai yang hanya ada saat runtime tetap berupa intrinsic CloudFormation.
Indeks referensi provider mengarahkan Anda ke halaman referensi masing-masing provider; jenis input yang diterima setiap provider dijawab oleh capability matrix di ../../architecture/16-recipe-input-composition.md.
Provider kustom
Tim enterprise yang membuat provider sendiri mengikuti pola yang sama dengan pustaka standar: buat Plugin provider-rendering (pluginType: provider) yang mendeklarasikan nama provider yang dilayaninya di spec.provider.capabilities, bersama metadata spec.provider lainnya, lalu kirimkan artefak Wasm yang mengimplementasikan kontrak rendering di atas. Compiler memperlakukan provider kustom secara identik dengan provider pustaka standar; dispatch per provider bekerja berdasarkan nama provider yang dideklarasikan oleh Recipe.
Cara membuatnya sudah didokumentasikan, bukan ditunda. Membuat provider membangun guest provider yang berfungsi dari awal hingga akhir — laporan diri describe(), build, entitas Plugin, pemasangan, dan render yang keluarannya dapat Anda baca. Panduan pengembang plugin Wasm adalah referensi untuk entitas dan siklus hidup publikasi, dan kontrak plugin mendokumentasikan bentuk payload dan hasil setiap socket. Guest ditulis dalam Go, Rust, atau TypeScript menggunakan kit pengembangan plugin.