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

FeatureRecipe

FeatureRecipe varlığının kavramsal rolü (Alan 3 — bir Feature arayüzünün Wasm Plugin’i ile yürütülen uygulaması) architecture/04-entity-taxonomy.md sayfasında anlatılır. Bu sayfa, FeatureRecipe kataloğunun yazım yüzeyini ele alır.

Katalog konumu

FeatureRecipes, provider baştaki yol bölümünde olacak şekilde düzenlenir (Recipes ile aynı desen):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

OCI URI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (ör. hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).

Yazım sözleşmesi

FeatureRecipes, implements aracılığıyla bir Feature arayüzüne bağlanır ve somut bir sağlayıcı bildirir. Yazım yüzeyleri, temel Recipe’in tüm girdi türlerine ek olarak FeatureRecipe’e özgü iki bloktan oluşur:

  1. Üç girdi türü — source + valuesMapping (kaynaklı), workload (sentezlenmiş) ve artifacts: biçim olarak temel Recipe ile aynıdır (bkz. Recipe girdi bileşimi ve entities/recipe.md). Bunlardan herhangi birini taşıyan bir FeatureRecipe kaynak üreten bir FeatureRecipe’tir — temel bileşenin yanında kaynaklar oluşturur. Bu kaynakların yerleştiği konum, önce Feature’ın bağlı olduğu bileşeni, ardından bağlandığı adı taşır; hedefin kendi düzeninin kabul ettiği iki biçimden hangisi geçerliyse o biçimde: sağlayıcısı her katkıda bulunana kendi konumunu veren bir hedefte, o hedefin katkıda bulunanların bulunduğu dizine verdiği ad altında, ana bileşenin dizininin yanında bir {component}--{instance}/ dizini olarak; yalnızca doğrudan bir dizinde duran dosyaları okuyan bir hedefte ise bileşenin kendi dosyalarının yanında bir {component}--{instance}-- dosya adı öneki olarak. Katkıda bulunanlarını tek bir belgede birleştiren bir sağlayıcıda ise kaynaklar bunun yerine o belgeye katlanır — Feature hangi aileye ait olursa olsun: satır içi ya da $import artifacts: olarak bir ServiceMonitor veya ExternalSecret CRD’si; source: + valuesMapping: aracılığıyla harici bir chart ya da modül; veya workload: aracılığıyla kendi hesaplama birimi (örneğin bir yan araç ajanı Deployment’ı). valuesMapping:, temel Recipe’in üç yazım kipini paylaşır (satır içi blok skaler, dosya $import:, bir MappingLibrary girdisine kütüphane $import:) — bkz. entities/recipe.md “valuesMapping alanı — üç yazım kipi”. Uzlaşım gereği bir FeatureRecipe temel bileşeni değiştirir ya da onun yanına kaynak ekler, ancak şema hangi girdi türlerini kullanabileceğini kısıtlamaz — derleyici, FeatureRecipe’in bildirdiği her şeyi yalnızca bağlı sağlayıcının yeteneğiyle sınırlı olarak oluşturur ve belirli bir türün “değiştiriciye uygun” olup olmadığı konusunda kendi görüşü olmayan bir tutum sürdürür (bkz. kurucu değişmezler). Sentez (workload:) bunu destekleyen bir sağlayıcı gerektirir; aksi hâlde derleme, oluşturma aşamasında sağlayıcı yeteneği tanılamasıyla durur.
  2. injectMapping (render öncesi yakalama): Temel Recipe render edilmeden önce yürütülen yerel bir Go şablon bloğu. Derleyicinin çağıranın .context.inject bellek kanalının üzerine yerel olarak derinlemesine birleştirdiği bir JSON veya YAML sözlüğü üretir; böylece ortam değişkenleri ve bağlantı dizeleri Wasm gerektirmeden çağıran tarafında değiştirilebilir.
  3. pipeline: Oluşturma sonrası Workload değişikliği için sıralı bir WebAssembly (Wasm) eklenti adımları dizisi (örneğin JSONPatch ile bir Envoy yan aracı enjekte etmek ya da bir gizli bilgi birimi bağlamak). Her adımın plugin alanı, bir Plugin varlığını URI’si ile adlandırır; bu ad her zaman eklentinin kendi soket türüyle kapsamlandırılır (<pluginType>/<name>, isteğe bağlı olarak sürümlü; parser/yaml veya parser/yaml:1.0.0 örneklerindeki gibi); derleme, varlığı eklentinin kimliğinden ve yapılandırılmış kayıt defterinden bulunan içerik adresli .wasm yapıtına çözümler ve burada çıplak bir .wasm ya da yapıt başvurusu kabul edilmez. Bir eklentiyi yazmak ve ona başvurmak için Wasm eklenti geliştirici kılavuzu’na, iki parçalı eklenti ilkesi (Fetcher / Injector) için architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base” bölümüne bakın. Derleyici her adımı bildirilen sırayla yürütür: adlandırılan eklentinin konuk dışa aktarımını oluşturulan çıktı üzerinde çağırır ve döndürülen JSON Patch’leri ile yayımlanan yan etkileri uygular; her işlem hattı yüzeyinin yürütme durumu için Dilin durumu sayfasına bakın. Bir pipeline: tek başına durabilir: bir FeatureRecipe yalnızca bunu bildirip hiçbir girdi türü bildirmeyebilir; bu durumda kendine ait hiçbir kaynak yaymaz ve tüm etkisi, adımlarının derlemenin önceden oluşturduğu belgelere yamaladığı ya da onların yanına yaydığı şeylerden ibarettir.

Bir FeatureRecipe bu blokların hiçbirini taşımayabilir de: etkisi taşıdığı uses kenarından ibaret olan salt bağlantı amaçlı bir Feature hiçbir şey oluşturmaz ve FeatureRecipe’i yalnızca çözümlemeyi karşılamak için vardır — her bileşenin bir Recipe’e çözümlenmesi gibi, her feature örneği de bir FeatureRecipe’e çözümlenir. Yukarıdaki bloklar arasında temel Recipe’te karşılığı olmayan tek alan injectMapping’dir; üç girdi türü ve pipeline temel Recipe ile paylaşılır.

Bir FeatureRecipe’in yanına sabitlenen, bir Recipe’in yanına sabitlenenle aynıdır: bir artifacts girdisinin içe aktardığı her dosyanın ve koordinatları eksiksiz yazılmış her uzak source: kaynağının özeti, FeatureRecipe’in kendi dizinindeki bir entity.lock dosyasında tutulur; bu dosyayı aggrega pin yazar ve siz onu yanına işlersiniz. Kilidi bu sabitlemeleri kaydetmeyen bir FeatureRecipe üzerindeki pull işlemi, bu adımı çalıştırması istenmedikçe durur ve o adımı adlandırır. İçe aktarılan bir dosya artık özetiyle eşleşmediğinde ve bir kaynağın özeti Release’in kilit dosyasının kaydettiği özetle uyuşmadığında derleme durur (git ref: ile yazılmış bir kaynak, çözümlendiği commit ile kaydedilir ve karşılaştırılmaz); FeatureRecipe dosyasının kendisine hiçbir zaman yazılmaz. Dosyayı ve her durmanın nasıl yanıtlanacağını aggrega pull açıklar.

Source alanı şablonlama

Bir FeatureRecipe’in source: alanı, bir Recipe’inkiyle aynı koşullarda bir şablonlama yüzeyidir: şablon kaynak çözümlemesi sırasında değerlendirilir ve ürettiği sonuç, derlemenin ardından çözümlediği şeydir. Her iki biçim de Go şablonlarını kabul eder: evrensel dize biçimi ve dize değerli alt alanları şablon olarak değerlendirilirken dize olmayan alt alanları olduğu gibi geçen yapılandırılmış nesne biçimi. Biçim envanteri, şema işleme ve sabitleme yorumu, entities/recipe.md içindeki “Source field templating”, “Source field scheme inventory” ve “How a source: path is anchored” bölümlerinde açıklananlarla aynıdır; bu bölüm yalnızca bir ek için farklı olanları belirtir.

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

Göreli bir sonuç neye göre çözümlenir. Onu bildiren FeatureRecipe belgesini barındıran dizine göre (bileşenin değil, ekin kendi dosyası) ve sonuç, tıpkı bir Recipe’te olduğu gibi bu dizinin içinde kalmalıdır: dizinin dışına çıkan ya da mutlak bir yol olan sonuç, FeatureRecipe ile birlikte taşınmayacak bir dosyayı adlandırır ve derlemeyi durdurur. Bir aktarım şeması taşıyan sonuç ise bir dizinle birleştirilmek yerine getirilir. Bir kayıt defterinden çözümlenen FeatureRecipe, yayımlanmış arşivinin taşıdığı ve içerik önbelleğine yerleştirilen dosyalardan okunur; böylece göreli bir sonuç, bir katalog dizininde FeatureRecipe’in yanında çözümlendiği gibi yayımlanan içeriğin içinde çözümlenir ve aynı sınıra tabidir.

Şablon neleri okuyabilir. Başvuru kümesi, FeatureRecipe’in kendi locals: girdilerinin denetlendiği kümedir; bu küme, bir bileşen yerine bir ekin çözümlenmesinden kaynaklanan iki açıdan bir Recipe’inkinden farklıdır:

  • .attachment_name kullanılabilir ve Feature’ın altında eklendiği örneği adlandırır. Bir Recipe’in kaynak şablonu bunu reddeder, çünkü bir Recipe’in kaynağı bir düğüm için çözümlenir ve ortada bir ek yoktur.
  • .context.instance_id, ekin değil, ekin kendisi için çözümlendiği barındırıcı bileşenin adını verir; .context.rendered_name ise barındırıcının kendi sağlayıcısının barındırıcı için bildirdiği adı taşır: yalnızca o sağlayıcı bir ad bildirdiğinde bulunur, bildirmediğinde derlemeyi durdurur. Bkz. Oluşturulan bir kaynağı adlandırma.

