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

Manifest

Manifest varlığının kavramsal rolü (Alan 4 — soyut arayüzleri somut Recipes’e bağlayan eşleme tablosu) architecture/04-entity-taxonomy.md sayfasında anlatılır. Bu sayfa Manifest’in yazım yüzeyini ele alır: Release ile birlikte nasıl konumlandığı, düz URI eşleme yapısı, extends aracılığıyla bileşim, URI kısaltma kuralları, ek açıklama güdümlü Feature bağlamaları ve platforma ayrılmış aggrega.ai/ öneki.

Manifest ve Release: sorumlulukların ayrılması

Manifest ve Release birbiriyle örtüşmeyen sorumluluklar taşır:

  • Manifest, her katalog türünü hangi Recipe’in gerçekleştirdiğini ve o Recipe’in spec.capability alanı aracılığıyla onu render eden sağlayıcıyı (ör. Helm, Helm-chart, Compose) belirler. Eşleme tablosudur: her soyut arayüzü hangi somut Recipe’in uyguladığını kaydeden, proje başına Git’e işlenen bir kayıttır; bir derlemenin bu Recipes için şart koştuğu sürümler ve özetler ayrıca, her Release’in kilit dosyasında sabitlenir.
  • Release, hedefi (ör. GitOps yapıt üretimi için fiziksel çıktı klasörü) belirler. Dağıtım yönlendiricisidir: derlenen yapıtların nereye yerleşeceğini anlatan, ortam başına bir tanımdır.

Release şeması hiçbir iç içe geçme düzeyinde provider alanı taşımaz; sağlayıcıya yönlendirme yalnızca Manifest’e aittir.

Derleme yolu. Bir kullanıcı aggrega build --release release.yaml komutunu çalıştırdığında derleyici, fiziksel yapıtları iki kaynağı birleştirerek çözümler:

  1. Hedefi okuma. Derleyici Release’in sınırlarını tarar; örneğin ovh-cluster-3 sınırı, user-db bileşenini (tür: core/postgres:1.0.0) içerir.
  2. Manifest’i tarama. Release’in manifest: alanıyla gösterdiği Manifest’i açar.
  3. İki katmanlı arama. Önce name katmanında "user-db" girdisini denetler. Bulunamazsa type katmanında önce "core/postgres:1.0.0" (sürümlü), ardından "core/postgres" (sürümsüz) girdisini denetler.
  4. Recipe’i çözümleme. Eşleşen girdinin değeri bir Recipe URI’sidir; bu URI’nin adlandırdığı Recipe, kendisini hangi sağlayıcının işleyeceğini spec.capability içinde bildirir.
  5. Çıktı üretimi. Derleyici artık hedef klasörü (dist/boundaries/ovh-cluster-3/), sağlayıcıyı (Wasm üzerinden Helm işleme) ve yapıtı (Recipe’in kaynak kodu) bilir. Önceden derlenen (ahead-of-time) GitOps sınırlarına uçtan uca uyulur.

Düz URI eşlemesi

Manifest’in mappings: bloğu, bileşen türü URI’sinden Recipe URI’sine (ve özellik türü URI’sinden FeatureRecipe URI’sine) düz bir eşlemedir. Eşleme Manifest düzeyinde yetenekten bağımsızdır; yetenek belirlenmesi, Manifest’in yapısal biçiminden değil, çözümlenen her Recipe’in spec.capability alanından render zamanında gelir. Blok, eşlemeleri iki üst düzey anahtar altında düzenler:

  • components.type, bir bileşen türü URI’sini bir Recipe URI’sine eşler. Bildirilen türdeki her bileşen örneği belirtilen Recipe’e çözümlenir. Eşleme her bileşen türü için bire birdir. Bir örneğin tam türünü adlandırmayan bir anahtar, o tam türü adlandıran bir anahtar yoksa ve aynı taban için başka bir anahtar yazılmamışsa, türün tabanı üzerinden yine de o örneğe ulaşır — bu nedenle sürümsüz yazılmış bir anahtar (core/postgres) ya da başka bir sürümü adlandıran bir anahtar (core/postgres:1.0.0), bir core/postgres:2.0.0 örneğine ulaşabilir — ancak adlandırdığı Recipe, bu tür her örneğin kendi sürümünü uygulamalıdır: bu yolla ulaşılan ve implements: core/postgres:1.0.0 bildiren bir Recipe’e eşlenen bir core/postgres:2.0.0 örneği derlemeyi durdurur. Böyle bir örneği, sürümünü adlandıran bir anahtarla (core/postgres:2.0.0) onu uygulayan bir Recipe’e eşleyin.
  • features.type, bir özellik türü URI’sini bir FeatureRecipe URI’sine eşler. Bildirilen türdeki her Feature eklentisi belirtilen FeatureRecipe’e çözümlenir. Kimlik bilgisi Features’ları (feature.aggrega.ai/kind: secret etiketli), operasyonel Features ile aynı features.type eşlemesinde yer alır — birleşik Feature varlık modeli.

