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

Komposisi keluaran

Satu build Aggrega menghasilkan berkas keluaran ke dalam direktori per batas di bawah dist/ melalui enam mekanisme yang berbeda — rendering bersumber, sintesis workload, FeatureRecipe Resource Generation, patch plugin-pipeline FeatureRecipe, komposisi tingkat Release, dan emisi artefak langsung. Mekanisme-mekanisme tersebut berjalan dalam urutan yang ditentukan; keluaran bertabrakan secara deterministik ketika dua mekanisme menghasilkan berkas dengan nama yang sama di direktori batas yang sama; ketika tabrakan terdeteksi, build berhenti sebelum emisi, dengan menyebutkan setiap kontributor, dalam kategori yang disebutkan oleh aturan tabrakan tersebut.

Halaman ini mendokumentasikan keenam mekanisme tersebut di satu tempat dan menyebutkan urutan rendering di antara mekanisme-mekanisme itu. Referensi per bab dan per entitas mencakup permukaannya masing-masing; aturan deteksi tabrakan untuk keenam mekanisme berada di sini.

Enam mekanisme penghasil keluaran

Setiap mekanisme berada pada permukaan penulisan Recipe / FeatureRecipe tertentu dan menghasilkan berkas dengan konvensi penamaan tertentu. Mekanisme-mekanisme ini terakumulasi per node — satu instans komponen dapat menggerakkan beberapa mekanisme sekaligus (sebuah Recipe dasar bersumber + sebuah berkas pendamping hasil sintesis Workload + sebuah CRD ExternalSecret yang diemisikan FeatureRecipe + sebuah patch plugin-pipeline yang diterapkan pada Deployment hasil sintesis).

1 — Rendering bersumber Recipe (source: + valuesMapping:)

Permukaan penulisan. Recipe mendeklarasikan source: <path> beserta valuesMapping: (field ini menerima templat Go inline, $import: berkas, atau $import: pustaka ke sebuah entri MappingLibrary — lihat entities/recipe.md “Field valuesMapping — tiga mode penulisan”). Sumber menunjuk ke chart Helm di disk, berkas YAML docker-compose, atau artefak native provider lainnya.

Penempatan dalam pipeline. Rendering dasar, setelah locals dan provides milik Recipe teresolusi.

Bentuk keluaran. Spesifik per Provider:

  • provider helm — berkas YAML Kubernetes datar, dinamai menurut identitas komponen lalu menurut resource itu sendiri: <component-id>-<kind>[-<namespace>]-<name>.yaml, sedangkan dokumen yang tidak memiliki kind atau name dinamai menurut path templatnya. Nama diambil dari resource, bukan dari templat, sehingga dua templat di subdirektori berbeda yang berbagi nama berkas tetap menjadi dua berkas. SDK Helm merender chart dengan values yang telah digabungkan; Aggrega menyisipkan label dan anotasi provenans setelah render.
  • provider helm-chart — berkas sub-chart disalin di bawah charts/<instance_id>/, apa adanya kecuali name milik chart itu sendiri, yang diatur oleh umbrella menjadi identitas terenkode instans sehingga dua komponen yang menyertakan chart dengan nama yang sama tetap dapat dibedakan (lihat providers/helm-chart.md); Chart.yaml + values.yaml umbrella per boundary diemisikan di sampingnya.
  • provider compose — berkas perantara <nodeID>.compose-fragment.yaml yang mengalir ke komposisi tingkat Release (mekanisme 5).

2 — Sintesis Workload Recipe (workload:)

Permukaan penulisan. Recipe mendeklarasikan workload: yang membawa dokumen Workload. Field ini menerima konten inline (block scalar) atau $import: (path berkas).

Penempatan dalam pipeline. Rendering dasar, setelah valuesMapping milik Recipe teresolusi (badan Workload sendiri adalah string bertemplat Go yang dievaluasi dengan konteks templat lengkap).