.locals, bu FeatureRecipe’in diğer şablonlarının okuduğu kümeyi taşır: kendi çözümlenmiş bloğu ve onun altında barındırıcı Recipe’inki; böylece ekin bildirdiği bir anahtar, aynı adlı bir barındırıcı anahtarına üstün gelir. Bu kümenin taşımadığı bir anahtara yapılan başvuru, anahtarı yok sayarak oluşturmak yerine derlemeyi durdurur ve anahtarı adlandırır. .provides, .context.inject ve .context.uses, bir Recipe’in kaynak yüzeyinin onları reddettiği aynı kendi kendine yeterlilik gerekçeleriyle reddedilir.

Sınır kapsamlı bir FeatureRecipe bunun yerine sınırı okur. FeatureRecipe’i executionScope: boundary bildiren bir Feature, her bileşen için bir kez değil, sınır için bir kez oluşturulur; bu nedenle kaynak şablonunun okuyabileceği bir barındırıcı bileşen yoktur. Şablon .boundary.* değerini okur (locals: ve provides: bloklarının okuduğu aynı temel öğeler) ve bileşen başına temel öğeler (.context, .workload, .attachment_name, .inject) onun için kullanılamaz.

Boş bir sonuç. Hiçbir şey üretmeyen bir şablon, eki kaynaksız bırakır; bu kaynaksız moddur. Bu, bir Recipe’in kaynağının aldığı yorumun aynısıdır ve source: "" değerini kendinizin yazmasından farklıdır.

.source daha sonra neyi okur. Source, valuesMapping: alanından önce değerlendirilir (bir Recipe’in source’u da kendi eşlemesinden önce değerlendirildiği gibi) ve ürettiği şey, ondan sonra çalışan her şablonda .source olur: valuesMapping:, omits:, workload: ve artifacts: gövdeleri ve pipeline: adımları. Bu nedenle .source okuyan bir valuesMapping:, bu FeatureRecipe’in kendi source’unu okur, asla eklendiği bileşenin source’unu değil; bu FeatureRecipe hiçbir source bildirmediğinde ya da şablonu hiçbir şey üretmediğinde de hiçbir şey okumaz. Sınır kapsamlı bir FeatureRecipe kendi source’unu aynı şekilde okur. injectMapping:, ekin source’u değerlendirilmeden önce çalışır; bu nedenle orada .source, barındıran bileşenin source’udur.

injectMapping alanının münhasırlığı

injectMapping alanı yalnızca FeatureRecipes’e özgüdür; temel Recipe şemasında bilinçli olarak yer almaz. Bu münhasırlık, değişken yakalamayı valuesMapping’den yalıtır: Base Recipe’in valuesMapping’i, FeatureRecipe injectMapping bloklarının ürettiği yeniden yazılmış .context.inject dizelerini farkında olmadan tüketir ve böylece ikisi ayrışık kalır. Mekanizmanın nasıl çalıştığı için aşağıdaki inject-mapping yakalama bölümüne, render öncesi yakalamanın tüm semantiği için ise inject mapping konusunda architecture/10-compilation-pipeline.md belgesine bakın.

Inject-mapping yakalama: injectMapping nasıl çalışır

Bir çağıran, hedefine giden bağlantı dizesinin hedefin değiştirilmemiş .provides.host değerinden farklı biçimlenmesine ihtiyaç duyduğunda — sınır ötesi Kubernetes DNS için bir namespace eklemek, çok bölgeli bir ağ geçidi için bir bölge kodu öne eklemek ya da bir DSN’e SSL modu soneki eklemek gibi — injectMapping bu değişikliği çağıranda, temel Recipe’in valuesMapping alanı inject hattını görmeden önce gerçekleştirir.

injectMapping alanı, renderer’ın inject mapping aşamasında, temel Recipe’in render işlemi çalışmadan önce değerlendirdiği bir Go text/template şablonudur. Şablon, isteğe bağlı mekanizma anahtarları (env, file, arg ya da bileşenin Recipe’inin .context.inject.<name> konumunda okuduğu özel bir mekanizma) içeren bir JSON veya YAML sözlüğü — ya da varsayılan olarak env kabul edilen düz bir eşlem — üretir ve renderer bu katmanı çağıran düğümün .context.inject hattının üzerine derinlemesine birleştirir. injectMapping ile çağıran tarafı yönlendirme, basit dize işlemleri için bir Wasm sandbox’ı çağırmadan inject mapping aşamasında çalışır; Wasm plugin’leri ise pipeline dizisi aracılığıyla yapılan yapısal AST değişikliklerine ayrılmış olarak kalır.

Her değeri toJson üzerinden yazın. Renderer şablonun çıktısını YAML olarak okur; bu nedenle tırnak işaretleri arasına olduğu gibi yerleştirilen bir değer, çift tırnak veya ters eğik çizgi içerdiği anda ya bu çıktıyı bozar ya da değişmiş olarak geri okunur — tipik örnek bir paroladır. toJson değeri, YAML’ın birebir geri okuduğu bir JSON dizesi olarak yazar; böylece değer içerdiği her karakterle birlikte teslim edilir:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

Birkaç parçadan oluşturulan bir değer, aşağıdaki örneklerde olduğu gibi önce birleştirilir ve ardından bir kez toJson üzerinden yazılır.

Okunamayan bir çıktı derlemeyi durdurur. Şablonun çıktısı iki biçimden hiçbiri olarak okunamadığında — tipik neden, içindeki değer tarafından bozulmuş tırnaklı bir skalerdir — anahtarlarından hiçbiri teslim edilemez; bu nedenle derleme, bileşeni hiçbir şey teslim edilmemiş gibi render etmek yerine eki ve FeatureRecipe’i belirterek durur; bkz. fatal-halts.md “An attached Feature’s injectMapping output cannot be read (Eklenmiş bir Feature’ın injectMapping çıktısı okunamıyor)”. Verdiği neden, duyarlı olarak bildirilmiş bir değere bağlı olduğunda gizlenir. Boş olan ya da hiçbir şey teslim etmeyen bir sözlük olarak ayrıştırılan bir çıktı hiçbir şey teslim etmez ve bir hata değildir.

Üst düzey bir anahtar bir mekanizmadır ve all bunlardan biri değildir. Sözlük biçimindeki bir çıktının her üst düzey anahtarı, girdilerinin teslim edildiği mekanizmayı adlandırır: env, file ve arg ya da başka herhangi bir ad; bu sonuncusu o ad altında kendi başına bir mekanizma olarak teslim edilir. .context.inject.all birleştirmeden sonra bu mekanizmalardan oluşturulur ve hiçbir zaman bir çıktıdan birleştirilmez; bu nedenle all: altına yazılan girdiler hiçbir yere ulaşmaz; bunun yerine derleme eki, anahtarı ve FeatureRecipe’i belirterek ve bir çıktının hangi anahtarları taşıyabileceğini söyleyerek durur; bkz. fatal-halts.md “An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Eklenmiş bir Feature’ın injectMapping çıktısı, hiçbir şeyin teslim etmediği bir anahtar altına teslimatlar yazıyor)”. Bu tür girdileri bileşenin onları okuduğu mekanizmanın altına yazın.

Değişiklik kesinlikle çağırana yereldir. FeatureRecipe yalnızca bağlı olduğu düğümün inject hattını değiştirir, hedefin .provides çıktısını asla değiştirmez. Bir hedefin .provides.host değeri küme genelinde potansiyel olarak birçok çağıran tarafından tüketilir; çağıran tarafı injectMapping yalnızca ilgili çağıranın hattına birleştirilir, böylece yönlendirme değişiklikleri onları talep eden kenarla sınırlı kalır.

Bir eşlemenin neyi yeniden yazabileceği. Eşlemeler render edildiğinde her inject: bloğu teslimatını yapmış olur; bu nedenle bir eşlemenin çıktısı her zaman başka bir şeyin önceden yazdığı anahtarların üzerine birleştirilir — ve bir anahtarı kimin yazdığı ne olacağını belirler. Çağıranın kendi inject: bloğunun ya da bağlantılarından birinin inject: bloğunun teslim ettiği bir anahtarı eşleme yeniden yazabilir: bu yakalamadır ve eşlemenin değeri o tek girdinin yerini alır. Eşlemenin kendi eklentisinin kendi inject: bloğu üzerinden teslim ettiği bir anahtar da aynı şekilde onun yeniden yazabileceği bir anahtardır. Farklı bir bağlı Feature’ın — kendi inject: bloğu ya da kendi FeatureRecipe’inin injectMapping alanı üzerinden — önceden teslim ettiği bir anahtar ise öyle değildir: çağıranın hangi değeri okuyacağına en son çalışan eşlemenin karar vermesine izin vermek yerine derleme, her iki eklentiyi de adlandırarak durur. Dolayısıyla iki yönlendirme Feature’ı her biri kendi anahtarını nitelendirebilir, ancak iki Feature aynı anahtarı birlikte teslim edemez — aynı bağlantının anahtarını yeniden yazan iki yönlendirme Feature’ı da buna dahildir, çünkü birincisi yakalamadır ve ikincisi birincinin teslimatıyla karşılaşır; bkz. fatal-halts.md “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (İki bağlı Feature aynı anahtarı teslim ediyor, sonraki kendi FeatureRecipe’inin injectMapping alanı üzerinden)”.

Sıfır bağımlılıkla hedef çıkarımı

Derleyici her hedefin kademeli açıklamalarını çağıranın .context.uses hattına gömdüğü için injectMapping şablonu, Ops’un hedef kimliğini Feature’ın infra alanına sabit kodlamasına gerek kalmadan yönlendirme koordinatlarını çıkarabilir:

  1. Şablon, geliştiricinin istediği değişkeni enjekte eden tam topolojik kenarı bulmak için .context.uses içinde arama yapar.
  2. Hedefin kademeli release_annotations değerlerini (örn. aggrega.ai/namespace) çıkarır.
  3. Tam Nitelikli Alan Adını (FQDN) ya da bağlantı dizesini biçimlendirir.
  4. Geçersiz kılma sözlüğünü üretir.

