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

Matriks ekspansi templat

Referensi ekspansi template — matriks lengkap

DSL Aggrega mendukung ekspansi Go text/template (dengan pustaka Sprig yang sudah terdaftar) di berbagai lokasi pada entitas YAML. Setiap lokasi memiliki himpunan referensi tersedia yang spesifik, yang ditentukan oleh kapan data menjadi konkret seiring berjalannya kompilasi. Halaman ini adalah referensi tentang apa yang dapat direferensikan di mana.

1. Pohon waktu pipeline (kapan data menjadi konkret)

Untuk memahami referensi apa yang tersedia, perlu dipahami kapan setiap bagian data di-resolve. Tahap-tahap di bawah ini dicantumkan sesuai urutan eksekusinya, dan masing-masing dinamai berdasarkan apa yang dilakukannya — nama itulah yang digunakan bagian lain halaman ini untuk merujuknya:

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. Matriks ekspansi template

Setiap lokasi dalam DSL tempat ekspresi template Go dievaluasi, beserta referensi yang tersedia secara persis:

#LocationEntitasDievaluasi padaReferensi yang tersedia
1{{ .parameters.X }} dalam string YAML AggregateAggregateResolusi (interpolasi)Hanya .parameters. Semua data lain belum di-resolve.
2{{ .parameters.X }} dalam string YAML ReleaseReleaseTidak dievaluasiTidak ada. String Release dibaca sebagaimana ditulis: {{ .parameters.X }} di bawah infra:, dalam anotasi, atau sebagai nilai parameters: mencapai tujuannya sebagai teks literal itu. Release menyediakan nilai parameter (map parameters: inline dan nilai yang dimuat $import: digabungkan ke dalam map parameter gabungan); string Aggregate membacanya (#1), demikian pula templat path (#3).
3Template directory / subDirectoryBatas ReleaseRendering (evaluasi path).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.*, dan .component_id (hanya subDirectory: — template directory: menolaknya).
4String value: pada inject ComponentKomponen AggregateResolusi self-inject.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (ketiga bucket), .metadata.* (release_name, release_version, environment, aggregate_name). DILARANG: .context.inject (sirkular — pipe sedang dibangun), .context.uses (gunakan uses[].inject untuk wiring lintas komponen). Templat berada di dalam teks Aggregate, yang terlebih dahulu dibaca oleh interpolasi parameter #1, jadi tulislah dalam bentuk ter-escape — value: '{{"{{"}} .metadata.release_name }}' — agar mencapai tahap ini; jika ditulis apa adanya, interpolasi mengevaluasinya dan berhenti, karena teks Aggregate tidak mendefinisikan root selain .parameters.
5String field source (string tingkat atas ATAU sub-field bernilai string dari map source: terstruktur)Recipe / FeatureRecipeResolusi sourceDua permukaan, ditentukan oleh apa yang dinamai source. Koordinat remote — version, chart, ref, dan module_subdir dari blok terstruktur yang menamai registry, repositori chart, atau repositori git — dievaluasi saat aggrega pull me-resolve artefak untuk mem-pin-nya: hanya .values, .infra, .locals, dan string statis, dengan helper milik Aggrega sendiri (optional, capitalizedWords, index) dan tanpa fungsi Sprig, serta tanpa root .context. Entri .locals yang dievaluasi di sana adalah entri yang dibaca field-field tersebut, secara langsung atau melalui entri lain — setiap entri jika suatu field membaca .locals dengan cara yang tidak menamai satu entri tertentu — sehingga entri yang tidak dibaca field mana pun diserahkan ke render. Source yang menamai path di workspace dievaluasi saat entitas di-render: .context.instance_id, .values, .infra, .locals (seluruh blok terselesaikan milik entitas yang mendeklarasikannya), string statis. Di sana source sebuah FeatureRecipe juga membaca .attachment_name — attachment-lah yang sedang di-resolve — dan .context.instance_id-nya menamai komponen host, di samping .context.rendered_name, nama yang dilaporkan komponen host (lihat #9); FeatureRecipe dengan cakupan boundary membaca .boundary.* dan tidak satu pun pilar per komponen. DILARANG pada keduanya: .context.inject, .context.uses, .provides (invarian self-containment — permukaan workspace-source berbagi konteks dengan locals milik entitas yang mendeklarasikannya, sehingga keduanya menerima dan menolak referensi yang sama, dan koordinat remote membaca subset dari konteks itu; resolusi source harus selesai sebelum pipe topologi di-hydrate dan sebelum body chart, modul, atau artefak apa pun dimuat).
6Template provides RecipeRecipeEvaluasi provides.context.instance_id, .context.rendered_name (nama yang diberikan provider node pada output yang di-render-nya untuk node — dari source yang disediakan penulis, atau dari workload yang disintesisnya; membacanya pada node yang provider-nya tidak melaporkan nama semacam itu akan menghentikan proses — lihat Menamai resource yang di-render), .values, .infra, .locals (seluruh blok terselesaikan milik node — locals di-resolve dalam preamble tahap ini, sebelum provides), string statis. DILARANG: setiap root lain — .context.inject, .context.uses (lintas node), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (terkait penempatan/deployment), dan .attachment_name (tidak ada attachment yang di-resolve selama evaluasi provides Recipe dasar). Pemeriksaan ini berupa allowlist positif: mereferensikan root apa pun yang tidak diekspos konteks provides akan menghentikan proses (invarian self-containment — memungkinkan evaluasi paralel tanpa sort topologis). .locals.<key> yang menamai key yang tidak dideklarasikan blok locals juga menghentikan proses, karena pilar tersebut adalah map berkey terbuka yang tidak dapat diawasi oleh pemeriksaan root saja.
7valuesMapping Recipe (inline, file $import:, atau pustaka $import:)RecipeRendering dasarKonteks templat lengkap: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Referensi .context.rendered_name yang ditulis inline menghentikan proses pada node yang provider-nya tidak melaporkan nama semacam itu, seperti pada #6; referensi di dalam body yang dimuat melalui $import: tidak diperiksa, dan di-render kosong pada node semacam itu.
8injectMapping FeatureRecipeFeatureRecipeInject mappingKonteks templat lengkap: .values, .infra, .context.* (termasuk .context.inject — pipe yang sedang diintersep — dan .context.uses). .context.used_by kosong di sini: output mapping mendarat di pipe pengiriman milik host sendiri. .context.render_facts tidak ada: mapping berjalan sebelum host di-render. .context.rendered_name adalah nama yang dilaporkan komponen host, seperti pada #9; mapping yang membacanya tidak diperiksa, dan me-render-nya kosong pada host yang provider-nya tidak melaporkan nama. Konteksnya sama apa pun executionScope FeatureRecipe: mapping FeatureRecipe lingkup batas berjalan sekali untuk setiap komponen yang dijangkau lampiran, membaca .context.* komponen tersebut, dan membaca .features.<attachment>.provides serta .locals sebagai satu evaluasi batas. DILARANG: .boundary, yang tidak dibawa konteks komponen mana pun — referensi menghentikan build.
9valuesMapping FeatureRecipe (beserta workload: dan artifacts:-nya)FeatureRecipeRendering dasarKonteks templat lengkap + .attachment_name, .inject (entri inject: milik lampiran sendiri, jika lampiran menulis blok inject:), .context.render_facts — apa yang dilaporkan provider host tentang render host — dan .context.used_by — komponen-komponen yang menggunakan host, masing-masing membawa render facts-nya sendiri jika FeatureRecipe menetapkan readsCallerRenderFacts: true. Setiap koneksi pada .context.uses membawa render facts target-nya, di .render_facts, jika FeatureRecipe menetapkan readsTargetRenderFacts: true. .context.instance_id dan .context.rendered_name adalah identitas komponen host dan nama yang dilaporkan provider milik host untuknya — nilai yang sama yang dibaca Recipe host, juga pada locals: dan provides: FeatureRecipe — dan referensi ke .context.rendered_name yang ditulis inline menghentikan proses pada host yang provider-nya tidak melaporkan nama semacam itu. .source adalah source: milik FeatureRecipe itu sendiri yang telah dievaluasi, tidak pernah milik komponen host, dan tidak berisi apa pun jika FeatureRecipe tidak mendeklarasikannya.
10Blok with: pipelineRecipe / FeatureRecipePipeline pluginKonteks templat lengkap + .steps (output antar-langkah dari langkah pipeline sebelumnya). .context.used_by kosong di sini, dan tidak ada koneksi pada .context.uses yang membawa render facts target-nya: sebuah langkah dapat menulis ulang dokumen milik host sendiri. Langkah FeatureRecipe yang terpasang membaca .context.render_facts, render facts milik host sendiri, seperti pada #9.
11Body workload: Recipe (setiap field bertemplate di dalamnya, baik inline maupun dimuat melalui $import:)RecipeRendering dasarKonteks templat lengkap. Setiap field di dalam body Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — merupakan bagian dari evaluasi template yang sama yang memproses seluruh string Workload. Konten Workload adalah satu template Go yang dievaluasi sekali terhadap konteks templat lengkap; template tingkat field di dalamnya di-resolve dalam evaluasi yang sama, bukan dalam evaluasi terpisah.

Catatan swa-kandungan. String source (#5) berbagi invarian swa-kandungan provides (#6): kedua permukaan menolak referensi .context.inject dan .context.uses. Resolusi sumber berjalan sebelum hidrasi inject yang mengisi .context.inject, dan sebelum apa pun di hilir mengonsumsi sumber yang telah diresolusi — sehingga aturan dan alasannya berlaku pada kedua permukaan. Perbedaan keduanya terletak pada pilar provides: source workspace berbagi konteksnya dengan locals milik entitas yang mendeklarasikannya, dan koordinat jarak jauh membaca subset darinya, sehingga keduanya menolak .provides, sedangkan provides sendiri adalah permukaan yang sedang diresolusi. Keduanya membaca .locals. Aturan ini berlaku untuk source milik FeatureRecipe dengan ketentuan yang sama seperti untuk milik Recipe, masing-masing diperiksa terhadap permukaan locals milik entitas itu sendiri.

Catatan templating badan Workload (#11). Badan Workload adalah satu string bertemplat yang dievaluasi renderer secara utuh, lalu hasilnya di-parse sebagai dokumen Workload. Templat tingkat field di dalamnya (sebuah replicas: {{ .infra.replicas | default 1 }} di sini, sebuah LOG_LEVEL: "{{ .values.log_level }}" di dalam containers.app.variables di sana) bukan situs evaluasi templat yang terpisah — semuanya ikut serta dalam satu evaluasi rendering dasar yang menghasilkan Workload. Penulis tidak memerlukan aturan ketersediaan terpisah untuk field internal Workload; aturan untuk Workload secara keseluruhan (#11) mencakup setiap templat tingkat field di dalamnya.

Fallback yang sadar diskriminator di dalam badan Workload. Contoh replicas: {{ .infra.replicas | default 1 }} di atas mencampuradukkan “penulis tidak menetapkan replicas” dengan “penulis menetapkan replicas ke 0” — default aktif pada keduanya. Ketika sebuah Release secara sah menulis infra.replicas: 0 untuk menyatakan scale-to-zero (pola Knative / KEDA yang umum), bentuk | default 1 diam-diam menimpa maksud tersebut. Bentuk yang sadar diskriminator adalah replicas: {{ optional .infra "replicas" 1 }} — optional memeriksa keberadaan kunci dan mengembalikan nilai yang ditulis (termasuk nol yang ditulis) ketika kunci ditetapkan, dan beralih ke 1 hanya ketika kunci tidak ada. Lihat sprig-functions.md untuk semantik lengkap dan panduan kapan sebaiknya digunakan.

3. Referensi terlarang & alasannya

LocationReferensi terlarangAlasan
inject value: Component (#4).context.injectPipa inject sedang dibangun pada titik tersebut — templat value: self-inject tidak dapat membaca dari pipa yang ia sumbangkan.
inject value: Component (#4).context.usesPengkabelan lintas komponen berada di uses[].inject. Templat value: self-inject sebuah komponen tetap tertutup atas data milik komponen itu sendiri.
provides Recipe (#6).context.injectTemplat provides dievaluasi dalam urutan apa pun dan hanya tertutup atas data milik node itu sendiri (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Pipa inject belum diisi sampai hidrasi inject, yang berjalan setelah provides setiap node dievaluasi.
provides Recipe (#6).attachment_nameTahap provides sebuah Recipe dasar tidak meresolusi lampiran apa pun, sehingga nama tersebut akan dirender kosong. Root ini ditolak alih-alih dikirimkan kosong.
source (#5).providesTidak satu pun permukaan sumber membawa pilar provides: permukaan sumber workspace berbagi konteksnya dengan locals milik entitas yang mendeklarasikannya, yang tidak memilikinya, dan koordinat jarak jauh membaca subset dari konteks tersebut. Locals diresolusi sebelum provides agar provides: dapat membaca .locals; templat sumber membaca locals yang sama alih-alih menjangkau balik ke provides.
locals Recipe (pembuka #6).providesLocals diresolusi sebelum provides, sehingga provides milik node itu sendiri belum ada ketika sebuah local dievaluasi. Local yang memerlukan nilai yang juga dipublikasikan provides menghitungnya langsung dari .values / .infra — dan entri provides kemudian membaca local tersebut.
locals Recipe (pembuka #6).context.rendered_nameLocals sebuah Recipe berbagi konteksnya dengan templat source miliknya (#5), dan permukaan itu tidak menyediakan nama tersebut: apakah node menyediakan sumber, yang diputuskan oleh templat source, adalah salah satu hal yang menentukan nama tersebut. Referensi ini berhenti dengan diagnostik root tidak dikenal, yang mencantumkan .context.instance_id sebagai apa yang didefinisikan .context di sana. Sebagai gantinya, bacalah kunci tersebut dalam entri provides, atau dalam templat tahap rendering dasar.
provides Recipe (#6).context.uses.context.uses merujuk ke provides milik node lain, dan evaluasi provides menjalankannya dalam urutan sembarang. Templat provides tetap swa-kandung agar evaluasi tetap bebas urutan.
locals, provides, source (#5) FeatureRecipe dan templat render inline (#9, #10), pada host yang provider-nya tidak melaporkan nama.context.rendered_namePada lampiran Feature, kunci ini membawa nama yang dilaporkan milik komponen host, dan host yang hanya menempatkan satu set artefak, atau yang merender melalui provider yang tidak menurunkan nama semacam itu, tidak memiliki nama untuk dibawa. Referensi ini berhenti dengan diagnostik root tidak dikenal, yang mencantumkan .context.instance_id di antara apa yang didefinisikan .context di sana; sebagai gantinya, bacalah identitasnya, yang menjadi dasar penamaan resource milik host itu sendiri pada host semacam itu.
source (#5).context.injectResolusi sumber berjalan sebelum hidrasi inject yang mengisi .context.inject. Pipa tersebut belum diisi ketika URI sumber dievaluasi.
source (#5).context.usesResolusi sumber harus selesai sebelum apa pun di hilir memuat chart, modul, atau badan artefak milik entitas yang mendeklarasikannya. Mengizinkan referensi lintas node akan mengikat resolusi sumber pada urutan iterasi topologi, yang sengaja dihindarinya.
Parameter (di mana pun kecuali templat path)Permukaan templat nilai mana pun setelah interpolasiInterpolasi mengonsumsi setiap referensi {{ .parameters.X }} dalam YAML yang ditulis dan menuliskan nilai yang telah diresolusi di tempatnya, sehingga permukaan templat nilai menerima literal yang telah diresolusi alih-alih pilar parameter. Templat path yang ditulis operator adalah satu-satunya pengecualian dan membaca .parameters.X secara langsung.

4. Jalur resolusi self-inject

Resolusi self-inject adalah paruh pertama hidrasi inject, dan berjalan setelah provides setiap node dievaluasi. Ketika sebuah komponen mendeklarasikan blok inject: tingkat komponen, compiler mengevaluasinya di sana:

  1. String value: literal: Jika nilai berisi ekspresi templat Go, compiler mengevaluasinya dengan konteks dari baris #4 matriks (.values, .infra, .context.instance_id, .metadata.*, dll.), yang ditulis dalam bentuk ter-escape seperti ditunjukkan baris #4. String biasa diteruskan tanpa perubahan.
  2. Referensi from:: Compiler mencari kunci dalam kamus provides milik node itu sendiri, yang saat itu sudah diresolusi. Jika kunci tidak ada, compiler menghentikan build dengan galat invalid-inject-key.
  3. Pemeriksaan tabrakan: Sebelum digabungkan ke pipa .context.inject, compiler memverifikasi bahwa tidak ada kunci yang bertabrakan dengan kunci uses-inject yang diresolusi oleh paruh kedua hidrasi inject. Tabrakan menghentikan build dengan galat duplicate-delivery-key.

String yang dihasilkan digabungkan ke .context.inject.env, .context.inject.file, .context.inject.arg (dan mekanisme kustom apa pun), bersama resolusi uses-inject tersebut. Pada saat pemetaan inject (injectMapping) berjalan, pipa berisi semua nilai inject yang ditulis pengembang dari kedua sumber.