Her blok, type yanında belirli bir örnek adını bir Recipe (veya FeatureRecipe) URI’sine eşleyen bir name katmanı da kabul eder. Ad katmanı tür katmanına göre önceliklidir: components.name içinde adı geçen bir örnek o Recipe’e çözümlenirken, aynı türdeki diğer her örnek components.type üzerinden çözümlenir. Bu, örnek başına bir geçersiz kılmayı ifade eder — tek bir bileşen türünün iki örneği, bileşen türünü çatallamadan veya Manifest’i çoğaltmadan iki farklı Recipe üzerinden dağıtılabilir (örneğin veritabanı örneklerinin çoğu toplu eşlenen Recipe’i kullanırken bir örnek farklı bir fiziksel uygulamaya sabitlenir). Geçersiz kılma tek biçimde uygulanır: adı geçen örnek hem geçersiz kılan Recipe üzerinden işlenir hem de kaynağını ondan sabitler. features.name, Feature eklentileri için simetrik katmandır ve eklentinin kendi adıyla, yani bir bileşenin features: bloğunda altına yazıldığı anahtarla anahtarlanır; asla eklendiği bileşenin adıyla anahtarlanmaz. Örnek başına recipe geçersiz kılma örneği, iki örnekli minimal bir durumu baştan sona ele alır.

Bir bağlantının taşıdığı eklenti, tüketen bileşende aldığı adla anahtarlanır: <alias>.<slot>, yani bağlantının altında yazıldığı takma ad, bir nokta ve eklentinin doldurduğu yuva (bkz. Aggregate’in bağlantı girdisi). Böylece bir bağlantının kimlik bilgisi, kendi türündeki diğer tüm eklentilerden farklı biçimde gerçekleştirilebilir:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

Girdi, bir sonraki paragrafta açıklandığı gibi, diğer tüm ad katmanı girdileri gibi sabitlenir ve doğrulanır. Eklentinin adlandırdığı Feature da, tam olarak bileşenin kendisine yazılmış bir eklentinin Feature’ı gibi, yazarının yazdığı bağlantı girdisi altında sabitlenir ve doğrulanır — bkz. Kilit dosyası.

Bir name anahtarı, derlemenin içerdiği bir şeyi adlandırmalıdır. Katman tam adla eşleştirilir; bu nedenle derlemede bir bileşen örneği olmayan bir components.name anahtarı ya da derlemede bir eklenti olmayan bir features.name anahtarı — çoğunlukla eklentinin kendi adının yazılması gereken yere yazılmış, eklentinin üzerinde bulunduğu bileşenin adı — hiçbir şey tarafından kullanılmaz ve hedeflendiği örnekler sessizce type katmanı üzerinden çözümlenir. Bunun yerine derleme, herhangi bir şey render edilmeden önce böyle bir anahtarda durur ve Manifest’i, anahtarı, derlemenin içerdiği o türdeki adları ve muhtemelen kastettiğiniz adı belirtir — bkz. A Manifest name mapping names nothing in the build (Bir Manifest eşlemesi derlemedeki hiçbir şeyi adlandırmıyor).