Derleyici ağ anlamlarından — Kubernetes namespace’leri, bulut bölgeleri, köprü-proxy topolojileri — bağımsız kalır ve yalnızca şablonun ürettiği her şeyle derin birleştirmeyi yürütür. Ardından temel Recipe’in valuesMapping alanı çalıştığında, .context.inject.env içindeki yakalanmış ve yeniden yazılmış dizeleri geliştiricinin özgün dizeleriymiş gibi tüketir.

Uygulamalı örnek: K8s DNS çözümleyici

Standart katalog bunu bir helm FeatureRecipe’i ile birlikte core/k8s-dns-resolver olarak sunar. Ortam değişkeni adlarının bir container içinde benzersiz olması gerektiğinden target_var (örn. API_HOST), çağıran içindeki belirli bir enjeksiyon sözleşmesi için genel olarak benzersiz bir tanımlayıcı işlevi görür. Şablon, .context.uses içindeki açık kenarlar üzerinde döngü kurup target_var değişkenini hangi kenarın sahiplendiğini denetleyerek doğru hedef düğümü bulur ve namespace’ini okur. Tek parametre yeniden yazılacak değişkendir; hedef ve namespace’i keşfedilir, asla sabit kodlanmaz.

Yönlendirme Feature şeması (core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

FeatureRecipe uygulaması:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

Yönlendirmenin ötesindeki kullanım senaryoları

injectMapping en çok sınırlar arası adres çözümlemesi için kullanılır (yukarıdaki K8s DNS çözümleyicisi gibi), ancak bu çağıran tarafı değişikliği, altyapı oluşturulmadan önce geliştirici niyetinin yakalanmasını ve biçimlendirilmesini gerektiren her senaryoya uygulanır. İki ek kalıp, bu kapsamı örnekler.

Dinamik güvenlik biçimlendirmesi (SSL ekleyici). Bir kuruluş tüm harici veritabanı bağlantılarının katı TLS doğrulaması kullanmasını zorunlu kılıyorsa, bir Feature geliştiricinin istediği DB_URL değerini yakalayıp gerekli SSL modunu ekleyebilir; böylece uygulama doğru güvenlik parametreleriyle başlar.

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

Çok bölgeli ağ geçidi ön eklemesi. Genel bir API bileşeni küresel olarak dağıtılmışsa, bölgesel bir yönlendirme Feature’ı, çağıranları için enjekte edilen bağlantı dizelerinin başına ön ek koymak üzere kendi ortam sınırı ek açıklamalarını kendiliğinden arayabilir.

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

injectMapping sınırı. Bu mekanizma yalnızca .context.inject bellek kanalını (Teslim Sözleşmesi) değiştirmekle sınırlıdır. Yeni kapsayıcı ekleyemez, birim bağlayamaz veya temel Recipe’in valuesMapping çıktısını değiştiremez. Oluşturulan AST’de yapısal değişiklik gerektiren her değişiklik (JSON veya YAML dizileri gibi), FeatureRecipe’in WebAssembly eklentileri aracılığıyla yürütülen pipeline dizisine aittir.

pipeline için yama hedefi sınırı. Bir pipeline adımı yalnızca sağlayıcının yapılandırılmış bir ağaç olarak oluşturduğu çıktıyı yamalar. YAML ve JSON biçimli çıktı yapılandırılmıştır — JSON ile yazılmış Terraform .tf.json modülleri dahil — bu nedenle bir adımın JSONPatch’i adreslenen değerleri yerinde düzenler ve diğer her baytı (yorumlar, sıralama, biçimlendirme) olduğu gibi bırakır. Sağlayıcının opak bir gövde olarak ürettiği çıktı, örneğin yerel HCL Terraform yapılandırması, yama hedefi değildir: opak bir gövdeye karşı uygulanan yama, yapısal olarak adresleyemediği metni değiştirmek yerine derlemeyi bir tanılama ile durdurur. Bu nedenle opak çıktıya karşı bir pipeline adımı yazmak, sessiz bir işlemsizlik olarak değil, açık bir durdurma olarak ortaya çıkan bir tasarım hatasıdır.

Dışarıdan alınmış bir Terraform modülünün girdileri yama hedefi değildir ve bu eksikliği belirtmekte yarar vardır. Bunlar, terraform sağlayıcısının sınırın kök yapılandırmasına yazdığı, o bileşenin module bloğunun argümanlarıdır: yerel HCL’dir, dolayısıyla yukarıdaki kurala göre opaktır ve adımın çıktısını yamaladığı düğümün değil, tüm sınırın bir yapıtıdır. Bu nedenle bir pipeline adımının onları adresleyebileceği bir konum yoktur ve kaynaktan alınan bir Terraform modülünün ne aldığını değiştirmek için yapabileceği hiçbir şey yoktur. Bu değerler yazıldıkları yerde biçimlendirilir — temel Recipe’in valuesMapping: alanında.

Koşullu adımlar — when:

Bir pipeline adımı isteğe bağlı bir when: alanı taşıyabilir: derleyicinin pipeline yürütme sırasında, adımın with: gövdesinin kullandığı şablon bağlamı ve değerlendiricinin aynısıyla değerlendirdiği satır içi bir Go şablonu. Adımın çalışıp çalışmayacağına, işlenen sonuç karar verir.

  • Yanlış değerli bir sonuç, adımı doğrudan geçiş olarak atlar: belge kümesi bir sonraki adıma değişmeden akar ve atlanan adım hiçbir katkıda bulunmaz — ne yama, ne yan etki, ne de çalıştığına dair bir kayıt.
  • Boş veya hiç bulunmayan bir when:, adımı her zaman çalıştırır.

when: ve optional: birbirinden bağımsızdır. when: bir adımın çalışıp çalışmayacağına karar verir; optional: ise çalışan bir adımın hatasını yumuşatır. Bir adım ikisini birden bildirebilir — when: girişi denetler ve adım çalışırsa, içindeki bir hatanın nasıl ele alınacağını optional: belirler. İşlenemeyen bir when: şablonu bir yazım kusurudur ve optional: ne olursa olsun derlemeyi durdurur.

İşlenen when: metni, ortak boolean şablon kuralına göre değerlendirilir: true, True ve TRUE dizeleri, sıfırdan farklı her sayı ve boş olmayan diğer her dize doğrudur; false, False ve FALSE dizeleri, boş dize ve sıfır değerli bir sayı yanlıştır.

Kimlik bilgisi FeatureRecipe deseni

Bir FeatureRecipe bir kimlik bilgisi Feature’ını (feature.aggrega.ai/kind: secret etiketli bir Feature) uyguladığında İki Parçalı Plugin İlkesi’ni izleyebilir: bir Fetcher plugin’ini (kasaya özgü CRD’yi üretir) ve bir Injector plugin’ini (secret’ı hedef konteynere bağlar) zincirleyen bir pipeline, yani examples/04-secrets sayfasının açıkladığı biçim. Standart kütüphanedeki kimlik bilgisi FeatureRecipes’i hiçbir pipeline: bildirmez ve secret kaynağını kendileri oluşturur; bkz. examples/05-credential-features.

Bir kimlik bilgisi FeatureRecipe’i, diğer tüm eklemelerinki gibi aynı Resource Generation geçişiyle render edilir ve pipeline: alanı aynı koşullarla yürütülür: derleyici, o geçişte işi olan her eklemeyi tek bir sıralı dizi olarak dolaşır ve her birinin bildirilen pipeline’ını aynı /own ve /host belge kümesi anlamlarıyla çalıştırır. Bir ekleme bu diziye iki nedenden biriyle katılır: FeatureRecipe’i bir girdi türü bildirir ve böylece kendi kaynaklarını üretir ya da bir pipeline: bildirir ve böylece önceden üretilmiş belgeleri yeniden yazar. Bu nedenle bir kimlik bilgisi eklemesi, tıpkı operasyonel bir ekleme gibi, ana bileşenin render edilmiş belgelerine erişebilir (bir secret birimi bağlayarak, bir env başvurusu ekleyerek) ve ikisi arasındaki tek fark, kendi ürettiği dosyaların nereye düştüğüdür.

Bir bileşende, Feature üzerindeki bir hassasiyet bildirimi, bir Component’inkinin Recipe’inkini izlemesi gibi, FeatureRecipe’in valuesMapping: alanını izler. Bir FeatureRecipe valuesMapping: olmadan bir source: üzerinden render edildiğinde, hedefinin aldığı değerler Feature’ın bildirdiği yaprak yollarıyla anahtarlanır; bu nedenle sensitive: true olarak bildirilen bir yaprak, render edilen anahtarını işaretler. FeatureRecipe bir valuesMapping: bildirdiğinde anahtarlar o şablonun kendi icadıdır, hiçbir bildirim onları adlandırmaz ve derleme bu tür her yaprak için eklemeyi, yaprağı ve FeatureRecipe’i adlandıran bir uyarı yazdırır. Bir sınıra eklenen bir Feature hiç uyarı üretmez: .values alanı her zaman boştur, dolayısıyla bildirilen hiçbir yaprağın işaretlenecek bir değeri yoktur; bkz. A declared-sensitive value reaches the target through a values mapping (Hassas olarak bildirilmiş bir değer hedefe bir değer eşlemesi aracılığıyla ulaşıyor).

provides: bloğu — tüketiciye yayımlama

Bir FeatureRecipe’in provides: bloğu, onun yayımlanan çıktısıdır: eklentinin kendi kapsamına (.values, .infra, FeatureRecipe’in tamamen çözümlenmiş .locals değerleri ve ana düğümün .context.instance_id ile .context.rendered_name değerleri) karşı değerlendirilen, dize değerli bir Go şablonları eşlemesidir. Yereller önce çözümlenir; bu nedenle bir provides: girdisi onları okur ve çözümlenmiş değerler alır; locals: bloğunun bildirmediği bir anahtarı adlandırmak derlemeyi durdurur. Bir eklenti, ürettiği şeyi — yayımlanan bir kaynağın adını, oluşturulan bir veri anahtarını, bir bulut kimliğini — tüketicisine bu yolla bildirir; tüketicinin bu kimliği aynı girdilerden yeniden türetmesi gerekmez.

Tüketici bunu .features.<instance-name>.provides.<key> konumunda (kimlik bilgisi eklentisi için .features.<slot>.provides.<key> konumunda) okur; bu, bir uses kenarı için .context.uses.<alias>.provides yapısını yansıtır. Eklenti, tüketicinin bağlantılarından birinde yazıldığında tüketici aynı eşlemeyi o bağlantının altında, .context.uses.<alias>.features.<slot>.provides.<key> konumunda okur ve eklenti onun .features değerleri arasında yer almaz (bkz. Bir bağlantının eklentileri). Eklentinin kendi inject: bloğu, from: başvurularını aynı eşlemeye karşı çözümler; böylece yazar iki kanaldan birini seçebilir: şablonda okuma için provides, bir ortam değişkenine, dosyaya veya argümana teslim için inject.

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Bu FeatureRecipe’in implements ile uyguladığı Feature bir schema.provides sözleşmesi bildirdiğinde, sözleşme FeatureRecipe’e karşı uygulanır: Feature’ın bildirdiği her anahtar FeatureRecipe’in provides: bloğunda yer almalıdır; aksi halde derleme eksik anahtarı adlandırarak durur. Fazladan yayımlanan anahtarlara izin verilir — sözleşme bir üst sınır değil, bir alt sınırdır. Değerler hiçbir zaman incelenmez; bunlar, çalışma zamanının çözümlediği opak ve deterministik işaretçilerdir.

Çözümleme, her eklenti için tüketici işlenmeden önce bir kez gerçekleşir ve aynı çözümlenmiş eşleme tüketicinin okumasını, sözleşme denetimini ve eklentinin kendi Resource Generation aşamasını besler — böylece tüketicinin okuduğu ile eklentinin ürettiği birbiriyle çelişemez.

Provider ve implements

spec.capability zorunludur ve Wasm işleme eklentisi FeatureRecipe’in çıktısını render eden sağlayıcıyı adlandırır (helm, helm-chart, compose vb.); bir Recipe’in spec.capability alanıyla aynı koşullar geçerlidir (bkz. entities/recipe.md): bir sürüm sabitlemesi, çıktıyı o eklentinin hangi sürümünün render edeceğini seçer ve FeatureRecipe’in adının parçası değildir — bir Manifest, capability: "compose:1.2.3" bildiren bir FeatureRecipe’i compose/<name>:<version> olarak eşler ve sabitlemeyi ada yazan bir eşleme değeri, herhangi bir arama yapılmadan önce hatalı biçimlendirilmiş bir recipe başvurusu (E0095) olarak reddedilir. implements alanı FeatureRecipe’i kendi Feature arayüzüne bağlar ve tam, ana sürümle uyumlu aralık veya sürümsüz eşleştirmeyi destekler; implements sürüm eşleştirme semantiği için vocabulary/inheritance-and-interface sayfasına bakın.

Yürütme kapsamı — spec.executionScope

İsteğe bağlı spec.executionScope enum’u, Resource Generation için dağıtım modelini seçer. İki değer kabul edilir; alan atlandığında varsayılan değer component’tir.

  • component (varsayılan). FeatureRecipe’in Resource Generation adımı, bağlı her bileşen örneği için bir kez çalışır. Her çağrı, .context.* köküne sahip bileşene özgü bir şablon bağlamı alır: .context.instance_id, .context.inject, .context.uses, .context.annotations vb. valuesMapping:, workload: ve artifacts: alanları ayrıca .context.used_by değerini de okur: uses girdileri ana bileşeni gösteren bileşenler — her biri kimliği, soketi, yayımladıkları ve yerleştirildiği ad alanı ve sınır ile birlikte — ki ana bileşenin kendi oluşturduğu hiçbir şablon bunları göremez.
  • boundary. Resource Generation, sınırın alt ağacındaki kaç bileşenin özelliği tükettiğinden bağımsız olarak bağlı her sınır için bir kez çalışır. Her çağrı, .context.* yerine .boundary.* köküne sahip sınır kapsamlı bir şablon bağlamı alır.

Yukarıda açıklanan injectMapping araya girmesi, executionScope’tan bağımsız olarak her zaman tüketici başınadır. Özelliği kullanan her bileşen, .context.inject için yine kendi çağıran tarafı yeniden yazımını alır. Yalnızca Resource Generation adımı (source/valuesMapping ve pipeline dizisi) sınır kapsamında tekilleştirilir.

Bu nedenle sınır kapsamlı bir FeatureRecipe’in şablonları iki kapsamda çalışır. injectMapping alanı, ekin ulaştığı her bileşen için bir kez, o bileşenin bağlamına karşı çalışır; bu bağlam, bileşen kapsamlı bir FeatureRecipe’in injectMapping alanının okuduğu bağlamdır: .context.*, .attachment_name, .features ve ekin kendi .values, .infra ve .locals değerleri. Buradaki .infra, sınır ekinin infra: bloğudur; .locals ise sınır için bir kez değerlendirilen bloktur. Yazdığı diğer her şablon — aralarında locals:, provides:, source:, valuesMapping: ve artifacts: ile işlem hattı adımlarının with: ve when: alanları da vardır — aşağıdaki sınır kapsamlı bağlama karşı, sınır için bir kez çalışır. Her şablon çalıştığı kapsama göre denetlenir: .context.instance_id okuyan bir valuesMapping: derlemeyi durdurur, onu okuyan bir injectMapping ise o bileşenin kimliğini render eder. .boundary hiçbir bileşenin bağlamında ayarlanmaz; bu nedenle FeatureRecipe’in executionScope değeri ne olursa olsun, onu okuyan bir injectMapping başvuruyu adlandırarak derlemeyi durdurur.

Sınır kapsamlı şablon bağlamı

executionScope: boundary olduğunda, FeatureRecipe’in injectMapping dışındaki şablonları, özelliğin bağlı olduğu sınırın .boundary.* görünümüne göre değerlendirilir. Görünüm şunları sunar:

  • .boundary.path — özelliğin bağlı olduğu Release sınırının yolu: en dıştan içe doğru sınır adları, / ile birleştirilmiş hâlde (bridge, bridge/frontend). Sınırı adlandırır, çıktısının yazıldığı dizini değil; dizini directory: belirler (.context.instance_id yerine geçer).
  • .boundary.assembly_path — derlemenin çıktı dizinine göreli olarak, ekin kendi çıktısının birleştirildiği dizin: sınırın değerlendirilmiş directory: ve subDirectory: değerleri, yani derlemenin o çıktıyı yönlendirdiği dizin (bridge/compose). Bir bağlantı uç noktasının source_assembly_path veya target_assembly_path değerine, tam olarak o uç nokta aynı birleştirilmiş dosyaya render edildiğinde eşittir; bu nedenle bir FeatureRecipe, kendi dosyası içindeki bir bağlantıyı başka bir dosyadakinden ayırt etmek için bunları karşılaştırır.
  • .boundary.boundary_name — sınırın Release içinde yazılan adı.
  • .boundary.components — sınırın alt ağacındaki her bileşeni içeren, örnek kimliğine göre anahtarlanmış bir eşlem (instance_id, component, resolved_version, boundary_path).
  • .boundary.internal_uses_edges — iki uç noktası da bu sınırın alt ağacında olan uses: kenarları (compose-bridge kalıbı, kenar başına proxy yapılandırmasını türetmek için bunları sıralar ve iki uç noktası da kendi compose dosyasına birleştirilen ve bu dosyanın farklı ağlarına yerleştirilen kenarları tutar). Her kenar, uç noktalarının çözümlenmiş provides değerlerini, enjekte edilen ortam değişkenlerini ve her uç noktanın yerleşimini taşır: source_namespace ve target_namespace, o uç noktaya uygulanan aggrega.ai/namespace ek açıklaması — varsa kendi Release girdisinin ayarı, yoksa sınırınınki; source_boundary_path ve target_boundary_path, onu barındıran Release sınırının yolu; ve source_assembly_path ile target_assembly_path, derlemenin çıktı dizini altında sağlayıcısının onu birleştirdiği, sınırının değerlendirilmiş directory: ve subDirectory: değerlerinden oluşan dizin (bridge/compose). Birleştirme yolu aynı olan iki uç nokta tek bir birleştirilmiş dosyaya render edilir ve hiçbir ad alanı uygulanmadığında compose sağlayıcısı birleştirme yolunu uç noktanın ağı olarak okur.
  • .boundary.outgoing_cross_boundary_uses_edges — kaynağı alt ağacın içinde, hedefi dışında olan kenarlar.
  • .boundary.incoming_cross_boundary_uses_edges — hedefi alt ağacın içinde, kaynağı dışında olan kenarlar (ingress tarzı toplayıcılar tarafından kullanılır).
  • .boundary.cross_boundary_uses_edges — FeatureRecipe sınırlar arası görünümün tamamını istediğinde, gelen ve giden sınırlar arası kenarların birleşimi.
  • .boundary.labels — yazım sırası korunarak alt ağaç etiketlerinin birleşimi.
  • .boundary.annotations — sınırın kendi ek açıklamaları ile kademeli olarak gelenler.
  • .boundary.feature_attachments — bu sınıra bağlı her özellik (böylece sınır kapsamlı bir FR gerekirse kardeşlerini inceleyebilir).

Sınır kapsamlı bir FR’deki .infra sütunu, sınıra bağlı özelliğin infra: bloğuna çözümlenir (o sınır bağlantısı için Release tarafında yazılan fiziksel boyutlandırma). Sınır kapsamlı FR’ler için .values her zaman boştur: Release şemasının sütun ayrımı kuralı, Release düzeyindeki Feature bağlantılarında values: kullanımını yasaklar, bu nedenle bir sınıra bağlı bir özellik yansıtılacak değer taşımaz. Parametre biçimli veriye ihtiyaç duyan sınır kapsamlı FR’ler bunu .infra (operatörün sınır özelliği yapılandırması için yazım yüzeyi) ya da .boundary.annotations (sınırda veya herhangi bir üst öğede yazılan, kademeli çözümlenebilir dize değerleri) üzerinden tüketmelidir; .parameters görünümün parçası değildir ve onu okuyan bir şablon, görünümün tanımladığı kökleri adlandırarak durur. .locals FR’nin kendi locals bloğu olmaya devam eder. .steps ve .metadata değişmeden kalır.

Sınır kapsamlı şablon alanı izin listesi

Sınır kapsamlı FR’ler, injectMapping dışındaki her şablonda yalnızca sınır kapsamlı görünümde bulunan alanlara başvurabilir. executionScope: boundary olduğunda yalnızca bileşene özgü bir alana (ör. .context.instance_id, .context.inject, .context.uses) başvuran böyle bir şablon yazmak, FeatureRecipe’in ayrıştırma sırasında; FR’yi, sorunlu alanı ve sınır kapsamlı görünümün tanımladığı alanları adlandıran bir hatayla doğrulamadan geçememesine yol açar. Ayna kural diğer yönde de geçerlidir: .boundary.* alanlarına başvuran bileşen kapsamlı bir FR aynı doğrulayıcıdan geçemez. injectMapping her iki kapsamda da çalıştığı bileşenin bağlamına göre denetlenir; bu nedenle .context.* okuyabilir ve içindeki bir .boundary başvurusu, başvuruyu ve o bağlamın tanımladığı kökleri adlandırarak durur.

Doğrulayıcı, yol şablonu değişken izin listesinin kullandığı aynı şablon AST gezinmesini, kapsam başına farklı bir başvuru kümesiyle çalıştırır.

Tekilleştirme ve Resource Generation çıktısı

executionScope: boundary için derleyici, Resource Generation’ı (boundary_path, FR-instance) demetine göre tekilleştirir. Aynı sınır alt ağacında, sınıra bağlı aynı özelliği tüketen iki bileşen iki değil tek bir FR çağrısını tetikler. Aynı özelliğin sınırlar arası bağlantıları her sınır için bağımsız olarak çalışır.

Sınır kapsamlı bir FR, her (boundary_path, FR-instance) demeti için bir ara olmayan dosya kümesi üretir ve bunların nerede duracağı, sağlayıcının sınırının çıktısını nasıl birleştirdiğine bağlıdır. Bileşen kapsamlı bir bağlantı bileşenini de taşırken, burada koordinat yalnızca örnek adıdır: sınır kapsamlı bir özellik herhangi bir bileşene değil sınıra bağlıdır, bu nedenle kapsayan sınır dizini bir bileşen bölümünün söyleyeceği her şeyi zaten söyler ve adlandırılacak bir bileşen yoktur.

Her belgeyi doğrudan sınır dizinine yazan bir sağlayıcı, hedefinin yalnızca doğrudan bir dizinde duran dosyaları okuduğunu bildirir. Bu nedenle bir bağlantının içinde duracağı kapsayan bir dizin yoktur ve örnek adı bunun yerine bir dosya adı önekine dönüşür: sınırın kendi dosyalarının yanında <boundary_directory>/<fr-provider>/<feature-instance>--<file>. Örnek adı kodlanır, çünkü bir dosya adının başvurabileceği bir ayırıcısı yoktur; ad, dosyanın kendi adıyla hiçbir kodlanmış koordinatın içeremeyeceği iki karakterlik bir sınırda birleşir — böylece aynı dosya adını üreten iki bağlantı yine iki ayrı dosyaya ulaşır.

Sınırının çıktısını kapsayan bir yapıda birleştiren bir sağlayıcı — katkıda bulunan başına bir chart barındıran tek bir chart, katkıda bulunan başına bir modül barındıran tek bir kök yapılandırma — her katkıda bulunanı kendine ait bir alt dizine yerleştirir ve bir sınır bağlantısı da diğerleri gibi bir katkıda bulunandır. Bu durumda çıktısı <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/ konumunda durur; burada <contributors-directory>, o hedefin alt birimlerinin bulunduğu yere verdiği addır. Alt dizin, bağlantının örnek adını, yani onu sınırın features: bloğunda yazdığınız adı taşır; böylece bir derlemenin ürettiği dizini yazdıklarınız içinde bulabilirsiniz.

Ara çıktı, FR’nin değerlendirilmiş yolunda, FR’nin kendi spec.capability’si altında sınırın (yol, sağlayıcı) başına birleştiricisine akar — core/compose-bridge Feature’ı, bir köprü hizmetini aynı birleştirme yolundaki bileşen başına compose katkıda bulunanlarının yanına birleştirmek için bu mekanizmayı kullanır. Böyle bir çıktı yalnızca orada sınırın bileşenlerinden birleştirilen dosyanın parçası olarak yazılır; bu nedenle bileşenlerin hiçbiri o yola düşmediğinde — örneğin her bileşen kendi subDirectory: değeriyle başka bir yere gönderildiğinde — derleme, çıktıyı hiçbir yere yazmak yerine sınırı, Feature’ı, çıktısının yönlendirildiği yolu ve sağlayıcıyı adlandırarak durur (bkz. fatal-halts.md içindeki “A boundary-level Feature’s output reaches no assembled file (Sınır düzeyindeki bir Feature’ın çıktısı hiçbir birleştirilmiş dosyaya ulaşmıyor)”).

Kademeli zincirden haberdar provides: çözümlemesi

Boundary kapsamlı FR’ler her (boundary_path, FR-instance) demeti için bir kez değerlendirilen bir provides: kümesi üretir. FR’nin provides: şablonu boundary kapsamlı şablon bağlamıyla değerlendirilir (bu nedenle .boundary.components, .boundary.path, .infra alanlarına başvurabilir, ancak tüketiciye özgü alanlara ve .values alanına başvuramaz). Sağlanan değerler tüketicilere göre sabittir: boundary’nin alt ağacındaki her tüketici aynı sağlanan değerleri görür.

Boundary kapsamlı FR provides değerlerinin tüketici tarafında çözümlenmesi her yerde o tek değerlendirmeyi okur. Attachment’ın ulaştığı her bileşen bunu .features.<instance-name>.provides.<key> konumunda okur — hem kendi Recipe’inin şablonlarında hem de o bileşenin bağlamında çalışan FeatureRecipe’in kendi injectMapping alanında. Attachment’ın taşıdığı bir uses kenarı üzerinden .context.uses.<feature-alias>.provides.<provided-name> konumunda okuyan tüketici bir Component aynı değerleri alır: derleyici bunu, tüketicinin bulunduğu boundary için boundary kapsamlı FeatureRecipe’in provides: değerine çözümler; tüketicinin uses kenarından (attachment başına feature örneği kimliğini taşır) boundary kapsamlı FR’nin provides: değerine doğru ilerler. Bir ön geçiş bu provides değerlerini tüketici birleştirmesinden önce değerlendirir, böylece tüketicinin hattı kurulduğunda değerler hazır olur.

Tüketici başına bir etki, injectMapping tarafından okunan provides: içindeki bir tablodur. Her tüketici için bir şeyi değiştirmesi gereken sınır kapsamlı bir FeatureRecipe, provides: içinde sınırın bağlantılarından tüketiciye göre anahtarlanmış bir tabloyu bir kez hesaplar; injectMapping alanı ise geçerli bileşenin satırlarını — .context.instance_id ile anahtarlanmış (index .features .attachment_name).provides — okur ve bunları her eşlemenin uyduğu kural altında tüketicinin kendi hattı üzerinden teslim eder (bkz. Bir eşleme neyi yeniden yazabilir). Derleyici FeatureRecipe’in yazdığı tabloyu iletir ve içindeki hiçbir şeyi okumaz.

Compose-bridge kalıbı

Compose-bridge FeatureRecipe’i, sınır kapsamlı FR’nin standart kalıbıdır ve yukarıdaki mekanizmalarla yazılmış katalog içeriğidir: ne derleyici ne de compose sağlayıcısı köprüye ait herhangi bir mantık barındırır; bu nedenle bir katalog core/compose-bridge Feature’ını farklı biçimde gerçekleştirebilir. Bir core/compose-bridge özelliği, ortak directory: değerine sahip iki alt sınır (ör. services-net ve data-net) içeren bir üst sınıra eklenir; her alt sınır kendi aggrega.ai/namespace ek açıklamasını (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) taşır, böylece her biri kendine ait bir ağa düşer; ek açıklamalar olmadan ikisi de compose dosyalarının yoluna göre adlandırılan tek ağı paylaşır ve birbirlerine köprü olmadan ulaşır. executionScope: boundary ayarı, FR’yi her üst sınır eki için bir kez çalıştırır.

provides: alanı köprü tablosunu bir kez hesaplar. .boundary.internal_uses_edges içinden, iki uç noktası da kendi compose dosyasına birleştirilen — source_assembly_path ve target_assembly_path değerlerinin ikisi de .boundary.assembly_path değerine eşit olan — ve bu dosyanın farklı ağlarında bulunan kenarları tutar; bir uç noktanın ağı onun aggrega.ai/namespace değeri, yoksa birleştirme yoludur. İki compose dosyası arasındaki bir kenar köprülenmez ve tüketicisi hedefin kendi adını korur. Köprülenen her kenar bir dinleme portu — hedefin kendi portu ya da daha önceki bir kenar zaten onu dinliyorsa, ekin portBase değerine (varsayılan 10000) eşit veya ondan büyük ilk boş port — ve bir upstream alır: hedefin yayımladığı host (ekin providesField alanının adlandırdığı provides alanı, varsayılan host) ve onun port değeri; upstream kenardan türetilir, asla elle yazılmaz. Aynı tablodan her tüketicinin yeniden yazımını hesaplar: kenarın host alanından teslim ettiği bir değişken aggrega-gw:<listen port> olur; aynı kenar port alanından da bir değişken teslim ediyorsa host değişkeni aggrega-gw olur ve bu port değişkeni dinleme portu olur.

injectMapping alanı her tüketicinin satırlarını teslim eder. Her tüketicinin bağlamında çalışarak tablonun o tüketiciye ait satırlarını .features.<attachment>.provides konumunda okur ve bunları tüketicinin kendi bağlantısının teslim ettiği değerlerin (ör. DB_HOST) üzerine teslim eder; bu araya girmedir. Satırı olmayan bir tüketici hiçbir şey almaz. Tüketiciye eklenmiş başka bir Feature bu anahtarı — inject: bloğu ya da injectMapping alanı yoluyla — teslim ettiyse, derleme bu teslimi değiştirmek yerine her iki Features’ı adlandırarak durur (bkz. fatal-halts.md içindeki “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Eklenmiş iki Features tek bir anahtarı teslim ediyor, sonraki kendi FeatureRecipe’inin injectMapping alanı üzerinden)”). Ağ geçidinin listen değeri ile tüketicinin yeniden yazımı tek bir tablodan okunur; böylece portBase ile yeniden atanan çakışmalar dahil, yapısı gereği her kenarda uyuşur.

