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

Derleme işlem hattı (üst düzey)

Bu bölüm Go derleyicisinin iç fiziğini ayrıntılandırır; soyut YAML’ın derleme işlem hattı, Ara Gösterim (Intermediate Representation, IR) Grafiği ve WebAssembly (Wasm) yürütme soketleri boyunca fiziksel yapılandırmalara nasıl çevrildiğini tanımlar.

Derleme işlem hattı & yürütme akışı

Aggrega, sabit kodlanmış orkestrasyon mantığı yerine katı, sabit sıralı bir Önceden Derleme (Ahead-of-Time, AOT) derleyici işlem hattı çalıştırır. aggrega build ile tetiklenen derleyici, fiziksel yapıtları oluşturmadan önce mimariyi değerlendirmek için düz grafiği yalıtılmış WebAssembly (Wasm) soketleri arasında aktarır.

Wasm soketleri gömülü bir host üzerinde — Wazero motorunun üzerindeki Extism araç seti — bir eklentinin her türlü çalışma zamanı erişim yeteneğini (ağ, dosya sistemi, duvar saati, ortam, standart G/Ç) reddeden bir AOT saflık güvenlik duvarının arkasında çalışır; böylece bir eklenti deterministik, önceden derleme garantisini bozamaz. Host, publishing-linter’ı bant dışı olarak aggrega lint aracılığıyla çalıştırır. Aşağıda açıklanan bant içi kapılar — yönetişim soketinin topoloji oluşturma sırasındaki label-transform rolü ve statik analizdeki IR-verdict rolü ile render aşamasını kapatan eklenti işlem hattı — her derlemede çalışır: bir yönetişim rolü, çalışma alanının ona bir eklenti iliştirdiği her yerde; eklenti işlem hattı ise adım bildiren her Recipe için. Her işlem hattı aşamasının durumunu Dilin durumu izler.

İşlem hattı tamamen bellek içinde, katı ve sabit bir sırayla yürütülür:

Çözümleme — Çözümleyici & sözdizimi doğrulayıcı

  • Mekanizma: Kalıtım birleştirme, Go şablon enterpolasyonu ve JSON Schema 2020-12 doğrulaması.
  • Eylem: CLI istenen tüm varlıkları (Components, Features, Releases) getirir. Önce bu tanımlarda extends anahtar sözcüğünü denetler. Katalog varlıkları için YAML meta verilerini derinlemesine birleştirir ve iki tür veri sütunlarında birbirinden ayrılır: bir Feature’ın schema: alanı JSON Schema 2020-12 bileşimi altında temelininkiyle birleşir; genişleten bir Component ise yalnızca yapıyı birleştirir — ek yuvalarını, topoloji soketlerini, kendine enjekte izin listesini ve adlandırılmış onaylamalarını — ve temelinin schema: bloğunu tam olarak temelin yazdığı şekilde alır. Genişleten bir Release aynı kurala göre katlanır: alt öğenin değeri anahtar anahtar, ilk bölünemez değere — bir skaler, bir liste, bir şablon — kadar kazanır; bu değer bütünüyle değiştirilir ve alt öğenin null olarak yazdığı bir anahtar kaldırılır. Böylece tüm yazım yüzeyi aktarılır — bileşen başına infra ve Feature eklemeleriyle sınır ağacı, parameters bloğu, ek açıklamalar ve Manifest işaretçisi — ancak hiçbir metadata alanı aktarılmaz, çünkü kimlik ve köken Release başınadır. Ardından üç alt adımda bellek içi bir enterpolasyon gerçekleştirir: Aggregate’in türlendirilmiş parameters: bildirimlerine karşı parametre sözleşmesi doğrulaması; çözümlenmiş değerlerin çevreleyen values: dizelerine enterpolasyonu; .parameters eşlemesinin her değer şablonu bağlamından geri çekilmesi, böylece yalnızca operatörün yazdığı yol şablonları tarafından okunabilir kalması. Son olarak çözümlenmiş infra bloklarını hedef bileşen yüklerine enjekte eder. Plan tamamen somutlaştığında derleyici, geliştiricinin values ve infra yapılandırmalarını yerel olarak katı biçimde doğrulamak için Katalogdaki birleşik schema: bildirimini (kompakt biçim veya tam JSON Schema 2020-12) kullanır.
    • Release Feature şema doğrulaması: Release aracılığıyla eklenen Features (hem sınır genelinde hem bileşene özgü) bu adımda Katalog varlıklarına karşı çözümlenir. Derleyici, Release tarafından sağlanan infra bloklarını katalog çözümlemesinin hemen ardından her Feature’ın schema: bildirimine karşı doğrular ve topoloji oluşturulmadan önce tür güvenliğini sağlar.
    • Ek açıklama güdümlü Feature genişletme alt aşaması: Manifest çözümlemesi, Recipe/Provider bağlama ve Manifest bağlama hedefi doğrulamasından (mappings.features.annotations.<key>.maps altında bildirilen yolların başvurulan Feature’ın spec.schema alanında bulunması) sonra derleyici, topoloji oluşturucudan önce bir ek açıklama genişletme alt aşaması çalıştırır. Alt aşama Release sınırlarını dıştan içe ve Aggregate alt sistemlerini dıştan içe dolaşır; bileşen başına etkin ek açıklama kümesini kademeli aktarım + geçersiz kılma + null ile devre dışı bırakma birleştirmesiyle hesaplar; her ek açıklama değerini YAML olarak bir skalere, yapılandırılmış bir değere veya null’a ayrıştırır; her değeri (skaler veya alt anahtar başına yapılandırılmış) Manifest bağlamasının maps bildirimi üzerinden hedef Feature şema sütununa, taraf-sütun zorlamasıyla yönlendirir (Aggregate tarafı maps.values tetikler; Release tarafı maps.infra tetikler); yaprak başına türleri Feature’ın spec.schema alanına karşı doğrular; ve IR grafiğinin origin: annotation ile işaretlediği sentetik Feature eklemeleri enjekte eder. Şemalar derleme başına bir kez derlenir ve kademeli dolaşımlar boyunca yeniden kullanılır. Genişletme, bağlama hedefi doğrulamasından sonra ve topoloji oluşturmadan önce çalışır; bu nedenle sonraki aşamalar sentetik eklemeleri yapısal olarak açık olanlarla aynı şekilde ele alır (köken incelemesi dışında). Bağlama biçimi, kademeli aktarım semantiği ve taraflar arası bileşim kuralları için bkz. 13-catalog-and-registry.md §“Ek açıklama güdümlü Feature genişletmesi” ve language-reference/providers/well-known-annotations.md.

