Variabel templat jalur
Field directory: dan subDirectory: pada boundary Release adalah templat Go yang dievaluasi pada waktu build. Keduanya mengendalikan lokasi artefak hasil render di disk dan, sebagai konsekuensinya, artefak mana yang dirakit bersama — dua boundary yang dievaluasi menjadi tuple (path, provider) yang sama berbagi satu assembler dan menghasilkan satu output gabungan (satu Chart.yaml, satu docker-compose.yaml). Halaman ini adalah referensi penulisan untuk variabel yang dapat dirujuk oleh templat tersebut, semantik evaluasi ketat, dan aturan kaskade yang memungkinkan boundary mewarisi dari induknya.
Untuk pembahasan konseptual tentang segregasi spasial dan dispatch per-(path, provider), lihat architecture/16-recipe-input-composition.md. Untuk permukaan penulisan Release di tingkat entitas, lihat entities/release.md. Konsekuensi di sisi provider dijelaskan di providers/architecture.md dan halaman per provider.
Evaluasi ketat: missingkey=error
Template path dievaluasi dengan mode missingkey=error milik Go. Referensi ke field yang tidak dideklarasikan, kunci parameters.X yang tidak diatur, atau salah ketik seperti {{ .parmaeters.region }} menghasilkan error eksplisit alih-alih secara diam-diam merender string kosong ke dalam path.
Keketatan ini asimetris dengan bagian lain compiler — valuesMapping, injectMapping, dan permukaan render nilai lainnya menggunakan missingkey=zero sesuai konvensi Helm/Sprig. Emisi path secara struktural berbeda: template render nilai yang menghasilkan string kosong berakhir di field manifest, tempat konsekuensinya terbatas; template path yang menghasilkan string kosong berakhir di tata letak direktori, tempat konsekuensinya tidak terbatas (tabrakan, perakitan yang rusak, path hantu). Rezim template path yang ketat ini ada untuk memunculkan kegagalan tersebut pada saat build, bukan pada saat deploy.
Validasi allowlist saat parse
Selain ketatnya evaluasi saat runtime, template path divalidasi pada saat parse terhadap allowlist tertutup berisi nama-nama variabel. Referensi ke nama variabel yang tidak ada dalam allowlist menghentikan build sebelum pekerjaan rendering apa pun dimulai, dengan diagnostik yang menyebutkan field yang bermasalah dan boundary tempat field tersebut muncul.
Allowlist ini sengaja dibuat tertutup: permukaan seperti .context.inject, .values, dan .locals dengan sengaja tidak diekspos ke template path. Emisi path merupakan urusan struktural, bukan urusan rendering nilai; mengaitkan path assembly dengan nilai per komponen akan membuat graf path bergantung pada data dan mengikis invarian keluaran yang deterministik.
Matriks variabel
| Variabel | directory: | subDirectory: | Deskripsi |
|---|---|---|---|
{{ .capability }} | ya | ya | Kapabilitas rendering (helm, helm-chart, compose, terraform, cloudformation) yang dideklarasikan oleh Recipe milik komponen kontributor, untuk artefak yang diemisikan pada path ini. |
{{ .boundary_name }} | ya | ya | Nama boundary yang ditulis di dalam Release (misalnya, production, eu-prod). |
{{ .parameters.X }} | ya | ya | Parameter bertipe apa pun yang dideklarasikan pada Aggregate dan dipenuhi oleh Release. Akses ketat — mereferensikan .parameters.unknown menghentikan build. |
{{ .manifest.recipe_name }} | ya | ya | Nama Recipe yang di-resolve melalui Manifest untuk komponen kontributor. Berguna untuk mengarahkan artefak per Recipe ke subfolder per Recipe. |
{{ .parent_boundary.* }} | ya | ya | Akses kaskade ke nilai yang telah dievaluasi dari boundary yang melingkupinya. Lihat Kaskade boundary induk di bawah. |
{{ .component_id }} | — | ya | ID instance dari komponen yang berkontribusi. Untuk sebuah Feature yang dilampirkan pada batas yang FeatureRecipe-nya berjalan sekali untuk batas tersebut (executionScope: boundary), nilainya adalah identitas gabungan yang dibawa sumber daya lampiran itu dalam label aggrega.ai/component-id mereka — bfr--app--shared untuk lampiran shared pada batas app, dipersingkat jika penyedia lampiran itu membatasi nama — sehingga keluaran lampiran tersebut berada di direktori yang dinamai sesuai label itu. Tersedia di subDirectory: saja karena directory: adalah properti per batas — string direktori dihitung sekali per batas, sebelum perutean per komponen apa pun terjadi. |
Field directory: secara default bernilai boundaries/ diikuti path boundary (pengenal build-time yang stabil yang diturunkan dari pohon boundary); Release yang mencantumkan komponennya tanpa mendeklarasikan boundary menuliskannya tanpa segmen direktori sama sekali. Field subDirectory: secara default bernilai {{ .capability }} sehingga artefak setiap kapabilitas ditempatkan di subfoldernya sendiri di bawah direktori boundary — baik field itu dihilangkan maupun ditulis sebagai subDirectory: "", yang dibaca persis seperti field yang dihilangkan. Menetapkan subDirectory: ".", atau menulis template yang dievaluasi menjadi string kosong, meratakan pengelompokan tersebut.
Yang tidak ditentukan oleh template ini: penempatan artifacts:
Satu segmen path output tidak ditetapkan oleh path template. File yang disebutkan oleh blok artifacts: milik Recipe ditulis di bawah direktori yang dinamai sesuai komponen yang mendeklarasikannya, di dalam apa pun hasil evaluasi subDirectory:. Segmen tersebut tetap dan selalu ada, untuk target yang menulis file kontributornya berdampingan alih-alih menempatkan setiap kontributor di dalam chart atau modulnya sendiri.
Alasannya terletak pada apa yang menamai file tersebut. Manifest yang di-render atau disintesis oleh target dinamai oleh target berdasarkan komponen pemiliknya, sehingga sudah mengidentifikasi komponennya. Artefak dinamai dengan kunci yang ditulis oleh penulisnya — app-config.yaml, netpol.yaml — dan kunci tersebut tidak menyatakan apa pun tentang komponennya, karena Recipe yang mendeklarasikannya tidak mengetahui komponen mana yang akan diikat padanya. Dua komponen dalam satu boundary yang diikat pada satu Recipe akan menulis ke satu path, dan baik penulis Recipe maupun penulis Release tidak memiliki tempat untuk memisahkannya.
Hanya direktori yang ditambahkan; nama file tetap berupa kunci yang ditulis, sehingga file yang dibaca kembali oleh penulis di output membawa nama yang mereka tulis.
Apa yang masih diberikan oleh subDirectory:, dan bagaimana keduanya digabungkan. subDirectory: memindahkan setiap file yang diemisikan kontributor — manifest yang di-render, manifest yang disintesis, dan artefak sekaligus — sehingga field ini adalah alat untuk memberikan satu komponen direktorinya sendiri bagi tooling hilir yang bekerja pada seluruh set manifest satu komponen, atau untuk mengarahkan beberapa komponen ke satu folder bersama. Segmen artifacts: berlaku di bawah apa pun hasil evaluasinya. Oleh karena itu, menulis subDirectory: "{{ .capability }}/{{ .component_id }}" pada komponen yang Recipe-nya mendeklarasikan artifacts: menghasilkan nama komponen dua kali — artefak ditempatkan di <capability>/<component>/<component>/<key> sementara manifest yang di-render milik komponen tersebut ditempatkan di <capability>/<component>/<key>. Gunakan override ini bila Anda ingin seluruh output komponen dikumpulkan, dan jangan gunakan bila Anda hanya perlu memisahkan artefak, yang sudah dilakukan oleh default.
.capability di-resolve per komponen, dan directory: milik boundary dievaluasi untuk dua tujuan yang berbeda. Evaluasi per boundary yang memublikasikan .parent_boundary.directory ke boundary anak berjalan sebelum komponen apa pun diikat, sehingga .capability kosong di sana. Evaluasi per komponen yang menetapkan tempat artefak kontributor benar-benar ditempatkan membawa kapabilitas komponen tersebut. Oleh karena itu, induk yang menulis directory: "d-{{ .capability }}" memublikasikan d- ke bawah kaskade sementara artefaknya sendiri ditempatkan di bawah d-compose.
Kaskade batas induk
Batas bersarang menerima tampilan .parent_boundary yang mengekspos jalur terevaluasi dari batas induk langsung beserta datanya sendiri yang diselesaikan melalui kaskade. Kaskade ini hanya satu tingkat — .parent_boundary milik sebuah batas adalah induk langsungnya, bukan kakeknya. Untuk menjangkau lebih ke atas, batas induk itu sendiri menggunakan .parent_boundary dalam templatnya sendiri, sehingga nilai diteruskan ke bawah pohon secara eksplisit.
Field yang tersedia di bawah .parent_boundary:
| Field | Deskripsi |
|---|---|
.parent_boundary.directory | Nilai directory: batas induk yang telah dievaluasi (setelah templat). |
.parent_boundary.boundary_name | Nama batas induk sebagaimana ditulis. |
.parent_boundary.parameters | Map .parameters.* yang sama dengan yang dilihat batas induk (nilai parameter bersifat global untuk Release, tetapi alias ini disediakan demi simetri). |
.parent_boundary.annotations | Anotasi batas induk yang diselesaikan melalui kaskade. |
Pola kanonis: sebuah batas induk yang menulis directory: satu kali, ditambah batas anak yang mengarahkan artefaknya ke bawah induk dengan mendeklarasikan directory: "{{ .parent_boundary.directory }}". Hal ini menyatukan anak-anak ke jalur perakitan induk, sehingga menghasilkan satu keluaran gabungan yang berisi kontributor dari setiap anak. Feature core/compose-bridge bergantung tepat pada hal ini: sebuah batas induk yang memuat fitur bridge, dua batas anak (misalnya services-net dan data-net) yang berbagi directory: induk, dan satu docker-compose.yaml gabungan yang berisi setiap komponen ditambah layanan bridge.
Kebalikannya: hilangkan .parent_boundary.directory pada anak-anak (atau evaluasi ke jalur yang berbeda) dan setiap anak mendapatkan perakitannya sendiri. Kedua bentuk ini sama-sama didukung penuh.
Contoh tata letak
Tata letak 1 — pemisahan bawaan per boundary
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Setiap boundary dievaluasi menjadi directory: yang berbeda, sehingga masing-masing mendapatkan assembly sendiri:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...subDirectory: "{{ .capability }}" bawaan memisahkan artefak per kapabilitas di dalam setiap direktori boundary. Dua boundary, dua keluaran assembly per kapabilitas, tanpa penggabungan.
Tata letak 2 — assembly yang digabungkan melalui direktori induk bersama
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Kedua boundary anak mengevaluasi directory: menjadi deploy/cluster (direktori induk), sehingga semua kontributor digabungkan pada satu path assembly. Dengan subDirectory: "{{ .capability }}" bawaan, kontributor compose dari kedua anak ditempatkan di deploy/cluster/compose/ dan menghasilkan satu docker-compose.yaml gabungan. Feature compose-bridge yang dilampirkan pada induk dijalankan sekali (dispatch cakupan boundary) dan menyumbangkan layanan bridge ke file gabungan yang sama.
Anotasi aggrega.ai/chart-name: "cluster-umbrella" milik induk diturunkan ke kedua anak; jika boundary tersebut juga memuat kontributor helm-chart, sub-chart helm-chart dari kedua anak akan disusun di bawah satu umbrella bernama cluster-umbrella. Nilai chart-name yang tidak cocok antar-kontributor pada satu path menghentikan build.
Tata letak 3 — perutean per komponen melalui subDirectory: ditambah parameter
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"directory: milik boundary dievaluasi menjadi deploy/eu-west-1 (substitusi parameter). Override subDirectory: per komponen merutekan setiap kontributor ke subfolder per komponen, dengan komponen ingress di-override ke subfolder datar shared untuk artefak lintas bagian:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Pola ini cocok untuk perusahaan yang menginginkan direktori artefak per komponen bagi tooling hilir yang bekerja pada manifest satu komponen. Jika Recipe sebuah komponen juga mendeklarasikan artifacts:, baca Hal yang tidak ditentukan oleh template ini di atas sebelum memilih bentuk ini: file-file tersebut sudah membawa segmen komponen, sehingga override ini menambahkan segmen kedua.
Diagnostik
Permukaan path-template menghentikan build dalam setiap situasi berikut, dan errors/fatal-halts.md mendokumentasikannya dengan nama-nama ini. Halaman tersebut mengutip pesan yang dikeluarkan setiap penghentian; cocokkan keluaran build dengan teks tersebut.
- Path-template references a variable outside the allowlist (Path-template merujuk variabel di luar allowlist) — saat parse: sebuah path template merujuk variabel yang tidak ada dalam allowlist.
- Path collision (Tabrakan path) — saat assembly: dua kontributor boundary dievaluasi ke path yang sama tetapi berbeda pada properti yang harus seragam di antara kontributor pada path tersebut.
- Instance-ID collision (Tabrakan ID instans) — saat assembly: dua boundary yang dievaluasi ke tuple
(path, provider)yang sama menyumbangkan komponen dengan ID instans yang identik. - Chart-name mismatch (Ketidakcocokan nama chart) — saat assembly: assembly helm-chart yang digabungkan menerima kontributor dengan anotasi
aggrega.ai/chart-namehasil resolusi cascade yang saling bertentangan. - Missing template key (Kunci template tidak ada) — sebuah path template merujuk field di bawah variabel terbuka yang tidak menghasilkan nilai (misalnya,
{{ .parameters.region }}ketika Release tidak menyertakanregion, atau kunci.parent_boundarypada boundary tingkat atas yang tidak memiliki induk);missingkey=errormenghasilkan pesan eksplisit yang menyebutkan boundary, field template (directory:vssubDirectory:), dan kunci yang hilang..parametersdan.parent_boundarybersifat terbuka — kuncinya adalah data yang ditulis pengguna — sedangkan.manifestmendeklarasikan kuncinya, sehingga kunci yang salah ketik di bawah.manifestjustru ditolak saat parse sebagai rujukan yang tidak dikenal, dengan diagnostik yang mencantumkan kunci-kunci yang didefinisikan.manifest.
Rujukan silang
entities/release.md— penulisan Release, termasuk segregasi spasial serta fielddirectory:/subDirectory:.providers/architecture.md— dispatch provider dan model perakitan per-(path, provider).providers/compose.md— output per-(path, provider)di sisi compose, termasuk skenario path yang digabungkan.providers/helm-chart.md— komposisi umbrella helm-chart dan aturan kaskade chart-name untuk path yang digabungkan.entities/featurerecipe.md— FeatureRecipes dengan cakupan boundary (Featurecore/compose-bridgebergantung pada model perakitan path gabungan yang didokumentasikan di sini).errors/fatal-halts.md— katalog diagnostik lengkap, termasuk penghentian path-dispatch yang diuraikan di atas.