valuesMapping alanı ağ geçidini yazar. FeatureRecipe’in kendi compose parçası aggrega-gw hizmetini bildirir. Köprülenen bir şey olduğunda, valuesMapping köprülenen her kenar için bir nginx stream server bloğu ekler (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;; her upstream’in başlangıçta bir kez değil bağlantı anında çözümlenmesi için bir resolver yönergesi altında; bu değişkenlerdeki $, Docker Compose’un $ enterpolasyonu nginx için düz bir $ bıraksın diye $$ olarak yazılır) ve bunu bağlanmış bir compose config olarak teslim eder: satır içi content: içeren, aggrega-gw tarafından başvurulan ve /etc/nginx/nginx.conf konumuna bağlanan üst düzey bir configs: girdisi (böylece nginx bunu yazılmış bir command: olmadan yükler). Satır içi configs.content, Docker Compose ≥ 2.23.1 gerektirir. Ayrıca köprülenen her uç noktayı ağ geçidinin x-aggrega-networks-of alanı altında adlandırır; compose sağlayıcısı bunu o uç noktaların yerleştirildiği ağlara çözümler, böylece ağ geçidi köprülenen kenarlarının kapsadığı her ağa (tüketicinin ağı ve hedefin ağı) katılır: çalışma zamanında tüketici aggrega-gw:<port> adresine erişebilir ve ağ geçidi hedefe proxy_pass yapabilir. Hiçbir şey köprülenmediğinde parçanın bildirdiği ağ geçidi yine de render edilir, ancak boşta kalır: yapılandırma yok, ek ağ yok ve yeniden yazım yok.