Topoloji oluşturma — Topoloji oluşturucu & mutasyon kapısı

  • Mekanizma: AST genişletme + yönetişim soketinin label-transform rolü.
  • Eylem: Derleyici, grafikteki düğümler arasında deterministik olarak topolojik kenarlar çizmek için doğrulanmış bileşenlerden açıkça bildirilmiş uses bloklarını yerel olarak okur ve values bloğunu tamamen opak bırakır. Ardından Mutasyon Kapısı’nı değerlendirir; grafiğin bir izdüşümünü — her düğümün etiketleri ve örneğinin bildirdiği, derleyicinin okumadan aktardığı values — Release’in adı ve ortamıyla birlikte label-transform rolüne eklenmiş bir yönetişim eklentisine aktarır. Eklenti bağlamı değerlendirir ve grafiği dinamik olarak otomatik etiketlemek için JSONPatch’ler döndürür (ör. Release’in ortamına dayanarak compliance.aggrega.ai/data-class: restricted etiketini veya bir veritabanının bildirdiği uzantılara dayanarak datastore.aggrega.ai/engine: vector etiketini enjekte etmek); yamalar yalnızca etiketlere ulaşır.

Grafiğin sonlandırılması

  • Mekanizma: Normalleştirme.
  • Eylem: Derleyici düz Ara Gösterim (IR) Grafiğini sonlandırır ve topoloji oluşturucunun çizdiği açık topolojik kenarları korur. Ardından eklenmiş Features ile bunların values yüklerini düğüm kimliğine göre eşlenmiş düz bir sözlüğe normalleştirir ve yetenekten bağımsız grafiği doğrulamaya hazırlar.
    • IR yük normalleştirmesi: IR’nin yapısal biçimi, yapılandırma için Tek Doğruluk Kaynağı ilkesini zorunlu kılar: topoloji katmanı yalnızca grafik yapısını (düğüm kimliği, kenarlar, meta veri etiketleri) taşır ve normalleştirilmiş yapılandırma durumu, derleyicinin sonraki eklentilere aktardığı ayrı bir bellek içi sözlükte yaşar. Yapılandırmayı değiştiren mutatörler onu tek bir yerde değiştirir; sağlayıcı, normalleştirilmiş durumu gereksiz depolamadan kaynaklanan sapma riski olmadan okur.

