İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Şablon genişletme matrisi

Şablon genişletme başvurusu — Tam matris

Aggrega DSL’i, YAML varlıkları genelinde birden çok konumda Go text/template genişletmesini (Sprig kitaplığı önceden kayıtlı olarak) destekler. Her konumun, derleme ilerlerken verinin ne zaman somutlaştığına göre belirlenen, kendine özgü bir kullanılabilir başvurular kümesi vardır. Bu sayfa, nerede neye başvurulabileceğine ilişkin başvuru kaynağıdır.

1. İşlem hattı zamanlama ağacı (verinin somutlaştığı an)

Hangi başvuruların kullanılabilir olduğunu anlamak, her veri parçasının ne zaman çözümlendiğini anlamayı gerektirir. Aşağıdaki aşamalar çalıştıkları sırayla listelenmiştir ve her biri yaptığı işe göre adlandırılmıştır; sayfanın geri kalanı ona bu adla başvurur:

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. Şablon genişletme matrisi

DSL’de Go şablon ifadelerinin değerlendirildiği her konum ve tam olarak hangi başvuruların kullanılabilir olduğu:

#LocationVarlıkDeğerlendirildiği aşamaKullanılabilir başvurular
1Aggregate YAML dizelerinde {{ .parameters.X }}AggregateÇözümleme (enterpolasyon)Yalnızca .parameters. Diğer tüm veriler henüz çözümlenmemiştir.
2Release YAML dizelerinde {{ .parameters.X }}ReleaseDeğerlendirilmezYok. Bir Release’in dizeleri yazıldığı gibi okunur: infra: altında, bir açıklamada ya da bir parameters: değeri olarak yazılmış bir {{ .parameters.X }}, hedefine o sabit metin olarak ulaşır. Release parametre değerlerini sağlar (satır içi parameters: eşlemi ve $import: ile yüklenen değerler birleştirilmiş parametre eşleminde birleştirilir); Aggregate’in dizeleri bunları okur (#1), yol şablonları da öyle (#3).
3directory / subDirectory şablonlarıRelease sınırıİşleme (yol değerlendirmesi).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* ve .component_id (yalnızca subDirectory:; bir directory: şablonu bunu reddeder).
4Component inject value: dizeleriAggregate bileşeniÖz-inject çözümlemesi.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (3 grubun tümü), .metadata.* (release_name, release_version, environment, aggregate_name). YASAK: .context.inject (döngüsel — boru henüz oluşturulmaktadır), .context.uses (bileşenler arası bağlantı için bunun yerine uses[].inject kullanın). Şablon, #1’in parametre enterpolasyonunun önce okuduğu Aggregate metninde durur; bu yüzden bu aşamaya ulaşması için kaçışlı yazın — value: '{{"{{"}} .metadata.release_name }}'; düz yazılırsa enterpolasyon onu değerlendirir ve durur, çünkü bir Aggregate’in metni .parameters dışında hiçbir kök tanımlamaz.
5source alanı dizeleri (üst düzey dize VEYA yapılandırılmış bir source: eşleminin dize değerli alt alanları)Recipe / FeatureRecipeKaynak çözümlemesiKaynağın neyi adlandırdığına göre belirlenen iki yüzey. Uzak bir koordinat — bir kayıt defterini, bir chart deposunu veya bir git deposunu adlandıran yapılandırılmış bir bloğun version, chart, ref ve module_subdir alanları — aggrega pull yapıtı sabitlemek için çözümlerken değerlendirilir: yalnızca .values, .infra, .locals ve statik dizeler; Aggrega’nın kendi yardımcılarıyla (optional, capitalizedWords, index), Sprig işlevlerinin hiçbiri olmadan ve .context kökü olmadan. Orada değerlendirilen .locals girdileri, bu alanların doğrudan veya başka bir girdi aracılığıyla okuduklarıdır — bir alanın .locals’ı tek bir girdiyi adlandırmayacak biçimde okuduğu durumda her girdi — böylece hiçbir alanın okumadığı bir girdi işlemeye bırakılır. Çalışma alanında bir yolu adlandıran kaynak ise varlık işlenirken değerlendirilir: .context.instance_id, .values, .infra, .locals (bildiren varlığın çözümlenmiş bloğunun tamamı), statik dizeler. Orada bir FeatureRecipe’nin kaynağı ayrıca .attachment_name’i okur — çözümlenen şey bir eklentidir — ve onun .context.instance_id’si, ana bileşenin bildirilen adı olan .context.rendered_name’in yanında ana bileşeni adlandırır (bkz. #9); sınır kapsamlı bir FeatureRecipe .boundary.*’i okur ve bileşen başına sütunların hiçbirini okumaz. Her ikisinde de YASAK: .context.inject, .context.uses, .provides (kendine yeterlilik değişmezi — çalışma alanı kaynağı yüzeyi bağlamını bildiren varlığın kendi locals’ı ile paylaşır, dolayısıyla ikisi aynı başvuruları kabul eder ve reddeder; uzak bir koordinat ise bu bağlamın bir alt kümesini okur; kaynak çözümlemesi, topoloji borusu doldurulmadan ve herhangi bir chart, modül veya yapıt gövdesi yüklenmeden önce tamamlanmalıdır).
6Recipe provides şablonlarıRecipeProvides değerlendirmesi.context.instance_id, .context.rendered_name (düğümün provider’ının düğüm için işlediği çıktıya verdiği ad — yazarın sağladığı kaynaktan veya sentezlediği bir workload’dan; provider’ı böyle bir ad bildirmeyen bir düğümde bunu okumak durdurur — bkz. İşlenen bir kaynağı adlandırma), .values, .infra, .locals (düğümün çözümlenmiş bloğunun tamamı — locals bu aşamanın ön bölümünde, provides’tan önce çözümlenir), statik dizeler. YASAK: diğer tüm kökler — .context.inject, .context.uses (düğümler arası), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (yerleşime/dağıtıma bağlı) ve .attachment_name (temel bir Recipe’nin provides değerlendirmesi sırasında hiçbir eklenti çözümlenmez). Denetim pozitif bir izin listesidir: provides bağlamının sunmadığı herhangi bir köke başvurmak durdurur (kendine yeterlilik değişmezi — sıfır topolojik sıralamayla paralel değerlendirmeyi mümkün kılar). locals bloğunun bildirmediği bir anahtarı adlandıran .locals.<key> de durdurur, çünkü bu sütun yalnızca kök denetiminin denetleyemeyeceği açık, anahtarlı bir eşlemdir.
7Recipe valuesMapping (satır içi, dosya $import: veya kitaplık $import:)RecipeTemel işlemeTam şablon bağlamı: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Satır içi yazılan bir .context.rendered_name başvurusu, #6’daki gibi, provider’ı böyle bir ad bildirmeyen bir düğümde durdurur; $import: ile yüklenen bir gövdenin içindeki başvuru ise denetlenmez ve böyle bir düğümde boş işlenir.
8FeatureRecipe injectMappingFeatureRecipeInject eşlemesiTam şablon bağlamı: .values, .infra, .context.* (.context.inject — araya girilen boru — ve .context.uses dahil). .context.used_by burada boştur: eşlemenin çıktısı ana bileşenin kendi teslim borusuna düşer. .context.render_facts yoktur: eşleme, ana bileşen işlenmeden önce çalışır. .context.rendered_name, #9’daki gibi ana bileşenin bildirilen adıdır; bunu okuyan bir eşleme denetlenmez ve provider’ı ad bildirmeyen bir ana bileşende onu boş işler. FeatureRecipe’in executionScope değeri ne olursa olsun bağlam aynıdır: sınır kapsamlı bir FeatureRecipe’in eşlemesi, ekin ulaştığı her bileşen için bir kez çalışır, o bileşenin .context.* değerini okur, .features.<attachment>.provides ve .locals değerlerini ise tek sınır değerlendirmesi olarak okur. YASAK: hiçbir bileşenin bağlamının taşımadığı .boundary — bir başvuru derlemeyi durdurur.
9FeatureRecipe valuesMapping (ve onun workload: ile artifacts: alanları)FeatureRecipeTemel işlemeTam şablon bağlamı + .attachment_name, .inject (ek bir inject: bloğu yazdığında, ekin kendi inject: girdileri), .context.render_facts — ana bileşenin provider’ının ana bileşenin işlenmesi hakkında bildirdikleri — ve .context.used_by — ana bileşeni kullanan bileşenler; FeatureRecipe readsCallerRenderFacts: true ayarladığında her biri kendi işleme olgularını taşır. FeatureRecipe readsTargetRenderFacts: true ayarladığında .context.uses üzerindeki her bağlantı, hedefinin işleme olgularını .render_facts altında taşır. .context.instance_id ve .context.rendered_name, ana bileşenin kimliği ve ana bileşenin kendi provider’ının onun için bildirdiği addır — ana bileşenin Recipe’sinin okuduğu aynı değer, FeatureRecipe’nin locals: ve provides: alanlarında da — ve satır içi yazılan bir .context.rendered_name başvurusu, provider’ı böyle bir ad bildirmeyen bir ana bileşende durdurur. .source, FeatureRecipe’nin kendi değerlendirilmiş source: alanıdır, asla ana bileşeninki değildir ve FeatureRecipe hiç bildirmediğinde hiçbir şey içermez.
10İşlem hattı with: bloklarıRecipe / FeatureRecipePlugin işlem hattıTam şablon bağlamı + .steps (önceki işlem hattı adımlarından adımlar arası çıktılar). .context.used_by burada boştur ve .context.uses üzerindeki hiçbir bağlantı hedefinin işleme olgularını taşımaz: bir adım ana bileşenin kendi belgelerini yeniden yazabilir. Eklenmiş bir FeatureRecipe’nin adımı, #9’un yaptığı gibi, ana bileşenin kendi işleme olguları olan .context.render_facts’i okur.
11Recipe workload: gövdesi (satır içi veya $import: ile yüklenmiş olsun, içindeki her şablonlu alan)RecipeTemel işlemeTam şablon bağlamı. Workload gövdesinin içindeki her alan — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — Workload dizesinin tamamını tüketen aynı şablon değerlendirmesinin parçasıdır. Workload içeriği, tam şablon bağlamına karşı bir kez değerlendirilen tek bir Go şablonudur; içerideki alan düzeyindeki şablonlar ayrı bir değerlendirmede değil, aynı değerlendirmede çözümlenir.

Kendi kendine yeterlilik notu. source dizeleri (#5), provides kendi kendine yeterlilik değişmezini (#6) paylaşır: her iki yüzey de .context.inject ve .context.uses başvurularını reddeder. Kaynak çözümleme, .context.inject’i dolduran inject hidrasyonundan önce ve aşağı akıştaki herhangi bir şey çözümlenmiş kaynağı tüketmeden önce çalışır; bu nedenle kural ve gerekçesi her iki yüzey için de geçerlidir. İkisinin ayrıldığı yer provides sütunudur: bir çalışma alanı source’u bağlamını bildiren varlığın locals’ı ile paylaşır, uzak bir koordinat ise bu bağlamın bir alt kümesini okur; bu yüzden ikisi de .provides’ı reddeder, provides ise zaten çözümlenen yüzeyin kendisidir. Her ikisi de .locals’ı okur. Kural, bir FeatureRecipe’in source’una bir Recipe’inkine ulaştığı koşullarla ulaşır ve her biri o varlığın kendi locals yüzeyine göre denetlenir.

Workload gövdesi şablonlama notu (#11). Workload gövdesi, oluşturucunun bir bütün olarak değerlendirdiği ve ardından sonucu bir Workload belgesi olarak ayrıştırdığı tek bir şablonlu dizedir. İçerideki alan düzeyindeki şablonlar (burada bir replicas: {{ .infra.replicas | default 1 }}, orada containers.app.variables içinde bir LOG_LEVEL: "{{ .values.log_level }}") ayrı şablon değerlendirme noktaları değildir; hepsi Workload’ı üreten tek temel oluşturma değerlendirmesine katılır. Yazarların Workload içi alanlar için ayrı bir kullanılabilirlik kuralına ihtiyacı yoktur; bir bütün olarak Workload kuralı (#11), içerideki her alan düzeyindeki şablonu kapsar.

Workload gövdesi içinde ayırt edici farkındalıklı geri dönüş. Yukarıdaki replicas: {{ .infra.replicas | default 1 }} örneği, “yazar replicas ayarlamadı” durumunu “yazar replicas’ı 0 olarak ayarladı” durumuyla karıştırır: default her ikisinde de devreye girer. Bir Release sıfıra ölçeklemeyi ifade etmek için meşru olarak infra.replicas: 0 yazdığında (yaygın bir Knative / KEDA kalıbı), | default 1 biçimi bu amacı sessizce geçersiz kılar. Ayırt edici farkındalıklı biçim replicas: {{ optional .infra "replicas" 1 }} biçimidir: optional anahtarın varlığını denetler ve anahtar ayarlandığında yazılan değeri (yazılan sıfır dahil) döndürür, yalnızca anahtar yoksa 1’e geri döner. Tam anlam ve hangisinin ne zaman tercih edileceğine ilişkin rehberlik için sprig-functions.md sayfasına bakın.

3. Yasak başvurular ve gerekçeleri

LocationYasak başvuruGerekçe
Component inject value: (#4).context.injectInject borusu o noktada oluşturulmaktadır: bir self-inject value: şablonu katkıda bulunduğu borudan okuyamaz.
Component inject value: (#4).context.usesBileşenler arası bağlantı uses[].inject içinde yer alır. Bir bileşenin self-inject value: şablonları bileşenin kendi verisiyle sınırlı kalır.
Recipe provides (#6).context.injectProvides şablonları herhangi bir sırayla değerlendirilir ve yalnızca düğümün kendi verisiyle (.values, .infra, .locals, .context.instance_id, .context.rendered_name) sınırlıdır. Inject borusu, her düğümün provides değerleri değerlendirildikten sonra çalışan inject hidrasyonuna kadar doldurulmaz.
Recipe provides (#6).attachment_nameTemel bir Recipe’in provides geçişi hiçbir eklentiyi çözümlemez, bu nedenle ad boş oluşturulurdu. Kök, boş teslim edilmek yerine reddedilir.
source (#5).providesKaynak yüzeylerinin hiçbiri bir provides sütunu taşımaz: çalışma alanı kaynak yüzeyi bağlamını, provides sütunu olmayan, bildiren varlığın kendi locals’ı ile paylaşır; uzak bir koordinat ise bu bağlamın bir alt kümesini okur. Locals, provides:’ın .locals’ı okuyabilmesi için provides’tan önce çözümlenir; kaynak şablonu provides’a geri uzanmak yerine aynı locals’ı okur.
Recipe locals (#6 ön bölümü).providesLocals provides’tan önce çözümlenir, bu nedenle bir local değerlendirildiğinde düğümün kendi provides değerleri henüz mevcut değildir. Provides’ın da yayımladığı bir değere ihtiyaç duyan bir local, onu doğrudan .values / .infra’dan hesaplar ve ardından provides girdisi local’ı okur.
Recipe locals (#6 ön bölümü).context.rendered_nameBir Recipe’in locals’ı bağlamını source şablonuyla (#5) paylaşır ve bu yüzey adı sunmaz: düğümün kaynak sağlayıp sağlamadığı, ki buna source şablonu karar verir, adın bağlı olduğu şeylerden biridir. Başvuru, .context’in orada tanımladığı şey olarak .context.instance_id’yi listeleyen bilinmeyen kök tanılamasıyla durur. Anahtarı bunun yerine bir provides girdisinde veya temel oluşturma aşamasının bir şablonunda okuyun.
Recipe provides (#6).context.uses.context.uses diğer düğümlerin provides değerlerine başvurur ve provides değerlendirmesi bunları rastgele sırayla çalıştırır. Provides şablonları, değerlendirmenin sıradan bağımsız kalması için kendi kendine yeterli kalır.
Sağlayıcısı ad bildirmeyen bir ana bilgisayarda FeatureRecipe locals, provides, source (#5) ve satır içi oluşturma şablonları (#9, #10).context.rendered_nameBir Feature eklentisinde anahtar, ana bileşenin bildirilen adını taşır; tek başına bir yapıt kümesi yerleştiren veya böyle bir ad türetmeyen bir sağlayıcı aracılığıyla oluşturan bir ana bileşenin taşıyacak adı yoktur. Başvuru, .context’in orada tanımladıkları arasında .context.instance_id’yi listeleyen bilinmeyen kök tanılamasıyla durur; bunun yerine kimliği okuyun, böyle bir ana bileşende ana bileşenin kendi kaynakları bu kimliğe göre adlandırılır.
source (#5).context.injectKaynak çözümleme, .context.inject’i dolduran inject hidrasyonundan önce çalışır. Kaynak URI’si değerlendirildiğinde boru henüz doldurulmamıştır.
source (#5).context.usesKaynak çözümleme, aşağı akıştaki herhangi bir şey bildiren varlığın chart’ını, modülünü veya yapıt gövdesini yüklemeden önce tamamlanmalıdır. Düğümler arası başvurulara izin vermek, kaynak çözümlemeyi kasıtlı olarak kaçındığı topoloji yineleme sırasına bağlardı.
Parametreler (yol şablonları dışında her yerde)İnterpolasyondan sonraki herhangi bir değer şablonu yüzeyiİnterpolasyon, yazılan YAML’daki her {{ .parameters.X }} başvurusunu tüketir ve yerine çözümlenmiş değeri yazar; bu nedenle bir değer şablonu yüzeyi parametre sütunu yerine çözümlenmiş sabit değeri alır. Operatörün yazdığı yol şablonları tek istisnadır ve .parameters.X’i doğrudan okur.

4. Self-inject çözümleme yolu

Self-inject çözümleme, inject hidrasyonunun ilk yarısıdır ve her düğümün provides değerleri değerlendirildikten sonra çalışır. Bir bileşen bileşen düzeyinde bir inject: bloğu bildirdiğinde, derleyici onu orada değerlendirir:

  1. Sabit value: dizeleri: Değer Go şablon ifadeleri içeriyorsa, derleyici bunları matrisin #4 satırındaki bağlamla (.values, .infra, .context.instance_id, .metadata.* vb.) değerlendirir; ifadeler #4 satırında gösterildiği gibi kaçışlı yazılır. Düz dizeler değişmeden geçer.
  2. from: başvuruları: Derleyici anahtarı, o zamana kadar çözümlenmiş olan düğümün kendi provides sözlüğünde arar. Anahtar yoksa derleyici derlemeyi geçersiz inject anahtarı hatasıyla durdurur.
  3. Çakışma denetimi: .context.inject borusuna birleştirmeden önce derleyici, hiçbir anahtarın inject hidrasyonunun ikinci yarısının çözümlediği uses-inject anahtarlarıyla çakışmadığını doğrular. Çakışmalar derlemeyi yinelenen teslim anahtarı hatasıyla durdurur.

Ortaya çıkan dizeler, bu uses-inject çözümlemeleriyle birlikte .context.inject.env, .context.inject.file, .context.inject.arg (ve tüm özel mekanizmalar) içine birleştirilir. Inject eşlemesi (injectMapping) çalıştığında boru, her iki kaynaktan gelen, geliştiricinin yazdığı tüm inject değerlerini içerir.