Yol ve sağlayıcı başına compose birleştiricisi, ağ geçidini aynı değerlendirilmiş yoldaki bileşen başına katkıcılarla birleştirir: her bileşeni ve köprü ağ geçidini içeren tek bir docker-compose.yaml. Sınırın bileşenlerinin hiçbiri ağ geçidinin dosyasına birleştirilmediğinde derleme, ağ geçidini hiçbir yere yazmak yerine durur. Upstream, derleme zamanında belirlenen deterministik bir compose hizmeti işaretçisidir; onu compose’un çalışma zamanı DNS’i çözümler (derleme zamanında çalışma zamanı çözümlemesi yapılmaz).

Çağıranlardan sonra render etme — spec.readsCallerRenderFacts

İsteğe bağlı spec.readsCallerRenderFacts (boolean, varsayılan false), bu FeatureRecipe’in şablonlarının, ana bileşenine bağlanan bileşenlerin render ettiklerini okuduğunu bildirir: bu çağıranların her birinin sağlayıcılarının, ürettikleri çıktı hakkında bildirdiği render olguları. Bir sağlayıcının neyi ve hangi adlar altında bildirdiği, o sağlayıcının kendi sözleşmesidir; Reporting facts about what a guest emitted bir sağlayıcının bildirebileceği olguları açıklar.