Statik analiz — Statik analizci & doğrulama kapısı

  • Mekanizma: Topolojik saflık denetimleri + yönetişim soketinin ir-verdict rolü.
  • Eylem: Derleyici IR Grafiği üzerinde soyut statik analiz çalıştırır. İlk olarak usesSchema tanımlarından selector dizelerini çıkarır ve bildirilmiş soketler üzerinde düğümler arası tür güvenliğini garanti etmek için bunları, açıkça tanımlanmış grafik kenarları boyunca yerel bir Go etiket eşleştirme motoruyla (Kubernetes tarzı AND, in() aracılığıyla OR ve != aracılığıyla NOT semantiğini destekleyen) değerlendirir. Geçici bir soketteki kenarın — bir Aggregate yazarının adlandırdığı ve kataloğun bildirmediği bir soket — katalog girdisi ve dolayısıyla seçicisi yoktur; bu yüzden bu denetimin değerlendireceği bir şey de, eksik olan bir şey de yoktur; her kenar ikisinden hangisi olduğunu kaydeder ve geçici bir kenarın ne taşıyabileceği bunun yerine hedefin bildirilmiş provides alanıyla sınırlanır. Ayrıca eklenmiş özelliklerin hedef bileşenlerinin etiketleriyle uyumlu olduğunu doğrulamak için Feature appliesTo ve appliesToAnyOf seçicilerini, her doldurulmuş ek yuvasının kendi selector alanını da onu dolduran Feature’ın etiketlerine karşı değerlendirir. İkinci olarak, bir düğümün Component’inin bildirdiği her varlık zorunluluğunu — her features.aggrega.ai/requiredType.<label> ek açıklamasını — o düğümün nihai ek kümesine karşı değerlendirir. Bu denetimin yeri analizcidir, çünkü kuralın iki yarısını birden tutan ilk aşama odur: çözümlenmiş Component varlığının ek açıklamaları ve 5 Katmanlı kademenin ürettiği ek kümesi; Aggregate’e eklenen, alt sisteme eklenen, Release’e eklenen ve ek açıklamayla genişletilen eklemeler aynı şekilde sayılır. Hiçbir eklemenin karşılamadığı bir zorunluluk derlemeyi durdurur; bildirimi hatalı biçimlendirilmiş bir zorunluluk ise ayrı bir tanılamayla durdurur, böylece bozuk bir bildirim hiçbir zaman karşılanmış bir gereklilik gibi okunmaz. Üçüncü olarak Doğrulama Kapısı’nı yürütür; tam grafik yapısını (tüm düğümler, kenarlar, eklenmiş özellikler ve önceden hesaplanmış DFS yolları dahil) ir-verdict rolüne eklenmiş bir yönetişim eklentisine aktarır. Kuruluşun özel Wasm ilkesi topolojiyi değerlendirir. Wasm eklentisi bir hata dizisi döndürürse (ör. belirli bir proxy özelliği olmadan bir public düğümden bir restricted düğüme kesintisiz bir yol tespit ederse), derleme durur.