Bentuk keluaran. Spesifik per Provider:

  • provider helm — satu objek controller yang dipilih oleh form milik Workload (Deployment untuk stateless, StatefulSet untuk stateful, DaemonSet untuk daemon, Job untuk task, CronJob untuk scheduled) + Service per layanan + satu PVC per volume persistent. Dua bentuk penamaan, dan keduanya tidak sama: objek controller dinamai menurut nama release node dan kind-nya — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml — sedangkan berkas per resource dinamai menurut resource yang dibawanya, dengan kind di akhir: <release name>-<svcName>-service.yaml dan <release name>-<volName>-pvc.yaml, karena masing-masing dinamai dari metadata.name milik resource itu sendiri. Nama release adalah identitas node yang ditulis dalam alfabet yang diterima nama Kubernetes, sehingga sama dengan ID node di mana pun ID tersebut tidak mengandung garis bawah dan huruf kapital: node my_api menulis my-zuapi-deployment.yaml (lihat entities/workload.md “Synthesized-name convention”). Workload yang eksposurnya hanya berupa nama eksternal mengemisikan <release name>-service.yaml, karena tidak ada kunci layanan yang perlu dibawa.
  • provider compose — berkas perantara <nodeID>.compose-fragment.yaml yang mengalir ke komposisi tingkat Release.
  • provider helm-chart — tidak didukung; peran helm-chart hanyalah komposisi chart mode bersumber. Recipe yang menargetkan helm-chart dengan workload: ditolak saat render (provider helm-chart tidak melaporkan kapabilitas sintesis).

3 — Resource Generation FeatureRecipe (mode bersumber untuk FeatureRecipes)

Permukaan penulisan. FeatureRecipe mendeklarasikan source: beserta valuesMapping: (atau yang setara), pola yang sama dengan rendering bersumber Recipe tetapi untuk lampiran Feature, bukan Components utama.

Penempatan dalam pipeline. Rendering dasar, bersamaan dengan rendering Recipe dasar untuk Component induk. Setiap lampiran Feature menjalankan pass rendering FeatureRecipe-nya sendiri.

Bentuk keluaran. Ditentukan oleh provider milik Component induk, karena keluaran lampiran bergabung dengan grup perakitan Component tersebut, bukan grupnya sendiri — dan bentuk itu mengikuti cara provider tersebut menggabungkan grup, karena itulah yang menentukan apakah ada tempat untuk meletakkan lampiran sama sekali. Tiga bentuk, satu untuk setiap cara penggabungan:

  • Provider yang memberi setiap kontributor posisinya sendiri — satu chart yang memuat satu chart per kontributor, satu konfigurasi root yang memuat satu modul per kontributor — juga memberi lampiran posisinya sendiri, di samping komponen tempatnya terlampir, bukan di dalamnya. Kedua koordinat menyusun satu segmen direktori posisi tersebut, <component-id>--<feature-instance-id>, sehingga komponen api yang membawa lampiran aux berada di api--aux di samping api, di bawah direktori mana pun yang ditetapkan provider tersebut untuk kontributornya. Di samping dan bukan di dalam, karena target provider semacam itu menemukan kontributornya pada posisi yang diberikannya: direktori satu tingkat di bawah salah satu posisi tersebut adalah konten milik kontributor itu, bukan kontributor tersendiri, sehingga tidak dialamatkan dan tidak dibaca oleh apa pun. Lampiran yang dideklarasikan pada boundary tidak memiliki komponen host untuk dinamai, sehingga segmennya hanya berupa nama instansnya. Setiap koordinat dienkode sebelum keduanya digabungkan, sehingga koordinat yang mengandung urutan penggabung tidak dapat dikira sebagai penggabung.
  • Provider yang menulis setiap dokumen langsung di direktori boundary tidak memiliki tempat semacam itu, karena itulah yang dideklarasikannya tentang targetnya: hanya berkas yang berada langsung di dalam direktori yang dibaca. Maka kedua koordinat yang sama berpindah dari segmen direktori ke nama berkas, dan berkas lampiran mendarat di samping berkas milik komponen sebagai <component-id>--<feature-instance-id>--<file>. Kedua koordinat dienkode, karena nama berkas tidak memiliki pemisah untuk diandalkan, dan keduanya digabungkan dengan nama berkas itu sendiri pada batas dua karakter yang tidak dapat dimuat oleh koordinat terenkode mana pun — itulah yang menjaga dua lampiran yang mengemisikan satu nama berkas tetap menjadi dua berkas berbeda.
  • Provider yang melipat kontributor grupnya ke dalam satu dokumen juga melipat keluaran lampiran ke dalam dokumen tersebut, dengan setiap resource membawa identitas lampiran itu sendiri sehingga asal setiap bagian tetap terbaca. Jika provider semacam itu membawa lampiran yang dirender untuk target yang berbeda, konten tersebut tidak dapat dilipat ke dalam dokumen yang bukan tempatnya, sehingga ditulis di samping dokumen hasil rakitan — dalam bentuk prefiks nama berkas di atas, dengan alasan yang sama.