Adla bağlanan bir gerçekleştirme, türle bağlanan gibi sabitlenir ve doğrulanır. aggrega pull, her iki katmanın bağladığı her Recipe ve FeatureRecipe’i — bir katalog dizininden, önbellekten veya bir kayıt defterinden — edinir ve her birini çözümlenmiş sürümü ve içerik özetiyle, onu bağlayan eşleme girdisi altında Release’in kilit dosyasına kaydeder: ad katmanı girdisi için manifest.spec.mappings.components.name.<instance>, tür katmanı girdisi için bunun yanındaki manifest.spec.mappings.components.type.<type>. aggrega build, bunların her birini kendi sabitlemesine bağlı tutar. Manifest’in bağladığı bir gerçekleştirme için satır kaydetmeyen bir kilit dosyası, gerçekleştirmeyi ve onu bağlayan girdiyi adlandırarak derlemeyi güncel değil diye durdurur; içeriği çekmeden bu yana değişen bir gerçekleştirme de her iki özeti adlandırarak derlemeyi aynı şekilde durdurur. Her iki durumda da aggrega pull --release <release>, gerçekleştirmeyi şu anki hâliyle kaydeder. Bir type girdisi gibi, bir name girdisi de Release o adda bir örnek bildirsin ya da bildirmesin sabitlenir; bu nedenle hiçbir katalog veya kayıt defterinin içermediği bir Recipe’i adlandıran bir name girdisi çekmeyi durdurur; derlemenin içerdiği hiçbir örneği adlandırmayan bir name girdisi de sabitlenir ve yukarıdaki paragrafta anlatıldığı gibi derlemeyi durdurur.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Render zamanında yetenek belirleme. Manifest girdisi bir bileşen türünü bir Recipe URI’sine bağlar. Bir Recipe URI’si en fazla iki segment taşır — isteğe bağlı baştaki bir yetenek, ardından recipe adı — ve isteğe bağlı bir :version; çözümleyici yalnızca ilk / üzerinden böler, bu nedenle üçüncü segmenti olan bir başvuru hiçbir recipe’i adlandırmaz ve çözümlemeyi durdurur. Render zamanında çözümleyici, Recipe’i kilit dosyası ve kataloğa karşı doğrudan URI aramasıyla yükler ve her Recipe’in spec.capability alanı (yol, yetenek) başına dağıtım gruplamasını belirler. Manifest’in yapısal biçimi, genel kataloğun kaç sağlayıcıyı desteklediğinden bağımsız olarak düz kalır.

Doğrudan URI araması

Manifest’in eşleme değeri bir Recipe URI’sidir. Derleyici URI’yi doğrudan kilit dosyası ve kataloğa karşı çözümler ve eşleşen Recipe’i döndürür. Derleyici, bir bileşen türünü “uygulayan” bir Recipe bulmak için spec.implements bildirimlerini dolaşmaz. Her Manifest girdisi, geliştiricinin yazdığı bileşen türünü belirli bir Recipe URI’sine bağlar; seçim Manifest içeriğinde açık ve belirsizlikten uzaktır.

spec.implements, eşleme tablosu üzerinde bir tutarlılık denetimidir. Çözümlenen Recipe’in spec.implements değeri, o eşleme girdisinin Manifest bileşen türü anahtarıyla — ya da zincirin herhangi bir derinliğinde o anahtarın extends ettiği bir tabanla — eşleşmek ZORUNDADIR; çünkü bir taban için yazılmış bir Recipe, ondan türeyen her şeyi uygular. Hiçbiriyle eşleşmeyen bir değer, Manifest girdisini, çözümlenen Recipe’i ve çakışan spec.implements değerini adlandıran açık bir tanılamayla bir OPS_ERROR üretir. Denetim, birleştirilmiş Manifest üzerinde ve herhangi bir Recipe çözümlenmeden önce, her Manifest eşleme girdisi için bir kez çalışır — statik, deterministik ve eşlenen türün kendi extends zinciri dışında hiçbir şeyi taramadan. Adlandırmadığı bir sürümdeki bir bileşen örneğine ulaşan bir components.type anahtarı, o örnek için aynı şekilde bir kez daha değerlendirilir; bu değerlendirmede anahtarın yerinde, örneğin derlemenin onu derlediği sürümdeki kendi türü durur; bkz. Düz URI eşlemesi. Bir tabanın Recipe’inin bir özelleştirmeyi neyden kurtarıp neyden kurtarmadığı için bkz. ../vocabulary/inheritance-and-interface.md.

Bir Release’in bağımlılıklarını okuyan her komut bu denetimi çalıştırır ve bir bulgunun ne anlama geldiğine her biri kendisi karar verir: aggrega build ve aggrega pull durur, çünkü ikisi de sizin kullanmaya devam edeceğiniz bir şey üretir; aggrega validate ve aggrega lint ise onu diğer bulgularıyla birlikte raporlar ve sıfır dışı bir kodla çıkar; düzenleyici de onu diğerleri arasında bir tanılama olarak yayımlar. Bir örneğe ilişkin değerlendirmede istisna aggrega lint’tir: eşleme girdilerini değerlendirir, onların ulaştığı örnekleri değil; bu yüzden bunu raporlamaz, oysa aggrega build, aggrega pull ve aggrega validate --release raporlar. Tanılama ve nasıl düzeltileceği için bkz. ../errors/fatal-halts.md.

Tutarlılık denetimi, extends zincirini okuyan tek eşleme yüzeyidir. Recipe seçimi eşleme anahtarında tam eşleşmeli kalır: eşlenmiş bir tabandan türeyen bir bileşen türünün burada yine kendi girdisine ihtiyacı vardır ve kalıtım yoluyla girdi almaz.