Böyle bir ekleme ne zaman render edilir. Derleme, bileşenlerini sabit bir sırayla tek tek render eder ve bir ekleme normalde eklendiği bileşenden hemen sonra render edilir. Ana bileşene bağlanan ve bu sırada daha sonra gelen bir bileşen o noktada henüz render edilmemiştir; dolayısıyla ürettiği ve okunabilecek hiçbir şey yoktur. FeatureRecipe’i readsCallerRenderFacts: true ayarlayan bir ekleme ise derlemedeki her bileşen render edildikten sonra, ne bu anahtarı ne de readsTargetRenderFacts anahtarını ayarlayan her ekleme ile birlikte render edilir; böylece ekleme değerlendirilmeden önce her çağıranın render’ı tamamlanmış olur. Çıktısı, normalde ineceği yere ve aynı adlar altında iner; anahtar, eklemenin neyi render ettiğini değil, ne zaman render edildiğini değiştirir. Sonraki render’dan bir sıralama doğar: FeatureRecipe, ana bileşeninin belgelerini yeniden yazan bir pipeline taşıdığında ve ana bileşenin sağlayıcısı ayrık belgeler yazdığında, bu adımlar ana bileşenin diğer eklemelerinin pipeline’larından sonra, ekleme sıralarına göre değil, çalışır.

Ne okur. Anahtar ayarlandığında .context.used_by öğesinin her girdisi .render_facts taşır: çağıranın olgu adına göre anahtarlanmış render olguları. Her render olgusu bir listedir, bu nedenle bir şablon onun üzerinde her zaman range ile dolaşır — tek bir girdi tutsa bile. Girdileri, çağıranın kendi render’ından ve çağırana eklenmiş Features’ın render’larından gelebilir: bir adın her birinden aldığı listeler tek bir listede birleştirilir; önce çağıranın kendi sağlayıcı çağrıları, ardından render edildikleri sırayla her bir Feature’ı gelir. Çağıranın, anahtarı kendisi de ayarlayan bir Feature’ı da her bileşenden sonra render edilir, bu nedenle onun bildirdikleri bunların arasında yer almaz. Sağlayıcıları hiçbir şey bildirmeyen bir çağıran boş bir .render_facts taşır; bu yüzden kimsenin bildirmediği bir ad hiçbir şey olarak okunur:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Hangi olgu adlarının var olduğu ve her girdinin ne tuttuğu, çağıranın sağlayıcısının belgelenmiş sözleşmesidir — örneğin helm sağlayıcısınınkiler, render ettiği pod’ların etiketlerini adlandıran render olgularıdır. Çağıranların olguları, FeatureRecipe’in valuesMapping:, workload: ve artifacts: alanlarının okuduğu bağlantılar üzerindedir; bir pipeline: adımının with: ve when: alanları ana bileşene bağlanan bileşenleri hiç görmez, bu nedenle bir adım yalnızca ana bileşenin kendi olgularını okur. Bir bileşene eklenen her FeatureRecipe — anahtarı ayarlasa da ayarlamasa da — bileşenin kendi olgularını aynı biçimde .context.render_facts konumunda okur; şablon bağlamı her ikisini de açıklar.

Bir şablon olguları okuduğunda bunu her zaman bildirin. Anahtarı ayarlamayan bir FeatureRecipe’te satır içi yazılmış ve .context.used_by altındaki render_facts öğesini okuyan bir şablon — valuesMapping:, workload: veya bir artifacts: girdisi — herhangi bir şey render edilmeden önce derlemeyi durdurur ve başvuruyu ile yazıldığı alanı adlandırır (bkz. fatal-halts.md içindeki “A template reads its callers’ render facts without declaring it (Bir şablon, bildirmeden çağıranlarının render olgularını okuyor)”). Denetim şablonu yazıldığı haliyle okur; bu nedenle şablon çalışırken oluşturulan bir başvuruyu veya bir dosyadan ya da kütüphaneden içe aktarılan içerikte yazılmış bir başvuruyu görmez — ve .context.used_by yanında başka bir listeden render_facts adlı bir alanı okuyan ya da yanında {{ with .context }} içinde ana bileşenin kendi olgularını .render_facts olarak okuyan bir şablon, çağıranların olgularını okuyor sayılır; ana bileşenin kendi olgularını tam olarak .context.render_facts şeklinde yazın. Eklemenin ne zaman render edileceğine denetim değil anahtar karar verir; bu nedenle şablonları çağıranlarının render olgularını — onlara nasıl ulaşırsa ulaşsın — okuyan her FeatureRecipe’te anahtarı ayarlayın; ayarlamanın tek bedeli sonraki render’dır.

Bir pipeline adımı yalnızca ana bileşeninin kendi olgularını okur. Bir adım ana bileşenin kendi belgelerini yeniden yazabilir ve bir bileşenin kendi çıktısı ona kim bağlanırsa bağlansın aynı kalır; bu nedenle bir adımın with: ve when: alanları ana bileşene bağlanan bileşenleri hiçbir zaman görmez — FeatureRecipe anahtarı ayarlasa da ayarlamasa da; anahtar eklemenin ne zaman render edileceğine karar verir, bir adımın ne gördüğüne dair hiçbir şeye değil. Bu nedenle bir adımın satır içi yazılmış ve .context.used_by altındaki render_facts öğesini okuyan with: veya when: alanı, boş bir değer render etmek yerine, herhangi bir şey render edilmeden önce E0326 kısa koduyla derlemeyi durdurur ve başvuruyu ile adımın alanını adlandırır. Bir adımda ana bileşenin kendi olgularını tam olarak yazılmış .context.render_facts konumunda, çağıranların olgularını ise FeatureRecipe’in valuesMapping:, workload: veya artifacts: alanlarında okuyun. Bu denetim şablonu yazıldığı haliyle, yukarıdakiyle aynı sınırlarla okur.