Bentuk umum:

  • CRD ExternalSecret / VaultSecret yang dihasilkan oleh Fetcher milik FeatureRecipe kredensial.
  • CRD ServiceMonitor / PrometheusRule yang dihasilkan oleh Feature observabilitas.
  • CRD HTTPRoute / Gateway yang dihasilkan oleh Feature routing.

4 — Pipeline plugin FeatureRecipe (patch RFC 6902 + emisi sumber daya)

Permukaan penulisan. FeatureRecipe mendeklarasikan pipeline: — sebuah larik langkah plugin Wasm (Prinsip Plugin Dua Bagian: Fetcher + Injector untuk Features kredensial; pipeline plugin arbitrer untuk Features non-kredensial).

Penempatan dalam pipeline. Pipeline plugin, setelah rendering dasar dan rendering bersumber FeatureRecipe selesai.

Bentuk keluaran. Spesifik per Plugin. Sebuah langkah mengembalikan dua kelas keluaran:

  • Patch RFC 6902 yang diterapkan oleh mesin penerapan pada dokumen yang dituju dalam himpunan hasil render (misalnya, menambahkan kontainer sidecar, memasang volume secret, menulis ulang variabel env pada Deployment hasil sintesis).
  • Efek samping — sumber daya baru yang lengkap yang diemisikan bersama patch melalui side_effects milik sebuah langkah (biasanya CRD vault-fetch milik Fetcher yang kemudian dirujuk oleh Injector).

Status saat ini: tersedia menurut Status Bahasa → Fase pipeline kompilasi. Setiap langkah yang dideklarasikan berjalan selama aggrega build: host menjalankan plugin Wasm milik langkah tersebut terhadap himpunan hasil render, menerapkan patch yang dikembalikan, dan mengemisikan efek samping langkah tersebut. Lihat plugins/plugin-contract.md untuk permukaan kontrak plugin.

5 — Komposisi tingkat Release (perakitan boundary per provider)

Permukaan penulisan. Digerakkan oleh bentuk Release — tanpa penulisan per Recipe. Kapabilitas yang merakit sebuah boundary melakukannya sekali, setelah setiap node dalam boundary tersebut selesai di-render: kapabilitas compose mengumpulkan semua fragmen per node ke dalam satu docker-compose.yaml per boundary, dan kapabilitas helm-chart mengumpulkan salinan sub-chart per node ke dalam satu chart payung per boundary.

Penempatan dalam pipeline. Setelah rendering dasar, begitu keluaran per Recipe dari setiap node telah terkumpul untuk boundary tersebut.

Bentuk keluaran. Per provider:

  • provider compose — satu docker-compose.yaml di akar boundary, yang menghimpun services, volumes, dan networks dari setiap node yang berkontribusi. Berkas perantara <nodeID>.compose-fragment.yaml (mekanisme 1 + 2) digabungkan ke dalam keluaran tunggal; fragmen-fragmen tersebut tidak muncul di direktori boundary akhir.
  • provider helm-chart — satu Chart.yaml + values.yaml payung di akar boundary, ditambah direktori sub-chart per node di bawah charts/<instance_id>/.

6 — Emisi artefak langsung Recipe (artifacts:)

Permukaan penulisan. Recipe mendeklarasikan artifacts: sebagai peta entri bernama; setiap entri berupa konten inline (string bertemplat yang membawa isi berkas) atau referensi $import: ke path berkas templat — emisi berkas langsung tanpa melalui provider.

Penempatan dalam pipeline. Evaluasi artefak, di dalam rendering dasar.

Bentuk keluaran. Satu berkas per entri artefak, dinamai menurut kunci entri dalam peta artifacts:. Penulis Recipe menentukan nama berkas dan konten secara langsung.

