Yol şablonu değişkenleri
Bir Release sınırındaki directory: ve subDirectory: alanları, derleme zamanında değerlendirilen Go şablonlarıdır. Bu alanlar, işlenen yapıtların diskte nereye yerleşeceğini ve dolayısıyla hangi yapıtların birlikte birleştirileceğini belirler: aynı (path, provider) demetine değerlendirilen iki sınır bir birleştiriciyi paylaşır ve tek bir birleşik çıktı üretir (tek bir Chart.yaml, tek bir docker-compose.yaml). Bu sayfa; bu şablonların başvurabileceği değişkenler, katı değerlendirme semantiği ve sınırların üst sınırlarından miras almasını sağlayan kademelenme kuralları için yazım başvuru kaynağıdır.
Uzamsal ayrıştırmanın ve (path, provider) başına dağıtımın kavramsal ele alınışı için architecture/16-recipe-input-composition.md sayfasına bakın. Varlık düzeyindeki Release yazım yüzeyi için entities/release.md sayfasına bakın. Sağlayıcı tarafındaki sonuçlar providers/architecture.md sayfasında ve sağlayıcıya özgü sayfalarda yer alır.
Katı değerlendirme: missingkey=error
Yol şablonları, Go’nun missingkey=error kipiyle değerlendirilir. Bildirilmemiş bir alana, ayarlanmamış bir parameters.X anahtarına ya da {{ .parmaeters.region }} gibi bir yazım hatasına yapılan başvuru, bir yola sessizce boş bir dize işlemek yerine açık bir hata üretir.
Bu katılık, derleyicinin geri kalanıyla asimetriktir — valuesMapping, injectMapping ve diğer değer işleme yüzeyleri, Helm/Sprig uzlaşımı uyarınca missingkey=zero kullanır. Yol üretimi yapısal olarak farklıdır: boş bir dize üreten bir değer işleme şablonu, sonucun sınırlı olduğu bir manifest alanına düşer; boş bir dize üreten bir yol şablonu ise sonucun sınırsız olduğu bir dizin düzenine düşer (çakışmalar, bozuk birleştirme, hayalet yollar). Katı yol şablonu rejimi, bu hataları dağıtım zamanında değil derleme zamanında ortaya çıkarmak için vardır.
Ayrıştırma zamanında izin listesi doğrulaması
Çalışma zamanı katılığına ek olarak, yol şablonları ayrıştırma zamanında kapalı bir değişken adları izin listesine göre doğrulanır. İzin listesinde bulunmayan bir değişken adına yapılan başvuru, herhangi bir işleme çalışması başlamadan derlemeyi durdurur ve sorunlu alanı ile bu alanın bulunduğu sınırı belirten bir tanılama üretir.
İzin listesi tasarım gereği kapalıdır: .context.inject, .values ve .locals gibi yüzeyler yol şablonlarına kasıtlı olarak açılmaz. Yol üretimi değer işlemeyle değil, yapıyla ilgili bir konudur; derleme yollarını bileşen başına değerlere bağlamak, yol grafiğini veriye bağımlı hâle getirir ve deterministik çıktı değişmezini aşındırır.
Değişken matrisi
| Değişken | directory: | subDirectory: | Açıklama |
|---|---|---|---|
{{ .capability }} | evet | evet | Bu yolda üretilen yapıtlar için, katkıda bulunan bileşenin Recipe’inin bildirdiği işleme yeteneği (helm, helm-chart, compose, terraform, cloudformation). |
{{ .boundary_name }} | evet | evet | Sınırın Release içinde yazılmış adı (ör. production, eu-prod). |
{{ .parameters.X }} | evet | evet | Aggregate üzerinde bildirilen ve Release tarafından karşılanan herhangi bir tipli parametre. Katı erişim: .parameters.unknown değişkenine başvurmak derlemeyi durdurur. |
{{ .manifest.recipe_name }} | evet | evet | Katkıda bulunan bileşen için Manifest aracılığıyla çözümlenen Recipe adı. Recipe başına yapıtları Recipe başına alt klasörlere yönlendirmek için kullanışlıdır. |
{{ .parent_boundary.* }} | evet | evet | Kapsayan sınırın değerlendirilmiş değerlerine kademeli erişim. Aşağıdaki Üst sınır kademesi bölümüne bakın. |
{{ .component_id }} | — | evet | Katkıda bulunan bileşenin örnek kimliği. FeatureRecipe’si sınır için bir kez çalışan bir sınıra eklenmiş bir Feature için (executionScope: boundary), bu, o eklemenin kaynaklarının aggrega.ai/component-id etiketinde taşıdığı birleşik kimliktir — app sınırındaki shared eklemesi için bfr--app--shared, eklemenin sağlayıcısının adları sınırladığı yerde kısaltılmış olarak — böylece eklemenin çıktısı o etiketin adını taşıyan bir dizine yerleşir. Yalnızca subDirectory: içinde kullanılabilir, çünkü directory: sınır başına bir özelliktir — dizin dizgesi, bileşen başına herhangi bir yönlendirme gerçekleşmeden önce, sınır başına bir kez hesaplanır. |
directory: alanının varsayılanı, boundaries/ ve ardından sınır yoludur (sınır ağacından türetilen, derleme zamanında kararlı bir tanımlayıcı); bileşenlerini sınır bildirmeden listeleyen bir Release, onları hiçbir dizin kesimi olmadan yazar. subDirectory: alanının varsayılanı {{ .capability }} olur; böylece her yeteneğin yapıtları, sınırın dizini altındaki kendi alt klasörüne yerleşir. Bu, alan atlandığında da, atlanmış bir alanla tamamen aynı okunan subDirectory: "" olarak yazıldığında da geçerlidir. subDirectory: "." ayarlamak ya da boş dizeye değerlendirilen bir şablon yazmak bu gruplamayı düzleştirir.
Bu şablonların belirlemediği şey: artifacts: yerleşimi
Çıktı yolunun bir kesimini belirlemek yol şablonunun işi değildir. Bir Recipe’in artifacts: bloğunun adlandırdığı bir dosya, subDirectory: neye değerlendirilirse onun içinde, onu bildiren bileşenin adını taşıyan bir dizin altına yazılır. Bu kesim sabittir ve her zaman bulunur; katkıda bulunanların dosyalarını her birini kendi chart’ına ya da modülüne yerleştirmek yerine yan yana yazan bir hedef için geçerlidir.
Nedeni, dosyayı neyin adlandırdığıdır. Bir hedefin işlediği ya da sentezlediği bir manifest, hedef tarafından ait olduğu bileşene göre adlandırılır; dolayısıyla bileşenini zaten tanımlar. Bir yapıt ise yazarının yazdığı anahtarla adlandırılır (app-config.yaml, netpol.yaml) ve bu anahtar bileşen hakkında hiçbir şey söylemez, çünkü onu bildiren Recipe hangi bileşenlerin kendisine bağlanacağını bilmez. Tek bir sınırda tek bir Recipe’e bağlı iki bileşen aynı yolu yazardı ve ne Recipe yazarının ne de Release yazarının onları ayırabileceği bir yüzeyi vardır.
Yalnızca dizin eklenir; dosya adı yazılmış anahtar olarak kalır, böylece yazarın çıktıda okuduğu dosya, kendi yazdığı adı taşır.
subDirectory: hâlâ ne sağlar ve ikisi nasıl birleşir. subDirectory:, bir katkıda bulunanın ürettiği her dosyayı (işlenmiş manifestler, sentezlenmiş manifestler ve yapıtlar birlikte) taşır; bu nedenle tek bir bileşenin tüm manifest kümesi üzerinde çalışan aşağı akış araçları için bir bileşene kendi dizinini vermenin ya da birkaç bileşeni tek bir ortak klasöre yönlendirmenin aracıdır. artifacts: kesimi, bu alan neye değerlendirilirse onun altında uygulanır. Bu yüzden Recipe’i artifacts: bildiren bir bileşende subDirectory: "{{ .capability }}/{{ .component_id }}" yazmak bileşenin adını iki kez üretir: yapıt <capability>/<component>/<component>/<key> konumuna yerleşirken o bileşenin işlenmiş manifestleri <capability>/<component>/<key> konumuna yerleşir. Bileşenin tüm çıktısının toplanmasını istediğinizde bu geçersiz kılmaya başvurun; yalnızca yapıtları ayırmanız gerekiyorsa, ki bunu varsayılan zaten yapar, onu kullanmayın.
.capability bileşen başına çözümlenir ve bir sınırın directory: alanı iki ayrı amaçla değerlendirilir. .parent_boundary.directory değerini alt sınırlara yayımlayan sınır başına değerlendirme, herhangi bir bileşen bağlanmadan önce çalışır; bu yüzden orada .capability boştur. Bir katkıda bulunanın yapıtlarının gerçekte nereye yerleşeceğini belirleyen bileşen başına değerlendirme ise o bileşenin yeteneğini taşır. Bu nedenle directory: "d-{{ .capability }}" yazan bir üst sınır, kademe boyunca aşağıya d- yayımlarken kendi yapıtları d-compose altına yerleşir.
Üst sınır kademelenmesi
İç içe sınırlar, doğrudan üst sınırın değerlendirilmiş yolunu ve onun kademelenme yoluyla çözümlenmiş kendi verilerini sunan bir .parent_boundary görünümü alır. Kademelenme tek düzeylidir: bir sınırın .parent_boundary görünümü, büyük üst sınırı değil doğrudan üst sınırıdır. Daha yukarıya ulaşmak için üst sınırın kendisi kendi şablonlarında .parent_boundary kullanır ve değerleri ağaçta aşağıya açıkça aktarır.
.parent_boundary altında kullanılabilen alanlar:
| Alan | Açıklama |
|---|---|
.parent_boundary.directory | Üst sınırın değerlendirilmiş directory: değeri (şablon sonrası). |
.parent_boundary.boundary_name | Üst sınırın yazılmış adı. |
.parent_boundary.parameters | Üst sınırın gördüğü aynı .parameters.* eşlemesi (parametre değerleri Release genelindedir, ancak bu takma ad simetri için sağlanır). |
.parent_boundary.annotations | Üst sınırın kademelenme yoluyla çözümlenmiş ek açıklamaları. |
Standart desen: bir directory: değerini bir kez yazan bir üst sınır ve directory: "{{ .parent_boundary.directory }}" bildirerek yapıtlarını üst sınırın altına yönlendiren alt sınırlar. Bu, alt sınırları üst sınırın birleştirme yoluna toplar ve her alt sınırdan katkıda bulunanları içeren tek bir birleştirilmiş çıktı üretir. core/compose-bridge Feature’ı tam olarak buna dayanır: köprü özelliğini barındıran bir üst sınır, üst sınırın directory: değerini paylaşan iki alt sınır (örneğin services-net ve data-net) ve her bileşeni ile köprü hizmetini içeren tek bir birleştirilmiş docker-compose.yaml.
Tersi de geçerlidir: alt sınırlarda .parent_boundary.directory kullanımını çıkarırsanız (ya da farklı bir yola değerlendirirseniz) her alt sınır kendi birleştirmesini alır. Her iki biçim de birinci sınıftır.
Örnek yerleşimler
Yerleşim 1 — varsayılan sınır başına ayrıştırma
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Her sınır farklı bir directory: değerine değerlendirilir, böylece her biri kendi derlemesini alır:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...Varsayılan subDirectory: "{{ .capability }}", yetenek başına yapıtları her sınır dizininin içinde ayrıştırır. İki sınır, yetenek başına iki derleme çıktısı, birleştirme yok.
Yerleşim 2 — paylaşılan üst dizin aracılığıyla birleştirilmiş derleme
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Her iki alt sınır da directory: değerini deploy/cluster (üst sınırın dizini) olarak değerlendirir, böylece tüm katkıda bulunanlar tek bir derleme yolunda birleşir. Varsayılan subDirectory: "{{ .capability }}" ile her iki alt sınırın compose katkıda bulunanları deploy/cluster/compose/ içine yerleşir ve birleştirilmiş tek bir docker-compose.yaml üretir. Üst sınıra bağlı compose-bridge Feature’ı bir kez çalışır (sınır kapsamlı dağıtım) ve köprü hizmetini aynı birleştirilmiş dosyaya ekler.
Üst sınırın aggrega.ai/chart-name: "cluster-umbrella" ek açıklaması her iki alt sınıra da kademeli olarak aktarılır; sınırlar helm-chart katkıda bulunanları da barındırsaydı, her iki alt sınırın helm-chart alt chart’ları cluster-umbrella adlı tek bir şemsiye altında birleşirdi. Tek bir yoldaki katkıda bulunanlar arasında uyuşmayan chart-name değerleri derlemeyi durdurur.
Yerleşim 3 — subDirectory: ve parametrelerle bileşen başına yönlendirme
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"Sınırın directory: değeri deploy/eu-west-1 olarak değerlendirilir (parametre ikamesi). Bileşen başına subDirectory: geçersiz kılmaları her katkıda bulunanı bileşene özgü bir alt klasöre yönlendirir; ingress bileşeni ise kesişen yapıtlar için düz bir shared alt klasörüne geçersiz kılar:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Bu kalıp, tek bir bileşenin manifest’leri üzerinde çalışan alt akış araçları için bileşen başına yapıt dizinleri isteyen kuruluşlara uygundur. Bir bileşenin Recipe’i artifacts: de bildiriyorsa, bu yapıyı seçmeden önce yukarıdaki Bu şablonların belirlemedikleri bölümünü okuyun: bu dosyalar zaten bir bileşen bölümü taşır, dolayısıyla bu geçersiz kılma ikinci bir bölüm ekler.
Tanılamalar
Yol şablonu yüzeyi aşağıdaki durumların her birinde derlemeyi durdurur ve errors/fatal-halts.md bunları bu adlar altında belgeler. O sayfa, her durdurmanın yaydığı iletiyi aktarır; derleme çıktısını o metinle eşleştirin.
- Path-template references a variable outside the allowlist (Yol şablonu izin listesi dışındaki bir değişkene başvuruyor) — ayrıştırma zamanı: bir yol şablonu, izin listesinde olmayan bir değişkene başvurur.
- Path collision (Yol çakışması) — birleştirme zamanı: iki sınır katkıcısı aynı yola değerlendirilir ancak o yoldaki katkıcılar arasında tek biçimli olması gereken bir özellikte uyuşmaz.
- Instance-ID collision (Örnek kimliği çakışması) — birleştirme zamanı: aynı
(path, provider)demetine değerlendirilen iki sınır, özdeş örnek kimliklerine sahip bileşenler katkıda bulunur. - Chart-name mismatch (Chart adı uyuşmazlığı) — birleştirme zamanı: birleştirilmiş bir helm-chart derlemesi, kademeli olarak çözümlenmiş
aggrega.ai/chart-nameek açıklamaları çelişen katkıcılar alır. - Missing template key (Eksik şablon anahtarı) — bir yol şablonu, açık bir değişken altında hiçbir değere çözümlenmeyen bir alana başvurur (ör. Release
regiondeğerini atladığında{{ .parameters.region }}ya da üst öğesi olmayan en üst düzey bir sınırda bir.parent_boundaryanahtarı);missingkey=error, sınırı, şablon alanını (directory:veyasubDirectory:) ve eksik anahtarı adlandıran açık bir ileti üretir..parametersve.parent_boundaryaçıktır — anahtarları yazılan verilerdir —.manifestise anahtarlarını bildirir; bu nedenle.manifestaltında yanlış yazılmış bir anahtar bunun yerine ayrıştırma zamanında bilinmeyen bir başvuru olarak reddedilir ve tanılama,.manifest’in tanımladığı anahtarları listeler.
Çapraz başvurular
entities/release.md— mekânsal ayrıştırma vedirectory:/subDirectory:alanları dahil olmak üzere Release yazımı.providers/architecture.md— sağlayıcı dağıtımı ve(path, provider)başına derleme modeli.providers/compose.md— birleştirilmiş yol senaryosu dahil olmak üzere compose tarafındaki(path, provider)başına çıktı.providers/helm-chart.md— helm-chart şemsiye bileşimi ve birleştirilmiş yollar için chart-name basamaklama kuralı.entities/featurerecipe.md— sınır kapsamlı FeatureRecipes (core/compose-bridgeFeature’ı, burada belgelenen birleştirilmiş yol derleme modeline dayanır).errors/fatal-halts.md— yukarıda sıralanan yol dağıtımı durdurmaları dahil olmak üzere eksiksiz tanılama kataloğu.