spec.implements aday da önerir. Türü için Manifest eşlemesi bulunmayan bir örnek, derlemeyi bir OPS_ERROR ile durdurur; bu hata, spec.implements değeri o türü gerçekleyebilen recipe’leri sabitleme adayları olarak listeler; bir eşleme değeri üzerindeki düzenleyici tamamlaması da aynı eşleşen recipe’leri ilk sıraya koyar. Her iki yüzey de spec.implements değerini istenen türün kendisine göre okur; bu nedenle o türün temel türlerinden birini gerçekleyen bir recipe, eşleme tutarlı kabul edilecek olsa bile aday olarak sunulmaz. Böylece spec.implements bir recipe’nin neyi gerçekleyebileceğini bildirir ve insanın seçimine bilgi sağlar — tutarlılık denetiminde, eşlemesizlik tanılamasında ve tamamlamada — ancak bir derlemeyi asla çözümlemez. Manifest eşlemesi, kullanıcının yeniden üretilebilirlik için kilit dosyasında sabitlenen açık dağıtım seçimidir; katalog hiçbir zaman kullanıcı adına bir dağıtım seçmez.

URI sürüm bölümü için üç biçim

Manifest içindeki bir Recipe URI’si sürümü üç biçimden herhangi biriyle taşıyabilir:

  • Tam — helm/postgres:1.2.0. Lockfile tam olarak bu sürümü sabitlemelidir; lockfile ilk kez çözümlenirken çözümleyici bu sürümü sabitler; çözümleme anında katalog veya kayıt defteri bu sürümü içermiyorsa çalışma alanının yüklenmesi bir hatayla durur.
  • Aralık — helm/postgres:^1.2.0. Standart MVS kuralıyla semver aralığı; lockfile ilk kez çözümlenirken çözümleyici aralığı karşılayan mevcut en yüksek sürümü sabitler.
  • Sürümsüz — helm/postgres. :version soneki yoktur; lockfile ilk kez çözümlenirken çözümleyici mevcut en son sürümü sabitler.

Sonraki derlemeler, kullanıcının yazdığı biçimden bağımsız olarak lockfile’da sabitlenmiş sürümü kullanır. Daha yeni bir sürüme yeniden çözümleme, kullanıcının açık bir eylemini gerektirir — aggrega pull --upgrade --release <release> <uri> diğer tüm sabitlemeleri koruyarak tek bir bağımlılığı yeniden çözümler, aggrega pull --upgrade --release <release> ise hepsini yeniden çözümler — derlemeler için doğruluk kaynağı lockfile’dır; kullanıcının yazdığı biçim, kullanıcının yazım anında sürüm kısıtını ifade etme şeklidir.

Yetenekle nitelenmiş başvurular

Katalogdaki Recipe kimliği yetenek kapsamlıdır: iki recipe, farklı spec.capability değerleri bildirirken aynı metadata.name ve sürümü paylaşabilir. Kayıt defteri kimliği, recipe’nin türünden, taşıyabileceği sürüm sabitlemesi olmadan spec.capability değerinden ve adından türetilen recipe/{capability}/{name}:{version} biçimindedir; standart kütüphane kataloğu ağacı uzlaşım gereği bu koordinatı recipe/{capability}/{name}/ konumunda yansıtır. Bir Manifest eşleme değeri recipe’yi iki kesinlik düzeyinden biriyle adlandırır:

  • Yalın — mariadb:1.0.0. Katalogda bu adı taşıyan tam olarak bir recipe varsa çözümlenir; pratikte baskın biçimdir.
  • Yetenekle nitelenmiş — compose/mariadb:1.0.0. İlk / öncesindeki bölüm recipe’nin spec.capability değerini, sürüm sabitlemesi olmadan adlandırır — başvuruya yazılan bir sabitleme reddedilir (E0095). Birden fazla recipe aynı adla geldiğinde gereklidir: iki recipe ile eşleşen yalın bir başvuru belirsizdir ve sessizce birini seçmek yerine çözümleme sırasında açıkça durur.

Bir Recipe URI’sinin başka konumu yoktur. Çözümleyici yalnızca ilk / üzerinden böler; bu nedenle compose/mariadb, compose yeteneğini ve mariadb recipe’sini adlandırır, üç bölümlü bir başvuru ise hiçbir kesinlik düzeyinde hiçbir recipe ile eşleşmez.

Yukarıdaki sürüm bölümü biçimleri her iki şekil için de geçerlidir.

Eşlemelerde kayıt defterinde yayımlanmış varlıklar