Status saat ini: tersedia menurut Status Bahasa → Jenis input Recipe. Setiap entri dievaluasi dengan konteks templat lengkap setelah sintesis workload dan resolusi sumber, dan berkas yang dihasilkan diemisikan dengan nama kunci entri tersebut. Apa yang dilakukan target terhadap artefak yang diemisikan bergantung pada kapabilitasnya: provider yang menerima artefak mandiri mengemisikannya sebagai berkas tersendiri, sedangkan provider yang hanya menerima artefak bersama jenis input lain melipat entri tersebut ke dalam apa yang dirakitnya — sehingga isi yang bentuknya tidak sesuai harapan perakit tersebut akan dihentikan dalam kategori TRANSLATION_ERROR alih-alih diemisikan apa adanya. Periksa tabel per kapabilitas di architecture/16-recipe-input-composition.md sebelum menulis artefak untuk suatu kapabilitas.

Urutan rendering

Keenam mekanisme berjalan dalam urutan yang telah ditentukan sehingga mekanisme hilir dapat membaca keluaran mekanisme hulu. Urutannya:

  1. Evaluasi provides — per node, blok locals: milik Recipe diresolusi terlebih dahulu, sesuai urutan penulis, dengan setiap entri membaca entri di atasnya; templat provides: milik node kemudian dievaluasi, dalam urutan apa pun di antara sesamanya (mandiri: .context.instance_id, .context.rendered_name jika provider milik node melaporkannya, .values, .infra, .locals yang telah diresolusi, teks statis). Urutan locals-sebelum-provides inilah yang memungkinkan entri provides: membaca sebuah local dan menerima nilai yang telah diresolusi.
  2. Publikasi locals dan resolusi sumber — locals tersebut dipublikasikan ke .locals, dan templat URI source: milik Recipe dievaluasi terhadapnya (meresolusi penunjuk sumber jika berupa templat). Permukaan sumber berbagi konteks locals, sehingga ia membaca .locals dan bukan .provides.
  3. Inject mapping — blok injectMapping: milik FeatureRecipe dievaluasi (pipa inject dicegat sebelum rendering Recipe).
  4. Values mapping — valuesMapping: milik Recipe dievaluasi (mode bersumber + mode tanpa sumber menghasilkan kamus nilai).
  5. Sintesis workload — sintesis Workload milik Recipe (mekanisme 2 mengeluarkan manifest untuk mode tersintesis).
  6. Evaluasi artefak — evaluasi artifacts: milik Recipe (mekanisme 6).
  7. Provider render — provider melakukan rendering (mekanisme 1 — mode sourced menghasilkan manifest datar; mode sourceless menghasilkan manifest generatif).
  8. Rendering Feature — rendering FeatureRecipe untuk setiap lampiran Feature pada node (mekanisme 3 + 4 — Resource Generation berjalan di sini; pipeline plugin berjalan kemudian, pada langkah 9).
  9. Pipeline plugin — mutasi pasca-render: langkah plugin pipeline: milik FeatureRecipe menerapkan patch RFC 6902 dan mengeluarkan resource tambahan (mekanisme 4).
  10. Komposisi tingkat Release — perakitan batas oleh kapabilitas mengumpulkan fragmen per node menjadi keluaran per batas (mekanisme 5).

Urutan ini penting karena mekanisme hilir dapat membaca keluaran mekanisme hulu — misalnya, sebuah langkah pipeline plugin dapat mem-patch Deployment hasil rendering provider, dan komposer tingkat Release dapat menggabungkan fragmen yang dikeluarkan oleh render provider, oleh rendering feature, dan oleh pipeline plugin.

Set aturan deteksi tabrakan

Ketika dua mekanisme menghasilkan file dengan nama yang sama di direktori boundary yang sama, build berhenti dengan menyebutkan setiap kontributor, dalam kategori yang disebutkan oleh masing-masing aturan di bawah ini. Set aturannya:

Aturan bentuk Recipe: tabrakan kunci entri artifacts:

