Recipe girdi bileşimi — Üç girdi türü, Workload, artifact'ler
Bir Recipe, hedef sağlayıcısı için manifest dosyaları üretir. Bu bölüm, Recipes’in çıktılarını birbirinden bağımsız üç girdi türünden — kaynaklı (sourced), sentezlenmiş (synthesized) ve artifact’ler — nasıl oluşturduğunu, her girdi türünün nasıl yapılandırıldığını ve hangi sağlayıcının hangi çıktıyı ürettiğini ele alır. Recipe varlığının kavramsal rolü (Developer Intent’i tek bir fiziksel sağlayıcıya eşleyen, Ops tarafından yazılan çeviri şablonu) 04-entity-taxonomy.md belgesinde; anahtar sözcük düzeyindeki Recipe yazım yüzeyi ise ../language-reference/entities/recipe.md belgesinde yer alır.
Gerekçe
Her provider’ın yerel oluşturma aracı — Helm, Docker Compose — provider’a özgü manifest’lerin nasıl oluşturulacağını zaten bilir. Bir Recipe’in görevi, bu manifest’lerin NE söylemesi gerektiğini bildirmektir: hangi container imajları, hangi portlar, hangi ortam değişkenleri, hangi birimler, hangi servisler, hangi kaynak sınırları.
Bir Recipe, bir Deployment ve bir Service üzerine eşlenen sabit bir anahtar kümesinin (örneğin image, environment, ports, replicas) taşıyabileceğinden fazlasını ifade etmek zorundadır; bunlar arasında şunlar vardır:
resources(CPU/bellek istekleri/sınırları)- Liveness, readiness veya startup yoklamaları
volumeMounts/volumesnodeSelector/affinity/tolerationsserviceAccount/securityContext- Çok container’lı pod’lar, sidecar’lar
- ConfigMap / Secret / PVC / CRD kaynakları
- ClusterIP olmayan Service’ler (LoadBalancer, NodePort, Headless)
Soyutlama katmanının sabit bir anahtar kümesini değil, eksiksiz bir iş yükü biçimini tanımlaması gerekir. Aşağıda açıklanan üç girdi türü bu soyutlamadır: bir Recipe, çıktısını toplamalı olarak harici olarak yüklenen bir chart’tan veya modülden (source:), provider’ın provider’a özgü manifest’lere sentezlediği soyut bir Workload belirtiminden (workload:) ve Recipe’in doğrudan ürettiği şablonlanmış provider’a özgü manifest’lerden (artifacts:) oluşturur.
Üç girdi türü
Toplama yoluyla birleştirme
Bir Recipe’ten sağlayıcıya özgü manifest dosyaları üretmenin üç yolu vardır ve bunlar birbirini dışlamak yerine toplama yoluyla birleşir:
source:— sağlayıcının yerel olarak işlediği, harici olarak yüklenen bir yapıt (Helm chart, compose dosyası); üst katman değerlerinivaluesMapping:sağlar.workload:— sağlayıcının sağlayıcıya özgü manifestlere sentezlediği soyut bir Workload belirtimi (platformun sahip olduğu tür). Alan, satır içi bir YAML blok skaleri veya tek bir yerel dosyaya ya da kütüphane girdisine işaret eden bir$import:kabul eder; yönlendirme içeriğin biçimine göre yapılır.artifacts:— tam sütun bağlamına karşı Go şablonuyla işlenen, satır içi veya$import:ile yüklenen sağlayıcıya özgü manifestlerden oluşan bir eşleme. Her girdi satır içi olarak (girdinin değeri bir blok skalerdir) veya tek bir dosyaya ya da kütüphane içeriğine işaret eden$import:ile yazılabilir.
Üçü de derleyicinin sınırın çıktı dizinine yazdığı dosyalar üretir. Aşağıdaki doğrulama kurallarına tabi olarak üçü tek bir Recipe içinde bir arada bulunabilir. Birleştirme semantiği yalnızca üst düzeydedir: her girdi türü eksiksiz dosyalar üretir; dosyalar yan yana yazılır; çıktı dosya adında çakışma ölümcül bir hatadır.
Tanımlayıcı mod adları
Üç “mod”, belgeler ve tanılamalar için tanımlayıcı bir sözcük dağarcığıdır. Recipe yazarları bir mod bildirmez; ihtiyaç duydukları anahtar sözcükleri yazarlar. Bir Recipe, baskın girdisiyle nitelendirilir:
| Baskın anahtar sözcük(ler) | Tanımlayıcı mod adı |
|---|---|
source: + valuesMapping: (workload: yok, artifacts yok) | kaynaklı |
workload: (source: yok, artifacts yok) | sentezlenmiş |
artifacts: (source: yok, workload: yok) | artifacts-only (gayriresmî olarak: “satır içi”) |
| İki veya daha fazlasının herhangi bir birleşimi | açıkça betimlenir (ör. “artifacts ile kaynaklı”, “artifacts ile sentezlenmiş”) |
mode: adında bir anahtar sözcük ve bir enum yoktur. Mod, hangi girdilerin mevcut olduğundan ortaya çıkan bir özelliktir.
Bir bakışta Recipe yapısı
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: ... version: 1.0.0spec: capability: helm | compose | helm-chart | ... implements: core/...:1.0.0
locals: { ... } provides: { ... }
# ─── Sourced input (optional, paired) ─── source: ... valuesMapping: | # Go template → YAML/JSON overlay values # OR: valuesMapping: $import: ./mappings/api-server.tmpl # local file path # OR: valuesMapping: $import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ─── workload: | # Go template → YAML → parsed Workload # OR (single-source $import for whole-content load from a file or library): workload: $import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ─── artifacts: "filename.yaml": | # Inline Go template → manifest YAML "other.yaml": $import: ./artifacts/other.yaml # per-entry $import: for file or library contentYukarıdaki her alan Recipe şeması tarafından kabul edilir ve derleyici üç girdi türünün tümünü işler: kaynaklı işleme, Workload sentezi ve artifacts üretimi. Farklı olan, sağlayıcı başına destektir; yani hangi sağlayıcının hangi girdi türünü işlediği. Bu bilgi, bu bölümün sonundaki Provider Capability Matrix’te (Provider yetenek matrisi) yer alır.
Yükleme zamanı doğrulama kuralları
Recipe şeması ve yükleme doğrulaması şu birleştirme kurallarını uygular:
valuesMapping:,source:gerektirir. Üzerine katman eklenecek birsource:olmadan eşlenen değerleri alacak bir şey yoktur.valuesMapping:içeren vesource:içermeyen bir Recipe yükleme zamanı hatasıdır. (valuesMapping:olmadan birsource:kullanılabilir — chart veya modül kendi varsayılanlarıyla işlenir.)workload:tek bir kaynak kabul eder — satır içi veya$import:, ikisi birden değil. Bir Recipe, Workload’u ya satır içi bir blok skaleri ya da tek bir dosyaya işaret eden bir$import:olarak belirtir.$import:biçimi, birleşik dosya içe aktarma sözcük dağarcığına göre tek kaynaklıdır;workload:düzeyinde çok kaynaklı birleştirme desteklenmez. Hatalı biçimlendirilmiş bir yönlendirmede yükleme zamanı hatası verilir.workload:sentez yapabilen bir sağlayıcı gerektirir. Sentez desteği, bildirilen herhangi bir alanın değil, sağlayıcının kendisinin bir özelliğidir. Sentez yapamayan bir sağlayıcıya bağlı birworkload:Recipe’si, düğüm işlendiğinde sağlayıcı yetenek kapısı aracılığıyla (bkz. Provider Capability Matrix) açık bir tanılama mesajıyla reddedilir. Standart kütüphane kataloğu, belgelenmiş çeviri sözleşmesi olarak, uzlaşım gereği sentez yapabilen sağlayıcılardaworkloadSchemabildirir; ancak kapı, bu alanın varlığına değil, sağlayıcının kendi bildirdiği yeteneğe göre karar verir.- En az bir girdi türü bulunmalıdır.
source:+valuesMapping:,workload:veyaartifacts:öğelerinden hiçbirini içermeyen bir Recipe çıktı üretmez ve yükleme zamanı hatasıdır. - Satır içi ve
$import:yapıt girdileri bir arada bulunabilir. Bir Recipe, bazıartifacts:girdilerini satır içi, diğerlerini girdi başına$import:yönergeleriyle bildirebilir. Her girdinin anahtarı kendi çıktısını adlandırır; bu yüzden iki biçimin girdileri hiçbir zaman birbiriyle çakışmaz (bkz. Her çıktı dosyasını ne adlandırır). - Girdi türleri arası dosya adı çakışmaları işleme zamanı hatalarıdır. Bir Recipe’in girdi türlerinden ikisi — kaynaktan işlenen çıktı, workload’dan sentezlenen çıktı veya yapıttan üretilen çıktı — aynı ada sahip bir dosya üretirse, derleyici her katkıda bulunanı belirten ölümcül bir hata verir. Bu denetim Workload çevirisinden sonra çalıştığı için yükleme zamanında değil, işleme zamanında gerçekleşir.
Workload türü
Sahiplik ve konum
Workload, apiVersion: aggrega.ai/v1beta1 sürümünde platforma ait bir türdür. JSON Schema 2020-12 bildirimi derleme zamanında derleyici ikili dosyasına gömülür; katalog yazarları Workload şemasını düzenlemez ve katalog varlıkları olarak bağımsız Workload YAML dosyaları da yazmaz. Workload dilbilgisi yalnızca bir Recipe’in veya FeatureRecipe’in workload: alanı içinde (satır içi ya da tek bir dosyaya veya bir WorkloadLibrary girdisine $import: ile) tüketilir, başka hiçbir yerde tüketilmez.
Workload, bir platform türü ve bir derleyici kavramıdır; Varlık taksonomisi içinde ayrı bir varlık değildir. Yazım varlığı Recipe’tir; Workload ise Recipe’in sentezlenen girdisinin aldığı biçimdir.
Recipe başına bir Workload
Bir Recipe en fazla bir workload: bildirir. Workload, bu Recipe’in uyguladığı Component ile ilişkili tek hesaplama birimini temsil eder. Bir FeatureRecipe de aynı şekilde kendisine ait en fazla bir workload: bildirir — aynı Workload türü üzerinden sentezlenen, Feature’a ait bir hesaplama birimi — bkz. FeatureRecipe. Ek yan iş yükleri gerektiren kullanım durumları şunlarla ifade edilir:
artifacts:— aynı Recipe içinde, iş yükünün yanında ek manifestler (satır içi ya da girdi başına$import:ile).- Kaynak üretimli Features — ayrı katalog varlıkları olarak bildirilen, kesişen yan iş yükleri (ör. veritabanlarına eklenen bir yedekleme sidecar’ı); burada FeatureRecipe kendi
workload:alanını sentezler (ya dasource:/artifacts:üzerinden işler). FeatureRecipe kaynak üretimi için bkz. 14-extensibility.md.
Bu, yazar başına tek hesaplama birimi modelini korur: bir Recipe, Component’in iş yükünü sentezler; bir FeatureRecipe ise kendi iş yükünü sentezler.
Tam yüzey
Workload’un alan kümesi büyüktür ve büyümeye devam eder. Bir kopyanın, bunu bildiren hiçbir şey olmadan sözleşmenin gerisinde kalacağı bu bölümde onu yeniden yazmak yerine, bu bölüm alan kümesinin tamamını taşıyan iki yüzeye işaret eder:
- Üretilen Workload şema başvurusu — her alan, türü, varsayılanı ve kısıtları; yayımlanan JSON Schema’dan üretilir ve her derlemede onunla karşılaştırılır, bu nedenle derleyicinin kabul etmediği bir biçimi tanımlayamaz.
- Workload yazım sayfası — alan düzeyinde yazım rehberliği: her alanın ne anlama geldiği, her sağlayıcının onu neye dönüştürdüğü ve derlemenin hangi birleşimleri reddettiği.
Workload JSON Schema 2020-12 bildirimi yetkili kaynaktır ve derleyici ikili dosyasına gömülü olarak gelir. helm ve compose sağlayıcıları, satır içi ya da $import: ile yüklenmiş olsun, bir Recipe’in workload: alanını sentezler; sağlayıcı başına destek için Provider Capability Matrix’e bakın.
featuresSchema ile gizli bilgi entegrasyonu
Workload’un containers.<name>.attachments bloğu, Component’in featuresSchema alanında bildirilen yuvalara başvurur; yeni yuva bildirmez. featuresSchema yazım yüzeyi için bkz. ../language-reference/entities/component.md.
Doğrulama sözleşmesi:
- Her
attachments.<KEY>.fromdeğeri, Component’infeaturesSchemaalanında bildirilen bir yuva adıyla — ya daconnection: <alias>ile bir bağlantıyı adlandıran bir girdi için, o bağlantının soketininusesSchema.<socket>.featuresSchemaiçinde bildirdiği bir yuvayla — eşleşmelidir. Böyle bir girdi, bu kuralların herhangi biri çalışmadan önce bağlantının eklentisinin bileşende aldığı ada (<alias>.<slot>) yeniden yazılır; böylece aşağıdaki her kural onu, Component’in kendi yuvasını adlandıran bir girdiyi okuduğu gibi okur. as:teslim mekanizması (envya dafile), o yuvanıninject:dizisinde izin verilenler listesinde bulunmalıdır.- Component’in
featuresSchemaalanındainject: [](kara kutu) olarak işaretlenen yuvalar Workloadattachments:bloklarında yer alamaz — bu yuvalar Workload açığa çıkarımı yoluyla değil, Recipe’in iç tesisatı tarafından (ör. HelmexistingSecretile) teslim edilir.
Örnek:
# In the Componentspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipeworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected — root_password is blackboxSağlık yoklamaları: mekanizma değil, niyet
Kubernetes yoklamaları ile Docker Compose healthcheck’leri farklı biçimlere sahiptir. Tek bir soyut niyet biçimi her ikisine de temiz biçimde dönüşür:
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Providers her niyeti kendi yerel biçimlerine dönüştürür:
| Niyet | Helm (K8s) | Compose |
|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" |
exec: [cmd] | exec.command: [cmd] | CMD [cmd] |
Açık bir port belirtilmemiş http: için port çözümlemesi, her iki hedefte de konteynerin containers.<name>.ports altında bildirdiği alfabetik olarak ilk port adını alır. Adlandırılmış port bildirmeyen bir konteyner HTTP yoklaması taşıyamaz ve derleme, yoklamayı adlandırarak durur.
Compose, HTTP/TCP yoklamalarını healthcheck kabuk komutlarına indirger ve bir compose servisi tek bir healthcheck taşır: birden fazla yoklama bildirildiğinde biri çevrilir ve bir uyarı atılanları adlandırır.
Birim türleri
Beş birim türü; bileşik tür yok:
| Tür | Anlam | K8s (helm) | Compose |
|---|---|---|---|
ephemeral | Tmpfs / emptyDir; pod ile birlikte yok olur | emptyDir: { sizeLimit } | tmpfs: bağlaması, boyut taşımaz (yazılmış bir sizeLimit bir uyarıyla bildirilir) |
configmap | Salt okunur yapılandırma dosyaları | ConfigMap birim başvurusu | Recipe’in artifacts: alanının bildirdiği üst düzey bir config’e servis düzeyinde configs: başvurusu |
secret | Salt okunur gizli bilgi dosyaları | Secret birim başvurusu | salt okunur bind-mount edilmiş gizli bilgi dosyası |
persistent | Tek PVC; pod yeniden başlatmalarından sağ çıkar | PVC kaynağı + volume.persistentVolumeClaim | adlandırılmış birim |
persistentTemplate | Kopya başına PVC; form: stateful ile birlikte kullanılır | StatefulSet.volumeClaimTemplates | adlandırılmış birim (indirgenmiş; uyarı verilir) |
Compose, kopya başına şablonları ifade edemez. persistentTemplate compose’a dönüştürüldüğünde, her kopyanın paylaştığı tek bir adlandırılmış birime indirgenir ve bir uyarı bu indirgemeyi bildirir. Bir persistentTemplate birimi form: stateful gerektirir; onu başka bir form üzerinde bildirmek derlemeyi durdurur.
Çoklu servis açığa çıkarımları
Her servis bağımsız bir açığa çıkarımdır. Yaygın bir örüntü: 8080 portunda bir HTTP servisi (ClusterIP dahili) + 9090 portunda bir metrik servisi (ClusterIP) + 9901 portunda bir yönetim uç noktası (LoadBalancer):
services: http: type: ClusterIP ports: web: 8080 metrics: type: ClusterIP ports: prom: 9090 admin: type: LoadBalancer ports: admin: 9901helm sağlayıcısı altında işlendiğinde her biri ayrı bir Kubernetes Service nesnesine dönüşür; bu sağlayıcı bir Loopback girdisinde ise durur. Compose’da NodePort ve LoadBalancer servisleri portlarını compose servisinin her ana makine arabiriminde, Loopback servisleri yalnızca ana makinenin geri döngü adresinde yayımlar; ClusterIP ve Headless servisleri ise hiçbir şey yayımlamaz.
K8s çıktısındaki servis adlarına benzersizlik için bileşenin instance_id değeri önek olarak eklenir. Port adları, containers.<name>.ports içinde bildirilen konteyner port adlarıyla eşleşmelidir.
Provider tarafı çeviri sözleşmesi: workloadSchema
Sağlayıcı işleyen bir Plugin (pluginType: provider), Workload alanlarının o sağlayıcının yerel çıktısına nasıl dönüştüğünü belgeleyen bir JSON Schema 2020-12 bildirimi olan spec.provider.workloadSchema alanını bildirir. Bu, kendini belgeleyen dönüştürme sözleşmesidir. spec.provider bloğu dahil Plugin yazım yüzeyi için bkz. ../language-reference/entities/plugin.md.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: helm-renderer version: 1.0.0 pluginType: providerspec: abiVersion: v1beta1 provider: workloadSchema: | # how Workload translates to K8s manifests // Each Workload produces: 1 controller object chosen by workload.form // (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job) // + 1..N Services (one per workload.services entry) // + 1..N PVCs (one per workload.volumes.*.persistent entry) // + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source) // ...workloadSchema alanı, dönüştürme niyetini katalog yazarlarına ve IDE araçlarına iletir. Sentez yapan sağlayıcılarda uzlaşım gereği bildirilen, belgelenmiş dönüştürme sözleşmesidir — ancak sentez desteğini bu alanın varlığı değil, sağlayıcının kendisi belirler. Sentez yapamayan bir sağlayıcıyı workload: ile hedefleyen bir Recipe, sağlayıcı workloadSchema bildirsin ya da bildirmesin, düğüm işlendiğinde — sağlayıcı yetenek kapısı aracılığıyla — açık bir hatayla reddedilir.
Plugin şeması spec.provider.workloadSchema alanını bildirir — gövdesi Plugin yüklendiğinde JSON Schema 2020-12’ye derlenir — ve Recipe tarafında workload: tüketimi kullanıma sunulmuştur. Sentez desteği, işleme zamanında, bağlı sağlayıcının bildirdiği yeteneğe göre çalışan sağlayıcı yetenek kapısı tarafından uygulanır; workloadSchema, standart kütüphane kataloğunun bu yetenekle eşzamanlı tuttuğu belgelenmiş sözleşmedir, kapının girdisinin kendisi değildir. Ayrıca tüm katalog üzerinde çalıştırılan aggrega validate, katalog o sağlayıcının Plugin varlığını içeriyorsa, sentez yapmayan bir sağlayıcıya bağlı bir workload: Recipe’ini derlemeden önce, erkenden gösterir.
Yardımcı kaynaklar Workload’un dışında yer alır
Workload spesifikasyonunda additionalResources alanı, extras alanı ya da satır içi ConfigMap/Secret/CRD bildirimleri yoktur. Workload yalnızca iş yükünün biçimini modeller: konteynerler, birimler, servisler, replikalar, zamanlama, güvenlik bağlamı, servis hesabı — tek hesaplama biriminin nasıl çalıştığını tanımlayan her şey.
Yardımcı kaynakların Workload dışında iki meşru yeri vardır:
- Features + FeatureRecipes — kesişen kaygılar için kullanılan mekanizma. “Metrikleri açığa çıkan herhangi bir sunucuya” eklenen bir ServiceMonitor, Feature olarak
core/prometheus-exporter’dır. Bir sunucuyu bir ana bilgisayar adında yayımlayan yönlendirme kaynağı da bir Feature’dır ve hangisi olacağına yönlendirme biçimi karar verir: hedefin bir Ingress’i uzlaştırdığı durumdacore/public-ingress, Gateway API’yi çalıştırdığı durumdacore/http-route— her biri, Manifest’in her Release için seçtiği bir FeatureRecipe tarafından gerçekleştirilir. Tüm üretim iş yüklerine uygulanan bir NetworkPolicy, üretim Release’inin sınırın tamamına eklediği bir Feature’dır. Features birbirinden bağımsız olarak birleşir ve Recipes genelinde yeniden kullanılabilir. FeatureRecipe kaynak üretimi için bkz. 14-extensibility.md. - Recipe düzeyinde
artifacts:— bu belirli Recipe’nin uygulamasına ait olan ve bir Feature oluşturmaya değmeyen kaynaklar için. Recipe’nin ihtiyaç duyduğu tek seferlik bir CRD kaydı. Yalnızca bu Recipe kullanıldığında geçerli olan, Recipe’ye özgü bir PodDisruptionBudget. Recipe’nin Workload’unun başvurduğu bir ConfigMap. Her girdi satır içidir ya da$import:ile yüklenir; aşağıdaki Artifacts mekanizması bölümüne bakın.
Feature ile artifact arasındaki çizgi toplumsal bir uzlaşımdır. Bir yardımcı kaynak kesişen bir nitelikteyse (birçok Recipes’e uygulanıyorsa ya da seçiciler aracılığıyla koşullu olarak bağlanıyorsa) bir Feature’dır. Yalnızca bu tek Recipe’e özgüyse (Recipe o kaynağı üretmeden işini yapamıyorsa) bir artifact’tir. Yazarlar yeniden kullanım ve bağlanma semantiğine göre seçim yapar; derleyici bu seçimi denetlemez.
Features ve Recipe artifact’ları birlikte, bir Recipe’in ihtiyaç duyduğu yardımcı kaynakları karşılar.
Artifacts mekanizması
Satır içi ve dosyadan yüklenen artifact’ler
artifacts girdi türü, şablonlanmış sağlayıcıya özgü manifest dosyalarını, kaynaktan render edilen ya da workload’dan sentezlenen çıktının yanında doğrudan sınır çıktısına yazar. Yazarlar bunu iki yüzey üzerinden bildirir:
spec: artifacts: "servicemonitor.yaml": | apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: {{ .context.instance_id }}-monitor spec: endpoints: - port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml": $import: ./artifacts/networkpolicy.yaml "crd-registration.yaml": $import: ./artifacts/crd-registration.yaml$import: yolları Recipe dizinine görelidir ve bu dizinin içinde kalmalıdır; çünkü Recipe’in bir yayınının taşıdığı her dosya bu dizinden alınır — bir içe aktarmanın adlandırdığı her dosya onunla birlikte taşınır — ve dizinin dışındaki bir dosya taşınmaz. Yaygın bir uzlaşım bunları bir ./artifacts/ alt dizinine yerleştirir, ancak derleyici bunu zorunlu kılmaz. Eşlem anahtarı yazılan her dosyayı adlandırır — bir sonraki bölüm bunun üç biçimin her birinde ne anlama geldiğini ele alır.
Her girdi (satır içi ya da $import: ile yüklenen), çıktı dizinine yazılmadan önce tam şablon bağlamına karşı Go şablonuyla işlenir.
Her çıktı dosyasını ne adlandırır
Eşlem, girdi adına göre anahtarlanır ve anahtar, her yazım biçiminde girdinin ne ürettiğini adlandırır. Satır içi bir girdi için anahtar, yazıldığı gibi kullanılan çıktı dosya adıdır:
artifacts: "configmap-config.yaml": | ... "pdb.yaml": | ...configmap-config.yaml ve pdb.yaml dosyalarını üretir. Anahtar dosya adını belirler; dosyanın nereye düşeceği hedefin kararıdır ve aşağıdaki sağlayıcı başına yazım bölümü bunu ele alır.
Bir dosya $import: girdisi için de anahtar çıktı dosya adıdır. İçe aktarılan dosya içeriği sağlar; adı sağlamaz, bu nedenle belirli bir çıktı dosya adı isteyen yazar bu adı anahtar olarak yazar:
artifacts: "monitor.yaml": $import: ./artifacts/monitor.yaml "netpol.yaml": $import: ./artifacts/subdir/some-other-name.yaml.../monitor.yaml ve .../netpol.yaml dosyalarını üretir. İkinci girdinin içe aktarılan dosyasının adı some-other-name.yaml’dir ve bu ad çıktıya ulaşmaz — anahtar ulaşır. Bu nedenle, adları tesadüfen aynı olan farklı dosyaları içe aktaran iki girdi, ./extras/shared.yaml ve ./overrides/shared.yaml, her biri kendi anahtarıyla adlandırılan iki ayrı çıktıdır.
Bir dosya demetini tek bir birim olarak çeken bir kütüphane $import: girdisi için girdi, demetteki her dosya başına bir çıktıya genişler ve her biri anahtarın altında <key>/<filename> olarak yer alır. Tek bir anahtar çok sayıda dosyayı adlandırdığından anahtar tek başına onları adlandıramaz: anahtar, herhangi birinin adı değil, demetin dosyalarının düştüğü dizindir.
Her biçim çıktısını anahtardan adlandırdığı için anahtar, yazım yüzeyinde tek bir dosya adının olabileceği şeyle sınırlandırılır: başta bir harf ya da rakam, ardından harfler, rakamlar, noktalar, tireler ve alt çizgiler. Noktalar tüketicinin beklediği uzantıyı taşır; bir anahtarı doğrudan dosya adı olarak kullanılabilir kılan da budur. Alfabe ne / ne de baştaki . karakterini içerir; bu nedenle bir anahtar hiçbir zaman birden fazla yol bölümü yazamaz ve hiçbir zaman üst dizin bölümü olamaz. 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.
Aynı dosya adını taşıyan iki artifacts: çıktısı, hangi biçimler üretmiş olursa olsun, düğüm render edildiğinde derlemeyi durdurur. Tek bir artifacts: eşleminin iki girdisi hiçbir zaman tek bir çıktıyı adlandırmaz: bir anahtar bir belge içinde benzersizdir ve tek bir dosya adıdır; bu nedenle tek dosyalı bir girdinin çıktı adı anahtarıdır ve bir demet girdisinin çıktılarının tümü anahtarıyla adlandırılan bir dizinin altında yer alır. Dolayısıyla yazılan her yolun ilk bölümü onu üreten anahtardır ve farklı anahtarlar farklı çıktı adları olarak kalır. Durdurmanın kapsadığı, girdi türleri arasında geçen durumdur — ikisi tarafından katkıda bulunulan tek bir dosya adı, örneğin bir chart şablonu ve bir artifact girdisinin her ikisinin de servicemonitor.yaml üretmesi — ve tanılama katkıda bulunan her kaynağı adlandırır.
Artifact’ler için şablon bağlamı
Artifact şablonları tam sütun bağlamına erişebilir:
.values,.infra,.context.*,.locals,.provides,.features,.metadata— 06-data-taxonomy-and-composition.md içinde açıklanan standart Aggrega sütunları..workload— bu Recipe için ayrıştırılmış Workload belirtimi (varsa). Artifact’lerin Workload değerlerine yineleme olmadan başvurmasını sağlar; örneğin.workload.services.metrics.ports.prom’a başvuran bir ServiceMonitor..source— çözümlenmişsource:alanı içeriği (varsa).
Artifact’ler Workload ayrıştırıldıktan sonra değerlendirilir; bu nedenle .workload mevcut olduğunda kullanılabilir. workload: içermeyen Recipes için .workload nil’dir; ona başvurmaya çalışan bir şablon açık bir hatayla başarısız olur. source: içermeyen Recipes için .source aynı başarısızlık biçimiyle nil’dir.
Kendi kendine yeterlilik değişmezi
Artifact’ler kendi kendine yeterli olmalıdır. Yalnızca Recipe’in bildirilmiş girdilerine başvurabilirler: sütun bağlamı, Recipe’in kendi Workload’u (varsa) ve Recipe’in kendi source: değeri. Şunlara başvuramazlar:
- Aynı sınırdaki diğer Recipes’in çıktıları.
- Recipe’in bildirmediği ortamdaki Kubernetes kaynakları.
- Harici olarak var olduğu varsayılan Secret’lar, ConfigMap’ler ya da diğer kaynaklar (bildirilmiş bir sütun üzerinden başvurulmadıkça).
Workload’un volumes.*.configmap.source alanının başvurduğu bir ConfigMap artifact’i, BU Recipe tarafından (o ConfigMap’i üreten artifacts: aracılığıyla) ya da bu düğüme eklenmiş bir Feature tarafından yazılmalıdır. Bir sınır içindeki Recipe’ler arası bağımlılıklar desteklenmez.
Bu değişmez, Recipe’in yeniden kullanılabilirliğini korur: bir Recipe, sütun sözleşmesini karşılayan herhangi bir Aggregate + Release birleşimine gizli bağımlılıklar olmadan yerleştirilebilir.
Köken etiketleri
Çeviri sonrasında, yayılan her dosya meta verisinde aggrega.ai/* köken bilgisi taşır; dosyanın kaynaktan işlenmiş, workload’dan sentezlenmiş ya da bir artifact şablonundan yayılmış olması fark etmez. Yayan her yüzey bu bilgiyi tek bir ortak oluşturucu kümesinden damgalar; böylece aynı dosya, hangi girdi türü üretmiş olursa olsun her zaman aynı köken bilgisini taşır. Küme, bir değerin Kubernetes etiket değeri karakter kümesini karşılayıp karşılamadığına göre ikiye ayrılır: etikete uygun anahtarlar etiketlerdir (sorgulanabilir); karakter kümesine uymayan anahtarlar — recipe-uri (bir : taşır), boundary-path (iç içe bir yol / taşır) ve sync-wave (negatif bir dalganın baştaki - işareti) — değerleri kısıtlanmamış olan ek açıklamalardır (annotation). Derlemenin etiket kurallarına uymaya zorlamadığı bir kimlik değeri — aggregate adı, ortam, sağlayıcı adı, derleyici ve sağlayıcı sürümleri — bir etiketin kabul ettiği biçimde yazılmış bir etikettir ve bu biçimin değerden farklı olduğu durumlarda değerin kendisi aynı anahtar altında ayrıca bir ek açıklamadır (imported/flow adlı bir Aggregate, imported-flow etiketini ve imported/flow ek açıklamasını alır). Aynı Recipe’in çıktısını taşıyan tüm dosyalar aynı köken bilgisini paylaşır:
metadata: labels: aggrega.ai/component-id: api # ... plus the recommended app.kubernetes.io/name label annotations: aggrega.ai/recipe-uri: api-server-helm:1.0.0 aggrega.ai/boundary-path: productionBu ayrım üç girdi türünün tamamında aynıdır. (Compose sağlayıcısında ek açıklama kavramı yoktur ve etiket değerleri kısıtlanmamıştır; bu nedenle kümenin tamamını servis etiketleri olarak yayar.) Derleme zamanında köken damgalama için bkz. 11-governance-and-compliance.md.
Bir sağlayıcı köken bilgisini kendi çıktı biçiminin onu taşıdığı yere damgaladığından, biçimi belirli bir dosya için böyle bir yer sunmayan sağlayıcı o dosyayı değiştirmeden yayar ve bunu bildirir. Bilinmesi gereken durum Compose’dur: köken bilgisinin yeri bir servisin labels: bloğudur; bu nedenle yalnızca üst düzey volumes:, configs: veya models: katkısı yapan bir compose artifact parçası köken bilgisi taşımaz ve derleme, artifact’ı adlandıran bir “skipped provenance label injection” (köken etiketi ekleme atlandı) uyarısı yayar. Bu uyarı, bu biçimdeki bir parça için bir sorun belirtisi değil, beklenen bir durumdur — aynı bileşenin yaydığı servisler kümenin tamamını taşır ve yayılan baytlarda hiçbir şey değişmez. Bunun dışladığı şey üçüncü olasılıktır: bir dosyanın adı belirtilmeden damgasız olarak derlemeden çıkması.
Bilinmesi gereken diğer durum CloudFormation’dır ve köken bilgisinin eklenip eklenmediğinde değil, nereye eklendiğinde farklılaşır. Bir CloudFormation şablonu, bir kaynakla birlikte taşınan belge düzeyinde bir meta veri bloğu içermez; bu nedenle köken bilgisi her kaynağın kendi Metadata özniteliğine, kümenin tamamını tutan tek bir aggrega.ai/provenance anahtarı altında yazılır:
"StoreBucket": { "Type": "AWS::S3::Bucket", "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/component-id": "store", "aggrega.ai/recipe-uri": "store-recipe:1.0.0", "aggrega.ai/boundary-path": "stack" } }}Bu konumdan üç özellik doğar. Metadata özniteliği türü ne olursa olsun her kaynakta bulunur; bu nedenle birleştirilmiş bir yığının taşıdığı her kaynak damgalanır — etiket tabanlı bir damganın yer bulamayacağı, hiç etiket kabul etmeyen pek çok kaynak türü de dahil. Damga, yazarın yazdığı Metadata’nın yerini almaz, ona eklenir; böylece yazarın kendi girdileri onunla yan yana durur. Ayrıca damga şablon başına değil kaynak başına olduğundan, birden çok bileşenin birleştiği bir yığın her kaynağın kendi katkı veren kimliğini — bileşenini, Recipe’ini ve sınırını — taşır; şablon genelindeki tek bir girdi bunu ifade edemezdi.
Kümenin tamamı o anahtar altında birlikte taşınır. Bir Metadata değeri kısıtlanmamış JSON’dur; bu nedenle yapılacak bir karakter kümesi ayrımı yoktur. Yalnızca bir Kubernetes çalışma ortamının okuduğu iki anahtar — standart önerilen etiket adı ve bir GitOps denetleyicisinin kullandığı dağıtım sıralama ek açıklaması — hiçbiri bir yığında bir şeyi adlandırmadığından dışarıda bırakılır. Düz aggrega.ai/sync-wave köken girdisi ise kalır, çünkü bir denetleyiciye talimat vermek yerine bileşenin bildirdiği dalgayı kaydeder.
Burada yeri olmayan biçim, hiçbir kaynak bildirmeyen bir şablon veya parçadır — yalnızca Parameters, Mappings, Conditions veya Rules katkısı yapan bir parça. Bu parça köken bilgisi taşımaz, birleştirilmiş yığına kendi içeriği bozulmadan ulaşır ve derleme onu adlandıran bir “skipped provenance injection” (köken ekleme atlandı) uyarısı yayar. Compose’da olduğu gibi bu uyarı, bu biçimdeki bir katkı için beklenen bir durumdur: aynı bileşenin başka yerlerde katkı yaptığı kaynaklar kümenin tamamını taşır ve yayılan baytlar, bir şeyin dinleyip dinlemediğinden bağımsız olarak aynıdır.
Provider başına artifact semantiği
Aşağıdaki provider başına semantik, her provider’ın artifact’leri kendi yerel çıktısına nasıl entegre ettiğini açıklar.
helm provider: artifact’ler, chart’tan işlenen ve Workload’dan sentezlenen manifest’leri tutan çıktı dizininin içinde, onları bildiren component’in adını taşıyan bir dizinin altına yazılan Kubernetes YAML belgeleridir. Bunun nedeni adlandırmadır: işlenen veya sentezlenen bir manifest, provider tarafından ait olduğu component’e göre adlandırılır; bir artifact ise yazarının yazdığı anahtarla adlandırılır ve bu anahtar hangi component’e ait olduğu hakkında hiçbir şey söylemez. Bu nedenle tek bir Recipe’e bağlı iki component, hiçbir yazarın onları ayıramayacağı şekilde aynı yola yazardı. Dizin, component’in kendi adıdır; böylece yazarın çıktıda geri okuduğu dosya, bir seviye aşağıda, kendi yazdığı addır.
Farklı bir düzen isteyen bir operatör, yalnızca artifact’leri değil bir katkıda bulunanın ürettiği her dosyayı taşıyan boundary’nin subDirectory: şablonunu kullanabilir. Bkz. ../language-reference/path-template-variables.md.
compose provider: artifact’ler compose parçalarıdır. Üst düzey anahtarlar (services:, volumes:, configs:, models:), boundary birleştirme adımı sırasında boundary başına birleştirilmiş docker-compose.yaml dosyasına birleştirilir.
helm-chart provider (özel durum): artifact’ler çıktı dizinine bağımsız dosyalar olarak yazılmaz; işleme hattının sahibi Helm’dir. Bunun yerine helm-chart provider her artifacts: girdisini chart’ın kendisinin içine yerleştirir ve girdinin yazıldığı biçim nereye düşeceğini belirler. Her girdi, herhangi bir yerleştirmeden ÖNCE, Aggrega’nın pillar bağlamıyla Go şablonundan geçirilir; oradan sonra iki biçim ayrılır. $import: ile yüklenen bir girdi, Helm öncesi bir şablon dosyasıdır: Helm işlemesinden ÖNCE chart’ın templates/ dizinine enjekte edilir; böylece Helm onu kaynak chart’ın kendi şablonlarıyla birlikte işler. Satır içi bir blok skaler ise serbest bir chart dosyasıdır: chart kökünde, yazıldığı anahtar altında, templates/ öneki ve birleştirilmiş provenance etiketleri olmadan yerleştirilir; böylece chart’ın kendi şablonları onu Helm’in .Files.Get / .Files.Glob işlevleriyle okuyabilir — dosyalardan ConfigMap kalıbı. Bu, helm-chart provider’a, Helm’in chart modeline saygı göstererek, artifacts: anahtarının düz helm provider için sağladığına eşdeğer bir genişletme mekanizması verir.
Enjekte edilen dosya boundaries/<bp>/charts/<nodeID>/templates/<authored-key> konumuna düşer — bir paketin dosyaları bu anahtarın altında iç içe yer alır — böylece kaynak chart’ın şablonlarının yanında durur ve Helm onu sonraki işleme geçişinde alır. Satır içi bir blok skaler boundaries/<bp>/charts/<nodeID>/<authored-key> konumuna düşer — chart kökü, templates/ dizininin bir seviye üstü — çünkü .Files ile okunan bir dosya chart’ın onu aradığı yerde bulunmalıdır ve templates/ altına yerleştirilen bir dosya bunun yerine manifest olarak işlenir. Her iki biçim de altında yazıldıkları anahtarla adlandırılır; aralarındaki fark, provider’ın onları yerleştirdiği dizindir.
helm-chart sınırlayıcı uzlaşımı. Aggrega’nın helm-chart artifact girdileri üzerindeki ön şablon geçişi, $import: ile yüklenenler ve satır içi olanlar için aynı şekilde, dosyanın içindeki Helm’in kendi {{ ... }} sözdiziminin Helm’in işleme geçişine dokunulmadan ulaşması için varsayılan {{ }} yerine [[ ]] sınırlayıcılarını kullanır. Yazarlar Aggrega tarafı yerine koymaları [[ .context.instance_id ]], [[ .values.name ]] vb. olarak yazar; Helm tarafı yerine koymalar {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} vb. olarak kalır. Yazarların iki sınırlayıcı çiftini tek bir dosyada karıştırması desteklenen yazım biçimidir.
Provenance ve helm-chart artifact’leri. Provenance, Helm belirteçleri korunarak YAML üzerinden gidiş-dönüş yapabilen $import: ile yüklenmiş dosyalar için — yalnızca [[ ]] Aggrega bağlamı kullanan veya Helm {{ }} ifadelerini yalnızca tırnaklı skaler konumlarda içeren dosyalar — (yukarıdaki karakter kümesi ayrımına göre) metadata.labels ve metadata.annotations içine birleştirilir. Yapısal Helm şablon eylemleri içeren dosyalar (skaler yapraklar yerine YAML yapısı ürettikleri konumlarda {{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }}) veya değer konumlarında tırnaksız {{ ... }} içeren dosyalar Aggrega’nın YAML gidiş-dönüşünden sağ çıkmaz; derleme, artifact’i adlandıran bir “skipped provenance label injection” (provenance etiketi enjeksiyonu atlandı) uyarısı verir ve dosyayı değiştirmeden geçirir. Bu uyarı, yapısal Helm şablon eylemleri veya tırnaksız Helm değer yerine koymaları kullanan her helm-chart $import: ile yüklenmiş artifact dosyası için beklenen bir durumdur — üretimdeki Helm yazımında uç durum değil, yaygın durumdur. Bu tür dosyalarda provenance etiketlerine ihtiyaç duyan yazarlar, bunları Aggrega’nın ön şablon enjeksiyonu yerine chart’ın kendi _helpers.tpl dosyasına yazdıkları adlandırılmış bir şablon (örneğin aggrega.commonLabels adlı bir şablon) veya eşdeğer bir Helm tarafı mekanizma aracılığıyla enjekte eder.
Chart kökü dosya adı çakışmaları. Yazıldığı anahtar bir chart kökü dosya adıyla (Chart.yaml, values.yaml, .helmignore vb.) çakışan $import: ile yüklenmiş bir artifact, Aggrega’nın dosya adı çakışma denetimi tarafından algılanmaz — artifact templates/<authored-key> konumuna düşerken chart kökü dosyası chart köküne düşer ve yol öneklemesi Aggrega’nın bakış açısından onları farklı kılar. Yazarlar bu anahtar adlarından kaçınır; bunları kullanmanın sonucu, Helm’in her iki dosyayı da görmesi (biri chart kökünde, biri templates/ içinde) ve templates tarafındaki kopyayı beklenmedik biçimde işleyebilmesidir.
terraform provider: artifact’ler, boundary’nin modules/ ağacı altındaki component’in kendi dizinine olduğu gibi yazılan Terraform yapılandırma dosyalarıdır. HCL (main.tf) ergonomik varsayılandır ve Terraform JSON (.tf.json) eşdeğer olarak kabul edilir; hiçbiri dönüştürülmez veya yeniden biçimlendirilmez. Boundary’nin kök yapılandırması o component’i, source değeri o dizini gösteren bir module bloğu olarak bildirir; böylece bir boundary’nin tamamı tek bir bağımlılık grafiği olarak kalır. Bu, vendor’lanmış bir modülün dosyalarının bulunduğu dizinle aynıdır; bu nedenle hem source: hem de artifacts: bildiren bir Recipe bunları yan yana yazar. Provenance, başta yer alan bir Terraform yorum bloğu olarak taşınır; bir component yorum sözdizimi olmayan bir JSON gövdesi katkıda bulunduğunda, her gövde değiştirilmeden yazılır ve provenance onların yanındaki yalnızca yorum içeren eşlik eden bir .tf dosyasında taşınır; böylece damga ikisi arasında asla yinelenmez. Bkz. terraform provider sayfası.
cloudformation provider: artifact’ler yığın parçalarıdır — bütün bir şablon değil, bir component’in katkıda bulunduğu kaynaklar. Provider her parçayı saf JSON uzun biçimli intrinsic’lere normalleştirir ve o çıktı dizini için birleştirilen tek yığına birleştirir; burada kaynaklar tek bir Resources eşlemesinde birleşir ve component’in provides değerleri, yayımlayan component’e göre kapsamlanmış adlar altında yığının Outputs bölümü olarak ortaya çıkar. Bir parçanın diğer üst düzey bölümlerinden hangilerinin birleştirmeden sağ çıktığı Birleştirilmiş bir belgenin artifacts: anahtarından taşıdıkları bölümünde açıklanır. Bkz. cloudformation provider sayfası.
Boundary kapsamı: bir boundary’nin paylaşılan çıktısı için dosyalar
Artifacts mekanizmasının ikinci bir kapsamı vardır. Yukarıdaki her şey, bileşenin kendi boundary’sinin çıktısındaki kendi konumuna yazılır; bir Recipe’in spec.boundary.artifacts alanı aynı eşlemedir — aynı üç biçim, aynı anahtardan dosya adına kuralı, aynı şablon bağlamı — ancak bunun yerine boundary’nin bütünü için bir kez yazılır. Hedefin bir boundary’nin dağıttığı her şey için bir kez okuduğu, hiçbir bileşenin kendi konumunun barındıramayacağı bir dosya için vardır: Terraform’un belgeleri, çağrılmak üzere tasarlanmış bir modülün provider blokları içermemesi gerektiğini ve içeren bir modülün depends_on, count veya for_each ile çağrılamayacağını söyler; bu nedenle bir provider’ın yapılandırması, bir bileşenin modülünün içinde değil, boundary’nin kök yapılandırmasında yer alır.
Nereye yerleşir. Dispatch grubunun birleştirilmiş çıktısını tutan dizine, provider’ın kendi birleştirmesinin oraya yazdığı dosyaların yanına — terraform için kök yapılandırmanın yanına. Derleyici her girdiyi Recipe’in render ettiği her bileşen için bir kez, o bileşenin bağlamına göre değerlendirir ve dosyayı kendisi yazar: bu dosyaların hiçbiri provider’a verilmez ve hangi bileşenden geldiğini belirtmek için hiçbirine bir şey damgalanmaz, çünkü dosya onu bildiren her katkıda bulunana aittir.
Katkıda bulunanlar nasıl buluşur. Bir dispatch grubuna katkıda bulunan herkesin bildirdiği dosyalar ada göre birleştirilir. Aynı baytlarla bildirilen bir ad tek bir dosyadır; farklı baytlarla bildirilen bir ad ya da sağlayıcının kendi birleştirmesinin yazdığı bir ad, dosyayı ve her katkıda bulunanı adlandırarak derlemeyi durdurur — bu, iki katkıda bulunanın tek bir çıktı yoluna yazmasının karşılaştığı retle aynıdır. Dolayısıyla iki Recipes’in ihtiyaç duyduğu bir sağlayıcı yapılandırması her ikisi tarafından tek bir ad altında yazılır ve derleme bunların uyuştuğunu denetler.
Kim kabul eder. Bir boundary’nin birleştirilmiş çıktısının yanına yerleştirilen bir dosyanın bir anlam taşıyıp taşımadığı, provider’ın hedefinin bir özelliğidir; bu yüzden bu, girdi türleri gibi provider’ın kendi bildiriminden okunan, provider’ın kendi beyanıdır. Bloğu, bunu beyan etmeyen bir provider için bildiren bir Recipe, herhangi bir şey render edilmeden reddedilir. Aşağıdaki tablo bu beyanı son sütunu olarak taşır; derleyiciyle birlikte dağıtılan provider’lar arasında bunu terraform beyan eder.
Artifacts ne değildir
Üç yapısal ayrım:
Tek bir Recipe içinde provider’lar arası değildir. Bir Recipe, spec alanının en üstünde tam olarak bir capability: bildirir. Recipe’in ürettiği her şey — kaynaktan render edilen çıktı, workload’dan sentezlenen çıktı ve artifact çıktıları — o provider’ın yerel biçimindedir. Bir helm Recipe’inin artifact’leri Kubernetes YAML içerir. Bir compose Recipe’inin artifact’leri compose parçaları içerir. Bir Recipe tek bir provider’ı hedefler; her çıktı o provider’ın yerel biçimindedir.
Çoklu provider bileşimi Release düzeyinde gerçekleşir. Boundary’ler karışık provider’lı bileşenler barındırır; her provider’ın bir boundary’nin değerlendirilmiş yolundaki katkıda bulunanları, (yol, provider) başına bağımsız olarak dispatch edilir ve birleştirilir. Sırasıyla helm, helm-chart ve compose hedefleyen bileşenlere sahip bir Release, üçünü de tek bir boundary’ye yerleştirebilir; dispatch gruplaması bunları provider başına ayırır, her provider’ın katkıda bulunanları boundary’nin yolu altındaki kendi birleştirilmiş çıktısına yerleşir ve operatör, provider’lar arası koordinasyonu seçtiği boundary yapısıyla kendisi yazar. Provider’lar arası koordinasyon Release yazarının sorumluluğundadır.
Recipe içinde Recipes değildir. Artifact’ler başka Recipes yüklemez veya birleştirmez. Bunlar bu Recipe’in sütunlarıyla şablonlanan ve bu Recipe’in çıktısına yazılan satır içi manifest’lerdir (ya da satır içi manifest’lere giden dosya yollarıdır). Recipe yeniden kullanımı üç mekanizma ile gerçekleşir: bir Component’in extends: alanı (temel bir Component’e göre yazılmış bir Recipe, onu genişleten her Component’e hizmet eder; kalıtılan şey çıktı dosyaları değil, meta veriler ve şemalardır — bir Recipe’in kendisi extends: bildirmez); Manifest’in düz URI eşlemesi (aynı Component, kataloglar arasında farklı Recipes’e çözümlenebilir — bkz. ../language-reference/entities/manifest.md); ve Features + FeatureRecipes (dikey olarak eklenen, kesişen kaygılar).
Recipe’ler arası bir yapıştırıcı katman değildir. Artifact’ler, Recipe’in kendisinin bildirmediği adlara, kaynaklara veya duruma başvuramaz. Recipe’in Workload’unun başvurduğu bir ConfigMap artifact’i bu Recipe tarafından üretilmelidir. Harici olarak sağlanan bir Secret bekleyen bir artifact, o Secret’ın adını var olduğunu varsaymak yerine .features pillar’ı aracılığıyla — onu üreten eklentinin çözümlenmiş provides değerlerinden — almalıdır. Bu, artifact yazımı perspektifinden ifade edilen kendi kendine yeterlilik değişmezidir (yukarıda): her Recipe, tek bir araçla uygulanan, tek biçimdeki dosyaları tek bir boundary’nin çıktı dizinine üretir.
Provider yetenek matrisi
Her provider hangi girdi türlerini işlediğini bildirir; merkezi bir girdi türü denetimi, düğüm işlendiğinde desteklenen birleşimleri kabul eder ve geri kalanını tek tip bir tanılamayla reddeder. Yetenek, Recipe’in değil provider’ın bir özelliğidir; bir provider üç türün bir alt kümesini işler. artifacts: sütunu, kaynaklı/sentezlenmiş bir birincil çıktının yanında yer alan artifact’leri, yalnızca artifact’lerden oluşan bağımsız bir Recipe’ten (source: yok, workload: yok) ayırır. Son iki sütun, provider’ın omits: alanını dikkate aldığına ve bir Recipe’in boundary.artifacts: altında sınırının paylaşılan çıktısına kattığı dosyaları kabul ettiğine ilişkin beyanlarıdır (yukarıda); ikisi de bir girdi türü değildir.
Her sütunu kendi başına okuyun. Bir satır, bir provider’ın hangi türleri tek tek ele alındığında işlediğini söyler. İşaretli iki türün birlikte bildirilebileceğini söylemez. Türler toplama yoluyla birleştiğinden, bildirilen her tür ayrı ayrı gönderilir ve üretilir; bu nedenle bir çift, iki sütunun da taşımadığı bir nedenle reddedilebilir; çoğunlukla iki tür de aynı çıktı adı altında bir dosya ürettiği için. Her provider’ın gerçekte hangi birleşimleri kabul ettiği Her provider’ın kabul ettikleri, eksiksiz altında düz metinle belirtilmiştir.
| Provider | source: + valuesMapping: | workload: | artifacts: (yanında) | yalnızca artifact (bağımsız) | omits: | boundary.artifacts: |
|---|---|---|---|---|---|---|
| helm | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| compose | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| helm-chart | ✅ | ❌ | ✅ [[ ]] ayraçlarıyla şablonlanır | ❌ | ❌ | ❌ |
| terraform | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| cloudformation | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
Bu tablo, derleyiciyle birlikte dağıtılan provider’ları kapsar. Ayrıca sağlanan bir provider, kabul ettiği girdi türlerini, omits: alanını dikkate alıp almadığını ve boundary.artifacts: alanını kabul edip etmediğini aynı şekilde bildirir ve derleyici bu bildirimi aynı yoldan okur; burada listelenmez, çünkü yayımlanmış bir sayfa hiç görmediği provider’ları sayamaz.
✅ ile işaretli hücreler işlenir; ❌, denetimin ortaya çıkardığı bir provider yeteneği reddidir. Düğüm başına compose parçaları birleştirme yolu başına birleştirilir; bu nedenle bir directory: paylaşan sınırlar tek bir dosyayı paylaşır.
Her provider’ın kabul ettikleri, eksiksiz
helm — her birleşim. source: + valuesMapping:, workload:, artifacts:, bunlardan herhangi ikisi ya da üçü birden. Derleyiciyle dağıtılan ve hiçbir birleşimi reddetmeyen tek provider’dır; bunun nedeni çıktıyı adlandırma biçimidir: üretilen her dosya içindeki kaynağın adını alır, bu nedenle bir chart’ın işlenmiş manifest’leri ile sentezlenmiş bir Workload’un manifest’leri asla aynı ada düşmez. Üçünü birden bildiren bir Recipe, chart’ın dosyalarını, Workload’un dosyalarını ve artifact dosyalarını sınırın çıktı dizininde yan yana üretir.
compose — source: ile workload: alanlarının birlikte yer aldığı iki birleşim dışında her birleşim. Her tür tek başına derlenir ve artifacts: ikisinden birinin yanında yer alabilir. workload: ile birlikte source: derlenemez, üçü birlikte de derlenemez; nedenini compose neden bir kaynağı bir workload ile birleştiremez açıklar ve bu bir yetenek reddi değildir.
helm-chart — source: + valuesMapping:, tek başına ya da yanında artifacts: ile. Başka hiçbir şey. Bir workload: sentezlemez ve yalnızca artifact’ten oluşan bir biçimi yoktur: tek girdi türü artifacts: olan bir Recipe durdurulur. Bunun nedeni bu provider’ın bir artifact’i nereye koyduğudur: component’in kendi chart’ının içine. Bu nedenle source: içermeyen bir Recipe, artifact’in konacağı bir chart bırakmaz.
terraform — üç biçim: tek başına source: + valuesMapping:, tek başına artifacts: ya da ikisi birlikte. Bir workload: sentezlemez.
cloudformation — terraform ile aynı üç biçim, aynı tek dışlamayla. Tek başına source: + valuesMapping:, tek başına artifacts: ya da ikisi birlikte; workload: yok.
Reddedilen bir girdi türü nasıl görünür
Bağlı olduğu provider’ın işlemediği bir girdi türünü bildiren bir Recipe, düğüm işlendiğinde derlemeyi durdurur ve Recipe’in o türün yanında başka ne bildirdiğinden bağımsız olarak durdurur: bir workload: alanını provider’ın işleyebildiği bir source: ile eşlemek, workload’u geçirmez. Durdurma; provider’ı, işleyemediği türü ve işlediği türleri adlandırır:
[CATALOG_ERROR E0265] instance unit provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesizedYalnızca artifact reddi de aynı şekilde okunur ve o biçimi adlandırır: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). Bu durdurmanın kalıcı olarak adlandırılması gerektiğinde (sürekli entegrasyon denetiminde, bir issue’da ya da bir runbook’ta) kaydedilecek tanımlayıcı E0265’tir; her koşulun tablosu bunu çözümler.
compose neden bir kaynağı bir workload ile birleştiremez
Compose provider’ı component başına bir parça üretir ve bu parçayı component’in adıyla adlandırır. Kaynaklı işleme ve Workload sentezi, her biri o component’in parçasını bu tek ad altında üretir; bu nedenle ikisini birden bildiren bir Recipe aynı adlı iki dosya üretir ve derleme bu çakışmada durur:
[CATALOG_ERROR E0211] instance unit rendering node "unit" caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")Parçanın adı component’in kendi tanımlayıcısından gelir ve bunun için bir yazım yüzeyi yoktur; bu nedenle Recipe’in kendi içeriğinde yapılacak hiçbir değişiklik çakışmayı önlemez. Durdurma, türlerden birinin değil çiftin bir özelliğidir: compose bir kaynağı işler, compose bir Workload sentezler ve tablonun ikisini de işaretlemesi doğrudur. Compose altında tek bir component için iki biçimi de kullanmak üzere onları iki component’e bölün ya da kaynağın içeriğini Workload’a katın.
Birleştirilmiş bir belge artifacts: içinden neleri taşır
İki provider, katkıda bulunanlarını her derleme yolu için tek bir belgede birleştirir: compose tek bir docker-compose.yaml dosyasında, cloudformation tek bir stack şablonunda. Birleştirilmiş bir belge yalnızca derleyicisinin modellediği bölümleri taşıyabilir; bu nedenle bir artifacts: işareti, bir parçanın içeriğinin nereye yerleştirildiğini söyler, parçanın içindeki her anahtarın korunduğunu söylemez.
compose, bir artifact parçasından services:, volumes:, configs: ve models: bölümlerini, x- önekli uzantı anahtarlarıyla birlikte taşır. Üst düzeyde başka herhangi bir şey bildiren bir parça, anahtarı adlandırarak derlemeyi durdurur: networks:, çünkü ağlar katkıda bulunanlardan biriktirilmek yerine her sınır için türetilir; aynı şekilde bir secrets: bloğu ya da üst düzey bir name: de. Compose provider sayfası, anahtar başına birleştirme kurallarını ve ağlar arası yönlendirme için alternatifi verir.
cloudformation; Resources, Outputs, Parameters, Mappings, Conditions, Metadata ve Rules bölümlerini taşır ve Transform bölümünü her katkıda bulunanınkinden oluşturur. Dönüşümler CloudFormation’ın belgelediği sırayla birleştirilir; SAM’in Globals bölümü onu okuyan dönüşümle birlikte taşınır ve başka bir katkıda bulunanın içeriğinin dağıtılma biçimini değiştirecek bir dönüşüm, derlemeyi adıyla durdurur. Description taşınmaz ve derleme bunu bildirir: bölümü ve bileşeni adlandıran bir desteklenmeyen alan uyarısı verir; stack’in taşımadığı diğer her üst düzey anahtar için de aynısını yapar, böylece hiçbir şey sessizce atılmaz. Uyarı yalnızca bilgilendirme amaçlıdır: üretilen şablon, uyarı olmadan olacağıyla bayt bayt aynıdır ve --no-unsupported-field-warnings bu sınıfı susturur. Outputs, provider’ın katkıda bulunan bileşene göre kapsamlandırdığı bir ad altında taşınır; böylece aynı stack’e aynı adlı bir çıktı ekleyen iki bileşenin çıktıları birbirinden ayrı kalır. Birleştirilmiş stack’teki üst düzey bölümler her bölümü tek tek açıklar.
Diğer üç provider birleştirme yapmaz; bu nedenle hiçbir artifact anahtarı bir derleyici tarafından atılma riski taşımaz. helm hiçbir şey birleştirmez: her bileşenin manifestleri sınırın çıktı dizinine olduğu gibi ulaşır. terraform ve helm-chart iç içe yerleştirir: her bileşenin dosyaları kendine ait bir dizine, bir Terraform modül dizinine ya da bir alt chart’a yerleşir ve sınırdaki bir kök belge bunlara başvurur; bu nedenle bir artifact girdisi ortak bir belgeye okunmak yerine bütün bir dosya olarak yerleştirilir. Bir helm-chart artifact girdisinin nereye yerleştiği ve sınırlayıcı çiftinin neden farklı olduğu Provider başına artifact semantiği altında anlatılır.