ArtifactLibrary
ArtifactLibrary, yeniden kullanılabilir artifact paketleri barındıran bir katalog varlığıdır: birbirine ait yardımcı çıktı dosyalarından oluşan adlandırılmış kümeler. Aynı destekleyici kaynakları üreten Recipes ve FeatureRecipes (RBAC’si ve bir ConfigMap ile birlikte bir CRD, bir HPA ile eşleştirilmiş bir NetworkPolicy) bu kümeyi bir kütüphanede bir kez bildirir ve tüketim anında değeri bir $import: yönergesi olan bir artifacts: girdisiyle ona başvurur. Kütüphane varlığı Tier 3’tür: Recipe’ler arası artifact yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Recipes’in her birinin kendi yardımcı dosyalarını taşıdığı kataloglar hiçbir ArtifactLibrary olmadan dağıtılır.
ArtifactLibrary’nin rolü
Platform mimarları, kataloğun Recipes ve FeatureRecipes genelinde tekrar eden yardımcı manifest dosyalarını merkezileştirmek için ArtifactLibraries yazar. Bir kütüphane dağıtılabilir bir derleme talimatı değildir; bir tanımlar ad alanıdır. Recipe ve FeatureRecipe yazarları bir paketi, bir kez yazılan ve içe aktarmanın çözümlendiği her yerde tüketilen bir $import: yönergesiyle referans verir.
Bu kütüphane türünü diğer üçünden ayıran şey bir girdinin ayrıntı düzeyidir. Bir SchemaLibrary girdisi tek bir şemadır, bir MappingLibrary girdisi tek bir şablon parçasıdır ve bir WorkloadLibrary girdisi tek bir Workload belgesidir; her biri tek bir noktada tüketilen tek bir gövdedir. Bir ArtifactLibrary girdisi ise bir dosya kümesidir, çünkü grupladığı kaynaklar yalnızca birlikte işe yarar: bir CRD’yi RBAC’si olmadan içe aktarmak çalışmayan bir manifest kümesi üretir. Bu nedenle yeniden kullanım birimi bir pakettir ve tek bir tüketim noktası birden çok çıktıya genişler.
Varlık zarfı
Bir ArtifactLibrary varlığı standart katalog zarfını taşır. apiVersion: aggrega.ai/v1beta1 ve kind: ArtifactLibrary varlık türünü belirtir; metadata.name PascalCase bir tanımlayıcıdır; metadata.version katı anlamsal sürümlemeyi izler. 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 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 paket bildirmesi gereken zorunlu bir eşleme olan spec.artifacts 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: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Artifact paketlerinin yazılması
spec.artifacts iki düzey derinliğindedir ve her düzeyin ayrı bir görevi vardır. Dış anahtar paket adıdır; bir tüketicinin başvurduğu tanımlayıcıdır. İç anahtarlar dosya adlarıdır ve her iç değer, o dosyaya üretilen Go şablonu gövdesidir. Bir paket en az bir dosya bildirmelidir.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"Bir dosya gövdesi, YAML dizesi olarak yazılmış bir Go şablonu parçasıdır. Bir manifest çok satırlı olduğundan, dosya gövdeleri YAML’ın literal biçimli skalerini (|) kullanır; böylece satır sonları ve girinti gidiş-dönüşte korunur. Bir paket girdisinin değeri, dosya adından dize gövdesine bir eşleme olmalıdır; paketin yerine yalın bir dize ya da bir dizi yazmak reddedilir, çünkü bir tüketicinin içe aktardığı düzey tek bir dosya değil, pakettir.
Gövde, varlık zarfı için opaktır. Derleyici her dizeyi ArtifactLibrary yüklenirken olduğu gibi saklar ve şablonu orada ayrıştırmaz; şablon ayrıştırıcısı tüketim zamanında, bir Recipe veya FeatureRecipe paketi içe aktardığında çalışır. Gövdeleri olduğu gibi saklamak, yeniden üretim için yazım sadakatini korur ve bir şablon hatasının kütüphanede değil, paketin tüketildiği ve pillar bağlamının bilindiği yerde ortaya çıkması anlamına gelir.
Bir paket içindeki dosya sırası, yazarın yazdığı sıradır ve yükleme ile tüketim boyunca korunur; böylece üretilen küme derlemeler arasında kararlı kalır.
Go şablonunun tüm birleştirme sözcük dağarcığı bir dosya gövdesi içinde kullanılabilir: {{ define "name" }}...{{ end }} yeniden kullanılabilir bloklar bildirir, {{ template "name" . }} onları çağırır; pipeline’lar ve fonksiyonlar standart Go text/template paketini izler. Bir dosya gövdesinin okuyabileceği pillar bağlamı (.values, .infra, .locals, .context, .features ve tüketen Recipe bunları bildirdiğinde .workload ile .source), tüketen Recipe’nin kendi artifacts: girdilerinin okuduğu bağlamdır ve Recipe sayfasında artifacts: alanı altında belgelenmiştir. Tüketen Recipe hiçbir workload: bildirmediğinde .workload okuyan ya da hiçbir source: bildirmediğinde .source okuyan bir gövde, karşılayamadığı başvuruyu adlandıran bir tanılamayla durur; her pillar ayrı ayrı denetlenir, dolayısıyla birini bildirmek diğerini okumaya izin vermez.
Tek yazım modu
ArtifactLibrary 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 paketi çö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 paket için başka bir model. Yüzeyin tekdüze tutulması, yazarların tek bir değerlendirme modeli öğrenip bunu her yerde uygulaması anlamına gelir.
Go şablonunun birleştirme sözcük 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 birleştirme yapar: kütüphane paketlerini kendi esaslı varyasyonlarıyla saran Components veya Features.
Adlandırma uzlaşımları
Kütüphane adları ve paket adları PascalCase biçimini 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.artifactseşlem anahtarları,propertyNamesaracılığıyla aynı desenle eşleşir.
PascalCase olmayan bir paket adına sahip bir ArtifactLibrary, çalışma alanı yüklenirken zarf doğrulamasında başarısız olur. Bu zorunluluk yük taşıyıcıdır: paket adları #/artifacts/<name> başvuru parçasında görünür; bu nedenle PascalCase olmayan bir ad, paketi içe aktaran her tüketiciye yayılır.
Adlandırmadaki tekdüzelik, #/artifacts/<name> parçasını okunaklı tutar: #/artifacts/OperatorSupport bir bakışta okunur.
Bir paketin içindeki dosya adları, her biri bir dosyayı adlandırdığı sürece serbest biçimlidir. Bunlar PascalCase değildir ve hiçbir şema deseni onları kısıtlamaz, çünkü bir derlemenin çıktısının sonunda taşıdığı dosyaları adlandırırlar — crd.yaml, deny-all.yaml, values-override.json hepsi geçerlidir. Bir dosya adının olması gereken şey, düz biçimde yazılmış sıradan bir göreli dosya adıdır; derleme, kendine ait hiçbir dosyayı adlandırmayan bir adı, Kütüphane girdilerine başvurma bölümünde açıklandığı gibi reddeder. İki düzey farklı biçimde kısıtlanır, çünkü farklı okuyuculara hizmet ederler: paket adı diğer varlıkların andığı bir tanımlayıcıdır, dosya adları ise bir tüketicinin, paketin içe aktarıldığı dizinin içinde gördüğü adlardır.
Kütüphane girdilerine başvurma
Recipe ve FeatureRecipe yazarları, değeri bir $import: eşlemi olan bir artifacts: girdisinin içinde bir pakete, paketin yalın ad kimliğiyle başvurur:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"#/artifacts/<name> parçası paketi seçer ve bir artifacts başvurusunu MappingLibrary’nin #/mappings/<name>, SchemaLibrary’nin #/schemas/<name> ve WorkloadLibrary’nin #/workloads/<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 asgari sürüm tabanını <Library>:<version>#/artifacts/<name> olarak belirtebilir — sürüm ayırıcısı, diğer kütüphane türleri ve kilit dosyası sabitlemesiyle uyumlu olarak : karakteridir; bunun yerine @ yazmak, düzeltilmiş başvuruyu adlandıran 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 kilit dosyası tarafından sağlanır; fiziksel konum çözümleme zamanında bağlanır.
Paket kendi dosya adlarına, tüketen anahtar ise bu dosyaların yerleştiği dizine sahiptir. Bir paketi içe aktaran tek bir artifacts: girdisi, o paketteki her dosya için bir çıktıya genişler ve her biri tüketim anahtarının altında <key>/<filename> olarak iç içe yerleşir. Tüketim noktasındaki anahtar — yukarıdaki operator-support — tek bir dosyayı değil, tüketimin tamamını adlandırır; örnek operator-support/crd.yaml ve operator-support/rbac.yaml dosyalarını üretir. Dolayısıyla paket adı başvuruda okunaklılık için, dosya adları çıktı dizininin okuyucusu için seçilir ve hiçbirinin diğeriyle uyuşması gerekmez. Tüketim anahtarının kendisi tek bir dosya adıyla sınırlıdır — başta bir harf veya rakam, ardından harfler, rakamlar, noktalar, kısa çizgiler ve alt çizgiler; bu alfabenin dışındaki bir anahtar zarf doğrulamasında başarısız olur — bu nedenle tam olarak bir dizin kesimini adlandırır ve bu kesimin altındaki her şey paketten gelir. Anahtar katı kalırken paketin dosya adlarının serbest biçimli kalabilmesini sağlayan da budur: bir dosya adı kendi paketi içinde, bir anahtar kendi belgesi içinde benzersizdir ve anahtar, girdinin ürettiği her yolun ilk kesimidir; bu yüzden hiçbir iki artifacts: girdisi aynı çıktıyı adlandırmaz. Serbest biçimli, bu kesim içinde serbest demektir: bir dosya adı kendine ait iç içe bir düzen taşıyabilir — crds/widget.yaml, <key>/crds/widget.yaml konumuna yerleşir — ancak anahtarın altında, düz biçimde yazılmış sıradan bir göreli dosya adı olmalıdır; böyle olmayan bir dosya adı, dosyayı tüketen Recipe’nin hiç adlandırmadığı bir yere koymak yerine derlemeyi durdurur. Bu, şunları reddeder: anahtarın üstüne tırmanan veya mutlak bir konumu adlandıran bir adı; anahtarın içindeki bir dosyayı değil, anahtarın kendi dizinini adlandıran . veya ./ ile x/.. gibi anahtarın üzerine geri çöken bir adı; ve sonda ya da çift / veya bir . ya da .. parçası içeren bir adı — x/, a//b, ./a, a/../b — bu, başka bir adın taşıyabileceği bir dosyanın ikinci bir yazılışıdır; dolayısıyla a/b yanında a//b iki dosyayı tek bir yola koyardı. Tanılama, paket dosyasını ve dosyanın içe aktarıldığı anahtarı adlandırır. Gerçekten aynı dosya adını taşıyan iki çıktı, düğüm işlendiğinde derlemeyi durdurur; bu da iki farklı girdi türü aynı dosya adına katkıda bulunduğunda olur. artifacts: girdisinin Recipe’nin diğer girdi türleriyle nasıl birleştiği ve kütüphane dışı iki yazım modu 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 bundle dosya gövdesi son içeriktir. Bir MappingLibrary veya WorkloadLibrary girdisinin aksine, bir bundle dosyası alan kökünde bir $import: yönlendirmesi olamaz: tek bir dosya yuvasında başka bir bundle’ın getireceği birden fazla dosyaya yer yoktur; bu nedenle derleyici bu biçimi, yazarın yazmadığı bir şeye çözümlemek yerine reddeder. İlk belirteci $import: olan bir gövde, bundle’ı ve dosyayı adlandıran bir tanılamayla durur.
Birleştirme bunun yerine, buna yer olan tüketim noktasında gerçekleşir. İki bundle’a ihtiyaç duyan bir Recipe iki artifacts: girdisi bildirir ve her biri bağımsız olarak genişler:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Bilinmeyen bir kütüphane adı ile çözümlenen bir kütüphanede bulunmayan bir bundle adı ayrı tanılamalar olarak raporlanır; böylece yazar eksik bir bağımlılığı yanlış yazılmış bir bundle adından ayırt edebilir.
Katman yerleşimi
ArtifactLibrary, varlık katmanı dokümantasyon modelinde Katman 3’tür; Recipe’ler arası artifact yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Recipes’i kendi yardımcı dosyalarını taşıyan kataloglar hiçbir ArtifactLibrary varlığı olmadan yayımlanır; katman işareti bir yeteneği değil, dokümantasyonda gezinme için “ileri düzey; gerekmiyorsa atlayın” anlamını belirtir. Derleyici ArtifactLibrary’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ı lockfile sabitlemesi.
Kütüphane türü, katalog düzeyinde bir kümeyi tamamlar: SchemaLibrary yeniden kullanılabilir şema tanımlarını, MappingLibrary yeniden kullanılabilir eşleme parçalarını, WorkloadLibrary yeniden kullanılabilir iş yükü içeriğini ve ArtifactLibrary yeniden kullanılabilir artifact paketlerini tutar. Her biri bağımsız olarak isteğe bağlıdır; kataloglar yalnızca ihtiyaç duyduklarını yayımlar, diğerlerinin hiçbirini yayımlamaz.
ArtifactLibrary ne değildir
Önceden giderilmesi gereken birkaç yaygın yanılgı:
-
Satır içi
artifacts:yerine geçmez. Çoğu Recipe, satır içinde yer alacak kadar kendine özgü yardımcı dosyalar taşır; yazar bu dosyaları Recipe’in geri kalanıyla birlikte okur. Bir ArtifactLibrary, AYNI dosya kümesi birçok Recipe’e eşlik ettiğinde işe yarar; tek seferlik içerik için doğru seçim satır içi yazımdır. -
Bir paketin içindeki dosyaları yeniden adlandırmanın bir yolu değildir. Dosya adları pakete aittir. Bir tüketici, dosyaların yerleşeceği dizini seçer (tüketim anahtarının işlevi budur), ancak bunlardan herhangi birinin adını seçemez: farklı bir dosya adına ihtiyaç duyan bir tüketici ya o adı bildiren bir paketi kullanır ya da dosyayı satır içinde yazar.
-
Workload, eşleme veya şema içeriğinin yeri değildir. Bir Workload belgesi bir WorkloadLibrary’ye, bir Recipe’in values belgesi bir MappingLibrary’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.
-
Kesişen kaynaklar için kullanılan mekanizma değildir. Hangi Recipe tarafından gerçekleştirildiklerinden bağımsız olarak birçok bileşene uygulanan yardımcı kaynaklar (örneğin her veri deposuna eklenen bir yedekleme sidecar’ı), Recipe’e göre değil Feature’a göre bağlanan FeatureRecipe kaynak üretimine aittir. Bkz. entities/featurerecipe.md. Bir ArtifactLibrary, birden çok Recipe’in her birinin kendi adına ürettiği dosyaları ortak bir yere çıkarır.
-
Bağımsız olarak dağıtılabilen bir varlık değildir. Bir paket artifact içeriğidir ve artifact içeriği hiçbir zaman tek başına adreslenemez; bir Recipe’in veya FeatureRecipe’in tükettiği girdi olarak var olur. Bir ArtifactLibrary’yi yayımlamak, paketlerini içe aktarılabilir kılar; onları dağıtılabilir kılmaz.