WorkloadLibrary
Bir WorkloadLibrary, yeniden kullanılabilir Workload şablon parçalarını barındıran bir katalog varlığıdır. Aynı iş yükü biçimini (metrik sunan bir sunucu, bir toplu iş, bir sidecar çifti) dağıtan Recipes ve FeatureRecipes, bu biçimi bir kütüphanede bir kez tanımlar ve tüketim anında bir workload: { $import: ... } yönergesiyle ona başvurur. Kütüphane varlığı Tier 3’tür: Recipe’ler arası iş yükü yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Recipes’i her biri kendine özgü bir iş yükü biçimi taşıyan kataloglar, hiçbir WorkloadLibrary olmadan yayımlanır.
WorkloadLibrary’nin rolü
Platform mimarları, kataloğun Recipes ve FeatureRecipes genelinde tekrarlanan Workload içeriğini merkezîleştirmek için WorkloadLibraries yazar. Bir kütüphane, dağıtılabilir bir derleme talimatı değildir; bir tanımlar ad alanıdır. Recipe ve FeatureRecipe yazarları kütüphane girdilerine bir $import: yönergesiyle başvurur; bu yönerge bir kez yazılır ve içe aktarmanın çözümlendiği her yerde kullanılır.
“Kütüphane” ile “tüketici” arasındaki ayrım kasıtlıdır. Recipes derleme talimatlarını (source, valuesMapping, artifacts) kodlar. FeatureRecipes davranışsal eklentileri kodlar. WorkloadLibraries yalnızca Workload içeriğini kodlar — sağlayıcının sağlayıcıya özgü manifestlere dönüştürdüğü iş yükü biçimini. Üç rolü birbirinden ayrı tutmak, her varlık türünün kendi hızında gelişmesini sağlar; paylaşılan workload içeriğine ihtiyaç duymayan yazarlar kütüphane varlığıyla hiç karşılaşmaz.
Varlık zarfı
Bir WorkloadLibrary varlığı standart katalog zarfını taşır. apiVersion: aggrega.ai/v1beta1 ve kind: WorkloadLibrary varlık türünü belirtir; metadata.name bir PascalCase tanımlayıcıdır; metadata.version katı anlamsal sürümlemeye uyar. Her ikisi de zorunludur. metadata.description, metadata.labels ve metadata.annotations isteğe bağlıdır — etiketler ve ek açıklamalar, kütüphaneyi okuyan her şeyin bunlarla eşleştirme yapabilmesi için taşınan, yazarın bildirdiği opak meta verilerdir ve derleyici bunların değerlerini yorumlamaz. Kütüphanenin içeriği, en az bir girdi bildirmesi gereken zorunlu bir eşleme olan spec.workloads altında yer alır.
Zarf üç düzeyin tümünde kapalıdır — belge kökü, metadata ve spec, şemanın bildirmediği anahtarları reddeder.
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Workload girdilerini yazma
Her girdi, YAML dizesi olarak yazılmış bir Go şablon parçasıdır. Girdinin işlenmiş çıktısı eksiksiz bir Workload belgesidir — kendi apiVersion: aggrega.ai/v1beta1 ve kind: Workload değerlerini taşır — çünkü bir Recipe’in workload: alanı, çevreleyen bir belgeye eklenen bir parça değil, tek bir eksiksiz Workload alır ve içe aktarma alanın tamamını değiştirir. Bir MappingLibrary girdisi de aynı şekilde bütündür: birini içe aktarmak Recipe’in valuesMapping: alanının tamamını değiştirir.
Gövde, varlık zarfı için opaktır. Derleyici dizeyi WorkloadLibrary yüklenirken olduğu gibi saklar ve şablonu orada ayrıştırmaz; şablon ayrıştırıcısı tüketim anında, bir Recipe veya FeatureRecipe girdiyi içe aktardığında çalışır. Parçanın olduğu gibi saklanması, yeniden üretim için yazım sadakatini korur ve bir şablon hatasının kütüphanede değil, girdinin tüketildiği ve sütun bağlamının bilindiği yerde ortaya çıkması anlamına gelir.
Bir Workload belgesi çok satırlı olduğundan, girdiler satır sonlarının ve girintinin gidiş-dönüşte korunması için YAML’ın literal stil skalerini (|) kullanır:
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]Bir girdinin değeri bir dize skaleri olmalıdır. Gövdenin bulunması gereken yere bir eşleme veya dizi yazılması reddedilir — girdi gövdesi, derleyicinin dolaştığı yapılandırılmış YAML değil, şablon metnidir.
Go şablonunun tüm birleştirme sözcük dağarcığı bir girdi içinde kullanılabilir: {{ define "name" }}...{{ end }} tek bir kütüphane içinde yeniden kullanılabilir bloklar bildirir, {{ template "name" . }} bunları çağırır, ardışık düzenler ve işlevler ise standart Go text/template paketini izler. Bir girdinin okuyabileceği sütun bağlamı — .values, .infra, .locals, .context, .features — herhangi bir Workload şablonunun okuduğu bağlamla aynıdır ve Workload sayfasında şablon değerlendirmesi başlığı altında belgelenmiştir.
Hedef sağlayıcı, iş yükü sentezini desteklemelidir. Bir kütüphane girdisini içe aktaran ancak Workload sentezleyemeyen bir sağlayıcıya bağlanan bir Recipe, bozulmuş bir biçim üretmek yerine işleme anında açıkça durur; standart kütüphane kataloğu, belgelenmiş sözleşme olarak bunu destekleyen sağlayıcılarda workloadSchema bildirir.
Tek yazım modu
WorkloadLibrary tek bir yazım moduyla gelir: Go şablonları. spec, kütüphane düzeyinde paralel bir yazım yüzeyi ya da ifade gücü için bir kaçış yolu kabul etmez.
Bunun nedeni tüketim yüzeyinin tekdüzeliğidir. Recipes ve FeatureRecipes baştan sona Go şablonudur ve kendi içerikleri, içe aktarılan bir parçayı çözümleyen aynı Go şablon motoru üzerinden değerlendirilir. Paralel bir yazım yüzeyi, yazarları tek bir Recipe’in işlenmesi sırasında değerlendirme modelleri arasında geçiş yapmaya zorlardı: Recipe’in kendi içeriği için bir model, içe aktarılan her kütüphane girdisi için başka bir model. Yüzeyin tekdüze tutulması, yazarların tek bir değerlendirme modeli öğrenip onu her yerde uygulaması anlamına gelir.
Go şablonunun bileşim söz dağarcığının ötesinde ifade gücüne ihtiyaç duyan yazarlar, kütüphanenin içinde ikinci bir yazım diline geçmek yerine daha üst bir düzeyde bileşim yapar: kütüphane girdilerini kendi esaslı varyasyonlarıyla saran Components ya da Features.
Adlandırma uzlaşımları
Kütüphane adları ve iş yükü girdisi anahtarları PascalCase’i izler. Varlık zarfının JSON Schema’sı bu uzlaşımı iki konumda desen kısıtlamalarıyla zorunlu kılar:
metadata.name,^[A-Z][A-Za-z0-9]*$ile eşleşir.spec.workloadseşleme anahtarları,propertyNamesaracılığıyla aynı desenle eşleşir.
spec.workloads içinde PascalCase olmayan bir anahtar bulunan bir WorkloadLibrary, çalışma alanı yüklenirken zarf doğrulamasında başarısız olur. Bu zorunluluk işlevsel bir rol taşır: iş yükü girdisi anahtarları #/workloads/<name> başvuru parçasında yer aldığından, PascalCase olmayan bir anahtar girdiyi içe aktaran her tüketiciye yayılır.
Adlandırmadaki bu tekdüzelik #/workloads/<name> parçasını okunaklı tutar: #/workloads/BatchJob bir bakışta okunur.
Kütüphane girdilerine başvurma
Recipe ve FeatureRecipe yazarları, bir workload: { $import: ... } bloğu içinde bir workload girdisine yalın ad kimliğiyle başvurur:
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"#/workloads/<name> parçası girdiyi seçer ve bir workload başvurusunu MappingLibrary’nin #/mappings/<name> ve SchemaLibrary’nin #/schemas/<name> başvurularından ayırır. Başvuru hiçbir kayıt defteri ana bilgisayarı taşımaz; ana bilgisayar içeren bir oci://… biçimi hem zarf şeması tarafından hem de tüketim noktasında reddedilir, böylece fiziksel bir kayıt defteri konumu yazılan kaynağa hiçbir zaman girmez. Bir yazar isteğe bağlı bir en düşük sürüm tabanını <Library>:<version>#/workloads/<name> olarak belirtebilir; sürüm ayırıcısı, recipe/feature eşlemeleri ve lockfile sabitlemesiyle uyumlu olarak : karakteridir ve bunun yerine @ yazmak, düzeltilmiş başvuruyu belirten bir tanılamayla reddedilir. Çözümlenen sürüm, tüketilen her kütüphaneyi ad, sürüm ve içerik özetiyle sabitleyen Release başına lockfile tarafından sağlanır; fiziksel konum çözümleme zamanında bağlanır.
Aynı workload: alanı iki başka biçimi de kabul eder: satır içi bir Go şablonu dizesi ve Recipe dizinine göreli yerel bir dosya yolunun $import: ile içe aktarılması. Üç biçim içeriğin şekline göre ayırt edilir ve üçü de ayrıştırma sonrasında aynı Workload’u üretir. workload: alanının Recipe’nin diğer girdi türleriyle nasıl birleştiğini öğrenmek için Recipe sayfasına, daha geniş $ref: / $import: ayrımı için vocabulary/cross-document-ref sayfasına bakın.
Kütüphaneler arası birleştirme
Bir WorkloadLibrary girdisi bir alan kökü $import: yönlendirmesi olabilir: gövdesinin ilk belirteci $import: <Library>#/workloads/<entry> olur ve bu, girdinin tamamını başvurulan girdinin içeriğiyle değiştirir; bu, yerinde şablonlama değil, kimlik üzerinden yeniden kullanımdır. Yönlendirme, WorkloadLibrary yüklenirken değil tüketim anında ve özyinelemeli olarak çözümlenir; dolayısıyla içe aktarılan bir girdinin kendisi de bir alan kökü $import: olabilir. Kendi üzerine geri dönen bir zincir, döngüyü adlandıran bir tanılamayla durur. $import: yalnızca girdinin tamamı için geçerlidir; parça ortasında kullanılan bir şablon işlevi değildir. Şablon metnini tek bir girdinin içinde birleştirmek için Go template define / template kullanın.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerBilinmeyen bir kütüphane adı ile çözümlenen bir kütüphanede bulunmayan bir girdi adı ayrı tanılamalar olarak bildirilir; böylece yazar, eksik bir bağımlılığı yanlış yazılmış bir girdiden ayırt edebilir.
Katman yerleşimi
WorkloadLibrary, varlık katmanı dokümantasyon modelinde Katman 3’tür; Recipe’ler arası workload yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Recipes’i kendi farklı workload içeriğini taşıyan kataloglar hiçbir WorkloadLibrary varlığı olmadan yayımlanır; katman işareti, yetenek değil, dokümantasyonda gezinme için “ileri düzey; gerekmiyorsa atlayın” anlamını taşır. Derleyici WorkloadLibrary’yi diğer katalog varlık türleriyle aynı şekilde ele alır: çalışma alanı yüklenirken aynı zarf doğrulaması, release zamanında aynı OCI yayımlama hattı, ad, sürüm ve içerik özetine göre aynı kilit dosyası sabitlemesi.
Kütüphane türü, katalog düzeyindeki bir kümenin üyelerinden biridir: SchemaLibrary yeniden kullanılabilir şema tanımlarını, MappingLibrary yeniden kullanılabilir eşleme parçalarını, ArtifactLibrary yeniden kullanılabilir yapıt paketlerini, WorkloadLibrary ise yeniden kullanılabilir workload içeriğini tutar. Her biri bağımsız olarak isteğe bağlıdır; kataloglar ihtiyaç duyduklarını yayımlar, diğerlerinin hiçbirini yayımlamaz.
WorkloadLibrary ne değildir
Önceden giderilmesi gereken birkaç yaygın yanılgı:
-
Satır içi
workload:yerine geçmez. Çoğu Recipe, satır içinde yer alacak kadar kendine özgü Workload içeriği taşır; yazar bu içeriği orada Recipe’in geri kalanıyla birlikte okur. WorkloadLibrary, AYNI Workload biçimi birçok Recipe’te görüldüğünde işe yarar; tek seferlik içerik için doğru seçim satır içi yazımdır. -
Kısmi parçaların yeri değildir. Bir girdi, eksiksiz bir Workload belgesine işlenir. Bir Recipe’in değerler belgesi bir MappingLibrary’ye, bir yardımcı dosya kümesi bir ArtifactLibrary’ye, şema tanımları ise bir SchemaLibrary’ye aittir. Kütüphane türleri yeniden kullanım örüntüsüne göre değil, içerik türüne göre ayrılır.
-
Bağımsız olarak dağıtılabilen bir varlık değildir. Bir kütüphane girdisi Workload içeriğidir ve Workload içeriği hiçbir zaman tek başına adreslenemez; bir Recipe’in veya FeatureRecipe’in tükettiği girdi olarak var olur. Bir WorkloadLibrary’yi yayımlamak girdilerini içe aktarılabilir kılar; onları dağıtılabilir kılmaz.
-
Go template mekanizmalarının ötesinde parametrik yeniden kullanım sunmaz. Parametrik çeşitlemeye ihtiyaç duyan yazarlar, kütüphane girdilerinin içinde Go template’in
{{ define }}+{{ template }}mekanizmalarını ya da tüketen Recipe’in sağladığı sütun bağlamını kullanır. Kütüphane varlığının kendisi hiçbir parametrik yardımcı mekanizma içermez.