Yerel bir katalog yerine bir kayıt defterinden kullanılan bir varlığa, yerel bir varlığın kullandığı kimliğin tam aynısıyla başvurulur: başvuru ne kayıt defteri ana makinesi ne de varlık türü bölümü taşır. Çözümleyici ikisini de aşağıdaki Context-Aware Shorthand URIs (Bağlama duyarlı kısaltma URI’leri) kurallarına göre sağlar — ana makineyi çalışma alanının yapılandırılmış varsayılan kayıt defterinden, tür bölümünü başvurunun şemada bulunduğu yerden. Ne yerel bir katalog dizini ne de önbellek bir kopya tutmadığında, aggrega pull — ya da --auto-pull ile çalıştırılan bir derleme — varlığı türetilen konumdan getirir, önbelleğe alır ve çözümlenen sürümü ve içerik özetini lockfile’da sabitler; sonraki derlemeler önbelleği ağ erişimi olmadan kullanır.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Ana makine ve varlık türü bölümü yazılmak yerine türetildiği için, bunlardan birini başvuruya yazmak yayımlanmış varlığı adreslemez — hiçbir katalog girdisinin taşımadığı bir kimlik üretir. Bir Component veya Feature başvurusu, varlık yerel katalogdan, önbellekten veya bir kayıt defterinden çözümlensin, birebir metadata.name değeri artı isteğe bağlı bir :version değeridir. Özel bir kayıt defterini kullanan bir çalışma alanı, o ana makineyi her başvuruda değil kendi yapılandırmasında adlandırır.

Tamlık denetimi

Tüm eşlemeler çözümlendikten sonra derleyici, geliştiricinin Aggregate’indeki her bileşen ve ek örneğinin (bir kimlik bilgisi Feature’ı da diğerleri gibi bir ektir) çözümlenmiş bir Recipe’ye veya FeatureRecipe’ye sahip olduğunu doğrular. Eşlenmemiş varlıklar, eksik her varlığı listeleyen ve boşluğu kapatmak için hangi components.type veya features.type anahtarının ekleneceğini öneren açık bir tanılamayla ölümcül bir durmaya yol açar.

DRY manifest’ler için YAML çapaları

Büyük eşleme kümelerinde YAML şişkinliğini önlemek için Manifest, standart YAML çapaları (& ve *) için isteğe bağlı bir defs: bloğunu destekler:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature müzakeresi

Yetenek el sıkışması aynı düz URI eşlemesini kullanır:

  1. Geliştirici core/data-masking öğesini Aggregate’teki bir bileşene, o bileşenin features: haritasında kendine ait bir ad altında ekler.
  2. Derleyici core/data-masking öğesini Manifest’in features.type haritasında arar.
  3. Arama bir FeatureRecipe URI’sine (ör. helm/data-masking-litellm:1.0.0) çözümlenirse yetenek mevcuttur ve FeatureRecipe’nin işlem hattı tanımlı sırayla yürütülür.
  4. features.type eşleşen bir girdi içermiyorsa derleyici derlemeyi durdurur ve eşlenmemiş Feature’ı listeler.

Manifest ayrıca bir features.annotations bloğunu da kabul eder — bir Release’in veya Aggregate alt sisteminin Features’ı bileşen başına bildirim yerine açıklama anahtarıyla eklemesini sağlayan paralel bir yazım yüzeyi. Bağlama şekli, hangi yazım yüzeyinin hangi yönlendirme yollarını kullandığını belirleyen yan-sütun ayrımı, açık ekin kazandığı disiplin ve şema varsayılanları kuralı aşağıdaki ayrı Annotation-Driven Feature Bindings (Açıklama güdümlü Feature bağlamaları) bölümünde yer alır.

extends ile birleştirme

Bir Manifest, mappings değerlerini devraldığı temel bir Manifest’i adlandıran tek bir extends: referansı bildirebilir. Referans bir URI değildir ve hiçbir zaman katalog üzerinden çözümlenmez: Manifest dağıtım tarafına aittir, yayımlanmak yerine Release’in yanında yazılır; bu nedenle değer ya bir Manifest dosyasına giden göreli bir yoldur — ./base-manifest.yaml — ya da Release’in kendi dizininde bulunan bir Manifest’in yalın metadata.name değeridir. Göreli bir yol, çalışma alanının içindeki bir Manifest’e çıkmalıdır; Release çalışma alanının dışında adlandırılmışsa (komut satırında ya da çalışma alanı yapılandırmasında) o Release’i barındıran dizinin içindeki bir Manifest’e, çalışma alanının dışında komut satırında tek başına adlandırdığınız bir Manifest için ise o Manifest’i barındıran dizinin içine çıkmalıdır: dışarı tırmanan ya da sembolik bir bağlantının dışarı taşıdığı bir yol, adlandırdığı dosya okunmadan önce reddedilir (bkz. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Başka bir dosyaya yapılan referans, içinde kalması gereken dizinin dışına çıkıyor)”). Anahtar çakışmasında alt eşlemeler temeldekilerin üzerine yazılır; bu da ortam katmanı kalıplarını (ortama özgü cerrahi farklarla staging/prod eşliği) ve yerel geliştirme kalıplarını tam kopya yazmadan destekler.

