Pilar data
Kerangka konseptual dari lima kata kunci struktural DSL — parameters, values, uses, infra, inject — terdapat di architecture/06-data-taxonomy-and-composition.md. Halaman ini membahas daftar pilar data kanonis, semantik penulisan per pilar, mekanisme lintas pilar, serta kosakata nilai default yang ditemui penulis di berbagai pilar. Triad topologi pelengkapnya (provides, inject, uses — kata kunci yang menghubungkan sisi graf) didokumentasikan di topology-triad.md; kosakata metadata yang berbeda dari pilar data (label, anotasi, bidang permukaan publikasi) terdapat di labels-and-annotations.md dan publishing-surface.md.
Daftar pilar kanonis
Entitas Aggrega membawa tujuh pilar data bernama. Lima di antaranya berpartisipasi dalam aliran data IR sebagai status hidup hingga perenderan; dua bersifat sementara atau privat dan hanya ada pada tahap kompilasi tertentu.
| Pilar | Berada pada | Siklus hidup | Peran |
|---|---|---|---|
values | Instans komponen / lampiran Aggregate | Hidup hingga perenderan | Muatan kognitif yang ditulis Developer |
infra | Entri komponen, lampiran, dan koneksi Release | Hidup hingga perenderan | Penentuan ukuran fisik yang ditulis Operator |
provides | Blok provides: Recipe | Hidup hingga perenderan (pilar turunan — lihat di bawah) | String keluaran publik yang dihitung Recipe dan dikonsumsi oleh pipa topologi |
uses | Instans komponen / fitur Aggregate | Hidup hingga perenderan | Sisi topologis ke komponen / fitur lain |
features | Instans komponen Aggregate + Release; slot dideklarasikan dalam featuresSchema entitas katalog — lihat “Pilar Features” di bawah | Hidup hingga perenderan | Pilar lampiran — satu bentuk untuk setiap keluarga lampiran |
parameters | Akar Aggregate + Release | Dapat dibaca hingga akhir pipeline, sampai setiap fase render selesai; dapat diakses oleh templat path selama perenderan melalui pemberian akses asimetris; konteks templat nilai mengonsumsi literal pasca-interpolasi alih-alih .parameters secara langsung | Slot per lingkungan yang dipenuhi oleh Release |
locals | Blok locals: Recipe | Privat bagi Recipe — hanya terlihat di dalam templat Recipe itu sendiri | Status string terhitung yang diturunkan Recipes dalam preambul locals |
values / infra / provides / uses / features adalah lima pilar hidup yang diekspos konteks templat runtime masing-masing melalui .values, .infra, .provides, .context.uses, dan .features. parameters dan locals tidak termasuk dalam daftar pilar hidup — parameters karena tidak bertahan setelah resolusi; locals karena bersifat privat bagi Recipe dan tidak pernah melintasi batas entitas.
Pilar adalah penanda, bukan dinding: mesin templat mengizinkan pembacaan lintas pilar di setiap situs kecuali secara eksplisit dilarang oleh aturan kemandirian (blok provides: Recipe dan blok source: Recipe yang membaca .context.inject / .context.uses; didokumentasikan di templates/expansion-matrix.md). Batas pilar adalah disiplin penulisan, bukan penegakan oleh bahasa.
Batas pilar dan disiplin penulisan
Pembacaan lintas pilar dari template Recipe tidak dibatasi di setiap situs yang mengizinkan konteks template penuh. Disiplin penulisan mengharapkan penulis untuk:
- Membaca
.valuesuntuk muatan kognitif (maksud yang ditulis oleh Developer). - Membaca
.infrauntuk penentuan ukuran fisik (ukuran yang ditulis oleh Operator). - Membaca
.context.uses[].provides.<key>untuk string penunjuk lintas komponen (aliran data triad topologi). - Membaca
.context.injectuntuk pipa pengiriman pascahidrasi (dirakit dari sumber inject di seluruhcomponent.inject,uses[].inject, dan intersepsiinjectMappingFeatureRecipe).
Disiplin ini berupa penanda arah, bukan dinding. Template Recipe yang membaca .infra.replicas untuk mengisi sebuah field values: tetap berfungsi; mesin template tidak membatasi pembacaan tersebut. Kerangka arsitekturnya adalah bahwa batas pilar menggambarkan maksud penulisan — siapa pemilik data — alih-alih pembatasan runtime. Konvensi mengikuti pembagian empat domain: nilai yang ditulis oleh Developer berasal dari .values; ukuran yang ditulis oleh Operator berasal dari .infra; koordinat lintas komponen berasal dari pipa topologi.
Ketika jembatan lintas pilar yang disengaja diperlukan — misalnya, schema: sebuah Component mengekspos pengaturan yang ditujukan bagi developer yang kemudian disalurkan oleh template valuesMapping: milik Recipe ke output berbentuk infra: di sisi Ops sesuai vocabulary/inheritance-and-interface.md — arsitektur memperlakukan jembatan tersebut sebagai pengecualian yang diberi penanda arah. Lihat “Mekanisme lintas pilar” di bawah.
Values
Pilar values: membawa muatan kognitif yang ditulis oleh Developer — parameter bentuk aplikasi yang ditentukan Developer per instans komponen. schema: milik Component mendeklarasikan bentuk values; Aggregate milik Developer mengisi values konkret per instans. Ini adalah domain Developer.
Ditulis di:
- Aggregate
components.<id>.values:— muatan kognitif per instans komponen. - Aggregate
subsystems.<name>.components.<id>.values:— sama, di dalam komponen yang dikelompokkan per subsistem. - Aggregate
components.<id>.features.<name>.values:danfeatures.<name>.values:milik subsistem — muatan values lampiran, apa pun keluarga Feature yang dilampirkan (parameter kueri vault dari lampiran kredensial ditulis di sini seperti yang lainnya).
Dilarang di:
- Entitas Release (skema Release melarang blok
values:di setiap tingkat penyarangan — Parameter Hoisting adalah jalur yang didukung untuk variasi per lingkungan; lihat Parameters di bawah).
Divalidasi oleh: blok values: dari schema milik Component (dan blok values: dari schema milik Feature untuk lampiran Feature), yang diresolusikan menjadi JSON Schema 2020-12 saat Component / Feature dimuat sesuai vocabulary/validation-surface.md Lapisan 2.
Dikonsumsi oleh: templat valuesMapping: milik Recipe melalui .values. Konteks templat lengkap menyediakan kamus values yang telah diresolusikan di setiap situs templat rendering dasar.
Infra
Pilar infra: membawa ukuran fisik yang ditulis oleh Operator — replika, permintaan sumber daya, batas IOPS, penyematan region, kelas mesin. Pilar ini menyatakan di mana dan seberapa besar, melengkapi apa dan bagaimana perilakunya dari values. Ini adalah domain Operator.
Empat permukaan penulisan
Penulis menjumpai infra: di empat permukaan yang berbeda, masing-masing dengan cakupan dan perilaku kaskade yang berbeda:
| # | Permukaan | Cakupan | Prioritas penggabungan |
|---|---|---|---|
| 1 | components.<id>.infra: batas Release (spec.components.<id>.infra: pada Release tanpa batas) | Satu instans komponen | Ukuran komponen itu sendiri; tidak ada permukaan lain yang menuliskannya |
| 2 | features.<name>.infra: batas Release | Lampiran selebar batas, pada setiap komponen di dalam batas | Terendah untuk lampiran itu — permukaan 3 menimpanya per field |
| 3 | components.<id>.features.<name>.infra: batas Release | Satu lampiran pada satu komponen | Menimpa permukaan 2 untuk lampiran itu, per field |
| 4 | components.<id>.uses.<socket>.<alias>.infra: Release | Satu koneksi | Divalidasi terhadap infraSchema milik socket; hanya mencapai render komponen konsumen |
Permukaan 1 adalah yang paling sering ditulis: seorang Operator menentukan ukuran setiap komponen yang ditempatkan Release. Batas tidak membawa infra: sendiri — skema Release menolaknya — sehingga ukuran yang dibagi beberapa komponen ditulis pada masing-masing komponen, atau diwarisi dari Release induk melalui extends: (di bawah). Permukaan 2 dan 3 mencakup ukuran lampiran Feature — Features membawa payload infra sendiri yang dikonsumsi oleh FeatureRecipe saat menyintesis sidecar atau sumber daya per Feature: lampiran selebar batas diberi ukuran sekali, dan satu komponen menyesuaikan satu field darinya.
“Infra terutama dilokalkan” — aturan dengan pengecualian
Target arsitektural untuk infra: adalah lokal terhadap komponen: ukuran sebuah komponen berlaku untuk instans komponen tersebut dan tidak merembes ke komponen lain. Inilah mekanisme yang memungkinkan Ops menaikkan IOPS basis data tanpa memengaruhi permintaan CPU server API.
Aturannya: infra: terutama dilokalkan pada permukaan yang menulisnya. Pengecualian kaskade ada secara sengaja menurut desain:
- Kaskade anotasi batas.
annotations:batas mengalir melalui batas bersarang ke komponen di dalamnya (Permukaan 5 dari matriks anotasi dalam labels-and-annotations.md). Anotasi yang dikonsumsi oleh Recipes sebagai masukan perutean menjadi jangkauaninfratidak langsung — anotasi tingkat batas mengalir melalui.context.annotations.releaseke dalam keluaran yang dirender oleh Recipe per node. - Pewarisan Release melalui
extends:. Sebuah Release yang melakukanextends:terhadap Release induk mewarisi deklarasiinfrainduk di setiap permukaan yang memuatnya, kecuali jika anak menimpanya per kunci. Nilai anak menang kunci demi kunci, hingga nilai pertama yang tak terbagi — skalar, list, templat — yang diganti secara utuh, dan kunci yang ditulis anak sebagainulldihapus alih-alih diisi dengan kosong. Pewarisan ini sengaja melintasi batas per Release; untuk aturan penggabungan lengkap dan apa lagi yang ikut terbawa, lihatentities/release.md. - Penyaluran lintas pilar melalui jembatan skema.
schema:sebuah Component dapat mengekspos pengaturvalues:yang ditujukan bagi pengembang, yang disalurkan oleh templatvaluesMapping:milik Recipe ke dalam keluaran berbentukinfra:dari provider (lihat “Mekanika lintas pilar — Penyaluran lintas pilar melalui jembatan skema” di bawah). Tepatnya, nilai tersebut berasal darivalues:dan mengalir ke dalam keluaran yang dirender; kaskadenya berada di dalam instans tetapi lintas pilar.
Lokalisasi adalah maksud desain, bukan dinding yang ditegakkan oleh mesin: kaskade di atas adalah pengecualian yang disengaja, masing-masing didokumentasikan pada permukaan yang membawanya.
Partisi sisi-vs-pilar untuk ekspansi Feature yang digerakkan anotasi. Invarian Aggregate-sebagai-Permukaan-Penulisan berlaku juga pada jalur ekspansi Feature yang digerakkan anotasi: anotasi sisi Aggregate (cakupan subsistem dan instans komponen) hanya boleh memicu subkunci maps.values; anotasi sisi Release (cakupan batas dan instans komponen) hanya boleh memicu subkunci maps.infra. Sebuah binding Manifest dapat mendeklarasikan path di kedua pilar; setiap sisi hanya memicu subset yang kompatibel dengannya, dan komposisi lintas sisi menggabungkan kontribusi per bidang pada saat pembangunan IR. Partisi ini mempertahankan pemisahan penulisan values-pengembang / infra-operator pada permukaan anotasi — pemisahan yang sama yang ditegakkan oleh values: dan infra: pada permukaan lampiran eksplisit. Lihat providers/well-known-annotations.md §“Side-vs-pillar partition per subkey” untuk penjelasan per subkunci dan pola komposisi lintas sisi.
Provides
Pilar provides: bersifat turunan — sebuah Recipe mendeklarasikannya, tetapi tidak seperti values / infra, developer tidak menulisnya secara langsung. Recipes menghitung string output publik yang akan dikonsumsi oleh pipa topologi.
Blok provides: milik sebuah Recipe adalah map berisi pasangan <key>: <template>. Setiap template dievaluasi terhadap permukaan Recipe itu sendiri yang mandiri (.values, .infra, .context.instance_id, .context.rendered_name jika provider node melaporkannya, dan .locals node yang telah di-resolve) selama evaluasi provides. String yang dihasilkan diekspos melalui .provides dan dikonsumsi oleh blok uses[].inject milik pemanggil melalui referensi from: "<key>". .locals tersedia karena locals node di-resolve dalam preamble tahap tersebut, sebelum provides-nya (lihat Locals di bawah); menyebut key yang tidak dideklarasikan oleh blok locals akan menghentikan proses.
Invarian kemandirian. Template provides: pada Recipe tidak boleh mereferensikan .context.inject atau .context.uses. Evaluasi provides menjalankan template tersebut dalam urutan apa pun — template tersebut hanya mencakup data milik node itu sendiri, sehingga urutannya tidak berpengaruh. Referensi lintas node akan mengikat evaluasi tersebut pada urutan iterasi topologis, yang sengaja dihindari oleh desain. Lihat templates/expansion-matrix.md baris 6 untuk aturan tersebut beserta alasannya.
Mengapa provides: merupakan pilar. String output adalah permukaan publik kanonis dari setiap Recipe; konsumen hilir (uses[].inject milik pemanggil, blok injectMapping pada FeatureRecipe yang membaca provides target yang telah di-resolve melalui .context.uses) memperlakukan kamus tersebut sebagai kontrak bertipe. Menyebut provides: sebagai pilar mengakui statusnya sebagai kelas utama bersama values / infra / uses / features. Memperlakukannya sebagai “sekadar internal Recipe” meremehkan perannya sebagai sumber data utama pipa topologi.
Uses
Pilar uses: adalah deklarasi tepi topologis. Blok uses: pada sebuah instans komponen menamai tepi-tepi yang diikuti oleh komponen tersebut — soket yang melaluinya komponen itu mengonsumsi target. Tata bahasa lengkapnya didokumentasikan di topology-triad.md; bagian ini menamai uses: sebagai pilar demi kelengkapan.
uses: berada pada instans komponen Aggregate + lampiran fitur; konteks templat runtime mengekspos satu entri per koneksi keluar, dengan alias koneksi sebagai kuncinya, sebagai .context.uses. Proyeksi tersebut membawa metadata target yang telah di-resolve dari setiap tepi (provides milik target, label, anotasi) sehingga Recipes milik pemanggil dapat membaca string penunjuk lintas komponen pada evaluasi templat base-rendering, serta lampiran yang ditulis pada koneksi tersebut, di .context.uses.<alias>.features.<slot>.
Pilar Features
features: adalah pilar lampiran: satu kata kunci, satu bentuk, untuk setiap lampiran. Feature operasional, Feature kredensial, dan Feature identitas semuanya dideklarasikan di sini dengan nama instans yang dipilih oleh penulis. Konteks templat runtime mengekspos lampiran node sebagai .features.<name>, masing-masing membawa type, values, infra, dan provides lampiran yang telah di-resolve. Lampiran yang ditulis pada salah satu koneksi komponen diekspos dalam bentuk yang sama di bawah koneksi tersebut, yaitu di .context.uses.<alias>.features.<slot>, dan tidak pernah di bawah .features — sehingga Recipe yang melakukan iterasi atas .features hanya menjumpai lampiran milik komponen itu sendiri (lihat kontrak konteks templat).
Lampiran yang nama instansnya cocok dengan slot yang dideklarasikan entitas dalam featuresSchema mengisi slot tersebut; nama instans lainnya merupakan lampiran bebas. Pengisian slot inilah yang menghubungkan empat permukaan yang dilalui kredensial berbasis slot:
| Permukaan | Tempat penulisan | Peran |
|---|---|---|
Component / Feature featuresSchema: | entitas katalog | Mendeklarasikan slot yang diharapkan entitas; per slot, membatasi daftar izin pengiriman (env / file / blackbox) dan, secara opsional, selektor label yang harus dipenuhi oleh pengisinya |
Aggregate components.<id>.features.<slot>: | Instans komponen Aggregate | Mengisi slot dengan lampiran; menyediakan values: milik lampiran itu sendiri dan, untuk slot transparan, pemetaan inject:-nya |
Workload containers.<name>.attachments.<KEY>.from/as: | Badan Workload pada Recipe | Merujuk slot yang dideklarasikan — atau, di samping connection: <alias>, slot yang dideklarasikan oleh soket koneksi tersebut — dan menentukan pengiriman per kontainer atas apa yang mengisinya |
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:) | FeatureRecipe yang terikat | Menghasilkan keluaran lampiran — sumber daya yang diemisikan, penulisan ulang pengiriman, atau keduanya |
Nama slot adalah pengenal utama di keempat permukaan: permukaan 1 mendeklarasikannya, permukaan 2–4 merujuknya, dan aliran datanya satu arah (deklarasi → isi → rujuk → hasilkan).
Untuk daftar periksa penulisan, lihat examples/04-secrets.md “The secret-delivery checklist”.
Locals
Pilar locals: adalah status privat milik Recipe. Seluruh blok diselesaikan dalam praambul locals, sebelum provides: milik node tersebut; string yang dihasilkan terlihat oleh setiap templat Recipe itu sendiri yang datang kemudian — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Templat provides: yang menyebut kunci yang tidak dideklarasikan oleh blok akan dihentikan.
Ditulis di: blok Recipe spec.locals: — peta pasangan <key>: <template> yang dievaluasi terhadap permukaan lokal-node yang mandiri: .context.instance_id, .values, .infra, dan entri dari blok yang sama yang sudah diselesaikan. Tidak ada yang lain di dalamnya: .provides, .metadata, dan sisa .context.* tidak termasuk, dan referensi ke salah satunya akan dihentikan.
Urutan bersifat menentukan. Entri diselesaikan sesuai urutan penulisan, dan sebuah entri dapat membaca entri saudara yang didefinisikan di atasnya, dengan menerima nilai yang telah diselesaikan. Perantaian hanya berjalan ke bawah — jika satu entri membaca entri lain, memindahkan definisi ke bawah pembacanya akan ditolak, dan compiler tidak pernah menyusun ulang blok agar referensi dapat diselesaikan. Referensi ke entri yang lebih belakang akan dihentikan dengan menyebut kesalahan urutan; referensi ke kunci yang tidak dideklarasikan akan dihentikan dengan menyebut kunci tersebut. Pada Recipe yang source:-nya berupa blok terstruktur, kedua kesalahan itu juga ditolak saat artefak yang disebutnya dipin, sehingga aggrega pull melaporkannya sebelum build apa pun merender keluaran. Pemeriksaan membaca jalur yang dituju oleh referensi, bukan ketikannya, sehingga mencakup secara sama bentuk langsung, blok with .locals, variabel yang terikat ke .locals, dan blok dalam tanda kurung, (.locals).<key> atau ($.locals).<key>. Ada satu penulisan yang tidak dicakupnya: kunci yang dicapai melalui fungsi, seperti index .locals atau (default dict .locals).<key>. Kunci yang tidak ada yang dicapai dengan cara tersebut tidak menghentikan proses, dan merender teks literal <no value> alih-alih tidak merender apa pun — kecuali melalui index itu sendiri, yang berhenti dengan menyebut kunci tersebut di setiap permukaan templat bila peta yang dibacanya tidak memuatnya.
Visibilitas: privat bagi Recipe. Tidak ada bidang .context.uses[].locals — pemanggil tidak dapat membaca locals milik targetnya melalui edge. Yang dapat dibaca pemanggil adalah provides: milik target.
Kasus penggunaan:
- Menghitung string penunjuk internal Recipe (misalnya,
secret_target_admin_password: "redis-auth", akhiran nama sebuah Secret) yang dikonsumsi olehvaluesMapping:danprovides:milik Recipe, dan yang dibaca oleh FeatureRecipe kredensial yang terpasang pada komponen yang sama sebagai.locals.secret_target_admin_password— templat sebuah attachment melihat locals Recipe induk yang telah diselesaikan, digabungkan dengan locals milik attachment itu sendiri. Pada targethelm, masing-masing menulis nama lengkapnya sebagai{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: nama yang dirender adalah nama komponen yang dieja dengan karakter yang diizinkan untuk nama Kubernetes, dan sebuah local tidak dapat membacanya, sehingga local membawa akhirannya dan setiap pembaca menggabungkan keduanya. - Menerapkan prinsip DRY pada nilai terhitung yang berulang di dalam satu Recipe (nama host yang dihitung sekali, direferensikan dari beberapa bidang
valuesMapping:). - Nilai perantara untuk logika templat kompleks yang akan sulit dibaca jika ditulis inline.
provides: dan locals: — wajah publik vs wajah privat
Kedua pilar di sisi Recipe membawa pemisahan visibilitas yang disengaja dan perlu diingat oleh penulis:
provides:adalah wajah publik. Setiap kunci adalah permukaan pipa topologi kanonis — blokuses[].injectmilik pemanggil hilir mengonsumsinya melalui referensifrom: "<key>". Kamusprovides:adalah kontrak bertipe yang diandalkan pemanggil; mengganti nama atau menghapus kunci merupakan perubahan yang merusak bagi setiap Recipe yang deklarasiuses[].inject-nya mereferensikannya.locals:adalah wajah privat. Setiap kunci adalah status internal Recipe yang hanya terlihat di dalam templat berikutnya milik Recipe itu sendiri. Tidak ada pemanggil yang dapat membaca locals sebuah Recipe; nama-nama dalamlocals:bukan bagian dari antarmuka terbitan mana pun, dan mengganti namanya adalah refaktor internal Recipe tanpa efek hilir.
Keduanya juga berurutan: locals: diselesaikan lebih dahulu, sehingga provides: dapat membaca .locals tetapi locals: tidak dapat membaca .provides. Karena itu, menerbitkan nilai sebuah local melalui provides: berarti menambahkan entri provides yang membaca local tersebut — ekspresinya tetap berada di satu tempat.
Pemisahan ini disengaja sesuai pemisahan arsitektural antara bagian internal Recipe (privat) dan antarmuka Recipe (publik). Penulis yang memperlakukan provides: dan locals: sebagai satu namespace kehilangan pembedaan visibilitas dan berisiko mengekspos status internal melalui pipa topologi — setiap kunci yang dideklarasikan dalam provides: menjadi bagian dari permukaan kontrak Recipe, disengaja atau tidak oleh penulisnya. Target disiplinnya: deklarasikan kunci dalam locals: terlebih dahulu; promosikan ke provides: hanya ketika pemanggil hilir benar-benar membutuhkannya.
Visibilitas ditentukan oleh pilar tempat kunci dideklarasikan: tidak ada penanda visibilitas per kunci, sehingga nilai yang sekaligus privat dan dipublikasikan adalah sebuah entri locals: dan sebuah entri provides: yang membacanya.
Parameter
Skema Aggregate dan Release sama-sama memuat kamus parameters pada akarnya. Developer mendeklarasikan kunci yang diharapkan oleh Aggregate; tim Ops mengisi nilainya dari berkas Release khusus lingkungan. Pemisahan ini merupakan mekanisme untuk promosi GitOps: satu Aggregate.yaml yang tidak dapat diubah berpindah melalui lingkungan Dev, Staging, dan Production, dengan Release setiap lingkungan menyediakan nilai parameternya sendiri.
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: falseUntuk alur CI/CD yang menyimpan nilai parameter dalam berkas terpisah (misalnya, .yaml per lingkungan yang di-check in bersama Release), Release menggunakan bentuk $import:: parameters: { $import: ./prod-values.yaml }. Isi berkas tersebut menggantikan map inline pada permukaan Release. Path di-resolve dari direktori yang memuat Release, dari mana pun perintah dijalankan, dan harus mengarah ke berkas di dalam workspace — atau, untuk Release yang disebut di luar workspace, di dalam direktori yang memuatnya. Pelapisan multi-berkas (menggabungkan berkas dasar dengan overlay khusus lingkungan) dinyatakan melalui rantai extends: Release — Release induk menyediakan parameter dasar; Release turunan memperluas dan menimpa per kunci.
Siklus hidup parameter. Compiler me-resolve parameter melalui tiga fase. (1) Pengisian default — slot yang memiliki default: dan tidak memiliki nilai Release menerima nilai default-nya. (2) Validasi kontrak parameter — kontrak parameters: bertipe memvalidasi setiap nilai terhadap batasan type / enum / min / max / pattern yang dideklarasikan, termasuk default yang telah diisi, sehingga default yang melanggar kontraknya sendiri menghentikan build. (3) Interpolasi — compiler mengevaluasi seluruh teks Aggregate sebagai template dan mengganti setiap referensi {{ .parameters.<slot> }} dengan nilai yang telah di-resolve. Map hasil penggabungan kemudian tetap dapat dibaca selama rendering, sehingga path template (directory: / subDirectory: batas Release) dapat membaca .parameters.<slot> secara langsung terhadap allowlist tertutup yang didokumentasikan di ../path-template-variables.md. Permukaan value-template (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, isi Workload) TIDAK menerima .parameters dalam konteks template-nya — permukaan tersebut mengonsumsi nilai yang telah di-resolve dan dituliskan ke dalam string values: di sekitarnya oleh interpolasi fase 3.
Daftar periksa pengangkatan parameter
Setiap nilai lintas lingkungan mengalir melalui empat titik sentuh penulisan secara berurutan. Model mental yang dipegang penulis: untuk setiap nilai yang berbeda antara Dev / Staging / Production, bersiaplah menyentuh Aggregate (deklarasi), template values (referensi), Release (pemenuhan), dan template Recipe (konsumsi).
| Langkah | Permukaan | Tindakan |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | Deklarasikan parameter sebagai bagian dari kontrak penulisan bertipe milik Aggregate. Setiap slot parameter memuat type yang dideklarasikan (string, integer, number, boolean, array, object), description opsional, default opsional, batasan ruang nilai opsional (enum, min, max, pattern, minLength, maxLength), serta struktur bersarang opsional untuk slot bertipe objek. Kontrak tersebut memvalidasi setiap nilai yang disediakan Release sebelum interpolasi. |
| 2 | Template values: Component di dalam Aggregate yang sama | Rujuk parameter melalui {{ .parameters.<name> }} dari dalam blok values: milik komponen mana pun (atau fitur, atau sub-aggregate) yang mengonsumsinya. Referensi tersebut adalah ekspresi template Go — compiler mengevaluasinya selama fase interpolasi pada resolusi. |
| 3 | Release spec.parameters.<name> (inline atau parameters: { $import: ./path.yaml }) | Penuhi parameter dengan nilai khusus lingkungan pada permukaan Release. Berkas Release per lingkungan menyediakan nilai yang berbeda untuk kunci parameter yang sama tanpa mengubah Aggregate. |
| 4 | Template valuesMapping: Recipe | Konsumsi nilai yang telah di-resolve melalui {{ .values.<key> }} — Recipe adalah permukaan value-template; konteks template-nya tidak memuat .parameters secara langsung. Variasi per lingkungan mencapai Recipe melalui kamus values: pasca-interpolasi yang ditulis oleh fase interpolasi di atas. (Path template pada batas Release adalah pengecualiannya: path template membaca .parameters.<slot> secara langsung selama rendering sesuai pemberian akses yang asimetris.) |
Keempat titik sentuh tersebut berurutan dan menopang: melewatkan deklarasi Aggregate membuat Release tidak memiliki slot untuk dipenuhi; melewatkan referensi values membuat Recipe tidak memiliki nilai untuk dikonsumsi; melewatkan pemenuhan Release membuat parameter kosong. Compiler memvalidasi rantai ini selama resolusi (validasi kontrak parameter terhadap deklarasi parameters: bertipe, kemudian interpolasi ke dalam string values: di sekitarnya, kemudian validasi JSON Schema atas kamus values: yang dihasilkan terhadap schema: Component atau Feature); ketidaksesuaian muncul sebagai pelanggaran kontrak parameter (ditangkap terhadap deklarasi parameters: bertipe), error template yang tidak terisi (ditangkap saat interpolasi), atau pelanggaran batasan JSON Schema terhadap skema values: (ditangkap saat validasi skema).
Pola ini adalah mekanisme kanonis untuk promosi GitOps: satu Aggregate yang tidak dapat diubah berpindah melalui berbagai lingkungan, dengan Release setiap lingkungan menyediakan nilai parameternya sendiri. Setiap nilai per lingkungan yang ingin dibuat bervariasi oleh penulis seharusnya berada dalam rantai parameter, bukan disematkan langsung di dalam Aggregate.
Semantik penggabungan extends: per pilar
Ketika sebuah entitas katalog mendeklarasikan extends: dan compiler menelusuri rantai pewarisan, konten setiap pilar digabungkan menurut aturan khusus pilar tersebut. Semantiknya berbeda antarpilar; tabel di bawah ini adalah referensi kanonis per pilar.
| Pilar | Perilaku penggabungan pada rantai extends: |
|---|---|
values (JSON Schema 2020-12) | Pada rantai Feature, skema dikomposisikan melalui komposisi JSON Schema 2020-12. Component yang memperluas tidak menulis konten pilar dan menerima blok dasarnya persis seperti yang ditulis oleh dasarnya, pada setiap kedalaman rantai. |
infra (fragmen JSON Schema 2020-12) | Sama seperti values — dikomposisikan pada rantai Feature, diwarisi utuh oleh Component yang memperluas. |
provides (peta templat Recipe) | Penggantian dangkal tingkat atas: kunci anak sepenuhnya menggantikan kunci induk dengan nama yang sama; kunci saudara dipertahankan dari induk. Templat tidak dikomposisikan; templat anak sepenuhnya memiliki slotnya. |
uses (usesSchema) | Overlay seluruh entri per soket berdasarkan nama soket. Anak menambahkan soket yang tidak dideklarasikan oleh dasarnya, dan soket yang dideklarasikan ulang dengan nama yang sudah ada menggantikan entri tersebut sepenuhnya — skema values dan infra-nya beserta selector-nya sekaligus. Entri soket tidak dikomposisikan, dan tidak ada yang membandingkan selector yang dideklarasikan ulang dengan milik dasarnya. |
features (skema per slot featuresSchema) | Overlay seluruh entri per slot berdasarkan nama slot, dengan ketentuan yang sama seperti usesSchema. Anak dapat menambahkan slot dengan bebas; slot yang dideklarasikan ulang menggantikan entri dasarnya sepenuhnya alih-alih dikomposisikan dengannya. |
locals (peta templat Recipe) | Penggantian dangkal tingkat atas — sama seperti provides. |
parameters (peta akar Aggregate) | Aggregate tidak memiliki bidang extends:, sehingga tidak ada rantai Aggregate yang menggabungkan parameter. Pada rantai extends: Release, parameter bernilai peta digabungkan secara mendalam dengan kunci anak yang menang, parameter bernilai skalar diganti oleh anak, dan kunci yang ditulis anak sebagai null dihapus. |
Pola umumnya bergantung pada jenis dan permukaannya. Pilar Feature yang divalidasi skema dikomposisikan di bawah JSON Schema 2020-12. Pilar Component yang memperluas diwarisi utuh — ia tidak menulis pilar apa pun, sehingga kontraknya persis milik dasarnya, dan karena itu batasan dasar tidak dapat dilonggarkan, secara konstruksi. Permukaan berbentuk tetap — usesSchema dan featuresSchema — di-overlay berdasarkan nama pada kedua jenis: anak menambahkan entri, dan entri yang dideklarasikan ulang menggantikan milik dasarnya sepenuhnya. Pilar yang ditulis sebagai templat menggunakan penggantian dangkal per kunci, sehingga anak sepenuhnya memiliki setiap slot templat yang dideklarasikannya.
Component yang memperluas memperketat batasan melalui assertions:, bukan melalui pilar — predikat yang ditambahkannya, dievaluasi bersama predikat yang diwarisinya. Lihat inheritance-and-interface.md untuk mekanisme tersebut.
Untuk mekanisme pewarisan itu sendiri, lihat inheritance-and-interface.md “Pewarisan melalui extends”, yang mencakup jenis-jenis katalog. Release bukan entitas katalog dan digabungkan menurut aturannya sendiri; aturan tersebut ada di entities/release.md “Release komposit dan pewarisan extends:”.
Mekanisme lintas pilar
Kerangka penunjuk arah mengizinkan pembacaan lintas pilar di mana saja kecuali pada permukaan swa-kandung yang terdokumentasi. Pola-pola di bawah memformalkan mekanisme lintas pilar yang umum; satu gejala penulisan yang buruk didokumentasikan agar penulis mengenali kompromi tersebut.
Penyaluran lintas pilar melalui jembatan skema — ditandai, bukan dibatasi
Batas pilar adalah disiplin penulisan: arsitektur menandai apa yang ditempatkan di mana (values: untuk maksud kognitif pengembang, infra: untuk ukuran fisik Ops, provides: untuk string yang dihasilkan Recipe, dan seterusnya) dan peninjau katalog menegakkan konvensi tersebut. Mesin templat itu sendiri mengizinkan pembacaan lintas pilar kecuali aturan swa-kandung yang terdokumentasi melarangnya (provides: pada Recipe tidak melihat .context.inject; provides: lingkup batas pada FeatureRecipe tidak melihat bidang per konsumen). Dinding pilar adalah penunjuk arah, bukan penegakan.
Pengecualian bertanda yang kanonis: schema: milik sebuah Component dapat mendeklarasikan pengatur values: yang menghadap pengembang, yang disalurkan oleh templat valuesMapping: milik Recipe ke dalam keluaran berbentuk infra: yang dirender. Pengembang menentukan maksud melalui bidang values: bertipe; templat Recipe menyalurkan nilai yang dihasilkan ke lapisan infrastruktur provider tanpa pengembang menulis kode infrastruktur. Contoh lengkap:
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"Jembatan ini didokumentasikan di inheritance-and-interface.md beserta contoh lengkap. Maksud arsitekturalnya (pengatur lintas pilar yang dideklarasikan dan disalurkan oleh Recipe) membawa satu arah — values: sisi pengembang yang mengalir ke keluaran render sisi Ops — dan berada di templat pemetaan Recipe, bukan di skema Component itu sendiri. Batas pilar tetap ditandai: pengembang melihat values:, Recipe melihat values: maupun infra:, dan keluaran render menggabungkan keduanya.
Akumulator inject lintas pilar
Pipa .context.inject adalah titik penggabungan tiga sumber yang melintasi pilar:
- Self-inject tingkat Component (
component.inject) — mengambil string darivaluesdanprovidesmilik komponen itu sendiri. - Uses-inject (
uses[].inject) — mengambil string dariprovidesmilik target. - Intersepsi
injectMapping:pada FeatureRecipe — mengambil string dari salah satu sumber di atas ditambah muataninfra:milik FeatureRecipe itu sendiri.
Saat rendering dasar berjalan, .context.inject.<mechanism>.<key> telah mengumpulkan entri dari ketiga sumber. Akumulator ini lintas pilar secara konstruksi — entri yang berasal dari values, provides, dan infra semuanya mengalir ke map .context.inject yang sama. Recipes yang mengonsumsi .context.inject melihat keadaan setelah penggabungan tanpa perlu mengetahui pilar mana yang menyumbang entri mana.
Untuk tata bahasa inject dan aturan tabrakan, lihat topology-triad.md.
Duplikasi batasan lintas pilar
Bidang yang berada di dua pilar dengan lapisan validasi berbeda dapat membawa batasan ganda. Contoh kanonis: nomor port yang dideklarasikan di usesSchema milik sebuah Component (divalidasi JSON Schema, rentang min: 1, max: 65535) dan nomor port yang sama dikonsumsi di bidang services.<name>.ports.<port> milik sebuah Workload, yang untuknya spec.provider.workloadSchema milik plugin rendering provider dapat menambahkan aturan min: 1024 untuk port non-privileged. spec.provider.workloadSchema milik Plugin rendering provider mendokumentasikan cara provider menerjemahkan sebuah Workload dan menandai provider sebagai mampu menyintesisnya; ia tidak memvalidasi apa pun. Setiap badan Workload divalidasi terhadap skema Workload milik platform, apa pun provider-nya, sehingga batasan yang hanya ditulis di workloadSchema — misalnya aturan port min: 1024 — tidak ditegakkan; untuk menolak nilai seperti itu, letakkan batasan di skema Component atau dalam sebuah asersi.
Lampiran Feature / isolasi pilar Component
Lampiran Feature tidak menulis ke pilar Component induk. Setiap Feature yang dilampirkan membawa muatan pilarnya sendiri (blok values: sendiri dan blok infra: sendiri). FeatureRecipe yang menyintesis sumber daya Feature membaca muatan pilarnya sendiri secara terpisah dari milik Component. Isolasi ini berlaku pada masukan: apa yang dibaca sebuah lampiran adalah miliknya sendiri, apa pun yang terjadi pada apa yang ditulisnya. Jika provider target menulis dokumen terpisah, keluaran render lampiran berada di samping keluaran Component di bawah direktorinya sendiri; jika provider melipat para kontributor suatu batas ke dalam satu dokumen, lampiran berkontribusi ke dokumen tersebut seperti halnya Component, dan setiap sumber daya tetap membawa identitas lampiran itu sendiri sehingga asal masing-masing tetap terbaca.
Dua konsekuensi bagi penulis:
- Pengaturan
values:pada lampiran Feature tidak muncul di.valuesmilik templatvaluesMapping:Component. Component hanya melihat nilainya sendiri. - Muatan
infra:milik sebuah Feature tidak mengalir keinfra:milik Component. Setiap Feature yang dilampirkan memiliki ukuran fisiknya sendiri yang terbatas pada sumber daya Feature tersebut.
Isolasi ini eksplisit sesuai pemisahan perhatian dalam arsitektur: Features adalah kontributor independen yang dilapiskan ke Components melalui Model Bawang 5 Tingkat. Untuk permukaan lampiran dan urutannya, lihat labels-and-annotations.md “Feature attachment — five surfaces”.
Nama properti yang sama di kedua pilar
Component atau Feature yang spec.schema.values: dan spec.schema.infra:-nya mendeklarasikan nama properti yang sama — di akar, di kedalaman bersarang mana pun, atau keduanya — merupakan gejala penulisan yang sering terjadi. Kedua pilar adalah namespace terpisah secara desain (compiler menerima tumpang tindih tersebut), sehingga skema tervalidasi dan keluaran render terbentuk dengan baik. Gejalanya bersifat kognitif: pembaca dan penulis templat mengalami hambatan “pilar mana yang menyimpan foo yang sedang saya baca?” setiap kali memindai skema atau menulis templat terhadapnya.
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }Penulis dengan tumpang tindih yang disengaja memiliki alasan nyata untuk mempertahankan keduanya — misalnya, mode yang berarti “mode operasional aplikasi” di bawah values ("debug" / "production") dan “mode topologi deployment” di bawah infra ("standalone" / "clustered") membawa semantik berbeda dan namanya kebetulan sama. Penulis dengan tumpang tindih yang tidak disengaja (kasus yang lebih umum) mengganti nama salah satu entri.
Bentuk disengaja kedua adalah satu datum yang dapat diberikan oleh salah satu penulis. Features kredensial pustaka standar yang membawa locator pemanggil — core/referenced-secret, core/referenced-secret-set, core/secret-value dan core/secret-provided — mendeklarasikannya di kedua pilar dengan satu nama dan satu bentuk, sehingga pengembang menulisnya di values atau operator di infra, dan asersi milik setiap Feature menolak lampiran yang menulisnya di keduanya atau tidak di keduanya. Peringatan di bawah menyebut keempatnya pada setiap pemuatan yang mencapainya; bagi keempatnya, peringatan itu melaporkan kontrak, bukan kekeliruan.
Pemuatan katalog mengeluarkan peringatan notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) untuk setiap properti bernama sama yang tumpang tindihnya berujung pada daun terminal di setidaknya satu sisi. Properti bernama sama yang ada sebagai namespace pengelompokan bersama (kedua pilar membawa objek bernama ingress dengan sub-properti yang tidak beririsan) tidak memicu peringatan; hanya tumpang tindih daun yang dilaporkan. Peringatan ini bersifat anjuran — build tetap berlanjut.
Tingkat validasi pilar
Pilar-pilar membawa validasi di tiga tingkat. Setiap tingkat mencakup kepentingan yang berbeda; bidang yang sama dapat divalidasi oleh lebih dari satu tingkat (lihat “Duplikasi batasan lintas pilar” di atas).
| Tingkat | Apa yang divalidasi | Tempat berjalan |
|---|---|---|
| 1 — Amplop JSON Schema | Bentuk struktural (kunci mana yang ada, tipe sesuai dengan deklarasi bidang) | Resolusi, per pemuatan berkas |
2 — Skema per pilar (schema / featuresSchema / usesSchema) | Konten bertipe per pilar yang divalidasi sebagai JSON Schema 2020-12 | Resolusi, setelah amplop lolos |
| 3 — gerbang kapabilitas penyedia | Konten Workload yang dibatasi oleh kapabilitas mode tersintesis dari penyedia yang terikat, didokumentasikan oleh spec.provider.workloadSchema milik plugin perender penyedia | Perenderan dasar, setelah valuesMapping teresolusi |
Untuk tabel bentuk galat empat lapisan dan prefiks galat per lapisan, lihat validation-surface.md.
Mekanisme nilai default
Nilai default muncul di seluruh korpus melalui beberapa mekanisme yang berbeda. Penulis menjumpai kata “default” dalam lima konteks atau lebih; tabel di bawah ini adalah rujukan kanonis tentang mekanisme mana yang menghasilkan nilai ketika penulis membiarkan sebuah field kosong.
| # | Mekanisme | Tempat penulisan | Pemicu |
|---|---|---|---|
| 1 | JSON Schema default: (bentuk ringkas { default: <value> }) | Component / Feature schema:, Aggregate parameters: | Field divalidasi dengan nilai default ketika developer menghilangkan kunci tersebut. Untuk parameter Aggregate, penggabungan parameter mengisi default yang dideklarasikan sebelum validasi kontrak berjalan (lihat templates/parameters-context.md). |
| 2 | Templat Go optional .X `Y` <fallback> | Recipe valuesMapping:, isi Workload, templat FeatureRecipe, evaluator asersi | Fallback yang sadar keberadaan — mengembalikan <fallback> hanya ketika kunci tidak ada di map; nilai nol / kosong / false yang ditulis pada kunci tersebut mengembalikan nilai yang ditulis itu. Bentuk kanonis fallback field yang tidak ada di sisi Aggrega. Lihat templates/sprig-functions.md. |
| 3 | Templat Go | default <expr> | Recipe valuesMapping:, isi Workload, templat FeatureRecipe | Pipeline inline yang terpicu pada nilai “kosong” (pemeriksaan kekosongan Sprig — nol, string kosong, false, nil). Menyamakan tidak-ada-di-map dengan ada-tetapi-nol/kosong/false. Cocok untuk semantik override per lokasi pemanggilan (fallback binding berbeda dari default tingkat skema milik field) ketika penyamaan tersebut dapat diterima. Tidak cocok untuk fallback field yang tidak ada ketika nilai nol / kosong / false yang ditulis merupakan maksud yang sah — gunakan optional (mekanisme 2) untuk kasus tersebut. |
| 4 | Fungsi Sprig default ({{ default <expr> .field }}) | Sama seperti 3 | Bentuk fungsi dari mekanisme 3 dengan penyamaan kekosongan yang sama. |
| 5 | Fallback locals: pada Recipe | Templat locals: pada Recipe | Sebuah entri locals menghitung string yang membawa nilai default, yang dikonsumsi oleh bagian lain Recipe |
Panduan penempatan yang disarankan. Ketika sebuah nilai default memang merupakan bagian dari kontrak tipe (mis., “port ini bernilai 5432 secara default kecuali developer menimpanya”), JSON Schema default: (mekanisme 1) adalah bentuk kanonis — pelengkapan otomatis IDE menampilkan nilai default tersebut; perangkat validasi mematuhinya; kontrak tersebut terbawa bersama entitas katalog Component / Feature ATAU bersama deklarasi parameter Aggregate. Ketika templat Recipe memerlukan fallback untuk kunci map opsional, helper optional (mekanisme 2) adalah bentuk kanonis fallback field yang tidak ada — helper ini membedakan nilai nol / kosong / false yang ditulis dari ketiadaan. Templat Go | default (mekanisme 3) dicadangkan untuk kasus override per lokasi pemanggilan ketika penyamaan antara nilai yang tidak ada dan nilai falsy dapat diterima; gunakan hanya ketika semantik override merupakan maksud yang eksplisit.
Rujukan silang
inheritance-and-interface.md— mekanismeextends:, Interface Bindingimplements:, penyaluran lintas pilar melalui jembatan skema.topology-triad.md— mekanika topologisprovides,inject,uses.labels-and-annotations.md— kosakata metadata sisi konten yang berbeda dari pilar data (daftar pilar kanonis di atas tidak mencakup label / anotasi / bidang publikasi — semuanya merupakan kosakata metadata).publishing-surface.md— kosakata metadata sisi publikasi yang berbeda dari pilar data.validation-surface.md— empat lapisan validasi skema, termasuk tiga tingkat validasi pilar di atas.templates/expansion-matrix.md— ketersediaan per situs templat untuk pembacaan lintas pilar + aturan kemandirian padaprovides:dansource:Recipe.examples/04-secrets.md— daftar periksa pengiriman rahasia dengan enam titik sentuh.architecture/06-data-taxonomy-and-composition.md— kerangka konseptual kanonis untuk lima kata kunci struktural DSL.