Sebuah Recipe mendeklarasikan dua entri di bawah artifacts: dengan kunci yang sama (kunci menentukan nama file yang diemisikan, baik isi entri ditulis inline maupun dimuat melalui $import:). Terdeteksi saat Recipe dimuat sesuai errors/fatal-halts.md “artifacts: entry keys must be unique (kunci entri harus unik)”.

Aturan bentuk Recipe: tabrakan saat emisi lintas jenis input

Tiga jenis input sebuah Recipe — sourced, synthesized, dan artifacts — masing-masing mengemisikan file ke direktori boundary yang sama. Jika output hasil render source, sintesis workload, atau emisi artefak menghasilkan file yang namanya juga dihasilkan oleh jenis input lain, build berhenti saat emisi. Terdeteksi saat emisi sesuai errors/fatal-halts.md “Emission-time filename collision across input kinds (Tabrakan nama file saat emisi lintas jenis input)”.

Tabrakan nama service compose (tingkat Release)

Ketika dua node berbeda (dalam kombinasi boundary apa pun) menyumbangkan service dengan nama yang sama ke output compose gabungan, provider compose berhenti saat menyusun boundary, dengan kategori TRANSLATION_ERROR, dengan menyebutkan setiap tuple (boundary, node, serviceName) yang berkontribusi. Terdeteksi pada komposisi tingkat Release sesuai bagian output tingkat Release di providers/compose.md.

Sebuah service ditolak berdasarkan namanya saja, tanpa membandingkan apa yang dideklarasikan kedua node. Service compose adalah satu kontainer yang berjalan, sehingga dua node yang masing-masing menginginkan satu hanya mendapat satu untuk berdua, dan maksud salah satu kontributor hilang seidentik apa pun kedua definisinya.

Konflik nama volume dan nama config compose (tingkat Release)

Ketika dua node berbeda menyumbangkan entri volumes: atau configs: tingkat atas dengan nama yang sama ke output compose gabungan, dan kedua deklarasinya berbeda, provider compose berhenti dengan kategori TRANSLATION_ERROR, dengan menyebutkan entri tersebut dan setiap tuple (boundary, node) yang berkontribusi. Terdeteksi pada komposisi tingkat Release sesuai bagian output tingkat Release di providers/compose.md.

Berbeda dengan aturan service di atas, aturan ini membandingkan deklarasinya, dan nama bersama sah jika para kontributor sepakat. Volume atau config bernama adalah satu objek, sehingga dua node yang mendeklarasikannya secara identik sama-sama meminta tepat entri yang akhirnya ada di dokumen gabungan dan tidak ada yang hilang. Dua node yang mendeklarasikannya secara berbeda tidak sepakat tentang satu objek itu, dan mempertahankan salah satu deklarasi akan membuang yang lain dari build yang seharusnya berhasil. Dua deklarasi dianggap sepakat jika keduanya menggambarkan entri yang sama dalam file yang dirakit, sehingga isi yang ditulis sebagai mapping kosong dan isi yang dihilangkan sama sekali dianggap sepakat.

Alias dan direktori sub-chart helm-chart

Sub-chart helm-chart berada di charts/<instance_id>/ dan nilainya dicakup di bawah aliasnya, yaitu ID instance yang dienkode untuk posisi alias. Dua instance tidak dapat menghasilkan satu alias yang sama kecuali ID instance-nya adalah string yang sama, karena enkode menuliskan karakter yang tidak diterima alias alih-alih menggantinya — sehingga sebuah alias mengidentifikasi tepat satu sub-chart, dan nilai yang ditulis di bawahnya hanya mencapai sub-chart itu. ID instance pada gilirannya unik per boundary berdasarkan aturan perataan Aggregate, sehingga direktorinya juga tidak dapat bertabrakan. Kedua bagian ini bersifat struktural: tidak ada yang bergantung pada pemeriksaan.

Tabrakan nama resource hasil render Helm

Di dalam sebuah boundary, dua node yang di-render ke nama resource Kubernetes yang sama menghasilkan dua file YAML dengan field metadata.name yang tumpang tindih. Nama file-nya berbeda, karena masing-masing diberi awalan basis penamaannya sendiri, sementara metadata.name di dalamnya masih dapat bertemu — sehingga build memeriksa nama yang dibawa resource hasil render, dan dua kontributor yang menurunkan satu nama untuk satu kind dalam satu namespace menghentikannya dengan kategori TRANSLATION_ERROR sebelum apa pun ditulis, dengan menyebutkan nama tersebut serta setiap komponen dan setiap lampiran yang menurunkannya (lihat errors/fatal-halts.md).