Birleştirme anlambilimi. Yerel bir Manifest temel bir Manifest’i genişlettiğinde derleyici her katman için sığ anahtar değiştirme yapar — type ve name sözlükleri derin birleştirilmez, birbirinden bağımsız olarak birleştirilir — bu da O(1) sözlük aramalarını garanti eder ve devralma davranışını öngörülebilir tutar. Her katmanın içinde alt anahtarlar üst anahtarların üzerine yazılır.

Yerel geliştirme köprüsü kalıbı. extends için yaygın bir kullanım, Aggregate’e dokunmadan yerel prototipleme için bir kimlik bilgisi FeatureRecipe’ini değiştirmektir. Üretimde temel Manifest, kimlik bilgisi Feature’ı olan core/aws-secrets-manager değerini features.type katmanı altında bir üretim FeatureRecipe’ine eşler. Yerel prototipleme için platform ekibi, temeli genişleten ve kimlik bilgisi Feature eşlemesini cerrahi biçimde geçersiz kılarak host-env-injector kullanmasını sağlayan bir local-manifest sunar; bu, kimlik bilgisini Compose dosyasına ${SECRET_NAME} gibi bir değişken referansı olarak ileten yerel bir FeatureRecipe’tir ve Docker Compose bu referansı yığın başlatıldığında kabuk ortamından ya da bir .env dosyasından yerine koyar. Geliştirici standart bir yerel iş akışı elde eder ve Aggregate üretim için yetenekten bağımsız kalır.

Bağlama duyarlı kısaltılmış URI’ler

Aggrega derleyicisi, Manifests içindeki OCI URI’lerini çözümlerken Bağlama Duyarlı Çıkarım kullanır. Bir mühendis Tam Nitelikli Alan Adını (FQDN) ve mimari varlık türünü belirtmezse, derleyici otomatik olarak varsayılan kayıt defterine (.aggrega-config.yaml içinde yapılandırılır) geri döner ve varlık türünü dizenin şemada bulunduğu yere göre çıkarır.

Çıkarım kuralları:

  1. Alan adı varsayılanı: Alan adı içermeyen her URI’nin (ör. python-worker-helm:1.0) önüne yapılandırılmış default_registry (varsayılan: hub.aggrega.ai/) eklenir.
  2. Bağlamsal varlık genişletmesi: Derleyici, katı şema sözlüğüne göre doğru varlık yolunu ekler:
    • Aggregate.spec.components[].type altındaki dizeler /component/ olarak genişletilir.
    • Aggregate.spec.aggregates[].type altındaki dizeler /aggregate/ olarak genişletilir.
    • Manifest.spec.mappings.components.type veya Manifest.spec.mappings.components.name altındaki dizeler /recipe/ olarak genişletilir.
    • Manifest.spec.mappings.features.type veya Manifest.spec.mappings.features.name altındaki dizeler /featurerecipe/ olarak genişletilir. Buna kimlik bilgisi Features (feature.aggrega.ai/kind: secret etiketli) da dahildir; bunlar aynı FeatureRecipe yolunu kullanır.
    • pipeline[].plugin alanına atanan dizeler /plugin/ olarak genişletilir.
  3. Üç katmanlı öncelik: Derleyici, OCI çıkarımını uygulamadan önce Üç Katmanlı Varlık Çözümleme Modeli içinde tanımlandığı şekilde çalışma alanının katalog dizinlerini ve yapıt önbelleğini (çalışma alanı ve önbellek katmanı) arar. OCI çıkarımı yalnızca varlık kayıt defteri katmanına ulaştığında uygulanır. Bir eşleme anahtarı veya değeri hiçbir zaman dosya yolu olarak okunmaz: yerel olarak yazılmış bir Recipe veya FeatureRecipe bir katalog dizininde — çalışma alanı kökündeki catalog/ ya da workspace.catalog_dirs alanının listelediği bir dizin — bulunur ve başvurusuyla adlandırılır.

