Recipe
Recipe varlığının kavramsal rolü (Geliştirici Niyetini fiziksel biçime eşleyen, Ops tarafından yazılan çeviri şablonu) architecture/04-entity-taxonomy.md sayfasında açıklanır. Bu sayfa Recipe yazım yüzeyini ele alır: işaretçi (source), eşleyici (valuesMapping:), yerel IaC desteği ve çalışılmış örnekler.
Recipe mimarisi: İşaretçiler ve eşleyiciler
Bir Recipe tam olarak iki işlev görür:
- İşaretçi (
source): Derleyiciye altyapı kodunun tam olarak nerede bulunduğunu söyler. - Eşleyici (
valuesMapping): Aggrega’nın soyut bağlamını, alttaki kodun beklediği belirli değişkenlere enjekte eder. Alan, üç yazım kipine sahip tek bir Go template yüzeyidir — satır içi blok skaler, dosya$import:veya kütüphane$import:— ve içeriğin biçimine göre yönlendirilir. AşağıdakivaluesMappingalanı — üç yazım kipi bölümüne bakın.
Bir Recipe bir işleme yeteneğiyle kesinlikle 1:1 ilişkili olduğundan, bu yetenek (spec.capability) kök düzeyde açıkça bildirilir; böylece Go derleyicisi hangi aşağı akış Wasm işleme plugin’ini çağıracağını tam olarak bilir.
spec.implements, Recipe’nin hangi katalog bileşen türünü uygulayabildiğini bildirir. Derleyici bunu Manifest eşlemelerini doğrulamak (eşlenen bir Recipe’nin implements değeri eşlenen türle eşleşmelidir) ve aday önermek için kullanır — adaylar, eşleme bulunmadığını bildiren tanılamada listelenen ve düzenleyici tamamlamasında ilk sıraya konan recipe’lerdir. Bir derlemeyi asla çözümlemez: Manifest eşlemesi, kullanıcının lockfile’da sabitlenmiş açık dağıtım tercihidir. implements değeri sürümsüz, tam sürüm veya ana sürümle uyumlu bir aralık olan bir Recipe de kendini bir tür için yalnızca önerir; tercihi kullanıcı sabitler. FeatureRecipe.spec.implements, özellik türleri için aynı rolü taşır.
A. Wasm güdümlü kaynak şemaları
Uygulama önyargılarını derleyicinin dışında tutmak için source bloğu sabit bir altyapı alanları kümesi değildir. source alanı iki biçimi destekler:
- Evrensel dize (hızlı ve temiz): Yerel yollar, OCI yapıtları ve Git depoları için en uygunudur. Derleyici, getirme yöntemini dizenin önekinden ve sonekinden (
./src,https://github.com/example/module.git,oci://...) çıkarır:.gitile biten ya dagit://veyassh://ile yazılmış bir URL, varsayılan dalından getirilen bir Git deposudur; ne bir depoyu ne de bir.tgzchart’ını veya.yamlparçasını adlandıran birhttps://URL’si belirsiz olduğu gerekçesiyle reddedilir. - Açık yapılandırılmış nesne: Anahtarları provider tarafından tanımlanan ve Recipe’nin şablonlarına
.source.*olarak (örneğin.source.chart) sunulan açık bir sözlüktür (additionalProperties: true). Tasarımın amacı, her provider’ın WebAssembly soketinin kendi kaynak biçimini tanımlaması ve doğrulamasıdır (örneğin Helm içinregistry/chart/appVersion).
Çekirdeğin çözümledikleri. Hiçbir provider kendine ait kaynak anahtarlarını doğrulamaz. Getirilen bir kaynak, kind değeri bir çözümleyici seçen yerleşik bir kimlikle çözümlenir — helm-oci-chart, helm-https-chart, compose-https-fragment ve git-repository. Getirilmesi amaçlanan bir kaynak kind ve url taşımalıdır; içeriği hangi ek koordinatın seçtiği türe bağlıdır. Chart ve fragment türleri version alır ve onu yazıldığı gibi sabitler. git-repository, ref alır — bir etiket, bir dal veya bir commit — ve isteğe bağlı olarak, depo içinde yapıt olan dizini adlandıran module_subdir alır; yalnızca bir commit yeniden yönlendirilemeyen içeriği adlandırdığından, referans kilitleme zamanında çözümlenir ve lockfile hem yazılan referansı hem de çözümlendiği commit’i kaydeder. Yazıldığı haliyle deponun üstüne çıkan bir module_subdir — ters eğik çizgi de ayırıcı sayılır — herhangi bir şey getirilmeden önce reddedilir. Depo kendi checkout’undan arşivlenir: deponun commit ettiği bir sembolik bağlantı, gösterdiği yer depo içindeyse gösterdiği dosya veya dizin olarak arşivlenir; depo dışına çıkan bir bağlantı ise bağlantıyı depodaki yeriyle adlandırarak çekmeyi durdurur. url: değeri bir dosya sistemi yolunu adlandıran yapılandırılmış bir kaynak getirilmez: yalın bir yol dizesiyle aynı koşullarda diskten okunur; göreli bir url:, onu bildiren varlık dosyasını içeren dizine göre bağlanır. kind/url içermeyen yapılandırılmış bir kaynak da getirilmez ve getirme amaçlanmışsa derleme, sessizce hiçliğe çözümlenmek yerine kilitleme zamanındaki kaynak inişinde açıkça durur. İçerik her zaman önceden sabitlenir; derleyici asla canlı çalışma zamanı durumunu getirmez.
Recipe’nin yanında sabitlenenler. kind, url, chart, module_subdir, version ve ref değerlerinin tümü şablonla değil açıkça yazılmış olan getirilmiş bir kaynak için aggrega pin, getirdiği şeyin özetini (digest), Recipe’nin kendi dizininde bulunan ve onun yanında commit ettiğiniz bir dosya olan entity.lock içine kaydeder. Sabitleme Recipe yazarının adımıdır ve Release gerektirmez; kilidi sabitlemeyi kaydetmeyen bir Recipe üzerindeki çekme, çekmeden aynı adımı çalıştırması istenmedikçe durur ve bunu adlandırır. Bir derleme bu özeti, Release’in lockfile’ının aynı kaynak için kaydettiği özetle karşılaştırır ve ikisi uyuşmadığında durur — git ref: ile yazılmış bir kaynak bunun dışındadır; onun satırı ref’in çözümlendiği commit’te kaydedilir ve karşılaştırılmaz. Koordinatları bir şablondan doldurulan getirilmiş bir kaynak ise Release başına, her Release’in lockfile’ında sabitlenir. Recipe’nin yanındaki bir dizini veya dosyayı adlandıran bir kaynak getirilmez: aggrega pin, Recipe’nin bir yayınının taşıdığı içeriğe kattığı her dosya için bir özet kaydeder — şablon olarak yazılmış bir kaynak için Recipe’nin dizinindeki her dosya — ve kilit bunları kaydettikten sonra derleme, provider kaynağı okumadan önce kaynağı bunlarla karşılaştırır; sabitlemeden bu yana eklenen, değiştirilen veya kaldırılan bir dosyada E0305 ile durur, ya da değişiklikten önce yazılmış Release lockfile’ı Recipe’yi taşıdığı içerikle kaydediyorsa önce E0130 ile durur. Böyle bir kaynak için sabitleme kaydetmeyen bir kilit, derlemeye karşılaştıracak hiçbir şey bırakmaz ve sabitleme yapmayan bir çekme veya yayın onu reddeder. Recipe dosyasının kendisine asla yazılmaz. aggrega pull dosyayı ve her durmanın nasıl yanıtlanacağını açıklar.
spec.capability, implements alanının aldığı biçimlerde bir sürüm sabitlemesi taşıyabilir — tam (helm:<version>) ya da şapka aralığı (helm:^<version>) — ve bu, Recipe’i provider eklentisinin hangi sürümünün işleyeceğini seçer; hiçbir kullanılabilir sürümün karşılamadığı bir sabitleme derlemeyi durdurur. Sabitlenmemişse (spec.capability: "helm"), kullanılabilir en yüksek sürüm işler. Kullanılabilir sürümler aggrega plugin list komutunun gösterdikleridir: aggrega içine yerleşik provider’lar derleyicinin kendi sürümünü taşır. Sabitleme Recipe’in adının bir parçası değildir: bir Manifest, capability: "compose:1.2.3" bildiren bir Recipe’i tam olarak sabitlenmemiş bir Recipe gibi compose/<name>:<version> olarak eşler ve sabitlemeyi değiştirmek onu asla yeniden adlandırmaz; sabitlemeyi ada yazan bir eşleme değeri (compose:1.2.3/<name>:<version>) herhangi bir şey aranmadan önce hatalı biçimlendirilmiş bir recipe başvurusu olarak reddedilir (E0095).
Zihinsel model: spec.capability istediğiniz çıktı biçimini adlandırır (örneğin helm, terraform, compose); derleyici bunu o biçimi işleyen Wasm plugin’ine (örneğin provider/helm) çözümler. Biçimi siz bildirirsiniz; aracı Aggrega bağlar.
B. Bağlam enjeksiyonu: Anlamsal eşleme katmanı
Derleyicinin birden çok ortam arasında tehlikeli ve deterministik olmayan derin birleştirmeler yapmasını önlemek için bir Recipe, eşleme katmanı için yalnızca tek bir doğruluk kaynağına izin verir.
Ops mühendisleri, Wasm işleme eklentisi çalışmadan önce soyut bağlamı çevirmek için eşleme içeriğini yazar. Eşleme dili Go template’tir (text/template + Sprig); Sprig kütüphanesi önceden kayıtlıdır; standart define ve template eylemleri desteklenir ve include kayıtlı değildir.
| Alan adı | Kapsam ve yürütme aşaması | En iyi kullanım durumu |
|---|---|---|
injectMapping (yalnızca FeatureRecipe) | İşleme öncesi araya girme. Go belleğinde temel Recipe’ten önce değerlendirilir. Çıktı sözlüğünü doğal olarak, kesinlikle çağıranın .context.inject borusunun üzerine derin birleştirir. Temel Recipe şemasında bilinçli olarak yer almaz; mimari gerekçe için entities/featurerecipe sayfasına bakın. | Enjekte edilen env değişkenlerini cerrahi biçimde yeniden yazmak veya bir çağıran için FQDN’leri Wasm JSONPatch gerektirmeden biçimlendirmek. |
valuesMapping | Temel işleme (Go template). Değişkenleri alttaki source altyapı chart’ına/modülüne eşlemek için değerlendirilir. Tek alan, üç yazım modu (satır içi, dosya $import:, kütüphane $import:). Dağıtım mekanizması için aşağıdaki alt bölüme bakın. | Standart değişkenleri (replika sayısı veya imaj etiketleri gibi) doğrudan Recipe YAML’ında bir Helm chart’ına eşlemek ya da Recipe’ler arası yeniden kullanım için $import: ile paylaşılan bir şablona başvurmak. |
Not: injectMapping yalnızca FeatureRecipes’e özgüdür ve değişken araya girmesini valuesMapping alanından yalıtır. Temel Recipe’in valuesMapping alanı, FeatureRecipe injectMapping bloklarının ürettiği yeniden yazılmış .context.inject dizelerini farkında olmadan tüketir; böylece ikisi birbirinden ayrık kalır.
valuesMapping alanının null olarak yazdığı bir anahtar sağlayıcıya null olarak ulaşır ve orada ne yapacağına sağlayıcı karar verir; bu yüzden her sağlayıcı sayfası bunu belirtir: helm chart’ın o anahtar için varsayılanını kaldırır, helm-chart onu şemsiyenin values’una yazar, compose onu compose dosyasına yazar, terraform onu null modül argümanı olarak yazar ve cloudformation onu reddeder.
valuesMapping alanı — üç yazım modu
Bir Recipe’in valuesMapping: alanı, üç dağıtım modunu kabul eden tek bir Go template yüzeyidir. Derleyici, alanın içerik biçimine göre dağıtım yapar; $mode: ek açıklaması gerekmez.
Mod 1: Satır içi Go template (YAML blok skaleri). Alanın değeri, YAML blok skaleri | biçiminde yazılmış bir dizedir:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}Satır içi mod, eşleme içeriği küçük ila orta boyutta (yaklaşık 50 satırın altında) olan Recipes için tipik yazım biçimidir. Şablon gövdesi Recipe zarfının geri kalanıyla birlikte satır içinde durur; Recipe’in içeriği kendi kendine yeterlidir.
Mod 2: Dosya $import:. Alanın değeri, yerel bir dosya yoluyla yalnızca $import: içeren bir eşlemdir:
spec: valuesMapping: $import: ./mappings/api-server.tmplDerleyici dosyanın içeriğini (bir Go template) yükler, standart Recipe şablon bağlamına göre işler ve sonucu eşleme çıktısı olarak ele alır. Yol çözümlemesi Recipe’in dizinine görelidir — göreli bir yol, derlemenin çağrıldığı dizine değil, onu bildiren recipe.yaml dosyasını içeren dizine bağlanır — ve yol, İçerik yolları Recipe’in kendi dizininde kalır bölümünün açıkladığı gibi bu dizinin içinde kalmalıdır. Dosya modu, orta ila büyük eşleme içeriğine (yaklaşık 50+ satır) ve eşleme değişikliklerinin bağımsız dosya farkları olarak göründüğü inceleme düzenlerine uygundur.
Mod 3: Kütüphane $import:. Alanın değeri, bir MappingLibrary girdisine yalın adlı kimlik başvurusuyla yalnızca $import: içeren bir eşlemdir:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreDerleyici başvuruyu çözümlenmiş MappingLibrary kümesine (yerel katalog ile lockfile’da sabitlenmiş tüm kütüphaneler) karşı çözümler, girdinin içeriğini yükler ve eşleme çıktısı olarak ele alır; gövdesi kendisi bir alan kökü $import: olan bir girdi özyinelemeli olarak çözümlenir. Başvuru hiçbir kayıt defteri ana bilgisayarı taşımaz — kütüphane adı kimliğe göre çözümlenir ve sürüm Release başına lockfile’dan gelir; isteğe bağlı bir :<version> en düşük sürüm tabanı da verilebilir (<Library>:<version>#/mappings/<entry>). Kütüphane içeriği standart Recipe şablon bağlamını paylaşır. Kütüphane modu Recipe’ler arası yeniden kullanıma uygundur — birçok Recipes genelinde yinelenen eşleme kalıpları (veri deposu yardımcı mantığını paylaşan birden çok veri deposu Recipe’i; pod şablonu kalıplarını paylaşan birden çok Helm sağlayıcısı Recipe’i). MappingLibrary varlığı sürümleme, lockfile sabitleme ve hub arayüzünde görünürlük sağlar.
Dağıtım kuralları. Derleyici YAML düğümünü dolaşır ve içerik biçimine göre dağıtım yapar:
- Düğüm bir dize skaleriyse satır içi mod (Mod 1) olarak dağıtılır.
- Aksi hâlde düğüm bir eşlemdir;
$import:anahtarı aranır. $import:değeri yalın adlı bir kütüphane başvurusuysa (<Library>#/mappings/<Entry>, isteğe bağlı olarak bir:<version>tabanıyla) kütüphane modu (Mod 3) olarak dağıtılır.- Aksi hâlde (yerel bir dosya yolu) dosya modu (Mod 2) olarak dağıtılır.
- Diğer her biçim (
$import:içermeyen bir eşlem,$import:dışında ek anahtarlar içeren bir eşlem vb.) derleme zamanı hatası üretir.
Yalnızca tek kaynaklı $import:. $import: tek bir kaynak kabul eder. valuesMapping: alanında çok kaynaklı birleştirme desteklenmez. Birden çok eşleme parçasını birleştirmesi gereken bir Recipe, dahili Go template define / template birleşimine sahip bir MappingLibrary girdisi, kardeş dosyaları çağıran Go template template yönergelerine sahip yerel bir dosya ya da kısa içerik için satır içi birleşim kullanır. Kütüphane varlığı için entities/mappinglibrary, daha geniş $ref: / $import: ayrımı için vocabulary/cross-document-ref sayfasına bakın.
Köken. Şablon işleme hatalarından gelen hata iletileri her mod için uygun kökeni belirtir: satır içi şablonlar blok skalerinin başladığı Recipe dosya:satır konumunu; dosya içe aktarmaları içe aktarılan dosyanın içeriğini; kütüphane içe aktarmaları ise MappingLibrary girdisinin kaynak konumunu belirtir ve kararlı başvurular için kanonik işaretçi olarak ana bilgisayarsız kütüphane kimliğini (<Library>#/mappings/<entry>) kullanır — başvurudaki bir kayıt defteri ana bilgisayarı reddedilir, böylece fiziksel konum işaretçiye asla girmez.
C. Yerel IaC desteği
Kendi kod olarak altyapısını getiren bir Ops ekibi onu Recipe’in kendi dizininde tutar — source: ile adlandırılan, ./src gibi bir modül veya şablon dizini — ya da yapılandırılmış bir source: ile getirir (kind: git-repository ile git deposundan alınan bir Terraform modülü) ya da artifacts: altında şablonlu gövdeler olarak yazar. Eşleme katmanı (valuesMapping: — satır içi, dosya içe aktarma veya kütüphane içe aktarma) bu koda soyut bağlamı sağlar ve provider sonucu hedefin kendi biçiminde üretir; hiçbir yapılandırma dili bir başkasına dönüştürülmez:
- Terraform: bir modül dosya dosya kopyalanır ve yazılmış bir gövde tam olarak yazıldığı gibi üretilir; yerel HCL (
main.tf) ve Terraform JSON (.tf.json) için de aynısı geçerlidir —terraformCLI ikisini de okur. Sınırın kök yapılandırmasıaggrega.modules.tf, her bileşenin dizinini birmodulebloğu olarak çağırır ve kaynaklı bir modülünvaluesMapping:çıktısı o bloğun argümanları olur. Bkz. terraform provider’ı. - CloudFormation: YAML veya JSON kaynaklı bir şablon ve bir Recipe’in yazdığı kaynak parçaları uzun biçimli JSON’a normalleştirilir ve sınır başına tek bir yığın şablonunda birleştirilir;
valuesMapping:çıktısı, kaynaklı şablonun bildirdiği parametreleri doldurur. Bkz. cloudformation provider’ı.
Yalnızca altyapı uygulandıktan sonra var olan bir değer, hedefin çözümlediği bir işaretçi olarak kalır — bir Terraform ${ ... } enterpolasyonu, bir CloudFormation Ref ya da Fn::GetAtt — ve derleme zamanında hiçbir zaman değerlendirilmez.
Örnek A: Uzak Helm chart’ı (satır içi eşleme ve locals sözleşmesi)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Örnek B: Yerel Terraform modülü (dosya eşlemesi)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Örnek C: Somut Component Recipe’i (altyapıyı bağlar)
Ops, genel arayüzü fiziksel gerçekliğe eşler. (L4 ağ ayrıntıları burada bağlanır — ya sabit kodlanarak ya da aşağıdaki proxy portunda olduğu gibi Release’in doldurduğu infra bloğundan alınarak.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Bulut kaynağı adlandırma disiplini.
Bulut kaynağı adları üreten Recipes — S3 bucket adları, RDS veritabanı tanımlayıcıları, IAM rol adları, CloudFormation stack adları ve değeri bulut sağlayıcısında küresel bir ad alanını işgal eden diğer her alan — aynı Recipe birden çok Releases veya bileşen örneği genelinde çalıştığında çakışmaları önlemek için oluşturulan ada {{ .metadata.release_name }} ve/veya {{ .context.instance_id }} eklemelidir. Örnek B’deki bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" standart kalıptır.
Disiplin, tek bir küresel ad alanının adı kısıtladığı her yerde geçerlidir. AWS S3 bucket adları bir bölgedeki tüm hesaplar genelinde küresel bir ad alanını paylaşır; aynı Aggregate’in iki Releases’i (prod-billing ve staging-billing) customer-data adlı bucket’ları birlikte dağıtamaz — ikinci dağıtım çalışma zamanında AWS tarafındaki bir retle başarısız olur. release_name eklemek Release’i ayırt eder; context.instance_id eklemek bileşen örneği başına ayırt eder; ikisini birden eklemek bileşen başına ve Release başına ayırt eder.
Derleyicinin denetlediği ve denetlemediği şeyler. Derleyici, valuesMapping: çıktılarını bu enterpolasyonlar olmadan bulut kaynağı adı alanları için incelemez. Disiplini Recipe yazarları (hedef sağlayıcı için hangi alanların küresel olarak benzersiz kaynakları adlandırdığını bilenler) ve inceleyiciler (adlandırılmamış kaynak kalıplarını PR incelemesinde yakalayanlar) sürdürür. Bir linter eklentisi, valuesMapping: çıktıları release_name / instance_id enterpolasyonu olmadan bulut kaynağı adı alanlarına başvuran Recipes’i işaretleyebilir; linter soketi sunulmaktadır ve aggrega lint üzerinden çalışır (bkz. plugins/plugin-contract.md “Placement criterion: the linter socket vs the governance verdict roles”), ancak yayımlama linter’ının kurallarından hiçbiri bunu denetlemez.
Bu disiplin, uzlaşımla sürdürülen birkaç toplumsal sözleşmeden biridir — yazarların derleyici zorlamasından değil belgelerden öğrendiği yazım disiplini. Uzlaşımların tam listesi ve her sözleşmenin sınıflandırmasının mimari gerekçesi için vocabulary/social-contracts.md sayfasına bakın.
Source alanında şablon kullanımı.
Bir Recipe’in source alanı kendisi de bir şablon yüzeyidir. source alanının her iki biçimi de Go şablonlarını kabul eder: evrensel dize biçimi
source: "{{ optional .infra `module_path` \"./src\" }}"ve yapılandırılmış nesne biçimi (dize değerli her alt alan şablon olarak değerlendirilir; dize olmayan alt alanlar olduğu gibi geçer). Bir source şablonunun neyi okuyabileceği, source’un uzak bir yapıtı adlandırıp adlandırmadığına bağlıdır. Uzak bir source’un koordinatı — bir registry’yi, bir chart deposunu veya bir git deposunu adlandıran yapılandırılmış bir bloğun version, chart, ref ve module_subdir alanları — aggrega pull yapıtı sabitlemek için çözümlediğinde değerlendirilir; bu değerlendirme yalnızca .values, .infra ve .locals üzerinde, Aggrega’nın kendi yardımcılarıyla (optional, capitalizedWords ve index) ve Sprig işlevlerinin hiçbiri olmadan yapılır. .context bu yüzeyde yer almaz; dolayısıyla bir bileşen için hangi yapıtın sabitleneceğine, ona verilen values ve infra karar verir, hiçbir zaman örnek adı karar vermez. Orada değerlendirilen locals: girdileri, bu alanların okuduğu girdiler ve böyle bir girdinin de okuduğu girdilerdir: hiçbir source alanının okumadığı bir girdi, source çözümlenirken değerlendirilmez; bu nedenle yalnızca render işleminin ihtiyaç duyduğu bir local — bir Sprig işlevi çağıran ya da .context.instance_id okuyan bir local — sabitlemeyi etkilemez ve düğüm render edilirken değerlendirilir. .locals değerini tek bir girdiyi adlandırmayacak biçimde okuyan bir alan, örneğin {{ index .locals "version" }}, tüm girdilerin değerlendirilmesine yol açar. Yukarıdaki gibi çalışma alanındaki bir yolu adlandıran bir source sabitleme için çözümlenmez: şablonu düğüm render edilirken, Recipe locals ile aynı kendi kendine yeten bağlamda — .context.instance_id, .values, .infra ve .locals, yani düğümün çözümlenmiş bloğunun tamamı — değerlendirilir; bu yüzden bir locals: girdisiyle aynı başvuru köklerini kabul eder ve reddeder, tek farkı lehinedir: yalnızca kendinden önceki girdileri değil, bloğun bildirdiği herhangi bir girdiyi okuyabilir. Uzak bir koordinat da aynı şekilde bloğun bildirdiği herhangi bir girdiyi okuyabilir. .provides iki bağlamda da yer almaz; kendi düğümünün provides değerlerine uzanan bir source şablonu derlemeyi durdurur ve sorunlu başvuruyu adlandırır. Bu, ileride yapılacak bir çalışmayı bekleyen bir eksiklik değil, yüzeyin sabit bir özelliğidir — bir düğümün locals değerleri, provides: alanının .locals okuyabilmesi için provides değerlerinden önce çözümlenir ve bir source şablonu ileriye, provides değerlerine uzanmak yerine aynı çözümlenmiş locals değerlerini okur. .context.inject ve .context.uses başvuruları da aynı kendi kendine yeterlilik gerekçesiyle yasaktır; source URI’si, topoloji kanalı doldurulmadan ve aşağı akıştaki herhangi bir şey URI’nin gösterdiği chart, modül veya yapıt gövdesini yüklemeden önce çözümlenmelidir. Tüm kullanılabilirlik kuralları ve yasaklı başvuruların gerekçesi Şablon Genişletme Matrisi satır #5 içinde yer alır. Standart kullanım, Component tarafından sunulan bir infra.source_version geçersiz kılmasının source’un version alanına aktarılmasıdır — bkz. entities/component “infra sütunu” — böylece bir katalog, uyumlu her üst akış sürüm artışında bir Recipe’i yeniden yayımlamak zorunda kalmaz.
Source alanı şema envanteri. source: alanı şemada birkaç biçim varyantını kabul eder. Her varyantın çalışma zamanı desteği sağlayıcıya göre değişir; aşağıdaki tablo her biçimin ne yaptığını belgeler.
| Biçim | Örnek | Durum |
|---|---|---|
| Yalın göreli dosya sistemi yolu | source: "./charts/postgres" | available — sunulan her sağlayıcı (helm, helm-chart, compose, terraform, cloudformation) yalın bir dosya sistemi yolu dizesini kabul eder. |
| Yalın mutlak dosya sistemi yolu | source: "/abs/path/to/chart" | accepted but blocked — şema bunu kabul eder ve Recipe’i okuyan her komut reddeder: mutlak bir yol, Recipe’in kendi dizinindeki içeriği değil, yazıldığı makinedeki bir yeri adlandırır; dolayısıyla Recipe ile birlikte taşınmaz. Chart’ı Recipe’in dizinine taşıyın ve ona göreli olarak adlandırın; bkz. İçerik yolları Recipe’in kendi dizini içinde kalır. |
| Boş dize | source: "" | accepted but blocked — şema boş dizeyi kabul eder ve Recipe’i yükleyen her komut, Recipe okunurken onu reddeder; çünkü boş bir dize iki moddan hiçbirini adlandırmaz. Ret, belirsizliği, ondan çıkmanın iki yoluyla birlikte adlandırır: kaynaksız mod için alanı çıkarın ya da kaynaklı mod için gerçek bir yol veya URI verin. aggrega validate <recipe-file> bunu Recipe için bildirir; aggrega pull, aggrega build ve aggrega validate --release ise Recipe’e ulaşan bir Release için bildirir. Bkz. errors/fatal-halts.md “Recipe source: is an empty string (Recipe source: boş bir dizedir)”. |
url: alanı bir aktarım şeması taşıyan yapılandırılmış nesne | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — yerleşik kaynak çözümleyici {kind, url, version, chart, ref, module_subdir} biçimini okur (türü url: alanının şeması seçer — oci:// → OCI chart, https://….tgz → chart arşivi, chart: ile eşlenen https:// depo kökü → depo chart’ı — ya da türü kind: ile adlandırabilirsiniz), yapıtı aggrega pull sırasında getirip sabitler ve derleme onu önbellekten çıkarır. Bir chart’ı yerel olarak kopyalamak alternatif olarak desteklenir, ancak gerekli değildir. Şema açık bir yapılandırılmış nesneyi kabul eder. Bkz. providers/helm.md “source: anahtar kümesi”. |
url: alanı bir dosya sistemi yolunu adlandıran yapılandırılmış nesne | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — taşıma şeması taşımayan bir url: bir yolu adlandırır; bu nedenle hiçbir şey indirilmez ve hiçbir şey sabitlenmez, derleme içeriği diskten okur. Göreli bir url:, onu bildiren recipe.yaml dosyasını içeren dizine göre konumlandırılır ve bu dizinin dışına çıkan biri (mutlak olanlar da dahil) reddedilir: bu, yukarıdaki iki yalın yol satırının aldığı yorumun aynısıdır ve onu hangi biçimde yazdığınız bunu değiştirmez. İçeriğin nereden okunacağına yalnızca url: karar verir; diğer alanlar neyin indirilmiş olacağını seçer ve Recipe’in şablonlarına yine .source.* olarak ulaşır. |
OCI URI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — katalog dağıtımı için tasarım hedefi. Bugünkü üç katmanlı çözümleyici (bir Release’in yoluyla adlandırdığı dosyalar, çalışma alanı katalogları, uzak OCI kayıt defteri) architecture/13-catalog-and-registry.md belgesinde açıklanmıştır; varlık düzeyindeki çözümleyici OCI URI’lerini bu kademe üzerinden kullanır, ancak Recipe başına source: alanının OCI biçimi bugün sağlayıcılarda bağlanmış değildir. |
Diğer URL şemaları (https://, git+https:// vb.) | (örnek amaçlı) | planned — mimarinin takılabilir kaynak yol haritasında tasarım amacı olarak belgelenmiştir; bugün hiçbir sağlayıcı desteği yoktur. |
Bir source: yolu nasıl bağlanır.
Bağlama yalnızca dosya sistemi yollarına uygulanır ve yolu iki biçimden hangisi taşırsa taşısın uygulanır. Göreli bir yol, onu bildiren recipe.yaml dosyasını içeren dizine bağlanır ve bu dizinden çıkan bir yol — mutlak yol dahil — İçerik yolları Recipe’nin kendi dizini içinde kalır bölümünde açıklandığı gibi reddedilir. Aktarım şeması taşıyan bir başvuru — oci://, https://, http://, git://, ssh://, git+ssh:// ya da .git ile biten herhangi bir başvuru — bir yol yerine getirilecek bir şeyi adlandırır; bu nedenle tam olarak yazdığınız gibi aktarılır ve hiçbir zaman bir dizinle birleştirilmez.
Yapılandırılmış biçimde yol url: alanıdır ve aynı şekilde okunur: göreli bir url:, recipe.yaml dosyasını barındıran dizine bağlanır, o dizinin dışına çıkan bir değer reddedilir ve bir aktarım şeması taşıyan bir değer getirilir. Yapılandırılmış bir source: alanının diğer tüm alanları, provider tarafından tanımlananlar da dahil olmak üzere, olduğu gibi aktarılır.
Şablon olarak yazılmış bir source:, şablonun kendi metnine göre değil, şablonun ürettiği değere göre bağlanır. Bir şablon değerlendirilene kadar hiçbir şeyi adlandırmaz; bu nedenle yukarıdaki okuma onun sonucuna uygulanır: göreli yol olan bir sonuç recipe.yaml dosyasını içeren dizine bağlanır, bu dizinden çıkan bir sonuç — mutlak yol dahil — derlemeyi durdurur ve aktarım şeması taşıyan bir sonuç aktarılıp getirilir. Bu yüzden bir şablon yukarıdaki envanterdeki biçimlerden herhangi birini üretmekte serbesttir ve her biri, aynı değer doğrudan yazılmış olsaydı nasıl ele alınacaksa tam öyle ele alınır; fark yalnızca yolun ne zaman değerlendirilebildiğidir; bu, bir şablon için Recipe okunduğunda değil, derleme onu değerlendirdiğinde gerçekleşir.
Hiçbir şey üretmeyen — boş sonuç veren — bir şablon, Recipe’yi kaynaksız bırakır; bu da kaynaksız moddur. Bu, source: "" değerini kendiniz yazmaktan farklıdır; o, iki moddan hiçbirini adlandırmaz ve reddedilir; yukarıdaki envanter satırına bakın.
Envanter, yazarların source: alanına neler koyabileceğine ilişkin kanonik başvurudur; etiketleri 10-status.md sayfasının tanımladıklarıdır.
İçerik yolları Recipe’in kendi dizininin içinde kalır
Bir Recipe’in içeriği, Recipe’in kendi dizininde bulunur, çünkü onun bir yayınının taşıdığı her dosya oradan alınır. Bir Recipe’in taşıdığı içerik için yazdığı her yol — ister yalın bir yol ister yapılandırılmış biçimin url: alanı olsun source: alanı ve valuesMapping:, workload: ve artifacts: girdilerinin $import: ile içe aktardığı her dosya — recipe.yaml dosyasını barındıran dizine göre okunur ve bu dizinin içinde kalmalıdır. Bu yollar aynı zamanda bir yayının taşıdığı şeydir: adlandırdıkları dosyalar Recipe ile birlikte taşınır, dizinindeki başka hiçbir şey taşınmaz (bkz. aggrega push). Dizinin dışına çıkan bir yol, Recipe ile birlikte taşınmayacak bir dosyayı gösterir; bu nedenle dosya, onu tüketen kişi için orada olmaz ve onun üzerine kaydedilen bir sabitleme, bu kişinin elde edemeyeceği baytlara kefil olur.
Dizinin dışına iki biçim çıkar ve her ikisi de reddedilir:
../shared/charts/appgibi dizinin üstüne çıkan bir yol;/opt/charts/appgibi, yazıldığı makinedeki bir yeri adlandıran mutlak bir yol.
Yukarı çıkıp yeniden içeri dönen bir yol, dizinin içindeki sıradan bir yoldur: ./charts/../values.tmpl, Recipe’in yanındaki values.tmpl dosyasını adlandırır. Değerlendirilen, yolun nereye vardığıdır ve bu, Recipe’in dizininden, dizinden çıkmadan ölçülür; bu nedenle dönüş yolunda dizini yeniden adlandıran bir dışarı çıkış da, örneğin 1.0.0 adlı bir dizinde yazılmış ../1.0.0/values.tmpl, reddedilir. Dizinin kendi adı taşınmaz: yayımlanmış bir Recipe, tüketicinin önbelleğinin adlandırdığı bir dizinden okunur ve orada bu ad hiçbir şey bulmaz.
Nerede reddedilir. Recipe’i okuyan her komut, böyle bir yolu okuduğu anda, herhangi bir şey getirilmeden, işlenmeden veya yayımlanmadan önce reddeder: katalog üzerinde ya da Recipe’in kendi dosyası üzerinde aggrega validate, aggrega pull, aggrega build, aggrega pin ve aggrega push. Şablon olarak yazılmış bir source:, derleme onu değerlendirene kadar hiçbir şey adlandırmaz; bu nedenle dizinin dışında bir yol üreten bir şablon, değerin oluştuğu anda derleme tarafından reddedilir. Durma, A path names content outside the entity’s own directory (Bir yol, varlığın kendi dizininin dışındaki içeriği adlandırıyor) hatasıdır ve yazdığınız yolu belirtir.
Bunun yerine ne yapılmalı. Dosyayı Recipe’in dizinine veya onun altındaki bir dizine koyun ve Recipe’e göre göreli olarak adlandırın: ./charts/app, ./extras/netpol.yaml. Birkaç Recipe’in kullandığı bir chart, her Recipe ayrı yayımlandığı için her Recipe’in dizinine kopyalanır; birkaç Recipe’in paylaştığı bir eşleme, iş yükü veya yapıt gövdesi ise her Recipe’in kimlikle başvurduğu bir MappingLibrary, WorkloadLibrary veya ArtifactLibrary içine konur.
Bir Release neden farklıdır. Bir Release başka varlıkları gösterir — Aggregate’ini, Manifest’ini, genişlettiği Release’i — ve hiçbir zaman yayımlanmaz; bu nedenle okuduğu hiçbir şey bir yere taşınmaz. Bu başvurular ve parameters: alanının içe aktardığı dosya yazıldığı gibi okunur; bir Aggregate’in alt dizinlerdeki Release varyantları tarafından paylaşılabilmesini sağlayan da budur. Bkz. entities/release.md.
Aynı sınır bir FeatureRecipe için ve bir Component’in veya bir Feature’ın içe aktardığı her şema için de geçerlidir.
workload: alanı — sentezlenen girdi türü
Recipe.spec.workload:, derleyicinin provider’a özgü kaynaklara sentezlediği Workload gövdesini bildirir. Bir Recipe’in source: (kaynaklı oluşturma) ve artifacts: (yardımcı manifestler) ile birlikte bildirebileceği üç girdi türünden biridir. Her provider’da üçünden en az biri bulunmalıdır; derlemenin sağlamadığı bir hizmet, form: reference biçiminde bir workload: bildirir.
Alan üç yazım kipini kabul eder: satır içi blok skaler, dosya $import: veya kütüphane $import:. Derleyici, alanın içerik biçimine göre ayrım yapar; $mode: ek açıklaması gerekmez.
Kip 1: Satır içi (Go şablonu dize skaleri). Değer, çıktısı aggrega.ai/v1beta1 Workload olarak ayrıştırılan bir YAML blok skaleridir:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Bir Workload’ın alanları belgenin kökünde yer alır — spec: sarmalayıcısı yoktur — ve containers: ile her container’ın ports: alanı, dizi yerine yazarın sırasını koruyan, ada göre anahtarlanmış eşlemlerdir. Provider bu biçimi kendi yerel biçimine çevirir; bu nedenle bir container eşlem girdisi, helm’in oluşturulan çıktısında anahtarıyla adlandırılmış bir containers[] öğesi olarak görünür; yazılan biçim, oluşturulan liste değil, eşlemdir.
Kip 2: Dosya $import:. Değer, yerel bir Go şablonu dosyasını gösteren tek bir $import: anahtarı içeren bir eşlemdir:
spec: workload: $import: ./workload/web-server.yaml.tmplYol çözümlemesi valuesMapping: ile aynıdır: göreli bir yol, derlemenin çağrıldığı dizine değil, onu bildiren recipe.yaml dosyasını içeren dizine göre bağlanır ve o dizinin içinde kalmalıdır. İçe aktarılan gövde, tıpkı satır içi bir gövde gibi, Recipe’in oluşturma bağlamında değerlendirilen bir Go şablonudur.
Kip 3: Kütüphane $import:. Değer, bir WorkloadLibrary girdisine yalın adlı bir kimlik başvurusu taşıyan tek bir $import: anahtarı içeren bir eşlemdir:
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceBir Workload girdisini seçen #/workloads/ parçasıdır ve bu başvuruyu valuesMapping: alanının kullandığı #/mappings/ biçiminden ayıran da bu parçadır — o biçim bir MappingLibrary girdisini adresler ve bir Workload gövdesini adlandırmaz. Başvuru bir kayıt defteri ana bilgisayarı taşımaz, çözümlenen sürüm Release başına kilit dosyasından gelir, isteğe bağlı bir :<version> en düşük sürüm tabanı <Library>:<version>#/workloads/<Entry> olarak belirtilebilir ve gövdesi kendisi alan kökünde bir $import: olan bir girdi özyinelemeli olarak çözümlenir. İçe aktarılan gövde, onu kullanan Recipe’in oluşturma bağlamında değerlendirilen bir Go şablonudur; bu nedenle .values, .infra ve .features, satır içi bir gövdeye aktıkları gibi ona da akar. Kütüphane varlığı ve başvurunun tam dilbilgisi için entities/workloadlibrary sayfasına bakın.
Hedef provider sentezi desteklemelidir (standart kütüphane kataloğu, uzlaşım gereği bu tür provider’larda workloadSchema bildirir); sentezleyemeyen bir provider’ı hedeflemek, düğüm oluşturulurken provider yeteneği tanılamasıyla reddedilir — bu tanılama workloadSchema varlığına değil, provider yeteneğine dayanır. Workload’ın tam dilbilgisi, K8s biçimli doğrudan geçiş alanları ve provider başına çeviri davranışı için entities/workload.md sayfasına bakın. Daha geniş üç girdi türü modeli ve sentezi kaynaktan oluşturulan çıktı ve artifact’larla birleştiren derleyici için architecture/16-recipe-input-composition.md sayfasına bakın.
Bir bileşenin kendi değerlerini geliştiricinin kendi imajına iletmek. Geliştiricinin derlediği bir imajı çalıştıran bir Recipe’den, standart kütüphane kataloğunun uzlaşımı gereği, geliştiricinin inject: bloklarının çözümlediği her şeyi .context.inject üzerinden iletmesi beklenir; bu Recipe ayrıca bileşenin kendi değerlerini kendi belirlediği adlarla da iletebilir. Component spec.inject bildirdiğinde adları geliştiricinin kendi bloğu seçer ve .context.self_inject, Recipe’ye her girdinin şablonunun okuduğu tek kendi değeri bildirir — tam olarak tek bir kendi değeri okuyan ve başka hiçbir şey okumayan bir girdi için values.<key>. Standart kütüphane kataloğunun uzlaşımı, bir Recipe’nin bu değerlere verdiği adları geliştiricinin kodunun okumak zorunda olduğu bir sözleşme olarak değil, varsayılanlar olarak ele almak ve bir değeri varsayılan adıyla yalnızca hiçbir girdi ona eşlenmediğinde iletmektir; bir kurumsal katalog farklı bir seçim yapabilir. Şablon bağlamı sözleşmesi, haritanın kesin kurallarını ve eksiksiz bir şablon örneğini verir.
artifacts: alanı — yardımcı manifest dosyaları
Recipe.spec.artifacts:, girdi adından yapıt gövdesi tanımına uzanan bir eşlemdir; girdileri, Recipe’nin kaynaktan üretilmiş veya sentezlenmiş birincil çıktısının yanında ek manifest dosyaları üretir. Üç girdi türünden biridir (kaynaklı / sentezlenmiş / yapıtlar); bir Recipe artifacts: alanını tek başına ya da workload: ve/veya source: ile birlikte bildirebilir.
Her girdinin değeri, workload: ile paralel olarak içerik biçimine göre ayırt edilen üç moddan birini taşır: satır içi içerik, bir dosya $import: veya bir kütüphane $import:. Derleyici değerin içerik biçimine göre ayırım yapar; $mode: notuna gerek yoktur. Eşlem anahtarı, üç modda da girdinin ne ürettiğini adlandırır: iki tek dosyalı modda çıktı dosya adıdır, paket modunda ise paketin dosyalarının altına yerleştirildiği dizindir. Anahtar çıktıyı adlandırdığı için, tek bir dosya adının olabileceği şeyle sınırlıdır: başta bir harf veya rakam, ardından harfler, rakamlar, noktalar, kısa çizgiler ve alt çizgiler. Noktalar, bir anahtarın uzlaşım gereği taşıdığı uzantıyı korur (main.tf, template.yaml, serviceaccount.yaml); alfabe ise bir anahtarın dosya yerine yol adlandırmasına yol açacak / karakterini ve başta . karakterini kabul etmez, böylece bir anahtar hiçbir zaman üst dizin bölümü olamaz. Bu alfabenin dışındaki bir anahtar; çalışma alanı yüklenirken, aggrega validate sırasında ve düzenleyici tanılamalarında zarf doğrulamasından geçemez.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportMod 1: Satır içi (Go şablonu dize skaleri). Değer bir blok skalerdir ve eşlem anahtarı, yazıldığı gibi kullanılan çıktı dosya adıdır; yukarıdaki ilk girdi extra-configmap.yaml üretir.
Mod 2: Dosya $import:. Değer, yerel bir Go şablonu dosyasını gösteren tek bir $import: anahtarına sahip bir eşlemdir ve eşlem anahtarı, tıpkı mod 1’deki gibi çıktı dosya adıdır. İçe aktarılan dosya içeriği sağlar; adı sağlamaz. Yukarıdaki ikinci girdinin anahtarı network-policy.yaml olup içe aktardığı dosyanın adı network-policy.tmpl olsa da network-policy.yaml üretir. Dolayısıyla belirli bir çıktı dosya adı isteyen yazar onu anahtar olarak yazar; aynı ada sahip farklı dosyaları içe aktaran iki girdi (./extras/shared.yaml ve ./overrides/shared.yaml) iki ayrı çıktıdır. Yol çözümleme valuesMapping: ve workload: ile aynıdır: göreli bir yol, derlemenin çağrıldığı dizine değil, onu bildiren recipe.yaml dosyasını içeren dizine bağlanır ve bu dizinin içinde kalmalıdır.
Mod 3: Kütüphane $import:. Değer, bir ArtifactLibrary paketine yalın adlı kimlik başvurusu (<Library>#/artifacts/<name>) taşıyan tek bir $import: anahtarına sahip bir eşlemdir. Paket, tek bir birim olarak içe aktarılan bir dosya kümesidir; bu nedenle tek bir girdi, paketteki her dosya için bir çıktıya genişler ve her biri eşlem anahtarının altına <key>/<filename> olarak yerleştirilir: anahtar, tüketim yerini adlandırır ve bu dosyalardan herhangi birinin adı değil, dosyaların yerleştiği dizindir. Yukarıdaki üçüncü girdinin anahtarı operator-support’tur; PlatformArtifacts#/artifacts/OperatorSupport crd.yaml ve rbac.yaml bildiriyorsa, bu tek girdi operator-support/crd.yaml ve operator-support/rbac.yaml üretir. Başvuru kayıt defteri ana bilgisayarı taşımaz (ana bilgisayar içeren bir oci://… biçimi reddedilir), çözümlenen sürüm Release başına kilit dosyasından gelir ve isteğe bağlı bir :<version> asgari sürüm tabanı <Library>:<version>#/artifacts/<name> olarak belirtilebilir. Kütüphane varlığı ve tam başvuru dilbilgisi için entities/artifactlibrary sayfasına bakın.
Bir dosya $import: Recipe’nin yanında sabitlenir. aggrega pin, içe aktarılan her dosyanın baytlarının özetini, girdinin eşlem anahtarıyla anahtarlanmış olarak Recipe’nin dizinindeki entity.lock dosyasına kaydeder; aggrega build dosyanın özetini yeniden alır ve artık eşleşmediğinde [CATALOG_ERROR E0026] ile durur (ya da düzenlemeden önce yazılmış Release kilit dosyası Recipe’yi taşıdıklarıyla kaydediyorsa önce E0130 ile); böylece sabitlendikten sonra düzenlenmiş bir dosya hiçbir zaman doğrulanmadan işlenmez. Değişiklik kasıtlıysa yeni özeti kaydetmek için Recipe üzerinde aggrega pin çalıştırın; aksi halde dosyayı geri yükleyin. Satır içi girdi Recipe dosyasının parçasıdır, kütüphane girdisi ise kilit dosyasının kaydettiği kütüphane sürümüyle sabitlenir; dolayısıyla ikisi de kendine ait bir sabitleme taşımaz. Dosya aggrega pull sayfasında açıklanır.
Her yapıt girdisinin şablonu, gövdesini hangi mod sağlamış olursa olsun, valuesMapping: ile aynı şablon bağlamında değerlendirilir. Aynı dosya adını taşıyan iki çıktı, düğüm işlenirken derlemeyi durdurur. Tek bir artifacts: eşleminin iki girdisi aynı çıktıyı adlandıramaz: eşlem anahtarı bir belge içinde benzersizdir ve tek bir dosya adını ifade eder; bu nedenle tek dosyalı bir girdinin çıktısı anahtarıdır ve paket girdisinin dosyaları anahtarıyla adlandırılan bir dizinin altında yer alır. Bir girdinin ürettiği her yolun ilk bölümü onu üreten anahtardır, dolayısıyla içe aktarılan dosyaların adı ne olursa olsun farklı anahtarlar farklı çıktı adları olarak kalır. Durmanın kapsadığı şey, iki farklı girdi türünün katkıda bulunduğu tek bir dosya adıdır (örneğin hem bir chart şablonunun hem de bir yapıt girdisinin servicemonitor.yaml üretmesi); bu durum, katkıda bulunan her kaynağı adlandıran bir tanılamayla o Recipe’ye karşı raporlanır.
Kullanım durumları. artifacts:, birincil chart veya modülün üretmediği yardımcı kaynakların yeridir: bir iş yüküne eşlik eden bir NetworkPolicy, bir Deployment ile eşleştirilmiş bir HPA, instance_id değerine göre anahtarlanmış yan araç ConfigMap. Birçok bileşene uygulanan kesişen yardımcı kaynaklar (örneğin her veri deposuna eklenen bir yedekleme yan aracı), Recipe başına artifacts: yerine FeatureRecipe Resource Generation’a aittir; FeatureRecipe genişletme yüzeyi için entities/featurerecipe.md sayfasına bakın.
boundary: bloğu — sınırın paylaşılan çıktısı için dosyalar
Çoğu Recipe’in buna hiç ihtiyacı olmaz. Bir Recipe’in yazdığı diğer her şey kendi bileşenine aittir: sağlayıcı bunu sınırın çıktısında o bileşenin kendi konumunun altına yerleştirir. Bazı dosyalar ise bunun yerine sınırın bütününe aittir — hedefin, sınırın dağıttığı her şey için bir kez okuduğu bir dosya. Terraform’un sağlayıcı yapılandırması yaygın örnektir: Terraform’un belgeleri provider bloklarını başka bir yapılandırmanın çağırdığı bir modülün dışında tutar ve kendine ait böyle bir blok taşıyan bir modül depends_on, count veya for_each ile çağrılamaz. spec.boundary.artifacts, bir Recipe’in böyle bir dosyayı yazdığı yerdir.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }Blok, ikinci bir kapsamdaki artifacts: alanıdır. Tek üyesi artifacts’tır ve tam olarak Recipe’in kendi artifacts: alanının biçimini alır: aynı üç kip — satır içi içerik, bir dosya $import:’u, dosyaları girdinin anahtarı altında <key>/<filename> olarak iç içe yerleşen bir kitaplık $import:’u —, aynı anahtardan dosya adına kuralı ve bir anahtar için aynı alfabe ile aynı şablon bağlamı; dolayısıyla bir girdi .values, .infra, .locals ve diğerlerini tam olarak bir artifacts: girdisinin okuduğu gibi okur. En az bir girdi gerektirir ve boundary: altındaki başka her üye Recipe okunurken reddedilir. Bir FeatureRecipe’in böyle bir bloğu yoktur.
Bir dosyanın yazıldığı yer. Bir kez, sınırın birleştirilmiş çıktısını barındıran dizine, sağlayıcının kendi birleştirmesinin oraya yazdığı dosyaların yanına — terraform için bileşenin modülünün içine değil, aggrega.modules.tf kök yapılandırmasının yanına. Bu dosyaların hiçbiri sağlayıcıya verilmez: derleyici bunları değerlendirir ve kendisi yazar; hangi bileşenden geldiğini belirtmek için bir dosyaya hiçbir şey işlemez, çünkü dosya onu bildiren her bileşene aittir. Şablonu boş çıktı üreten bir girdi hiçbir dosya yazmaz.
Birden çok katkıda bulunanın buluşması. Her girdi, Recipe’in sınırda işlediği her bileşen için değerlendirilir ve sınıra katkıda bulunan herkesin bildirdiği dosyalar ada göre birleştirilir. Aynı baytlara değerlendirilen tek bir ad — tek bir Recipe’e bağlı iki bileşen ya da tek bir sağlayıcıyı aynı şekilde yapılandıran iki Recipe tarafından — tek bir dosyadır. Farklı baytlara değerlendirilen tek bir ad, dosyayı ve her katkıda bulunanı adlandırarak derlemeyi durdurur, çünkü hiçbir tekil dosya hepsinin yazdığı şey değildir; sağlayıcının kendi birleştirmesinin yazdığı aggrega.modules.tf gibi bir ad da aynısını yapar. Her ikisi de birleştirilmiş çıktı çakışmasıdır. Tek bir sağlayıcıyı iki farklı dosya adı altında yapılandıran iki Recipe birleştirilmez — her dosya yazılır — ve bu durumda yinelenen yapılandırmayı bildiren hedeftir; dolayısıyla bir sağlayıcı yapılandırmasını paylaşması amaçlanan Recipes dosya adını da paylaşır, uzlaşım gereği yapılandırdığı sağlayıcıya göre adlandırılmış bir ad.
Hangi sağlayıcıların kabul ettiği. Bir sınırın birleştirilmiş çıktısının yanına yerleştirilen bir dosyanın bir anlam taşıyıp taşımadığı sağlayıcının hedefinin bir özelliğidir; bu yüzden sağlayıcının kendi bildiriminin bir parçasıdır. Bloğu bildiren ve sağlayıcısı bunu kabul etmeyen bir Recipe, girdileri ne üretirse üretsin, herhangi bir şey işlenmeden önce reddedilir; bkz. The provider does not support boundary artifacts (Sağlayıcı sınır yapıtlarını desteklemiyor). Yetenek tablosu her sağlayıcının beyanını listeler.
| Provider | boundary.artifacts: |
|---|---|
terraform | Kabul edilir. Her dosya, sınırın kök yapılandırmasının yanına yazılır; Terraform bunu o dizindeki diğer tüm yapılandırma dosyalarıyla birlikte okur. |
helm, compose, helm-chart, cloudformation | Herhangi bir şey işlenmeden önce reddedilir. |
Burada bir dosya $import:’u, bir artifacts: girdisinin içe aktardığı dosya gibi sabitlenir. Varlık kilidi özetini aynı artifactDigests listesine, yalnızca anahtarın altına değil boundary/<key> altına kaydeder; böylece tek bir anahtar altında yazılmış her bloğun girdisi ayrı ayrı sabitlenir. Sabitleme adımı bunu kaydeder, sabitleme yapmayan bir çekme işlemi sabitin eksik olduğu ya da artık eşleşmediği yerde durur ve bir derleme, sabitlendikten sonra düzenlenmiş bir dosyayı tam olarak bir artifacts: dosyasını reddettiği gibi reddeder.
outputLabels: alanı — işlenmiş çıktıda yazarın bildirdiği etiketler
Recipe.spec.outputLabels:, provider’ın Recipe’in işlenmiş çıktısının ürettiği her nesneye bastığı bir etiket anahtarı → değer eşlemesidir. Bir gerçekleştirme özelliği için doğru yer burasıdır: bileşenin ne olduğunun aksine, belirli bir Recipe’in bir bileşeni nasıl gerçekleştirdiğine ilişkin bir özellik. Bir gerçekleştirmenin kalıcılık için kullandığı depolamayı ele alalım; aşağıda bu, örnek amaçlı example.io/storage-backing anahtarıyla yazılmıştır: bir PersistentVolumeClaim bağlayan bir Helm Recipe’i ile adlandırılmış bir birim bağlayan bir Compose Recipe’i aynı bileşeni farklı mekanizmalarla gerçekleştirir; bu nedenle farklı outputLabels taşırlar ve aşağı akıştaki araçlar (maliyet dağıtımı, politika, envanter) bunları üretilen kaynaklar üzerinde birbirinden ayırt edebilir. Anahtar yalnızca örnek amaçlıdır — example.io/ bir örnek ad alanıdır ve bir katalog, kendi araçlarının okuduğu anahtarları kendisi seçer.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformÇıktı etiketleri, sabit derleme kökeni etiketleriyle aynı rayı izler: çıktı üreten her yüzeyin bastığı etiket kümesine birleştirilirler, dolayısıyla köken bilgisinin vardığı her yere varırlar. Farklı olan sahipliktir — köken anahtarları derleyiciye aittir, outputLabels ise Recipe yazarına aittir.
Bir bileşenin kendi kimlik etiketi buraya yazılmaz — bu, derleyicinin zorunlu kıldığı bir kural değil, bir katalog uzlaşımıdır. Bir Recipe’in bileşeni nasıl gerçekleştirdiğini değil, bileşenin ne olduğunu belirten anahtarlar — bilişsel kategorisi, operasyonel türü, rol başına yetenek etiketleri, alttaki kaynağı kimin işlettiği, sarmaladığı şeyin lisans sınıfı — Component’in metadata.labels alanında bildirilir; eksenler için entities/component “The Semantic Label Taxonomy” bölümüne bakın. Bir Recipe bunlardan birini işlenmiş çıktısına, anahtarı ve bir değeri buraya yazarak değil, anahtarı aşağıdaki outputComponentLabels: alanında adlandırarak koyar. Bunun nedeni, düz bir girdinin bileşenin zaten taşıdığı bir değerin ikinci kopyası olması ve ikinci bir kopyanın birincisiyle çelişebilmesidir: bir Recipe yazarı, Component’i başka bir duruş bildiren bir düğüme farklı bir duruş yazabilir ve aşağı akıştaki bir okuyucuya grafiğin söylemediği bir şey söyleyebilir. Yükseltilmiş bir girdi referansla kopyalar ve bu nedenle sapabilecek ikinci bir kopyası yoktur. Çekirdek, aşağıdaki ayrılmış ad alanı kuralı dışında, hangisini yazarsanız kabul eder; uzlaşımı katalog yazarları sürdürür.
Ayrılmış ad alanları. aggrega.ai/ ve app.kubernetes.io/ ad alanları platforma özgü köken bilgisi için ayrılmıştır. Bu öneklerden herhangi biri altında bir outputLabels anahtarı bildiren bir Recipe, yükleme sırasında sorunlu anahtarı adlandıran açık bir katalog hatasıyla reddedilir. Diğer her anahtar kabul edilir. Çekirdek, bunun dışında anahtarı veya değeri denetlemez — hedef motorun etiket yüzeyi için geçerli olmayan bir anahtar veya değer yazarın sorumluluğundadır ve aşağı akıştaki çalışma zamanı onu reddeder; derleyici, ayrılmış ad alanı kuralının ötesinde işe karışmaz.
Provider başına yüzeye çıkarma. Her provider etiketleri kendi çıktı yüzeyine aktarır:
- helm, workload sentezi — hem nesnenin
metadata.labelsalanına hem de pod şablonununmetadata.labelsalanına; sentezin provenance bilgisini yerleştirdiği yerlerle eşleşecek şekilde. - helm, kaynak işleme ve yapıtlar — nesnenin
metadata.labelsalanına. - compose — her hizmetin
labels:eşlemesine. - terraform — yapısal olarak adreslenebilir
.tf.jsonyapıt gövdelerinde kaynak başına etiketler olarak, elden geldiğince: zaten birtags(AWS/azurerm) veyalabels(Google) eşlemesi bildiren bir kaynak bloğu çıktı etiketlerini orada alır, yazarın bildirdiği bir anahtarın üzerine asla yazılmaz ve böyle bir özniteliği olmayan bir kaynağa dokunulmaz (hiçbir zaman öznitelik uydurulmaz). Yerel HCL gövdeleri (main.tf,*.tf) ve vendor’a alınmış modüller olduğu gibi üretilir ve enjekte edilmiş etiket taşımaz. Terraform köken bilgisi, etiket rayından ayrı olarak eşlik eden yorum dosyasında taşınmaya devam eder.
Çıktı etiketleri yalnızca etikettir; ayrı bir çıktı ek açıklaması yüzeyi yoktur. outputLabels, Aggregate tarafından değil, Recipe yazarı (operasyon ekibinin yazdığı gerçekleştirme katmanı) tarafından bildirilir — gerçekleştirmeyi tanımlar, asla geliştiricinin soyut grafikteki kimliğini değil.
outputComponentLabels: alanı — bir bileşenin kendi etiketlerini öne çıkarma
Recipe.spec.outputComponentLabels:, anahtar-değer çiftlerinden değil, etiket anahtarlarından oluşan bir listedir. Adını verdiği her anahtar için sağlayıcı, o anahtarı oluşturulan çıktıya, anahtarın oluşturulmakta olan bileşen örneğinde taşıdığı değerle basar. outputLabels bir değer belirtirken outputComponentLabels değerin nereden okunacağını belirtir.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingmetadata.labels alanı component.aggrega.ai/hosting: managed bildiren bir Component verildiğinde, bu Recipe’in o bileşen için oluşturduğu her nesne component.aggrega.ai/hosting: managed taşır. Aynı Recipe’i self-hosted bildiren bir bileşene bağlarsanız, o bileşenin nesneleri bunun yerine self-hosted taşır — tek Recipe, tek adlandırılmış anahtar, bileşen başına bir değer.
Öne çıkarma başvuru yoluyla yapılır ve asıl amaç da budur. Değer, çıktı her oluşturulduğunda bileşenden okunur; bu nedenle geldiği kimlikten sapamaz: bileşenin etiketi değiştiğinde senkron tutulması gereken ikinci bir kopya yoktur. Bir bileşenin etiketini yeniden belirten değişmez bir outputLabels girdisi tam da o ikinci kopyadır ve ikisinden biri değiştiği anda ikisi birbiriyle çelişir. Bu yüzden değer bu Recipe’in bileşeni nasıl gerçekleştirdiğine ait bir özellik olduğunda outputLabels alanını, değer bileşende zaten mevcut olduğunda ve oluşturulan çıktının da onu taşıması gerektiğinde outputComponentLabels alanını kullanın.
Öne çıkarılan bir anahtar, değişmez bir anahtarla tam olarak aynı yüzeye yerleşir — yukarıda açıklanan sağlayıcı başına yüzeye çıkarma değişmeden uygulanır ve hiçbir sağlayıcı öne çıkarılmış bir anahtarı yerinde yazılmış bir anahtardan ayırt etmez.
Ayrılmış ad alanları. aggrega.ai/ ve app.kubernetes.io/ ad alanları platforma özgü köken bilgisi için ayrılmıştır ve bu öneklerden birinin altındaki öne çıkarılmış bir anahtar, yükleme sırasında anahtarı ve içinde bulunduğu alanı adlandıran bir katalog hatasıyla reddedilir. Sınama yalnızca öneke bakar: component.aggrega.ai/hosting gibi bir anahtar ayrılmış kökün altında değil, kendine ait bir ad alanında yer alır ve öne çıkarılabilir.
Bir anahtar ya bir bloğa ya da diğerine aittir. Aynı anahtarı hem outputLabels hem de outputComponentLabels içinde bildirmek yükleme sırasında reddedilir; böylece basılan her anahtarın tek bir kaynağı olur — ya Recipe üzerinde yazılmış değişmez değer ya da bileşenin kendi etiketi, asla ikisi birden değil.
Bileşenin bildirmediği öne çıkarılmış bir anahtar hiçbir şey basmaz. Derleme devam eder ve düğümü, Recipe’i ve eksik anahtarı adlandıran bir uyarı verir. Bu bilinçli bir tercihtir: etiket kümeleri farklı olan bileşenlere bağlanmış bir Recipe yine de çıktı oluşturur ve tutarsızlık derlemeyi durdurmak yerine görünür kılınır.
Tek duruşlu bileşenler — bir kural değil, bir uzlaşım. Öne çıkarma, bileşenin bildirdiği değer neyse onu taşır ve derleyici bu değeri yorumlamaz. Bu nedenle kimlik etiketi “değişir” anlamına gelen bir yer tutucu içeren bir bileşen, o yer tutucuyu kendisi için oluşturulan her nesneye öne çıkarır. Bir bileşenin gerçekten birden fazla duruşu olduğunda, standart kitaplık kataloğunun uzlaşımı, her Recipe’in kendi gerçekleştirmesinin duruşunu, aynı uzlaşımın bunun yerine outputComponentLabels: üzerinden yönlendirdiği bileşenin kimlik anahtarı aracılığıyla değil, Recipe’in sahip olduğu bir outputLabels anahtarı aracılığıyla belirtmesi — ya da hiçbir şey basmamasıdır. İki anahtar farklı soruları yanıtlar ve biri diğerinin yerini tutmaz: kimlik anahtarı bileşenin tüm gerçekleştirmelerde ne olduğunu, Recipe’e ait anahtar ise bu tek gerçekleştirmenin ne yaptığını söyler. Bu, derleyicinin zorunlu kıldığı bir kısıt değil, yazarlarınca sürdürülen bir katalog uzlaşımıdır.
locals: bloğu
Recipe.spec.locals:, Özel Operasyon Durumu’dur (Private Ops State): işlenmiş çıktısı Recipe’in sonraki şablonlarına bir .locals.* eşlemi sunan, adlandırılmış Go şablon dizelerinden oluşan bir eşlem. Fiziksel gerçeklikleri (hedef konteynerler, JSON yolları, türetilmiş ana makine adları) bir kez hesaplayıp yeniden hesaplamadan provides:, source:, valuesMapping:, workload:, artifacts:, assertions: ve pipeline[].with yüklerinde yeniden kullanmak için çalışma alanıdır. Her girdinin işlenmiş çıktısı baştaki ve sondaki boşluklar kaldırılarak saklanır.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: çağıranlara hiçbir zaman açılmaz: bu Recipe’i uses: üzerinden tüketen aşağı akış bileşenleri yalnızca provides: bloğunu görür. Recipe’in kendi provides:, source:, valuesMapping:, workload:, artifacts:, assertions: ve pipeline[].with şablonlarının tümü çözümlenmiş .locals.* eşlemini görür. Anahtar başına değerler düz dizeler ya da Go şablonları olabilir; derleyici bloğun tamamını, o düğümün provides: bloğundan önce, locals ön aşamasında çözümler; böylece sonraki her şablon kararlı, çözümlenmiş değerler görür.
Her girdi, kendi içinde bağımsız, düğüme yerel bir bağlama göre değerlendirilir: .context.instance_id, .values, .infra ve aynı blokta önceden çözümlenmiş girdiler. Bir local, .provides değerini okuyamaz: bu sütun bu yüzeyde yer almaz ve ona erişmeye çalışan bir girdi durdurmaya yol açar. .context.rendered_name değerini, yani helm gibi bir sağlayıcının düğüm için işlediği kaynaklara verdiği adı da okuyamaz; bu nedenle bu kaynaklardan birini adlandıran bir local, yukarıdaki secret_target_db_password örneğinde olduğu gibi yalnızca o addan sonraki kısmı taşır ve tam adı yazan şablon ikisini birleştirir.
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: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveZincirleme yalnızca aşağı doğru işler. Bir girdi diğerini okuduğunda, derlemenin başarılı olup olmayacağına girdilerin sırası karar verir: db_identifier girdisini secret_target girdisinin altına taşırsanız derleme durur. Derleyici bir başvuruyu çözümlemek için bloğu hiçbir zaman sıralamaz ya da yeniden düzenlemez; bu nedenle yazılan sıra sözleşmedir: bir locals: bloğunu yeniden sıralamak görünüşe ilişkin değil, davranışsal bir değişikliktir.
Düzeltmeleri farklı olduğu için, bir yazarın yapabileceği iki hatayı iki ayrı durdurma birbirinden ayırır:
- Bloğun daha sonra tanımladığı bir girdiye yapılan başvuru, sıralama hatasını belirterek durur; düzeltme, tanımı onu okuyan girdinin üstüne taşımaktır.
- Bloğun hiç bildirmediği bir anahtara yapılan başvuru, anahtarı belirterek durur; düzeltme, yazımı düzeltmektir.
Denetim, blok için kullanılan bir takma adı izler. Bir with .locals gövdesinin yeniden bağladığı nokta üzerinden ya da .locals değerine bağlanmış bir değişken üzerinden erişilen bir anahtar, doğrudan yazımla tamamen aynı koşullarda denetlenir: {{ with .locals }}{{ .nope }}{{ end }} ve {{ $l := .locals }}{{ $l.nope }} ifadelerinin ikisi de, tıpkı {{ .locals.nope }} gibi, .locals.nope adını belirterek durur; {{ (.locals).nope }} ve {{ ($.locals).nope }} da öyle, çünkü parantezler bloğun kendisini verir, fazlasını değil. Tek bir yazım denetimin dışında kalır: sonucunu şablon metninin adlandıramadığı bir çağrı üzerinden erişilen anahtar ({{ index .locals "nope" }} ya da {{ (default dict .locals).nope }}), çünkü böyle bir çağrının ne döndüreceği yazılana göre değil, şablon çalışırken belirlenir. Böyle bir çağrının sonucundan alan olarak okunan mevcut olmayan bir anahtar durdurmaya yol açmaz ve hiçbir şey yerine <no value> düz metnini işler. index üzerinden erişilen mevcut olmayan bir anahtar, anahtarı belirterek durur; çünkü index, okuduğu eşlem istenen anahtarı içermediğinde her şablon yüzeyinde durur. Bu, bu denetimin raporundan farklı bir rapordur ve errors/fatal-halts.md sayfasında “A template indexes a map with a key the map does not hold (Bir şablon, eşlemin içermediği bir anahtarla eşlemi dizinliyor)” başlığı altında belgelenmiştir. Bu nedenle index, adı kendisi hesaplanan bir anahtara erişmenin yolu olmaya devam eder; örneğin {{ index .locals (printf "secret_target_%s" .values.slot) }}; bloğun bildirmediği hesaplanmış bir ad yine de anahtarıyla raporlanır.
provides:, .locals değerini okur ve çözümlenmiş değerleri alır, çünkü bir düğümün locals bloğu provides bloğundan önce çözümlenir. locals bloğunun bildirmediği bir anahtarı adlandıran bir provides: şablonu durur. Bu, hem bir provides: girdisinin hem de bir yapıtın ihtiyaç duyduğu bir değerin locals: içinde bir kez yazılıp her iki yerden okunduğu anlamına gelir.
Genel API karşılığı için aşağıdaki provides: bloğu bölümüne bakın. FeatureRecipe yüzeyi aynı kuralları izler; entities/featurerecipe.md içindeki “locals: bloğu” bölümüne bakın.
provides: bloğu
Recipe.spec.provides: Genel Geliştirici API’sidir: bu Recipe’nin aşağı akıştaki çağıranların .context.inject ve .context.uses kanallarına sağladığı değerleri bildiren, ad → Go şablon dizesi eşlemesidir. Derleyici provides: şablonlarını provides değerlendirmesi aşamasında (kendi içinde bağımsız, herhangi bir sırayla) değerlendirir; çağıranların inject anahtarları inject doldurma aşamasında bu değerlere göre çözümlenir.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"Her girdinin şablonu, kendi içinde bağımsız provides değerlendirme yüzeyine göre değerlendirilir: .context.instance_id, düğümün sağlayıcısı bir tane bildirdiğinde .context.rendered_name, .values, .infra, düğümün çözümlenmiş .locals değerleri ve statik metin. Düğümün yerleştirildiği namespace bu yüzeyde yer almaz; bu nedenle yayımlanan bir host namespace içermez: başka bir namespace’teki tüketici onu kendi tarafında nitelendirir. .locals bu yüzeydedir, çünkü düğümün locals değerleri aynı aşamanın ön bölümünde, provides değerlerinden önce çözümlenir; locals bloğunun bildirmediği bir anahtarı adlandıran bir provides şablonu derlemeyi durdurur. Provides değerlendirmesini inject doldurmadan ayırmak belirleyicidir: bir Recipe’nin provides: bloğu hiçbir çağıranın durumuna başvuramaz, çünkü provides değerlendirmesi çalıştığında çağıranlar henüz çözümlenmemiştir; mimari değişmez gereği provides: kendi içinde bağımsızdır. Çağıranlar daha sonra bu değerleri kendi şablonlarında .context.uses.<alias>.provides.<provided-name> üzerinden okur; sağlanan adlar, kenarın diğer alanlarıyla birlikte kenar üzerinde provides altında iç içe yer alır. Kenar üzerinde bir inject: izin listesi bildiren çağıran ise aynı değerlere bunun yerine kendi .context.inject kanalı üzerinden ulaşır.
provides: anahtarları Recipe’nin sözleşme yüzeyinin parçasıdır. Bir anahtarı yeniden adlandırmak veya kaldırmak, eski ada dayanan her çağıran için geriye dönük uyumluluğu bozan bir değişikliktir; implements: arayüz sürümü sözleşmedeki bu evrimi yansıtmalıdır. Kademeli çözümleme anlamı, inject kanalı sözleşmesi ve namespace’ler arası ile bölgeler arası yönlendirmeyi kapsayan çalışılmış örnekler için architecture/06-data-taxonomy-and-composition.md §3 ve templates/expansion-matrix.md sayfalarına bakın.
Bir eklentinin yayımladığı değerleri okuma
Bir Recipe, kendi bileşenine eklenmiş Features’ı .features.<instance-name> altında, kimlik bilgisi Features’ını ise .features.<slot> altında okur. İkisi de aynı eklenti biçimindedir — .type, .values, .infra, .provides — bu nedenle bir eklenti, onu hangi eşleme taşırsa taşısın aynı şekilde okunur; aralarındaki fark, eklentinin ne ürettiğidir.
.provides, eklentinin yayımlanan çıktısıdır ve ona bağlı FeatureRecipe’ten çözümlenir. Yukarıdaki provides: bloğunun tüketen taraftan görülen karşılığıdır: bir Recipe çağıranlarına yayımlarken, bir eklenti kendi ana bileşenine yayımlar.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Yayımlanan değeri aynı values/infra girdilerinden yeniden hesaplamak yerine okumak, bir adın tek bir ifadesi ile birbirinden sapabilen iki ifadesi arasındaki farktır. Kullanılabilirlik kuralları dahil olmak üzere alan alan tam biçim templates/template-context-contract.md sayfasındadır.
Bileşenin bağlantılarından birine yazılan bir eklenti — bileşenin tek bir hedefe sunduğu bir kimlik bilgisi — aynı biçimde o bağlantının altında, .context.uses.<alias>.features.<slot> konumunda okunur ve hiçbir zaman .features arasında yer almaz. Birkaç hedefe ulaşan bir Recipe, her hedefin kendi kimlik bilgisini o hedefin takma adı altında okur; eklentileri türe göre seçen ve .features üzerinde dönen bir döngü yalnızca bileşenin kendi eklentileriyle karşılaşır:
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Biçim ve bir şablonun bağlantılar üzerinde hangi sırayla dolaştığı için Bir bağlantının eklentileri bölümüne bakın.
pipeline: alanı
Recipe.spec.pipeline:, işlemeden sonra işlenmiş belge kümesi üzerinde çalışan ve her biri RFC 6902 yamaları ile yan etkiler döndüren Wasm işlem hattı adımlarından oluşan sıralı bir dizidir. Her girdi bir id (adım başına tanımlayıcı: harfler, rakamlar ve alt çizgiler), bir plugin (adımın çalıştırdığı Plugin varlığı; eklenti türüyle kapsamlanır — pipeline-step/<name>, isteğe bağlı olarak bir sürümle; yalın bir .wasm ya da yapıt başvurusu reddedilir), bir function (çağrılacak eklenti dışa aktarımı), eklentinin yükünü sağlayan isteğe bağlı bir with: Go şablonu gövdesi ve adımın çalışıp çalışmayacağını belirleyen isteğe bağlı bir when: Go şablonu bildirir; yanlış değerli (falsy) bir sonuç adımı doğrudan geçiş olarak atlar ve belge kümesini değiştirmeden bırakır. when: koşulu, optional: alanından bağımsızlığı ve doğruluk kuralı entities/featurerecipe.md içindeki “Conditional steps — when:” bölümünde ayrıntılı olarak ele alınır:
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"Derleyici, bir temel Recipe’in pipeline: adımlarını, bir FeatureRecipe’in pipeline: alanını yürüttüğü şekilde, bildirildikleri sırayla yürütür: her adımın adlandırdığı Wasm eklentisini oluşturulan çıktıya karşı çalıştırır, döndürülen JSON Patch işlemlerini hedeflenen belgelere uygular ve adımın yan etkilerini üretir. FeatureRecipe pipeline: alanı aynı şema yapısını ve aynı yürütmeyi paylaşır; her yüzeyin yürütme durumu için entities/featurerecipe.md içindeki “Authoring Contract” bölümüne ve Dilin durumu sayfasına bakın.
Alanın işleyişi FeatureRecipe semantiğini yansıtır: bildirilen sırayla ardışık değerlendirme, işlenmiş belgelere uygulanan JSON Patch işlemleri, bunlarla birlikte üretilen yan etkiler ve soruna yol açan adımı gösteren köken bilgisiyle bildirilen hatalar. when: koşulu yanlış değerli işlenen bir adım, doğrudan geçiş olarak atlanır ve belge kümesi bir sonraki adım için değiştirilmeden bırakılır.
assertions: bloğu
Recipe.spec.assertions:, Recipe’nin uygulama değişmezlerini ifade eden adlandırılmış kurallardan oluşan isteğe bağlı bir eşlemedir — Recipe’nin kaynak olarak aldığı belirli chart’a veya modüle göre 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 şablonu gövdesidir. Component doğrulamalarından farklı olarak (bunlar hangi Recipe bağlanırsa bağlansın sözleşme düzeyindeki değişmezleri ifade eder), Recipe doğrulamaları seçilen belirli uygulamanın özellikleridir.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}Yukarıdaki kural Bitnami chart 20.x’e özgüdür; farklı bir MariaDB Recipe’si bağlanırsa geçerli olmaz. Sözleşmedeki Component düzeyindeki kurallar da yanında geçerliliğini korur ve daha önceki bir işlem hattı aşamasında değerlendirilir.
Recipe doğrulamaları, Recipe bağlandıktan sonra ve işlemeden önce, her düğümün locals ve provides değerleri çözümlendiğinde değerlendirilir. Şablon bağlamı, varlık örneği alanlarına (.values, .infra, .uses, .features) ek olarak Recipe’nin .provides, .locals ve .recipe.source alanlarını da içerir. Buradaki .uses ve .features, bir Recipe şablonunun değil, doğrulama yüzeyinin daha dar biçimleridir: bir bağlantının girdisi hedefini ve takma adını, hedefin labels alanını, bağlantının kendi values değerlerini ve üzerine features altında yazılan eklentileri taşır, ancak hedefin yayımladığı hiçbir şeyi taşımaz; bir eklentinin girdisi ise, ister bileşenin kendisine ister bir bağlantıya ait olsun, type, resolved_version ve values alanlarını taşır, ancak ne infra ne de provides alanını taşır — doğrulama çalıştığında eklentinin FeatureRecipe’si provides değerlerini henüz çözümlemiş değildir. Bu nedenle .features.<name>.provides başvurusu derlemeyi durdurur ve buna yönelik varlığa duyarlı bir okuma, yedek değerini döndürür. Yazım dilbilgisinin tamamı, sözleşme düzeyindeki ve uygulama düzeyindeki kurallar arasındaki sorumluluk paylaşımı ve uygulamalı örnekler için bkz. templates/assertions-block.md.
omits: alanı — işlenen belgeleri bir kaynağın dışında bırakmak
Çoğu Recipe buna hiç ihtiyaç duymaz. Bu alan, olduğu gibi aldığınız bir kaynak içindir — çoğunlukla bir kayıt defterinden getirilen bir chart — ve bu kaynak, Release’inizin yayımlamaması gereken bir belge işler: örneğin chart’ın her işlemede yeniden ürettiği bir Secret; bu, iki derlemenin birbirinden farklı olmasına yol açar ve uygulandığında operatörün sağladığı Secret’ın üzerine yazar. Getirilmiş bir chart’ı düzenlemezsiniz ve hiçbir yok sayma kuralı onun içine uzanmaz; bu nedenle bir Recipe böyle bir belgeyi derlemenin dışında omits: ile bırakır. Getirilmiş bir compose dosyası da aynı durumdadır: Release’in sahip olmaması gereken bir service, volume veya config içerebilir ve bir valuesMapping: katmanı bunlardan birini değiştirebilir ama asla kaldıramaz. Getirilmiş bir CloudFormation şablonu da öyledir; Release’in oluşturmaması gereken bir kaynak bildirebilir: bir valuesMapping: şablonun bildirdiği parametreleri doldurabilir ama kaynaklarından birini asla kaldıramaz.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringNeyi kapsar. Yalnızca source: alanının işlediklerini. Bir workload: ve artifacts: girdileri hiçbir zaman filtrelenmez: bunları Recipe içinde siz yazarsınız, dolayısıyla orada istemediğiniz bir belge, yazmadan bıraktığınız bir belgedir. Anahtar source: gerektirir; bu kuralı çiğneyen bir belge okunduğunda, kural adı belirtilerek reddedilir.
Bir girdi. Her girdi, dışarıda bırakılacak şeyi üç alanla adlandırır; dördüncü bir alan ise girdinin uygulanıp uygulanmayacağına karar verir. İlk üç alanın adlandırdığı şey, provider’ın kendi kaynağının işlediklerine ilişkin kendi sözcük dağarcığıdır ve aşağıdaki tabloda provider bazında açıklanmıştır:
kind— kaynağın işlediği şeyin türü: bir chart için işlenen bir belgenin türü —Secret,ConfigMap,Deployment; bir compose dosyası içinservice,volumeveyaconfig; bir CloudFormation şablonu için bir kaynağınTypedeğeri —AWS::S3::Bucket. Yapılandırılmış birsource:alanının taşıdığı, kaynağın nasıl getirileceğini adlandırankind:ile ilgisi yoktur.name— adı: bir belgeninmetadata.namedeğeri; bir compose birimininservices:,volumes:veyaconfigs:altındaki anahtarı; bir CloudFormation kaynağının mantıksal kimliği, yaniResourcesaltındaki anahtarı.namespace(isteğe bağlı) — çıktısında namespace bulunan bir provider için belgenin bulunduğu namespace. Bu alan olmadan girdi, herhangi bir namespace’teki türü ve adı adlandırır; hiçbir şeye işlenmeyen birnamespaceyokmuş gibi değerlendirilir.when(isteğe bağlı) — girdinin bu derlemeye uygulanıp uygulanmayacağı. İlk olarak değerlendirilir ve bir pipeline adımınınwhen:alanıyla aynı kurala göre okunur: yanlış bir sonuç girdiyi düşürür, böylece diğer alanları değerlendirilmez ve girdi ne provider’a iletilir ne de denetlenir; bulunmayan ya da boş birwhen:ise girdiyi korur.
kind ve name zorunludur; başka herhangi bir alan taşıyan bir girdi, Recipe okunduğunda reddedilir.
Her değer bir şablondur ve valuesMapping: ile aynı bağlama göre değerlendirilir. Bu bağlam .context.rendered_name değerini taşır; bu, provider’ın düğümün kaynaklarına verdiği ve bir chart’ın kaynaklarını genellikle göre adlandırdığı addır; böylece bir girdi, bir belgeyi tam olarak chart’ın adlandıracağı şekilde adlandırabilir. İşlenemeyen bir şablon, başarısız bir valuesMapping: şablonunun yaptığı gibi derlemeyi durdurur.
Uygulanan her girdi bir şeyi dışarıda bırakmalıdır. Provider her girdinin kaç birimi dışarıda bıraktığını bildirir ve hiçbir şeyi dışarıda bırakmayan bir girdi, girdi adı belirtilerek derlemeyi durdurur; bkz. An omits entry left out nothing the source rendered (Bir omits girdisi kaynağın işlediği hiçbir şeyi dışarıda bırakmadı). Olağan neden, belgeyi yeniden adlandıran veya kaldıran bir kaynak yükseltmesidir; bu durdurma da yeniden adlandırılmış bir belgenin fark edilmeden çıktınıza ulaşmasını önler. Bir belgeyi yalnızca bazen dışarıda bırakmak için, belgenin bulunmamasına güvenmek yerine bunu when: ile belirtin.
Kaynak yine de eksiksiz işlenir. Yalnızca çıktısı filtrelenir: chart’ın her şablonu yine çalışır, dolayısıyla başarısız olan bir şablon derlemeyi yine başarısız kılar ve dışarıda bırakılan bir belge önce işlenir, ardından düşürülür. Düşürüldükten sonra derlemenin sonradan yaptığı hiçbir şeye ulaşmaz — ne üretilen bir dosyaya, ne diğer bileşenlerin adlarıyla karşılaştırılan bir ada, ne bir Feature’ın işleme hakkında okuduğu bir olguya, ne de bir pipeline adımına iletilen herhangi bir şeye.
Bir Release anahtara infra ve parameters aracılığıyla ulaşır. Anahtar Recipe’e aittir, dolayısıyla bir Release onu yazamaz. Yine de bir girdinin ne yapacağına karar verebilir: bir girdinin şablonları Release’in doldurduğu infra değerini okur ve Release’in sağladığı parameters, Aggregate onları nereye yönlendirirse orada Recipe’in .values alanına ulaşır. Böylece bir Release, yukarıdaki ikinci girdinin yaptığı gibi bir girdiyi when: ile açıp kapatır ya da girdinin neyi adlandıracağına karar verir.
Dışarıda bıraktığınız şeyin sorumluluğu size aittir. Derlemedeki hiçbir şey bir belgenin ne işe yaradığını bilmez. Chart’ın geri kalanının çalışma zamanında bağlı olduğu bir belgeyi — bir Deployment’ın bağladığı Secret’ı, bir pod’un kimliğiyle çalıştığı ServiceAccount’u — dışarıda bırakmak, yanında uygulanan başka bir şey o belgeyi sağlamadıkça, sorunsuz derlenen ama uygulandığında başarısız olan bir çıktı üretir. Bir compose dosyası ve bir CloudFormation şablonu için derleme bunu denetler, çünkü her biri kendi başvurularını belirtir: kalan kısımda hâlâ dışarıda bırakılmış bir birimi adlandıran bir şey — dışarıda bırakılmış bir service’i adlandıran bir service, dışarıda bırakılmış bir kaynağı adlandıran bir kaynak ya da çıktı — aşağıdaki tabloda açıklandığı gibi derlemeyi durdurur.
Hangi provider’lar bunu destekler. Bir belgeyi dışarıda bırakmak yalnızca provider’ın yapabileceği bir şeydir, çünkü kaynağının neyi işlediğini yalnızca provider bilir; bu nedenle bir provider’ın anahtarı destekleyip desteklemediği, provider’ın kendi bildiriminin bir parçasıdır. Provider’ı bunu desteklemeyen ve omits: bildiren bir Recipe, girdilerinin when: değerleri neye işlenirse işlensin, herhangi bir şey işlenmeden önce reddedilir; bkz. The provider does not support omits (Provider omits desteklemiyor).
| Provider | omits: |
|---|---|
helm | Desteklenir. Bir girdi, chart’ın işlediği bir belgeyi — bir şablondan ya da crds/ dizininden — belgenin kendi kind ve metadata.name değerleriyle ve girdi bir namespace adlandırıyorsa belgenin bulunduğu namespace ile adlandırır. Bkz. helm → Kaynaklı mod. |
compose | Desteklenir. Bir girdi, kaynaklı compose dosyasının bir service, volume veya config öğesini services:, volumes: veya configs: altındaki anahtarıyla adlandırır; eşleştirme valuesMapping: dosyaya birleştirildikten sonra yapılır ve girdi namespace adlandırmaz: başka bir türü ya da bir namespace’i adlandıran bir girdi, bileşen işlendiğinde derlemeyi durdurur. Kalan kısmın hâlâ dışarıda bırakılmış bir birimi — depends_on, links, volumes_from, bir service: ağ veya namespace modu, extends, bir derleme bağlamı ya da bir volumes: veya configs: girdisi aracılığıyla — adlandırdığı bir dosya, her başvuruyu belirterek derlemeyi durdurur. Bkz. compose → Kaynaklı mod. |
cloudformation | Desteklenir. Bir girdi, kaynaklı şablonun bir kaynağını Type değeri ve mantıksal kimliğiyle, bir dizin kaynağının her şablonunda adlandırır ve namespace adlandırmaz: namespace taşıyan bir girdi, bileşen işlendiğinde derlemeyi durdurur. Kalan kısmın hâlâ dışarıda bırakılmış bir kaynağı — Ref, Fn::GetAtt, DependsOn veya bir Fn::Sub değişkeni aracılığıyla — adlandırdığı bir şablon, her başvuruyu belirterek derlemeyi durdurur. Bkz. cloudformation → Kaynaklı bir şablondan kaynakları dışarıda bırakmak. |
helm-chart, terraform | Reddedilir: provider kaynağını dağıtıldığında işlenmek üzere iletir, dolayısıyla derleme zamanında dışarıda bırakılacak bir belge yoktur. Yerel bir chart veya modül için bunun yerine Recipe’in yanındaki .aggregaignore dosyasında bir satır, ondan bir dosyayı dışarıda bırakır. |
Aynı anahtar bir FeatureRecipe üzerinde de yazılır; bkz. entities/featurerecipe.md.
Uygulamalı bir örnek için — getirilmiş bir chart’ın ürettiği Secret’ın dışarıda bırakılması, aynı chart’ın girdi olmadan karşılaştığı belirlenimcilik durdurması ve hiçbir şeyle eşleşmeyen bir girdideki durdurma; her biri gerçek bir derlemeden — bkz. ai-gateway-own-webhook-certificate.