Kapsam. Anahtar, bileşen başına bir kez render edilen bir FeatureRecipe’e uygulanır — varsayılan olan executionScope: component. executionScope: boundary bildiren bir FeatureRecipe, anahtarı ayarlasa da ayarlamasa da her zamanki yerinde render edilir ve kaynaklarını üreten şablonlar .context yerine .boundary okur.

Hedeflerden sonra render etme — spec.readsTargetRenderFacts

İsteğe bağlı spec.readsTargetRenderFacts (boolean, varsayılan false), bu FeatureRecipe’in şablonlarının, host’unun bağlandığı bileşenlerin render ettiklerini okuduğunu bildirir: bu hedeflerin her birinin provider’larının, ürettikleri çıktı hakkında raporladığı render olguları. Bir bağlantının diğer ucunu readsCallerRenderFacts anahtarına göre okur — uses girdileri host’u gösteren bileşenleri değil, host’un uses girdilerinin gösterdiği bileşenleri — ve olguların kendisiyle ilgili her şey aynı şekilde okunur.

Anahtarlardan herhangi biri, eklemenin her bileşenden sonra render edilmesini sağlar. FeatureRecipe’i readsCallerRenderFacts: true, readsTargetRenderFacts: true ya da her ikisini ayarlayan bir ekleme, yukarıdaki bölümde açıklandığı gibi, derlemedeki her bileşen render edildikten sonra render edilir — böyle tek bir sonraki render vardır ve bunun eklemenin çıktısının nereye düştüğüne ve pipeline adımlarının sırasına etkisi, eklemeyi oraya hangi anahtar taşımış olursa olsun aynıdır. İki anahtar yalnızca eklemenin bağlamında hangi bağlantıların olgu taşıdığı konusunda farklılaşır: derleme sırasında host’tan sonra gelen bir hedef o zamana kadar render edilmiştir, dolayısıyla ürettiği şey okunmak üzere oradadır.

Ne okur. Anahtar ayarlandığında, .context.uses öğesinin her girdisi .render_facts taşır: hedefin olgu adına göre anahtarlanmış render olguları, bir çağıranın girdisinin taşıdığı biçimde. Her render olgusu bir listedir, dolayısıyla bir şablon her zaman onun üzerinde dolaşır. Girdileri hedefin kendi render’ından ve hedefe eklenmiş Features’ın render’larından gelebilir; önce hedefin kendi provider çağrıları, ardından Features’ının her biri render edildikleri sırayla gelir; hedefin kendisi de her bileşenden sonra render edilen bir Feature’ı bunların arasında yer almaz. Provider’ları hiçbir şey raporlamayan bir hedef boş bir .render_facts taşır. Bir şablon tek bir bağlantının olgularını takma adının altında, .context.uses.<alias>.render_facts.<name> olarak, ya da her bağlantınınkini sırayla okur:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Anahtarı ayarlamayan bir FeatureRecipe, başka ne ayarlarsa ayarlasın, hiçbir bağlantıda .render_facts görmez. Hangi olgu adlarının var olduğu, her hedefin provider’ının belgelenmiş sözleşmesidir — helm provider’ınınkiler onun render olgularıdır; bunlar render ettiği pod’ların etiketlerini, controller seçicilerini ve container portlarını adlandırır; bu da bir egress politikasının, host’unun erişebileceği pod’ları tam olarak seçmek için ihtiyaç duyduğu şeydir.

Bir şablon olguları her okuduğunda anahtarı bildirin. Anahtarı ayarlamayan bir FeatureRecipe içinde satır içi yazılmış — valuesMapping:, workload: ya da bir artifacts: girdisi — ve .context.uses altında render_facts okuyan bir şablon, hiçbir şey render edilmeden önce derlemeyi E0347 kısa koduyla, başvuruyu ve yazıldığı alanı adlandırarak durdurur (bkz. fatal-halts.md içindeki “A template reads its targets’ render facts without declaring it (Bir şablon, hedeflerinin render olgularını bildirmeden okuyor)”). readsCallerRenderFacts ayarlamak bunu gidermez. Denetim şablonu yazıldığı haliyle okur ve çağıranların denetiminin sınırlarına sahiptir: şablon çalışırken oluşturulan bir başvuruyu ya da bir dosyadan veya bir kütüphaneden içe aktarılan içerikte yazılmış bir başvuruyu görmez — ve .context.uses öğesini herhangi bir şekilde okuyan ve ayrıca başka bir değerden, {{ range .context.used_by }} içindeki bir çağıran girdisi dahil, render_facts adlı bir alan okuyan bir şablon, hedeflerinin olgularını okuyor kabul edilir. Her iki ucun olgularını okuyan bir şablon her iki anahtarı da ayarlar.

Bir pipeline adımı yalnızca host’unun kendi olgularını okur. Bir adımın with: ve when: alanları, host’un kurduğu bağlantıları host’un kendi Recipe’inin okuduğu gibi okur ve hedeflerinin render olgularını asla okumaz — FeatureRecipe anahtarı ayarlasa da ayarlamasa da. Bir adım host bileşenin kendi belgelerini yeniden yazabilir ve host’un kendi render’ı hedeflerinin ürettiklerini değil, yayımladıklarını okur. Bu nedenle .context.uses altında render_facts okuyan, satır içi yazılmış bir adım with: ya da when: alanı, boş bir değer render etmek yerine, hiçbir şey render edilmeden önce derlemeyi E0348 kısa koduyla, başvuruyu ve adımın alanını adlandırarak durdurur. Hedeflerin olgularını FeatureRecipe’in valuesMapping:, workload: ya da artifacts: alanlarında okuyun.

Kapsam. Çağıranların anahtarında olduğu gibi: bileşen başına bir kez render edilen bir FeatureRecipe’e uygulanır. executionScope: boundary bildiren bir FeatureRecipe, anahtarı ayarlasa da ayarlamasa da her zamanki yerinde render edilir ve .boundary altında okuduğu bağlantılar hiçbir render olgusu taşımaz.

locals: bloğu

FeatureRecipe.spec.locals:, oluşturulan çıktısı aynı FeatureRecipe içindeki diğer her şablona bir .locals.* haritası sunan, isteğe bağlı bir adlandırılmış Go şablon dizeleri haritasıdır. Recipe locals: bloğunun FeatureRecipe’e özel karşılığıdır: türetilmiş dizeleri bir kez hesaplayıp yeniden hesaplamadan injectMapping, valuesMapping, pipeline[].with ve provides içinden başvurmak için bir yerdir. FeatureRecipe’nin assertions: bloğu bunları okumaz: assertions-block.md belgesinin belirttiği gibi, bir onaylamanın .locals değerleri konak bileşenin Recipe’sine aittir. Her girdinin oluşturulan çıktısı baştaki ve sondaki boşluklar kaldırılarak saklanır. Blok tek bir şablon gövdesi değil, bir haritadır; bu konumdaki bir skaler değer şema tarafından reddedilir.

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

.locals.* çağrı başınadır: her FR çağrısı kendi locals: bloğunu çözümler ve sonuç yalnızca o çağrının sonraki şablonlarına görünür. Blok, FR’nin diğer yazım yüzeyi şablonları değerlendirilmeden önce çözümlenir; böylece bunların her biri çözümlenmiş değerleri görür.

Her girdi kendi içinde bağımsız bir bağlama göre değerlendirilir: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra ve aynı bloğun daha önce çözümlenmiş girdileri. Bu, FR’nin diğer şablonlarının okuduğu bağlamdan bilinçli olarak daha dardır: bir locals: girdisi .context.annotations, .context.inject, .context.uses veya .provides değerlerine erişemez ve bunlardan herhangi birine yapılan başvuru, başvuruyu belirterek derlemeyi durdurur. Bu temel alanlara ihtiyaç duyan türetilmiş değerler locals: içine değil, onları okuyan şablona aittir.

Bu bağlamdaki adlar farklı sorulara yanıt verir ve bir locals: girdisi bunları FeatureRecipe’in diğer şablonlarının okuduğu şekilde okur:

  • .context.instance_id, eklentinin kendisi için çözümlendiği ana bileşendir. Derleyicinin değerlendirdiği her şablon yüzeyinde ana bileşen anlamına gelir; böylece aynı başvuru, hangi varlığın bloğunu yazıyor olursanız olun aynı şekilde okunur.
  • .context.rendered_name, ana bileşenin kendi sağlayıcısının bildirdiği adıdır: helm altında, ana bileşenin kimliğinin bir Kubernetes adının kabul ettiği alfabeyle yazılmış hâli olan release adıdır. Yalnızca ana bileşenin sağlayıcısı bir ad bildirdiğinde bulunur ve sağlayıcısı ad bildirmeyen bir ana bileşende okunması derlemeyi durdurur.
  • .attachment_name, çözümlenen eklenti örneğidir: sahip varlığın featuresSchema alanında doldurduğu yuva veya ona verdiğiniz serbest ad.

Dolayısıyla, üretilen bir kaynak için ad türeten bir locals: girdisi, tıpkı bir artifacts: şablonunun yapacağı gibi ana bileşeni ve eklentiyi birleştirir:

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

Adın platformun kabul ettiği bir ad olması gerektiğinde ve ana bileşenin sağlayıcısı bir ad bildirdiğinde, adı bunun yerine .context.rendered_name üzerinden oluşturun: helm altında my_api adlı bir ana bileşen ve scrape eklentisi için {{ .context.rendered_name }}-{{ .attachment_name }}, my-zuapi-scrape verir; kimlik ise bir Kubernetes adının reddettiği my_api-scrape değerini verirdi. Bkz. Oluşturulan bir kaynağı adlandırma.