Kısaltmanın uygulamadaki hâli:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

ops/ öneki yoktur. Recipe adları ops/ öneki taşımaz; OCI taksonomisindeki recipe/ varlık türü dizini alanı zaten tanımlar ve Recipes ek bir önek olmadan recipe/{capability}/{name} altında yayımlanır. Manifests, Recipes’e {capability}/{name} ile ya da bağlama duyarlı çıkarım için yalın adla başvurur. OCI taksonomisinin tamamı için bkz. architecture/13-catalog-and-registry.md §6.

Annotation tabanlı Feature bağlamaları

Manifest’in features.annotations bloğu, annotation anahtarları ile Feature türleri arasındaki bağlamaları ve her bağlamanın annotation değerini gönderdiği yönlendirme yollarını bildirir. Bağlama, yinelenen bileşen başına Feature eklemelerini (bir sınır boyunca onlarca bileşenin her birinin aynı features: bloğunu taşıdığı örüntüyü) Release sınırlarında veya Aggregate alt sistemlerinde tek annotation bildirimlerine sıkıştırmak için kullanılan yazım yüzeyidir.

Şema yapısı:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Bir bağlama, hedef Feature türünü adlandıran bir feature alanı ve noktalı yol alt anahtar yönlendirmelerini hedef sütuna göre gruplayan bir maps bloğu taşır. feature alanı, kardeş features.type bölümünde de (FeatureRecipe sürüm bağlamasının bulunduğu yer) yer alması gereken bir Feature türüne başvurur. maps bloğu, sütun anahtarlı iki liste bildirir: maps.infra ve maps.values; her biri hedef Feature’ın spec.schema.<pillar>.<path> özelliklerini gösteren noktalı yol dizeleri taşır. Bir bağlama, iki liste genelinde en az bir yol bildirmelidir (JSON Schema, maps üzerinde minProperties: 1 koşulunu uygular).

Aynı annotation anahtarı için Provider çok biçimliliği (ör. feature.aggrega.ai/rewrite-host anahtarının bir Kubernetes dağıtımında core/k8s-dns-resolver öğesine, yerel bir Compose dağıtımında ise core/compose-bridge öğesine bağlanması), farklı Manifests içinde farklı Feature türleri seçilerek ifade edilir; her Manifest annotation’ı tek bir Feature’a bağlar ve seçilen Feature’ın FeatureRecipe’i sağlayıcıya özgü uygulamayı taşır.

Taraf-sütun ayrımı. Yazım Yüzeyi Olarak Aggregate değişmezi, her yazım tarafını tek bir sütunun yönlendirme yollarıyla sınırlar. Aggregate tarafı annotation’lar yalnızca maps.values yolları üzerinden yönlendirilir; Release tarafı annotation’lar yalnızca maps.infra yolları üzerinden yönlendirilir. Her iki sütunda yol bildiren bir bağlama, taraflar arası bileşimi destekler: Aggregate tarafı bir annotation values sütunu alt kümesini tetikler; aynı anahtara karşı Release tarafı bir annotation infra sütunu alt kümesini tetikler; her iki katkı, (Component, Feature) çifti başına her iki sütunu doldurulmuş tek bir Feature eklemesinde birleşir. Bir taraf-sütun uyuşmazlığı (ör. yalnızca maps.infra bildiren bir bağlamaya karşı Aggregate tarafı bir annotation), annotation anahtarını, yönlendirilen sütunu, yazım tarafını ve kaynak konumunu adlandıran açık bir tanılamayla derlemeyi durdurur; bu tanılama, annotation değerinin yazıldığı belgenin alanı altında kaydedilir.

Yol hedefi doğrulaması. Katalog yüklenirken derleyici, maps.infra ve maps.values altında bildirilen her noktalı yolun, hedef Feature’ın spec.schema.<pillar> bölümünün gerçekten bildirdiği bir özelliğe karşılık geldiğini doğrular. Feature şemasının listelemediği bir yola yönlendiren bağlama, bağlamayı, hedef Feature’ı ve üzerinden yönlendirdiği sütun ile yolu adlandıran açık bir OPS_ERROR ile katalog yüklemesini durdurur. Basit özellik taramasının dışına çıkan şema yapıları ($ref, patternProperties, oneOf / anyOf / allOf bileşimi) statik denetimi o dalda sonlandırır ve uyuşmazlıkların sonraki şema doğrulamasında yakalanmasını sağlar.