Render aşaması

  • Mekanizma: Render öncesi yakalama (injectMapping), geç bağlama (valuesMapping) ve Wasm render soketleri (pipeline).
  • Eylem: Son yapıt üretim aşaması, sabit bir sırayla çalışan katı zamansal alt aşamalara bölünür; bu da yürütmeyi deterministik tutar:
    • Inject eşleme (render öncesi yakalama): Go derleyicisi Geliştiricinin soyut .context.inject sözleşmesini çözümler. Ardından eklenmiş tüm FeatureRecipes içindeki injectMapping Go şablonlarını katı 5 Katmanlı Soğan Modeli yürütme sırasına göre yürütür (Alt Aggregate — önce bir modül bileşeninin kendi eklemeleri, ardından modülünün alt sistemlerinin bildirdikleri, dıştan içe → Kök Aggregate bileşeni → Kök Aggregate alt sistemi → Release sınırı dıştan içe → Release bileşene özgü). Derleyici ortaya çıkan sözlükleri Çağıranın .context.inject bellek borusunun üzerine yerel olarak derinlemesine birleştirir. Bu, Temel Recipe bunları görmeden önce Çağıran için ortam değişkenlerini ve bağlantı dizelerini güvenli biçimde yeniden yazar. Bir eşleme, Çağıranın kendi inject: bloğunun veya bağlantılarından birinin sağladığını yeniden yazabilir; farklı bir eklenmiş Feature’ın zaten sağladığı bir anahtar — kendi eşlemesi veya kendi inject: bloğu aracılığıyla — her iki eklemeyi adlandırarak derlemeyi durdurur; böylece yürütme sırası hiçbir zaman iki eklemenin değerleri arasında karar vermez.
    • Locals ön bölümü: Herhangi bir provides şablonu çalışmadan önce derleyici, Recipe’nin .locals girdilerini yazıldıkları sırayla, her birini kendi içinde bütünlüklü, düğüme yerel bir bağlama karşı değerlendirir — .context.instance_id, .values, .infra ve aynı bloğun o ana kadar çözümlenmiş girdileri; ancak .context.inject veya .context.uses değil. Bu nedenle bir girdi, üstünde tanımlanmış bir kardeşi okuyabilir ve o kardeşin çözümlenmiş değerini alır; bir girdinin diğerini okuduğu her yerde yazım sırası sözleşmenin parçasıdır ve bir başvurunun çözümlenmesi için blok hiçbir zaman yeniden sıralanmaz. Önce locals’ın çözümlenmesi, bir provides şablonunun .locals okuyabilmesini sağlar. Recipe’nin .source şablonu, bu locals çözümlendikten sonra aynı bağlama karşı değerlendirilir; bu da .locals alanını bir Recipe’nin şablonları boyunca kısaltma olarak yeniden kullanılabilir tutar ve yazarların .source alanını (chart sürümü, yol, kayıt defteri) sınır başına parametrelendirmesine olanak tanır.
    • Temel render (temel Recipe valuesMapping): Derleyici Temel Recipe’nin valuesMapping şablonunu değerlendirir. Şablon, yakalanan dizeleri .context.inject borusundan okur (inject eşleme sırasında yeniden yazılmış) ve ortaya çıkan değerler sözlüğü, temel altyapı yapıtlarını render etmek için Recipe’nin capability alanının adlandırdığı sağlayıcıya verilir — helm ve helm-chart sağlayıcılarının ikisi de Helm üzerinden render eder.
    • Workload ayrıştırma ve doğrulama: workload: bildiren bir Recipe’de — satır içi blok içeriği veya bir dosyayı adlandıran workload: { $import: <path> } — bu belge düğümün render bağlamına karşı bir şablon olarak değerlendirilir, ardından YAML olarak Workload biçimine ayrıştırılır ve denetlenir: render edilen baytlar Workload şemasına karşı doğrulanır, çözülen değer de ona karşı doğrulanır (baytlar çözmenin attığı anahtarları taşır ve çözme boş verilen bir alanı atlar; bu yüzden her biri diğerinin göremediğini reddeder), her attachments girdisi bağlı Component’in featuresSchema alanının bildirdiği yuvalara karşı denetlenir ve her kaynak başvurusu adlandırdığı yuvanın çözümlenmiş provides alanına karşı denetlenir. Buradaki bir hata derlemeyi durdurur. Ayrıştırılan Workload şablon bağlamına .workload olarak yerleştirilir; böylece aynı düğümde daha sonra değerlendirilen bir şablon onu okuyabilir.
    • Yapıt değerlendirmesi: Bir Recipe’nin artifacts: altında bildirdiği her girdi — satır içi içerik veya o girdinin kendi $import: alanıyla adlandırılan bir dosya — okunur, şablon olarak ayrıştırılır, tam şablon bağlamına karşı değerlendirilir ve derlemenin kökenini taşır. Ortaya çıkan izdüşüm sağlayıcıya verilir; çıktı biçimine, kökenin nereye yerleşeceğine, çıktı yoluna ve nihai baytlara sağlayıcı karar verir. Üretilen her dosya hangi yazım biçiminden geldiğini kaydeder; böylece bir dosya adı çakışması katkıda bulunan herkesi adlandırabilir.
    • Workload sentezi: Ayrıştırılan Workload, Recipe’nin capability alanının adlandırdığı sağlayıcıya verilir ve sağlayıcı onu kendi yerel kaynaklarına çevirir. workload: bildirmeyen bir Recipe’nin burada sentezleyecek bir şeyi yoktur; dosyaları bunun yerine kaynak render işleminden gelir.
    • Feature render (FeatureRecipe kaynak üretimi): Düğüm üzerindeki, bağlı FeatureRecipe’si kendi source, workload, artifacts ve/veya valuesMapping alanını taşıyan her ekleme — bir ServiceMonitor, bir NetworkPolicy, bir sidecar ConfigMap veya bir kimlik bilgisi teslim kaynağı gibi yardımcı manifestler için kullanılan Kaynak Üretimi deseni — inject eşlemenin izlediği aynı 5 Katmanlı Soğan Modeli sırasıyla tek geçişte değerlendirilir. Tek bir ekleme kümesi üzerinde tek bir sıra vardır: operasyonel bir Feature ile bir kimlik bilgisi Feature’ı aynı yolu izler ve aralarındaki fark, her birinin FeatureRecipe’sinin ne ürettiğidir. Her eklemenin .values ve .infra alanları kendi kapsamına çevrilir; ekleme, temel Recipe’nin değerlendirilmiş .locals alanını devralır; .attachment_name render edilen örneği adlandırır ve .provides eklemenin kendi çözümlenmiş provides değerlerini, yani tüketicinin okuduğu aynı torbayı taşır. Ortaya çıkan değerler sözlüğü FeatureRecipe’nin kendi capability’sinin adlandırdığı sağlayıcıya verilir ve render edilen dosyalar sınırın çıktısına iki koordinat taşıyarak eklenir — Feature’ın eklendiği bileşen, ardından eklendiği ad — böylece birkaç bileşene eklenmiş tek bir Feature adı her birini ayrı tutar. Bu koordinatların hangi biçimi alacağı host sağlayıcının kendi düzeninden çıkar: hedefin her katkıda bulunana kendi konumunu verdiği yerde bileşenin kendi dizininin yanında bir <component>--<instance>/ dizini, hedefin yalnızca doğrudan bir dizinde duran dosyaları okuduğu yerde ise bir <component>--<instance>-- dosya adı öneki. Yalnızca inject yapan FeatureRecipes — yalnızca injectMapping taşıyanlar, inject eşleme sırasında zaten işlenmiş olanlar — burada atlanır. Önceki alt aşamalar gibi özellik render aşaması da her seferinde bir bileşen için çalışır; bu yüzden bir ekleme normalde eklendiği bileşenden hemen sonra değerlendirilir. FeatureRecipe’si readsCallerRenderFacts: true veya readsTargetRenderFacts: true bildiren bir ekleme ise her bileşen ve ikisini de bildirmeyen her ekleme render edildikten sonra değerlendirilir — böylece host’una bağlanan her bileşen ve host’unun bağlandığı her bileşen o zamana kadar render edilmiş olur — ve çıktısı aksi halde yerleşeceği yere yerleşir.
    • Eklenti işlem hattı (Wasm adım yürütme): Derleyici Recipe’nin pipeline dizisini okur ve adımlarını bildirildikleri sırayla yürütür. Her adımın adlandırılmış Wasm eklentisini düğümün render edilmiş belgelerine karşı çalıştırır, adımın döndürdüğü RFC 6902 JSON Patch işlemlerini bu işlemlerin hedeflediği belgelere uygular ve adımın yan etkilerini bunların yanında üretir — bir Envoy sidecar enjekte etmek veya bir secret VolumeMount bağlamak gibi cerrahi mutasyonların arkasındaki yüzey budur. when: kapısı yanlış değerli (falsy) render edilen bir adım geçiş olarak atlanır ve belge kümesi sonraki adım için değişmeden kalır. Her adımın plugin URI’si, yürütmeden önce kilit dosyasının özetle sabitlediği doğrulanmış yapıt baytlarına çözümlenir. Bir FeatureRecipe’nin pipeline adımları da aynı şekilde, eklemenin kendi render edilmiş belgeleri üzerinde ve bileşen kapsamlı bir ekleme için bunların yanında host bileşeninkiler üzerinde yürütülür.