Bir locals: girdisindeki .values ve .infra, ana bileşenin değil, eklenti bildiriminde yazılmış olan eklentinin kendi temel alanlarıdır.

Yazım sırası belirleyicidir

Girdiler yazıldıkları sırayla çözümlenir ve bir girdi, kendisinden önce tanımlanmış bir kardeş girdiyi okuyabilir; bu durumda o kardeşin çözümlenmiş değerini alır:

spec:
locals:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

Zincirleme yalnızca aşağı doğru işler. Bir girdi diğerini okuduğunda, derlemenin başarılı olup olmayacağını girdilerin sırası belirler: region_prefix girdisini bucket girdisinin altına taşırsanız derleme durur. Derleyici bir başvuruyu çözümlemek için bloğu asla yeniden sıralamaz; bu nedenle bir locals: bloğunu yeniden sıralamak görsel değil, davranışsal bir değişikliktir.

Bloğun daha sonra tanımladığı bir girdiye yapılan başvuru, sıralama hatasını belirterek durur (tanımı okuyucusunun üstüne taşıyın); bloğun hiç bildirmediği bir anahtara yapılan başvuru, anahtarı belirterek durur (yazımı düzeltin). Denetim, blok için kullanılan bir takma adı izler: bir with .locals gövdesinin yeniden bağladığı nokta üzerinden veya .locals değerine bağlanmış bir değişken üzerinden erişilen bir anahtar, doğrudan yazımla tamamen aynı koşullarda durur; parantez içindeki bloktan okunan bir anahtar da öyle: {{ (.locals).nope }} veya {{ ($.locals).nope }}. Tek bir yazım bundan kaçar: sonucunu şablon metninin adlandıramadığı bir çağrı üzerinden erişilen anahtar ({{ index .locals "nope" }} veya {{ (default dict .locals).nope }}). Böyle bir çağrının sonucundan okunan bir alan durmaz ve <no value> metnini olduğu gibi oluşturur; index okuması anahtarı belirterek durur, çünkü index, okuduğu harita anahtarı içermediğinde her şablon yüzeyinde durur; bkz. errors/fatal-halts.md “A template indexes a map with a key the map does not hold (Bir şablon, haritada bulunmayan bir anahtarla haritayı indeksliyor)”. provides: tamamen çözümlenmiş bloğu okur, çünkü bu FeatureRecipe’in locals değerleri provides değerlerinden önce çözümlenir; bildirilmemiş bir anahtarı belirten bir provides: şablonu durur. Bunlar bir Recipe’in locals: bloğunun izlediği kuralların aynısıdır; bkz. entities/recipe.md “locals: bloğu”.

Kapsam davranışı. executionScope: component (varsayılan) için locals:, eklenmiş her bileşen örneği başına yukarıdaki kendi içinde bağımsız bağlama göre değerlendirilir. executionScope: boundary için locals:, her sınır eklentisi başına .boundary.* kökenli sınır kapsamı görünümüne göre değerlendirilir; bileşen başına alanlar (.context.instance_id, .context.inject, .context.uses) ve .attachment_name kullanılamaz, çünkü FeatureRecipe bileşen başına bir kez değil, sınır için bir kez çalışır. Sınır kapsamı şablon alanı izin listesi, diğer FR yazım yüzeyi şablonlarına uygulandığı şekilde locals: için de uygulanır. Eklentinin ulaştığı her bileşen için çalışan injectMapping, sınır için yapılan o tek değerlendirmeyi kendi .locals değeri olarak okur. Değerlendirme sözleşmesi (yazım sırası, yalnızca aşağı doğru kardeş okumaları, iki durdurma) her iki kapsamda da aynıdır; yalnızca çevreleyen bağlamın biçimi farklıdır.

injectMapping katmanlarından ve pipeline[].with eşlemelerinden farkı. locals:, sonraki şablonlar için bağlamda görünür bir harita üretir; çıktıya katkıda bulunmaz. injectMapping, tüketicinin .context.inject kanalına yazar (çağıran tarafında değişiklik). pipeline[].with, Wasm plugin’inin args yükünü sağlar. Bu üç yüzey birbirinden bağımsızdır: bir FeatureRecipe genellikle üçünü birlikte kullanır ve locals: diğer ikisinin başvurduğu ortak türetilmiş dizeleri taşır.

assertions: bloğu

FeatureRecipe.spec.assertions:, FeatureRecipe’in uygulama değişmezlerini ifade eden adlandırılmış kurallardan oluşan isteğe bağlı bir eşlemedir: FeatureRecipe’in üzerine kurulduğu belirli Wasm plugin işlem hattı, chart veya mekanizma göz önüne alındığında geçerli olan, alanlar arası kurallar. Her anahtar, hata iletisinde görünen bir kural tanımlayıcısıdır; her değer bir Go şablon gövdesidir. Recipe assertion’ları gibi FeatureRecipe assertion’ları da belirli uygulamanın özellikleridir; Feature düzeyindeki sözleşme kuralları, işlem hattının daha önceki bir aşamasında bunlardan bağımsız olarak uygulanır.

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

Yukarıdaki kural aws-secrets-manager plugin’inin 1.x sürümüne özgüdür; farklı bir core/referenced-secret FeatureRecipe’i bağlanırsa uygulanmaz. Feature tanımındaki Feature düzeyindeki sözleşme kuralları da yanında uygulanmaya devam eder.

FeatureRecipe assertion’ları, FeatureRecipe bağlamadan sonra ve Resource Generation’dan önce değerlendirilir. Bileşen kapsamlı FR’ler için şablon bağlamı, Recipe assertion bağlamını yansıtır (varlık örneği alanları ile birlikte .provides, .locals, .recipe.metadata, .recipe.source); sınır kapsamlı FR’lerde (executionScope: boundary) assertion’lar sınır kapsamı görünümüne göre değerlendirilir (.boundary.* alanları kullanılabilir; bileşen başına alanlar kullanılamaz). Yazım dilbilgisinin tamamı ve çalışılmış örnekler için bkz. templates/assertions-block.md.

omits: alanı — işlenen belgeleri bir kaynağın dışında bırakmak

Çoğu FeatureRecipes buna hiç ihtiyaç duymaz. Bu alan, source: değeri olduğu gibi alınan bir chart olan — çoğu zaman bir kayıt defterinden getirilmiş bir chart — ve eklentinin yaymaması gereken bir belge işleyen bir FeatureRecipe içindir: chart’ın her işlemede yeniden ürettiği bir Secret ya da ana bileşenin veya operatörün zaten sağladığı bir nesne. omits:, böyle bir belgeyi FeatureRecipe’in ürettiklerinin dışında bırakır; FeatureRecipe’in kaynak olarak kullandığı bir compose dosyası için eklentinin katkıda bulunmaması gereken bir service, volume ya da config’i, kaynak olarak kullandığı bir CloudFormation şablonu için ise bir resource’u dışarıda bırakır.

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

Anahtar bir Recipe üzerinde de aynı şekilde yazılır ve Recipe → omits: alanı onun tam başvurusudur: her girdi alanının neyi seçtiği, when: ifadesinin önce değerlendirildiği ve false olanın girdiyi düşürdüğü, uygulanan her girdinin bir şeyi dışarıda bırakması gerektiği, aksi halde derlemenin o girdiyi adlandırarak durduğu, kaynağın yine tümüyle işlendiği ve yalnızca çıktısının filtrelendiği ve anahtarı hangi sağlayıcıların dikkate aldığı. Bir FeatureRecipe üzerinde farklı olan tek şey, şablonların nerede değerlendirildiğidir:

  • Her girdinin şablonları, bu FeatureRecipe’in valuesMapping: alanının değerlendirildiği bağlama göre değerlendirilir; bu, executionScope alanının seçtiği kapsamda gerçekleşir. Bileşen kapsamlı bir FeatureRecipe’in girdileri eklenti başına bir kez, o eklentinin .values ve .infra değerlerine göre değerlendirilir; sınır kapsamlı bir FeatureRecipe’inkiler ise sınır başına bir kez, sınır kapsamı görünümüne ve sınır eklentisinin .infra değerine göre değerlendirilir. Bir eklentinin şablonlarının neleri okuyabileceğine ilişkin kurallar, eklentinin valuesMapping: alanına uygulandığı gibi girdilere de uygulanır.
  • Yalnızca bu FeatureRecipe’in kendi source: alanının işlediği şey filtrelenir. workload: ve artifacts: filtrelenmez, ana bileşenin çıktısı da filtrelenmez: bir eklentinin girdileri yalnızca kendi chart’ına, kendi compose dosyasına veya kendi CloudFormation şablonuna ulaşır, başka hiçbir şeye ulaşmaz — ana bileşenin, ikisinin birlikte birleştirildiği docker-compose.yaml içinde aynı anahtar altında bildirdiği bir compose service’i etkilenmez; ana bileşenin, ikisinin birlikte birleştirildiği stack içinde aynı mantıksal kimlik altında bildirdiği bir resource da etkilenmez. Ana bileşenin işlediği bir belgeyi değiştirmek için girdiyi ana bileşenin Recipe’i bildirir ya da belgeye bir pipeline: adımı yama uygular.

Bir girdideki durma; düğümü, sağlayıcıyı, bu FeatureRecipe’i ve girdinin omits: listesindeki konumunu adlandırır; sınır kapsamlı bir FeatureRecipe için mesajın üstündeki satır eklentiyi ve sınırını adlandırır.

Anahtarın bir Recipe üzerinde yazılmış örneği için — getirilmiş bir chart’ın ürettiği Secret’ın dışarıda bırakılması ve girdi olmadan ve hiçbir şeyle eşleşmeyen bir girdide oluşan durmalar — bkz. ai-gateway-own-webhook-certificate.