Annotation değeri biçimleri. Bir binding, annotation değerlerini üç biçimde tüketir. Skaler — tek bir YAML değeri (string, sayı, boolean). İki pillar genelinde tam olarak bir yol bildiren bir binding ile eşleşen skaler, değeri o tek yola yönlendirir; birden fazla yol bildiren bir binding ile eşleşen skaler belirsiz yönlendirmedir ve derlemeyi, annotation değerinin yazıldığı belgenin alanı altında kaydedilen açık bir tanılama ile durdurur. Yapılandırılmış — üst düzey alt anahtarlarının her biri maps.infra veya maps.values altındaki bir noktalı yol girdisiyle eşleşen bir YAML map’i; her alt anahtar bildirilen pillar’ına bağımsız olarak yönlenir ve taraf-pillar ayrımı alt anahtar başına uygulanır. Açık YAML null — cascade kapsamında devralınan binding’den çıkar (yapılandırılmış bir değer içindeki alt anahtar başına null, kardeşler yerinde kalırken tek tek alt anahtarlardan çıkar). Yapılandırılmış değerlere ilişkin temel yazım rehberi için — alt anahtar başına cascade birleştirme, taraflar arası birleşim, alt anahtar başına tür doğrulaması, bildirilmiş bir type olmayan şema alanları için gevşetilmiş varsayılan disiplini — bkz. providers/well-known-annotations.md §“Yapılandırılmış annotation değerleri”.

Anahtar çakışmasında açık ekleme kazanır. Bir Release bileşeni veya Aggregate bileşeni hem açık bir features: girdisi hem de aynı Feature anahtarına genişleyen bir annotation taşıdığında, açık girdi korunur ve o bileşendeki o anahtar için annotation genişletmesi etkisizdir. Sentetik ekleme, yazarın bildirdiği bir Feature örneğinin üzerine asla yazmaz. Bu nedenle yazarlar bileşenlerin çoğu için annotation genişletmesini kullanabilir ve aynı anahtarla açık bir features: girdisi yazarak tek tek bileşenleri hassas biçimde geçersiz kılabilir — açık girdi bileşene özgü özelleştirmeyi taşır, annotation ise diğer tüm bileşenlere değişmeden yayılır.

Taraflar arası bileşimde yaprak başına açık ekleme kazanır. Açık bir ekleme ve bir annotation katkısı aynı Feature örneğini doldurup farklı yapraklara yazdığında her iki katkı da korunur ve sonuçtaki Feature, her yaprağın kaynağını kaydeden yaprak başına köken bilgisiyle her iki yaprağı taşır. Açık bir ekleme ve bir annotation katkısı aynı sütun içinde aynı yaprağı hedeflediğinde açık katkı kazanır ve IR, bastırılan annotation köken bilgisini o yaprakta bir geçersiz kılma işaretçisi olarak kaydeder. Katalog yüklemesi bu geçersiz kılmayı derleme zamanında, bastırılan annotation anahtarını ve kaynağını adlandıran öneri niteliğinde bir lint uyarısıyla bildirir.

Genişletme zamanında şema varsayılanları. Annotation genişletmesiyle üretilen sentetik Feature eklemesi yalnızca annotation değerinin, bağlamanın bildirilen yolları üzerinden doldurduğu yaprakları taşır. Hedef Feature’ın spec.schema bölümünde bildirilen şema varsayılanları, genişletme zamanında sentetik eklemeyle birleştirilmez. Varsayılan değerlerin somutlaştırılması FeatureRecipe işleme katmanının sorumluluğudur; bu, açık ve sentetik eklemelere tek biçimde uygulanır, böylece iki yol aynı etkin yapılandırma için aynı sonraki çıktıyı üretir.

Annotation ad alanı ayrımı:

ÖnekSahipAmaç
aggrega.ai/Yalnızca Aggrega platformuSağlayıcının doğrudan okuduğu platforma özgü annotation’lar (ör. aggrega.ai/namespace).
feature.aggrega.ai/Resmî standart kitaplıkManifest’te bağlanan Feature annotation kısayolları.
{any-other-domain}/Kurum / toplulukÖzel Feature annotation kısayolları.

aggrega.ai/ önekinin ayrılması

Manifest features.annotations bağlamaları yalın aggrega.ai/ önekini kullanamaz; bu önek, derleyicinin ürettiği platforma özgü ek açıklamalar (OTel/köken etiketleri vb.) için ayrılmıştır. Kapsamlı alt önekler (component.aggrega.ai/*, compliance.aggrega.ai/*, kurumsal acme.aggrega.ai/*) kullanıcıların yazımına açık kalır. Platforma ayrılmış ek açıklama kümesi için providers/well-known-annotations sayfasına bakın.