Kasus terbesar ditutup melalui konstruksi alih-alih diperiksa. Chart sourced yang menamai resource-nya berdasarkan nama release tidak lagi dapat menghasilkan hal ini di antara dua komponen, karena dua basis penamaan yang berbeda sedikit pun menghasilkan dua nama release — lihat providers/helm.md “How the release name is derived”. Dua kasus tersisa, dan pemeriksaan di ataslah yang melaporkannya. Salah satunya adalah chart yang menuliskan nama resource secara literal ke dalam templatnya, dan tidak ada derivasi yang dapat membedakan nama seperti itu dari literal lain. Yang lainnya adalah dua lampiran Feature pada satu komponen yang masing-masing mengirimkan chart yang ditulis penulisnya: keduanya di-render terhadap nama release komponen tersebut, secara desain, sehingga dua chart yang menamai resource berdasarkan .Release.Name bertemu di sana — berikan nama berbeda untuk resource kedua chart, atau lampirkan keduanya ke komponen yang berbeda.

Setiap nama hasil sintesis diawali dengan identitas node itu sendiri — nama objek controller, dan setiap nama per resource melalui konvensi nama Service hasil sintesis <release name>-<svcName> (sesuai entities/workload.md “Synthesized-name convention”) — yang membuat tabrakan lintas node secara struktural mustahil melalui konstruksi. Penulis yang build-nya berhenti pada nama Deployment / Service sebaiknya pertama-tama memeriksa apakah dua Recipes berbeda mengemisikan resource bernama sama melalui jalur render yang berbeda (misalnya, templates/deployment.yaml dari chart sourced yang bertabrakan dengan metadata.name dari Deployment hasil sintesis workload).

Pola interaksi lintas mekanisme

Hasil sintesis Workload + patch pipeline plugin

Pola kanonis: mekanisme 2 (sintesis workload) menghasilkan Deployment dasar; mekanisme 4 (plugin Injector) menerapkan patch RFC 6902 yang memasang volume secret ke dalam Deployment. Kedua mekanisme tersebut tersusun bersama — Deployment tersebut adalah resource K8s yang sama, dengan patch yang melapiskan referensi ConfigMap / Secret di atas dasar hasil sintesis.

Ini adalah pola yang dominan untuk injeksi kredensial pada workload hasil sintesis. Fetcher (mekanisme 3, Resource Generation) menghasilkan CRD ExternalSecret yang diambil oleh klaster saat runtime; Injector (mekanisme 4, patch pipeline plugin) memodifikasi Deployment untuk memasang Secret K8s yang dihasilkan.

Sintesis sourced + Workload pada boundary yang berbeda

Satu Aggregate dapat memiliki satu komponen yang terikat ke Recipe helm sourced (mekanisme 1) pada boundary A dan komponen saudara yang terikat ke Recipe helm yang menyintesis Workload (mekanisme 2) pada boundary B. Direktori setiap boundary memuat bentuk output yang sesuai; penamaan file lintas boundary tidak bertabrakan karena direktori dist/ per boundary terisolasi satu sama lain.

Penggabungan compose tingkat Release per direktori keluaran

Perakitan kapabilitas compose mengumpulkan fragmen per node dari setiap boundary yang direktorinya dievaluasi menjadi satu path ke dalam satu docker-compose.yaml di path tersebut; dua boundary bertarget compose dalam satu Release menulis dua berkas ketika direktorinya berbeda, dan satu berkas gabungan ketika keduanya berbagi direktori.

Oleh karena itu, tabrakan nama service dideteksi per berkas, pada penggabungan tingkat Release-nya, sesuai aturan di atas. Dua boundary bertarget compose di direktori berbeda yang masing-masing mendeklarasikan service bernama api tidak bertabrakan: berkas setiap boundary membawa service-nya sendiri. Dua boundary yang berbagi direktori menulis satu berkas, dan build berhenti dengan menyebutkan kedua kontributor.

Rujukan silang