Üç Recipe girdi türünün üçü de derleyiciye ulaşır: source: + valuesMapping: temel render aracılığıyla, workload: iş yükü ayrıştırma ve iş yükü sentezi aracılığıyla, artifacts: ise yapıt değerlendirmesi aracılığıyla. Belirli bir sağlayıcıya bunlardan hangisinin verilebileceğine alt aşama alt aşama karar verilmez — bu, herhangi bir render gönderiminden önce, sağlayıcının kendi bildirdiği sözleşmeden, düğüm başına bir kez belirlenir; böylece girdi türünü bağlı sağlayıcının kabul etmediği bir Recipe render işleminin ortasında değil, orada reddedilir. Üç girdi türü bileşim modeli, Workload türü ve Artifacts mekanizması için bkz. 16-recipe-input-composition.md; hangi sağlayıcının hangi türü kabul ettiği için bkz. Dilin durumu.

GitOps’a özgü çıktı

Çıktısının nasıl uygulandığı konusunda kesinlikle kendi görüşü olmayan bir yapıda kalmak için render eklentileri, üretilen yapıtları temiz, sınırlara göre yalıtılmış bir dizin yapısına yazar (ör. dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Bu, harici GitOps denetleyicilerinin (ArgoCD veya Flux gibi) altyapıyı eşitleyip uygulamasına olanak tanır; Aggrega derleyicisinin canlı küme API kimlik bilgilerine hiçbir zaman ihtiyacı olmaz.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Altyapı kaynak haritası

Aggrega, ~30 satırlık bir Aggregate.yaml dosyasını binlerce satırlık fiziksel JSON veya YAML yapılandırmasına derler. Çalışan bir kaynağı kaynağına kadar izlemenin bir yolu olmadan, “main.tf.json satır 4.032” konumundaki bir hatayı ayıklamak geliştiricileri eşlemeyi elle yeniden kurmaya zorlar. Aggrega’nın render eklentileri bunu, izleme tanımlayıcılarını sağlayıcının yerel meta veri yüzeyine — Kubernetes için metadata.labels ve metadata.annotations, Terraform için bir köken yorumu ve sağlayıcı başına eşdeğer uzlaşımlar — birleştirerek ele alır; böylece render edilen her nesne geldiği kaynağa geri işaret eden bir işaretçi taşır. aggrega.ai/compiler-version etiketi (governance-and-compliance §5 içinde belgelenmiştir) bu ailedeki izleme anahtarlarından biridir; damga onun yanında aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri ve aggrega.ai/environment anahtarlarını taşır ve helm, helm-chart, compose, terraform ve cloudformation sağlayıcılarının her biri onu üretir — helm-chart sağlayıcısı, chart’ın kendi şablonlarını değiştirmeden kopyaladığı için bir Recipe’nin chart’a eklediği şablon dosyalarında.

Damga, özelliğin kökenini veya katalog türünü tanımlayan hiçbir anahtar taşımaz.

Derleyiciyle birlikte iki hata ayıklama yüzeyi daha gelir. aggrega build --trace, her aşamanın ne aldığını ve ne ürettiğini inceleyen bir Recipe yazarı için her düğümün ara durumunu geçiş geçiş .trace/ dizinine (dist/ yanında) yazar; ve derlemeyi durduran bir tanılama, hatanın ait olduğu bir yazım yüzeyi varsa o yüzeyin kategorisini — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR ve diğerleri — taşır; böylece doğru yazarı gösterir. Başarısız olan üretilmiş bir manifest alanını onu üreten şablon satırına kadar izleyen hatalar derleyicinin parçası değildir.

Doğrulayıcı işlem hattı

Çözümlemenin şema doğrulama aşaması, varlık spesifikasyonu içeriğini (kompakt biçim, JSON Schema YAML’ı veya karışık) yaprak başına köken bilgisi taşıyan birleşik bir JSON Schema 2020-12 belgesine dönüştüren ve ardından geliştiricilerin yazdığı örnek içeriğini buna göre doğrulayan bir doğrulayıcı işlem hattına dayanır. Beş evre sırayla saf dönüşümler olarak çalışır; her biri, bildirilen girdileri üzerinde deterministik bir fonksiyondur.

Evre 1 — Kompakt biçim derlemesi. Derleyici schema:, parameters: ve SchemaLibrary içeriğinin YAML ağacını dolaşır; düğüm başına yönlendirme yapar (kompakt biçim yaprağı, JSON Schema YAML’ı, $ref: başvurusu ya da bileşim); çözümlenmiş JSON Schema 2020-12 üretir. Kompakt biçim ve JSON Schema YAML’ı, $jsonschema: kaçışı aracılığıyla herhangi bir düğüm sınırında karışabilir; derleyici karışık durumu ağacı dolaşıp düğüm başına yönlendirme yaparak ele alır. Dönüşüm saf bir fonksiyondur: aynı kompakt biçim girdisi her zaman aynı JSON Schema çıktısını üretir. Anahtar sözcük dağarcığı için language-reference/vocabulary/compact-form-authoring.md sayfasına bakın.

Evre 2 — spec.templates ve $instantiate: çözümlemesi. Şablon başvurusu olarak yazılmış SchemaLibrary girdileri için derleyici, $instantiate:’i $args: ile çağıran her kitaplık girdisini dolaşır, parametre değerlerini değişmez skaler yerine koyma olarak yerleştirir ve somut şema girdileri üretir. Yerine koyma, kitaplığın her yüklenişinde bir kez çalışır; çözümlenmiş girdiler önbelleğe alınır. Kitaplık varlığının yazım biçimi için language-reference/entities/schemalibrary.md sayfasına bakın.

Evre 3 — Belgeler arası $ref: genişletmesi. $ref: aracılığıyla yapılan SchemaLibrary başvuruları için (kimlik biçimi <Library>#/schemas/<entry>), derleyici başvuru zincirini derleme zamanında bir çözümleme yığını taşıyarak dolaşır; başvurulan içerik tüketicinin şemasına satır içi yerleştirilir. Genişletme; döngü algılamayı (döngüler derlemeyi zinciri adlandıran bir hatayla durdurur), konum değil kimlik korumasını (registry ana bilgisayarı içeren bir başvuru derlemeyi durdurur ve kimlik biçimine yönlendirir — başvurular kitaplıkları fiziksel konumla değil kimlikle adresler) ve tek kaynaklı bileşimi ($ref: blokları yalnızca çıplak başvuruyu kabul eder; tüketici tarafı geçersiz kılmalar JSON Schema’nın allOf:’u ile birleştirilir) korur. Çözümleme anlambilimi için language-reference/vocabulary/cross-document-ref.md sayfasına bakın.

Evre 4 — featuresSchema: için köprü sentezi. Derleyici her varlığın featuresSchema: içeriğini yazar sırasıyla dolaşır ve her ek yuvasını bağlayabilecek bir dolgunun yapısını tanımlayan bir JSON Schema parçası üretir; inject izin listesi bildiren bir yuvaya x-aggrega-inject: uzantı anahtar sözcüğü eklenir. Bu parça, geliştiriciye dönük schema: içeriğine katılmak yerine yazılmış ek bloğuna karşı kendi başına derlenir ve denetlenir; uzantı anahtar sözcüğü, JSON Schema doğrulamasının yok saydığı bir meta veridir ve sonraki hiçbir evre onu parçadan geri okumaz — bir yuvanın izin listesine ihtiyaç duyan bir denetim yuvayı okur. usesSchema: soket tablosu hiçbir parçaya yansıtılmaz: bir soketin selector: ve inject: değerleri Mimar’ın yazdığı türlendirilmiş YAML olarak okunur ve bir soketin kenar başına valueSchema: / infraSchema: değeri kendi başına derlenir. Sentez, girdileri üzerinde saf bir fonksiyondur.

Evre 5 — Köken bilgili özel birleştirici. extends: bildiren varlıklar için derleyici üst zinciri dolaşır; üst varlığın çözümlenmiş JSON Schema’sı temel olur; alt varlığın geçersiz kılmaları bunun üzerine uygulanır. Çözümlenmiş şemadaki her yaprak, yaprak başına bir köken etiketi taşır (dosya yolu, satır numarası, üst veya alt kaynaklı olduğu). Birleştiricinin çıktısı doğrulayıcı motorun tükettiği şeydir; doğrulayıcı motor, değiştirilmemiş üçüncü taraf bir JSON Schema 2020-12 uyumlu uygulamadır ve bulguları sıralı üretmek için etrafında deterministik bir gezgin bulunur.

Beş evre, doğrulayıcı motor şemayı görmeden önce çalışır. Motor tek bir çözümlenmiş JSON Schema 2020-12 belgesi ile geliştiricinin örnek içeriğini alır; bir doğrulama raporu üretir. Hata biçimlendirici, kaynak konumlarını açıkça adlandıran kullanıcıya dönük tanılamalar üretmek için köken etiketlerine başvurur — bir Feature’ın kendisi yazmak yerine tabanından devraldığı bir kısıtın kaynak dosyası da buna dahildir.

Doğrulayıcı işlem hattı, her yükün ilk kez tamamlandığı yerde çalışır — çözümleme sırasında bir bileşenin values ve infra alanları, topoloji oluşturma onları dahil ettiğinde bir alt aggregate’in bileşenleri ve grafik sonlandırılırken bir eklemenin yükü — böylece bir şema bulgusu, statik analiz herhangi bir seçiciyi değerlendirmeden önce ve doğrulama ifadesi değerlendirmesinden önce derlemeyi durdurur; bu da doğrulama ifadesi şablonlarının doğrulanmış yüklere güvenmesini sağlar.

İşlem hattı boyunca determinizmin korunması

Derleme işlem hattının her evresi Deterministik Çıktı Değişmezini korur: aynı kaynak dosyalar, aynı kilit dosyası ve aynı derleyici sürümü verildiğinde, derleme bayt bayt aynı çıktıyı üretir. Değişmez temeldir — kilit dosyasında içerik adreslemesi kararlı yapıt özetleri gerektirir; yeniden üretilebilir derlemeler, geliştirici A’nın dizüstü bilgisayarında yazılan bir sürümün geliştirici B’nin dizüstü bilgisayarında ve CI’da aynı çıktıya derlenmesini gerektirir; fark incelenebilirliği, kaynak değişikliklerinin derlenmiş çıktıdaki tek değişiklikler olarak görünmesini gerektirir.

Determinizm, her dönüşümün uyduğu az sayıda disiplinle korunur:

  • Sabit yineleme sırası. Harita biçimli YAML üzerindeki her dolaşma sabit bir sırayla yinelenir, çünkü Go’nun yerel harita yinelemesi rastgeledir. Derleyici çoğu evrede yinelemeden önce sıralar (kompakt biçim derleyicisi, birleştirici, spec.templates çözümleyicisi, hata biçimlendirici, YAML serileştirici); ek yuvası izdüşümü ise yazarın kendi sırasını korur, böylece bir yuva tablosunun özellik sırası yazıldığı sıradır.
  • Zaman gömme yok. Derleme, çıktıya zaman damgası gömmez. Saat 14:00’teki bir derleme, saat 02:00’deki bir derlemeyle aynı yapıtı üretir. Birleştiricinin köken meta verisi dosya:zaman damgası değil, dosya:satır kullanır.
  • Çalışma alanına göreli yollar. Çözümlenmiş çıktıdaki tüm yollar çalışma alanına görelidir; yol çözümleme katmanı, yollar herhangi bir çıktıya girmeden önce onları normalleştirir.
  • Rastgele kaynak yok, harici durum yok. Dönüşümler, bildirilen girdileri (varlık içeriği, üst zincir, kilit dosyası) üzerinde saf fonksiyonlardır. Harici duruma yalnızca çözümleme sırasında (OCI yapıtlarının getirilmesi) başvurulur ve çözümlenmiş içerik özetle içerik adreslidir.
  • Kanonik YAML serileştirmesi. Çıktı, bir girdi için tek bir sabit biçimde yazılır: her çalıştırmada her derinlikte aynı anahtar sırası, diziler ve enum: dizileri girdi sırasında; 2 boşluklu girinti; Unix LF satır sonları; YAML’ın izin verdiği yerlerde tırnaksız dizeler; true/false mantıksal biçimi; bulunmayan alanlar için null atlanır.
  • $defs: alfabetik sırası. Şema $defs: girdileri, çözümlenmiş JSON Schema’da alfabetik anahtar sırasıyla üretilir. $defs: kavramsal olarak sıralı bir liste değil, bir sözlüktür; alfabetik sıra, kaynağın yeniden düzenlenmesi boyunca farkları öngörülebilir kılar.
  • Paralellik çıktıya yansımaz. Derleyici bağımsız birimleri paralelleştirebilir (farklı varlıklar eşzamanlı derlenebilir). Paralel sonuçlar serileştirilmeden önce deterministik bir yapıda toplanır (ör. varlık adına göre sıralanmış).

Derleyicinin uçtan uca testleri, her fikstürü tek bir test içinde birkaç kez derler ve her çalıştırmanın bayt düzeyinde aynı içeriğe sahip aynı dosyaları ürettiğini doğrular. Bir harita yineleme sırası sızıntısını veya sıralanmamış bir küme üzerindeki yinelemeyi yakalayan şey derlemenin tekrarlanmasıdır; bunlar çoğu çalıştırmada kararlı çıktı verir ve ara sıra ayrışır. Testler derleyicinin geri kalan test paketiyle birlikte çalışır.

Deterministik Çıktı Değişmezi derleme zamanında geçerlidir: aynı kaynak dosyalar + aynı kilit dosyası + aynı derleyici sürümü verildiğinde bayt bayt aynı çıktı. Kilitleme zamanındaki eşlik eden özellik (aynı kaynak dosyalar + aynı registry durumu verildiğinde aynı kilit dosyası) daha zayıftır — registry’ler değişkendir (yeni sürümler yayımlanabilir; yan araçlar eklenebilir; bileşen başına meta veriler değişebilir), bu nedenle aynı kaynak dosyalara karşı farklı zamanlarda yapılan iki kilitleme çağrısı farklı kilit dosyaları üretebilir. npm, Cargo ve Go’daki uzlaşımları yansıtan kilit dosyasının amacı da budur. Yeni bir kilit dosyasından derleme deterministik çıktı üretir. İki anın ayrılması, registry tarafındaki değişkenliği katlanılabilir kılan şeydir: T2 zamanında yayımlanan bir yan araç bir sonraki kilitleme çağrısını değiştirir; T1 zamanında üretilen kilit dosyasına karşı yapılan derlemeleri değiştirmez.