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

Component

Component varlığının kavramsal rolü (Alan 2’deki soyut hesaplama düğümü arayüzü) architecture/04-entity-taxonomy.md sayfasında anlatılır. Bu sayfa Component yazım yüzeyini kapsar: Mimarların işlevsel temel ontolojinin üzerine bilişsel kimlik katmanı eklemek için kullandığı Anlamsal Etiket Taksonomisi, veri sütunları için schema: bildirimi, topoloji soketleri ve ekleme yuvaları için usesSchema ve featuresSchema bildirimsel tabloları, varlık zorunlulukları, extends: kalıtım mekanizması ve assertions: alanlar arası kural bloğu.

Anlamsal etiket taksonomisi (standart kütüphane uzlaşımı)

Temel türler tamamen bulut yerelyse, mimarinin operasyonel ve bilişsel zekâsı tümüyle anlamsal ördek tiplemesiyle katmanlanır.

Çekirdek Go derleyicisi bu etiketleri yorumlamaz. Derleyici, düz Ara Temsil (IR) grafiğini etiket anlamlarını yorumlamadan oluşturur. Bu etiketler Standart Kütüphane Uzlaşımını temsil eder: Alan 2’de Platform Mimarı tarafından yazılan değişmez “genetik işaretler”. Wasm politika doğrulayıcılarının ve fiziksel Ops Recipes’in mimariyi yönetmek için kullandığı açık anlamsal kancaları sağlarlar.

(A) Genel bulut katmanı Bu etiketler evrensel davranışları tanımlar; böylece politika motorları ve üretilen L7 proxy’leri, yapay zekâ çerçevelerini doğal olarak anlamaya gerek duymadan standart kurumsal mimarileri yönetebilir.

Etiket önekiİzin verilen değerler (uzlaşım)Platform Ops’un buna neden ihtiyaç duyduğu (politika kancası)
tool.aggrega.ai/impactread-only, mutatingPolitika motorlarının En Az Ayrıcalık yetkilendirmesini değerlendirmesini sağlar. Değişiklik yapan araçlar, katı onay kapısı sidecar’larının eklenmesini gerektiren politikaları otomatik olarak tetikleyebilir.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (değer kümesi, doldurulmuş kataloğa göre kararlı hâle gelmektedir)Politika motorlarının düğümler arası tür güvenliğini zorlamasını sağlar (ör. bir ajanın bir vektör veritabanına SQL yükleri göndermeye çalışmasını önlemek).
gateway.aggrega.ai/intelligencesemantic, l4-meshBir yönlendiricinin fiziksel olarak hangi özellikleri destekleyebileceğini belirler (ör. bir isteğin adını verdiği modele göre yönlendiren bir Feature’ın, örneğin bir yedek zincirinin, standart bir TCP mesh’ine eklenmesini önlemek).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledCanlı trafiği ikinci bir hedefe kopyalayan bir Feature’ın, kopyalama yapabilen bir proxy seçmesini ve eşleşen her isteği kopyalayan bir proxy’yi, kopyalanan istek payı ayarlanabilen bir proxy’den ayırt etmesini sağlar.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerAsıl çağıranın proxy arkasındaki hizmete tanıtılmasına ihtiyaç duyan bir Feature’ın, bu kimliği iletebilen bir bileşen seçmesini ve kimliği hangi mekanizmanın ilettiğini okumasını sağlar: istemcinin kendi TLS sertifikası ayrıntılarının iletilmesi ya da proxy’nin çağıranı doğruladıktan sonra kendisinin oluşturduğu bir başlık.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listHassas metni maskeleyen bir Feature’ın, yönlendirdiği sohbet ve tamamlama yükünde bu metni, metin daha ileri gitmeden önce bir yer tutucuyla değiştirebilen bir bileşen seçmesini sağlar. Değer, doğruluk düzeyini adlandırır: entity-recognition ile bileşen, yapılandırmasında verilen kalıpların eşleşmelerini ve ayrıca çağırdığı bir tanıyıcı hizmetin algıladığı varlık türlerini değiştirir; pattern-list ile yalnızca yapılandırmasında verilen kalıpların eşleşmelerini değiştirir ve hiçbir tanıyıcı hizmeti çağırmaz.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierModel istemlerini tarayan bir Feature’ın, yönlendirdiği sohbet ve tamamlama yükünü inceleyip bir isteği içeriğine göre reddedebilen bir bileşen seçmesini sağlar. Değer, doğruluk düzeyini adlandırır: pattern-list ile eşleştirme, rastgele bir HTTP gövdesine değil model yüküne karşı, yapılandırmasında verilen kalıplara göre yapılır; classifier ile karar, bileşenin çağırdığı bir algılama hizmeti aracılığıyla, yapılandırmasında verilen bir eşiğe göre ulaşılan eğitilmiş bir metin sınıflandırıcısının kararıdır.
dataplane.aggrega.ai/upstream-tlstrust-anchorProxy’nin kiminle konuştuğunu denetlemesini gerektiren bir Feature’ın, bir yukarı akış sunucusunun sertifikasını Release’in sağladığı bir güven çapasına karşı doğrulayabilen bir bileşen seçmesini sağlar.
dataplane.aggrega.ai/upstream-pinningpublic-keyBir yukarı akış sunucusunun hangi anahtarı sunabileceğini sabitleyen bir Feature’ın, sunduğu sertifika Release’in sağladığı açık anahtarlardan birini taşımadıkça yukarı akış sunucusunu reddedebilen bir bileşen seçmesini sağlar. upstream-tls’ten farklı bir iddiadır: sabitleme, bir sertifikanın hangi anahtar olması gerektiğini; çapa ise ne söylemesi gerektiğini belirtir.
dataplane.aggrega.ai/period-budgetcost, tokensTrafiğin bir dönem boyunca ne kadar tüketebileceğini sınırlayan bir Feature’ın, dönem boyunca saydığı miktar yapılandırmasında belirlenen bir sınırı aştığında model isteklerini reddedebilen bir bileşen seçmesini sağlar. Değer, neyin sayıldığını adlandırır: cost, trafiğin maliyeti, bileşenin model başına tuttuğu bir tablodan fiyatlandırılır; tokens, her modelin yanıtının okuduğunu, yazdığını ya da her ikisini bildirdiği token’lar; bileşen bunları sayar ve hiçbir şeyi fiyatlandırmaz.
dataplane.aggrega.ai/concurrency-captotal, per-targetBir bileşenin aynı anda taşıdığı istek sayısını sınırlayan bir Feature’ın, yapılandırmasında belirlenen bir sınırı aşan isteği bekletebilen ya da reddedebilen bir bileşen seçmesini sağlar. Değer, bir sınırın neyi saydığını adlandırır: total, bileşenin ilettiği her istek, tek bir sınıra karşı; per-target, gönderdiği her yukarı akış hedefine yönelik devam eden istekler, her biri için bir sınırla ve toplamlarına hiçbir sınır olmadan.

dataplane.aggrega.ai/ anahtarları bir bileşen türünü değil, trafik yolu üzerindeki bir konumu adlandırır; böylece bir proxy, bir giriş ağ geçidi ve bir hizmet ağı, her biri kendi sözlüğüne ihtiyaç duymak yerine kendilerini tek bir sözlükle tanımlar. Ailenin iki özelliği dikkatle okunmaya değer, çünkü ikisi de kolayca tersine çevrilebilir:

  • Değer, yalnızca yeteneğin varlığını değil, doğruluk düzeyini de taşır. İki bileşenin her ikisi de istekleri yansıtabilir ve yine de bir Feature’ı ilgilendiren bir biçimde farklı olabilir; bu nedenle ayrım değerde taşınır ve bir Feature ihtiyaç duyduğu doğruluk düzeyini seçer. Daha güçlü bir doğruluk düzeyi sunan bir bileşen daha güçlü değeri taşır, başkasını taşımaz.
  • Bir değer, ürünün ne yapabildiğini iddia eder; asla bir dağıtımın neyi etkinleştirdiğini değil. İkisi benzer okunur ve yalnızca ilki bileşenin bir özelliğidir. Bir yukarı akış sertifikasını doğrulayabilen bir proxy, herhangi bir dağıtım denetimi etkinleştirse de etkinleştirmese de upstream-tls: trust-anchor taşır, çünkü etiket, herhangi bir şey yapılandırılmadan önce bir Feature’ın seçim yaptığı şeydir.

Bu eksenlerden birinde tanımlayacak bir şeyi olmayan bir bileşen, orada en zayıf değeri değil hiçbir değeri taşımaz; taksonominin başka yerlerinde olduğu gibi: yokluk, eksenin o bileşende bir konusu olmadığı anlamına gelir; dolayısıyla bu eksende herhangi bir değer gerektiren bir Feature doğru şekilde eklenmez.

(B) Uzmanlaşmış yapay zekâ katmanı (bilişsel kimlik) Bu etiketler iş yükünün bilişsel kimliğini tanımlar ve mimarinin modern yapay zekâ çerçevelerini güvence altına almasını sağlar.

Etiket önekiİzin verilen değerler (uzlaşım)Platform Ops’un buna neden ihtiyaç duyduğu (politika kancası)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionusesSchema seçici dizeleri tarafından (statik analiz sırasında Go derleyicisi tarafından doğal olarak değerlendirilir), bir geliştiricinin üretken bir metin yükünü yanlışlıkla bir gömme uç noktasına yönlendirmemesini güvence altına almak için kullanılır.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeBir bileşenin yayımladığı adreste hangi model API’sinin yanıt verdiğini adlandırır: OpenAI API’si olduğunda (satıcının kendisi ya da bir sunucunun uygulaması) openai, Anthropic’in Messages API’si olduğunda (satıcının kendisi ya da bir sunucunun uygulaması) anthropic, Google’ın Gemini API’si olduğunda gemini ve ürünün kendi API’si olup bunların hiçbiri olmadığında native. Her model bileşeni bunu taşır, bir model API’si sunabilen bir ağ geçidi de taşır; böylece component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api seçen bir soket bir modeli ya da böyle bir ağ geçidini kabul eder ve hiçbirini sunamayan bir ağ geçidini reddeder; model.aggrega.ai/api=anthropic gibi tek bir değeri adlandıran bir soket ise yalnızca o API’yi sunanı kabul eder. Bir Release’in neyi bağladığını değil, ürünün neyi sunduğunu adlandırır: modelleri kendine ait bir sokete bağlanan bir ağ geçidi, hiçbir şey bağlı değilken de bunu taşır. Etiket, seçicinin eşleştirdiği bir dizedir; adreste gerçekte neyin yanıt verdiğini hiçbir şey denetlemez.
agent.aggrega.ai/autonomyautonomous, copilotBilişsel döngünün yürütme riskini belirler ve politikaların tamamen özerk ajanlar için insan onayı özelliklerini zorunlu kılmasını sağlar.

(C) Kesişen etiketler (yönetişim, durum ve donanım) Bunlar, Sıfır Güven doğrulamasını ve donanım yönlendirmesini yönlendiren temel kurumsal etiketleri temsil eder.

Etiket önekiİzin verilen değerler (uzlaşım)Platform Ops’un buna neden ihtiyaç duyduğu (politika kancası)
component.aggrega.ai/hostingself-hosted, managed, external, mixedBir bileşenin altta yatan kaynağını kimin işlettiğini kaydeder: güven sınırı ekseni. Politika motorları bunu Veri Sızdırma riskini hesaplamak için okur (ör. managed bir üçüncü taraf API’sine yönlendirilen iç veriler operatörün sınırını terk eder). Kesişen bir etikettir: aynı değerler yönetilen bir veritabanını, yönetilen bir model API’sini ve kendi işletilen bir çıkarım sunucusunu aynı şekilde tanımlar. mixed, Recipes’i birden fazla işletim biçimine yayılan bir bileşeni işaretler — Helm ve Compose Recipes’i tarafından kendi barındırılarak çalıştırılan, RDS Recipes’i tarafından ise yönetilen bir veri deposu gibi — bu nedenle bir Release’in işletim biçimi, Manifest’inin seçtiği Recipe’i izler.
compliance.aggrega.ai/data-classpublic, internal, restrictedBir bileşenin tuttuğu verinin sınıfı. Derleyici bunu derleme grafiğine bir dize olarak taşır ve hiçbir sıralama yapmaz; bir operatörün ir-verdict rolünde eklediği bir politika, sınıflara kendi ayarlarında sıralarını verir ve etiketi derleyicinin sıraladığı rotalar boyunca okur — örneğin, rotada sınıf düşürücü bir Feature eklenmemişken restricted bir bileşenin başka sınıftan bir bileşene ulaştığı bir derlemeyi durdurur (policy-data-class-route). Hiçbir standart kütüphane Component’i bunu taşımaz: sınıf, bir yapının bir bileşeni nasıl kullandığına dair bir ifadedir ve yapının kendi Component’i tarafından taşınır — örneğin extends aracılığıyla bir özelleştirme.
compliance.aggrega.ai/contains-piitrue, falseİş yüklerini GDPR/CCPA kapsamı için açıkça işaretler. Bir operatörün eklediği bir politika, bu etiketi okuyarak böyle bir iş yükünün trafiğinin izlediği rotalarda belirli Features gerektirebilir — örneğin, model trafiğini üzerinden gönderdiği bir yapay zekâ ağ geçidinde core/data-masking; bu, policy-data-class-route örneğinin bir veri sınıfı için denetlediği yapıdır. Hiçbir standart kütüphane Component’i bunu taşımaz; veri sınıfı gibi, bir yapının kendi bileşenleri hakkındaki ifadesidir.
hardware.aggrega.ai/acceleratorgpu, tpu, npuDevOps tarafından Release dosyasında kullanılır. Bu bileşenleri components: {} eşlemi aracılığıyla fiziksel donanım havuzu sınırlarına (ör. GPU destekli bir küme) açıkça yönlendirirler; bir yönetişim karar rolü ise GPU etiketli bileşenlerin hiçbir zaman GPU olmayan sınırlara yerleştirilmemesini zorunlu kılabilir.
state.aggrega.ai/retentionretain, deleteAOT silme boşluğunu çözer. Bir geliştirici Aggregate’inden bir veritabanını silerse, bir GitOps düzenleyicisi diski fiziksel olarak kaldırır. Bir Recipe’in pipeline: adımı retain etiketini okuyabilir ve işlenmiş yapıtlara düzenleyiciye özgü koruma (ör. helm.sh/resource-policy: keep) ekleyebilir.
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralSOC2 kullanılabilirlik kancası. Ops FeatureRecipe’ine kaynak için otomatik Snapshot/Volume Backup yapılandırmalarını fiziksel olarak üretip üretmeyeceğini bildirir.

(D) Dinamik iş bağlamı (kademeli ek açıklamalar) labels değiştirilemez katalog DNA’sını tanımlarken, dinamik iş bağlamları (SOC2 denetim kapsamı veya FinOps maliyet takibi gibi) uygulamayı kimin dağıttığına ve nerede çalıştığına bağlı olarak değişir. Bunlar, geliştiricinin subsystems’i, Ops Release sınırları veya annotation-transform rolünde eklenmiş bir yönetişim eklentisi tarafından dinamik olarak eklenen ek açıklamalar ile yönetilir.

Ek açıklama önekiİzin verilen değerler (uzlaşım)Platform Ops’un buna neden ihtiyaç duyduğu (politika kancası)
business.aggrega.ai/cost-centerör. finance, ai-researchBulut faturalandırma panoları için son üretilen yapıtlara fiziksel etiketleme (ör. AWS etiketleri veya K8s etiketleri) eklemek üzere Wasm işleme eklentileri tarafından gereklidir.
business.aggrega.ai/ownerör. team-alpha@corp.comOlay müdahalesi yönlendirmesi. Altyapının bir insan ekibine eşlenmesini güvence altına alır.
compliance.aggrega.ai/frameworksör. soc2, hipaaSOC2 kapsam tetikleyicisi. Ortam Release’i aracılığıyla eklenir. Wasm eklentileri bu dizeyi okuyarak, bir uygulama üretim uyumluluk sınırına girdiğinde katı denetim günlüğü yan araçlarını otomatik olarak üretir ve hata ayıklama bağlantı noktalarını devre dışı bırakır.

Taksonomi bir derleyici kuralı değil, bir katalog uzlaşımıdır. Kuruluşlar onu yok sayabilir, silebilir veya kendi etiket sözlüklerini (mycompany.com/custom-trait) oluşturabilir. Wasm eklentileri, kuruluşun yazdığı etiket anahtarları ne olursa olsun bunları değerlendirir.

Şema yazımı

Component şeması (ve feature.aggrega.ai/kind: secret etiketli kimlik bilgisi Features dahil Feature karşılığı), geliştiricinin yazdığı values için doğrulama sözleşmesini bir spec.schema: bloğu aracılığıyla bildirir. Blok, JSON Schema 2020-12’yi ya kompakt biçimli YAML kısaltmasıyla (varsayılan; yaklaşık 15 anahtar sözcük, derleme zamanında mekanik olarak JSON Schema’ya dönüştürülür) ya da tam JSON Schema YAML’ıyla (ayrıntılı biçim) ifade edilmiş olarak kabul eder; birden fazla Components arasında paylaşılan SchemaLibrary girdileri için $ref: aracılığıyla belgeler arası başvurular da desteklenir.

  • Satır içi kompakt biçim (varsayılan yazım yüzeyi): kompakt biçimli yaprakları doğrudan Component YAML’ı içinde taşıyan gömülü bir YAML bloğu. Katalog şema içeriğinin büyük çoğunluğunu, tam JSON Schema’nın satır sayısının küçük bir kısmıyla karşılar. Anahtar sözcük dağarcığı ve yazım uzlaşımları için vocabulary/compact-form-authoring.md sayfasına bakın.
  • Satır içi JSON Schema YAML’ı: ayrıntılı biçim; şema, kompakt biçimin doğrudan taşımadığı JSON Schema 2020-12 anahtar sözcüklerine ($dynamicRef, derin unevaluatedProperties, karmaşık not: bileşimi) ihtiyaç duyduğunda uygundur. Kompakt biçim ve JSON Schema, tek bir schema: bloğu içinde herhangi bir düğüm sınırında $jsonschema: kaçış yolu aracılığıyla karıştırılabilir.
  • Belgeler arası başvuru (bir SchemaLibrary girdisine $ref:): bir SchemaLibrary girdisini kimliğiyle (Datastores#/schemas/MariaDBValues veya benzeri) işaret eden, JSON Schema’ya özgü bir $ref:. Yüzlerce satıra yayılan ve birden fazla Components arasında yeniden kullanılan kurumsal şemalar SchemaLibrary varlıklarında yaşar; tüketici Component, içeriği satır içine almadan girdiye başvurur. Kütüphane varlığı ve çözümleme semantiği için entities/schemalibrary.md ve vocabulary/cross-document-ref.md sayfalarına bakın.

Yukarıdaki üç biçim sütun içeriği yazar ve hiçbir şeyi genişletmeyen bir Component tarafından kullanılabilir. extends: bildiren bir Component hiç sütun içeriği yazmaz: schema: inherited sabit işaretçisini yazar ve tabanının sütun bloğunu tam olarak tabanın yazdığı şekliyle alır. Bu işaretçi, böyle bir Component üzerinde schema: alanının alabileceği tek değerdir. Aşağıdaki “Katalog yazımı: Temel Components’ı genişletme” bölümüne bakın.

Derleyici schema: bloğunu çözümler — kompakt biçimi genişletir, $ref: URL’lerinin başvurularını çözer, SchemaLibrary kütüphaneden kütüphaneye zincirlerini uygular — ve ortaya çıkan JSON Schema’yı, Component’in doğrulama geçişi sırasında usesSchema ve featuresSchema alanlarından türetilen otomatik oluşturulmuş tabanlarla (aşağıdaki bölüme bakın) birleştirir. Doğrulama çözümlenmiş şemaya karşı çalışır; yazım yolu, sonraki işlem hattı aşamaları için opaktır.

Yazılmış örnekler, derleme zamanında bu çözümlenmiş şemaya karşı doğrulanır: bir bileşen örneğinin geliştirici tarafından yazılmış values alanı ve Operatörün çözümlediği infra alanı ile her Feature eklentisindeki values/infra, bildirilen sütunlara uymalıdır — yanlış türde bir değer, aralık dışı bir sayı, bildirilen format biçimine sahip olmayan bir dize, eksik bir zorunlu alan veya (kapalı olarak doğrulanan values için) bildirilmemiş bir özellik, dağıtım zamanında bozuk bir manifest üretmek yerine derlemeyi yazıldığı kaynakta durdurur. Şeması derleyicinin denetlemediği bir format adlandıran bir sütun — email, uri, hostname, ipv4, ipv6, uuid, date-time ve date dışındaki her şey, password dahil — katalog yüklenirken desteklenen adlar listelenerek reddedilir; her adın neyi denetlediği için vocabulary/compact-form-authoring.md sayfasına bakın. Bir tabanı extends: ile genişleten bir Component’in örneği, genişleten Component’in değiştirmeden devraldığı tabanın sütun bloğuna karşı doğrulanır — böylece tabanın bir örneği ile onu genişleten herhangi bir şeyin örneği aynı sütun sözleşmesiyle karşılaşır. Tanılamalar ve sütun başına kurallar (infra alanının Component ile provider anahtar birleşimine karşı nasıl doğrulandığı dahil) için errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema (Yazılmış values veya infra bildirilen şemaya uymuyor)” bölümüne bakın.

Bildirilen varsayılanlar işlenmiş sütunlarda somutlaşır. Doğrulamanın ötesinde, bir values alanında (veya bir infra alanında) bildirilen default:, yazarın atladığı her anahtar için derleme zamanında işlenmiş sütuna doldurulur — böylece {{ .values.charset }} okuyan bir Recipe şablonu boş bir değer yerine şemada bildirilen utf8mb4 değerini alır. Yazarın sağladığı değerler her zaman önceliklidir; iç içe nesneler atlanan her alt öğe için doldurulur. Somutlaştırma doğrulamayla aynı şema çözümlemesini kullandığından, bir SchemaLibrary’ye belgeler arası $ref: ile ulaşılan varsayılanlar da somutlaşır — hem bütün sütun başvurusu (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) hem de taban artı çeşit biçimi (her biri kendi varsayılanlarını taşıyan kardeş properties ile birlikte bir taban $ref:). Yalnızca yerel, belge içi bir #/$defs/ başvurusunda veya bir allOf / oneOf / anyOf dalı altında bildirilen varsayılanlar somutlaştırılmaz; standart kütüphane sütunları, somutlaştırılan belgeler arası $ref: ile oluşturur.

values sütunu

Component şeması üç sütunu sahipliğe göre ayırır: values, Aggregate içinde Developer tarafından doldurulur (bilişsel niyet — veritabanı adı, sürüm, karakter kümesi), infra, Release içinde Operator tarafından doldurulur (operasyonel boyutlandırma — işlem gücü, depolama, HA) ve provides, Recipe tarafından belirlenir (genel API sözleşmesi — host, port, protokol). Developer infra sütununu hiçbir zaman görmez; Operator da values sütununu hiçbir zaman görmez. Recipes, temel işleme sırasında her iki sütunu da tüketir ve soyut sütunları hedef sağlayıcılarının beklediği somut biçime eşler. Bu bölüm values sütununun yazım yüzeyini ele alır. Daha geniş sütun taksonomisi ve sütunlar arası kademelenme disiplini için vocabulary/data-pillars.md sayfasına bakın.

values, Developer’ın bilişsel niyetini taşır — uygulamanın nasıl boyutlandırıldığını veya çalıştığını değil, ne olduğunu ya da ne yaptığını tanımlayan seçimler. Veritabanı adı, karakter kümesi, motor sürümü, günlük düzeyi, özellik bayrakları ve uygulama sürümleri arasında değişen ancak ortamlar arasında sabit kalan uygulama katmanı ayarları tipik values içeriğidir. Operator values: alanını hiçbir zaman geçersiz kılmaz (architecture/06-data-taxonomy-and-composition.md §8 Kısıt 4 uyarınca Release şeması bir values: bloğunu mekanik olarak reddeder); ortama özgü farklılıklar Parametre Yükseltme (Parameter Hoisting) yoluyla akar — Aggregate tipli parameters.* alanlarını dışa açar, Component’in values şablonu bunlara başvurur ve Release parametreleri karşılar.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Recipe tarafında tüketim. Recipes, çözümlenmiş değerleri valuesMapping:, provides:, assertions: ve diğer şablon yüzeylerinde .values.<field> aracılığıyla okur — şablon başına kullanılabilirlik matrisi için entities/recipe.md sayfasına bakın. Derleyici, çözümlenmiş şablon bağlamının geçerli her alanı taşıması için Component’in values şemasını aynı Component düğümündeki tüm Feature eki values: şemalarıyla birleştirir.

Sütunlar arası disiplin. values, Developer’ın Aggregate’te yazdığı tek sütundur. Yalnızca geliştiriciye yönelik alanlar buraya aittir; operasyonel ayarlar (replika sayıları, CPU/bellek sınırları) Release’te yer almaları için Component’in infra sütununa aittir; genel çıktı (host, port) ise Recipe’in provides alanına aittir. Bunları karıştırmak sahiplik değişmezini bozar; bilinçli sütunlar arası aktarımın haklı olduğu nadir durumlar için vocabulary/data-pillars.md “Sütunlar arası mekanikler” bölümüne bakın.

infra sütunu

Component şeması üç sütunu sahipliğe göre ayırır: values Aggregate içinde Developer tarafından doldurulur (bilişsel niyet — veritabanı adı, sürüm, karakter kümesi), infra Release içinde Operator tarafından doldurulur (operasyonel boyutlandırma — hesaplama, depolama, HA; bir veri deposunun yedeklemesi burada boyutlandırılmaz, Operator’ün Release’te eklediği core/backup Feature’ıdır) ve provides Recipe tarafından belirlenir (genel API sözleşmesi — host, port, protokol). Developer infra alanını hiçbir zaman görmez; Operator da values alanını hiçbir zaman görmez. Recipes temel işleme sırasında her ikisini de tüketir ve soyut sütunları hedef provider’larının beklediği somut biçime eşler.

Standart kütüphanedeki yetenekten bağımsız her Component için üç infra uzlaşımı önemlidir: provider’a özgü ayarlar için açık yapılı bir kaçış yolu, upstream yapıt sürümü için isteğe bağlı bir geçersiz kılma ve yüksek erişilebilirlik alanları için niyete dayalı bir sözcük dağarcığı. Kanonik başvuru Component’i, standart kütüphane kataloğundaki core/datastore/mariadb’dir — resmi mariadb imajını çalıştıran ya da bir MariaDB özel kaynağını mariadb-operator denetleyicisine veren Helm Recipes, AWS RDS’ye karşı Terraform Recipes, aynı RDS yüzeyine karşı CloudFormation Recipes ve yerel bir konteynere karşı Compose Recipes ile gerçeklenebilir — ve infra bloğu birinci ve üçüncü kalıbı gösterir.

infra.overrides

Evrensel infra alanları — compute, storage, ha — provider’lar genelinde operasyonel boyutlandırmanın çoğunu karşılar. Geriye kalan kısım indirgenemez biçimde provider’a özgüdür: bir Kubernetes Recipe’i nodeSelector gerektirir, bir RDS Terraform Recipe’i instance_class gerektirir, bir CloudFormation RDS Recipe’i DBInstanceClass gerektirir, bir Compose Recipe’i ise image geçersiz kılması gerektirir. Component şeması, bu ayarların şemayı şişirmeden aktarılabilmesi için kaçış yolu olarak gerçekten açık bir eşlem sunar:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

additionalProperties: true ile birlikte açıkça belirtilen type: object, açık eşlem semantiğini etkinleştirir. Derleyici yapıyı dokunmadan aktarır; Recipe’in şablon gövdesi bildiği anahtarları okur ve geri kalanları yok sayar. Her Recipe, geçersiz kılma anahtarlarının ontolojisini başlık yorumunda belgeler; böylece belirli bir Component × Recipe birleşimi için Release yazan bir Operator, Recipe’in hangi ayarları sunduğunu bilir.

Geçersiz kılmaları kullanan bir Release parçası:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Developer overrides alanını hiçbir zaman görmez — bu alan, Operator’ün alanı olan Release içinde yer alır.

infra.source_version

Bir Recipe’in source alanı, belirli bir sürümdeki upstream yapıta başvurur (Helm chart 25.0.8, Terraform modülü 4.2.0, OCI imaj etiketi). Sürümü Recipe içine sabit kodlamak, katalog bakımcısını her uyumlu upstream sürüm artışında yeni bir Recipe yayımlamaya zorlar. Component şeması isteğe bağlı bir geçersiz kılma sunar:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Recipe bunu source bloğundaki optional yardımcısıyla okur; böylece sabitleme yoksa Recipe’in yazıldığı sürüme geri dönülür:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Recipe source dizeleri (ve yapılandırılmış bir source: eşleminin dize değerli alt alanları) Go şablonları olarak değerlendirilir. Uzak bir koordinat — yukarıdaki version gibi — aggrega pull yapıtı sabitlediğinde, .context kökü olmadan .values, .infra ve .locals’a karşı değerlendirilir; çalışma alanındaki bir yolu adlandıran bir kaynak ise varlık işlenirken, Recipe locals ile aynı kendi kendine yeterli bağlama karşı değerlendirilir — .context.instance_id, .values, .infra ve düğümün çözümlenmiş .locals bütünü. Her ikisinde de .context.inject, .context.uses ve .provides yasaktır. Yukarıdaki geçersiz kılmanın çalışmasını sağlayan, .infra’nın bu bağlamda bulunmasıdır; .locals ise bir Recipe’in bir kaynak parçasını bir kez hesaplayıp burada geri okumasını sağlar. Bir kaynak şablonu kendi düğümünün provides değerlerini hiçbir zaman okumaz: bu sütun bağlamın parçası değildir ve ona erişmeye çalışan bir şablon derlemeyi durdurur — bu, ileride yapılacak bir işi bekleyen bir eksiklik değil, yüzeyin sabit bir özelliğidir. Tam erişilebilirlik kuralları için Şablon Genişletme Matrisi, satır #5 bölümüne bakın. infra.source_version değerini Recipe’in varsayılanından farklı bir değere değiştirmek, Recipe’in valuesMapping eşlemesinin yeni upstream sürümüyle uyumlu olacağını garanti etmez; Component şemasındaki source_version bildiriminin description alanı bu uyarıyı taşır.

infra.ha.*

Yüksek erişilebilirlik alanları mekanizma sözcük dağarcığını değil, niyet sözcük dağarcığını kullanır:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled “bu Component’i yüksek erişilebilir yap” der, infra.ha.read_replicas ise “N adet salt okunur kopya istiyorum” der. Niyetin kendi provider’ında neye dönüşeceğine her Recipe karar verir. core/datastore/mariadb için standart kütüphane Recipes’i, bir Manifest’in onları eşlerken kullandığı adlarla:

Recipeha.enabled: true karşılığıha.read_replicas: N karşılığı
helm/mariadb (resmi mariadb imajı üzerinde bir StatefulSet)tek bir sunucu çalıştırır, bu nedenle derleme anahtarı adlandırarak dururtek bir sunucu çalıştırır, bu nedenle 0’dan büyük N derlemeyi durdurur
helm/mariadb-cluster (mariadb-operator denetleyicisinin uzlaştırdığı bir MariaDB özel kaynağı)otomatik yük devretmeyi açar (replication.primary.autoFailover: true); bir okuma kopyasına devrettiği için N’nin 0 olması derlemeyi durdururspec.replicas değerini N + 1 yapar ve çoğaltmayı açar; provides.host, <name>-primary Service’i olur
terraform/mariadb-rds (AWS RDS)birincil aws_db_instance üzerinde multi_az = true ayarlarN adet ayrı aws_db_instance okuma kopyası kaynağı oluşturur
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (bir modül üzerinden AWS RDS)modüle multi_az = true geçirirtek bir örnek sağlar, bu nedenle 0’dan büyük N derlemeyi durdurur
cloudformation/mariadb-rds (AWS RDS)AWS::RDS::DBInstance üzerinde MultiAZ: true ayarlartek bir örnek sağlar, bu nedenle 0’dan büyük N derlemeyi durdurur
compose/mariadb (yerel geliştirme konteyneri)tek bir sunucu çalıştırır, bu nedenle derleme anahtarı adlandırarak dururtek bir sunucu çalıştırır, bu nedenle 0’dan büyük N derlemeyi durdurur

Mekanizma sözcük dağarcığı (infra.primary.replicas) bir provider için doğal okunur (Kubernetes pod’ları bir StatefulSet’in kopyalarıdır), başka yerlerde ise bir kategori hatası olarak okunur — RDS’de birincil üzerinde “kopya” kavramı yoktur, CloudFormation RDS’yi yansıtır, Compose’da ise yatay kopya soyutlaması hiç yoktur. Niyet sözcük dağarcığı ise çevrilebilir: her provider’da bir biçimde “bu veritabanını yüksek erişilebilir yap” kavramı ve bir biçimde “N adet salt okunur kopya istiyorum” kavramı bulunur ve provider’a özgü çeviriyi Recipe taşır. Bir gerçeklemede böyle bir mekanizma yoksa, Recipe’i anahtarı adlandırarak derlemeyi durdurabilir; helm/mariadb ve compose/mariadb her iki anahtar için, tek örnekli RDS Recipes’i ise okuma kopyaları için bunu yapar.

infra.ha.read_replicas: 0 varsayılandır; iki anahtar da varsayılan değerlerindeyken helm/mariadb-cluster, tek bir örnek üzerinde çoğaltma yerine replication bloğu olmayan tek örnekli bir MariaDB işler. compose/mariadb yerel Docker ana makinesinde tek bir sunucu çalıştırır; bu nedenle infra.ha.enabled: true veya sıfırdan farklı bir infra.ha.read_replicas derlemeyi anahtarı adlandırarak durdurur ve ileti, yük devretme ve okuma kopyaları sağlayan helm/mariadb-cluster’ı gösterir.

provides sütunu

provides, Recipe tarafından yazılan genel API’dir: bir Component’in çözümlenmiş Recipe’inin, aşağı akıştaki çağıranlara onların .context.uses.<alias>.provides.<provided-name> yüzeyi üzerinden (ya da çağıran kenar üzerinde bir inject: izin listesi bildirdiğinde, onun .context.inject kanalı üzerinden) sağladığı değerler. Component şeması biçimi (anahtar adları ve türleri) bildirir; bağlanan Recipe’in provides: bloğu değerleri sağlar. Bir Aggregate yazan Developer, Component sayfasındaki provides biçimini çağıranların güvenebileceği sözleşme olarak görür; Recipe yazarı ise sözleşmeyi sarmaladığı belirli uygulama için yerine getirir.

Sözleşmenin yerine getirilmesi bir Loud Guardrail olarak zorunlu kılınır: bağlanan bir Recipe, Component’inin bildirdiği her provides anahtarını üretmelidir. Bağlanan Recipe bildirilmiş bir anahtarı atlarsa, derleme durur ve eksik anahtarı adıyla belirtir; ona başvuran çağıranlara sessizce hiçbir şey iletmez. Bildirilen kümenin ötesinde fazladan anahtar üretmeye izin verilir. Yalnızca anahtarın varlığı denetlenir: üretilen değerler, derleyicinin olduğu gibi aktardığı opak dizelerdir; bu nedenle bildirilen türleri, derleyicinin doğruladığı bir değer değil, çağıranların okuduğu bir sözleşme olarak kalır.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Önce provides, sonra inject değerlendirme ayrımı. Derleyici provides: şablonlarını provides değerlendirmesi aşamasında kendi içinde yeterli şablon bağlamına göre değerlendirir (.context.instance_id, düğümün provider’ı bir tane bildiriyorsa .context.rendered_name, .values, .infra ve aynı düğümdeki Recipe’in çözümlenmiş locals: değerleri); hiçbir çağıran durumu görünür değildir. Düğümün locals değerleri bu aşamanın ön bölümünde, provides değerlerinden önce çözümlenir; bir provides: şablonunun .locals okuyabilmesini sağlayan budur. Ardından çalışan inject hidrasyonu aşamasında derleyici uses: kenarlarını dolaşır ve her çağıranın .context.uses.<alias>.provides.<provided-name> ifadesini çözümlenmiş provides değerlerine göre çözümler. İkisinin ayrılması döngüsüz çözümlemeyi garanti eder: provides: bir çağırana başvuramaz ve bir çağıranın inject: bloğu, inject hidrasyonu çalışana kadar henüz çözümlenmemiş bir sağlayıcının çıktısına başvuramaz.

Sözleşmenin evrimi. Bir provides alanını yeniden adlandırmak veya kaldırmak, eski ada dayanan her çağıran için geriye dönük uyumsuz bir değişikliktir. Component’in metadata.version değeri (ve Recipe’nin implements: bildirimi) sözleşme evrimi sinyalini taşır; belirli bir ana sürüme sabitlenmiş alt akış çağıranları kararlı bir provides biçimi görür.

Recipe tarafındaki anlatım. provides: şablonu yazım dilbilgisi, şablon başına kullanılabilirlik matrisi ve ad alanları ile bölgeler arası yönlendirmenin işlenmiş örnekleri için entities/recipe.md “The provides: block” bölümüne ve architecture/06-data-taxonomy-and-composition.md §3 belgesine bakın.

Varlık zorunlulukları: features.aggrega.ai/requiredType.<label>

Bir Component, kendisinin her örneğinin belirli bir Feature türünde bir eklentiyi taşıması gerektiğini bildirebilir. Buna varlık zorunluluğu denir ve Component’in kendi metadata’sı üzerinde yinelenebilir bir annotation olarak yazılır:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

Anahtar, features.aggrega.ai/requiredType. önekinin ardından sizin seçtiğiniz bir etiketten oluşur; değer ise en az bir eklentinin taşıması gereken Feature türü URI’sidir. Etiket, karşılanmayan bir zorunluluğun ürettiği tanılamada gereksinimi adlandırır (yukarıda audit ve compliance) ve tek işlevi budur. Etiketli anahtarlar, bir Component’in aynı anda birden fazla zorunluluk bildirmesini sağlar: annotation’lar düz bir dize eşlemidir ve yinelenen bir anahtar taşıyamaz.

Derleyici her zorunluluğu, 5 Katmanlı Soğan Modeli kademelenmesi her kapsamı katladıktan sonra örneğin nihai ek kümesine karşı değerlendirir: Aggregate’in bileşen düzeyindeki ve alt sistem düzeyindeki features: blokları, Release’in sınır düzeyindeki ve bileşen düzeyindeki features: blokları ve ek açıklama güdümlü genişletmenin ürettiği ekler. Bunlardan herhangi biri zorunluluğu karşılar; kural neyin mevcut olduğunu sınar, oraya nasıl geldiğini asla sınamaz. Dolayısıyla zorunluluğu yalnızca bir operatör Release’te bir izleme ek açıklaması ayarladığı için karşılanan bir Component, geliştiricisi Feature’ı elle eklemiş olan bir Component ile tam olarak aynı şekilde geçer.

Hiçbir eklentinin karşılamadığı bir zorunluluk, bileşen örneğini, gereksinimin etiketini ve gerekli türü adlandıran bir tanılamayla derlemeyi durdurur. Bir annotation değeri opak bir dizedir, bu nedenle derleyici onu okumadan önce hiçbir şey biçimini doğrulamaz; dolayısıyla Feature türü URI’si olmayan bir değer ya da önekten sonra etiketi olmayan bir anahtar, bildirimin hatalı biçimlendirildiğini söyleyen ayrı bir tanılamayla durur. İkisi bilerek ayrı tutulur: bozuk bir bildirim katalog varlığında düzeltilir, karşılanmayan bir gereksinim ise Feature eklenerek giderilir ve bir yazım hatası asla karşılanmış bir gereksinim gibi okunmamalıdır.

Her iki tanılama da errors/fatal-halts.md içinde “Required feature not attached (Gerekli feature eklenmemiş)” başlığında belgelenmiştir.

Zorunluluk bir yuva değildir. İki yüzey farklı sorulara yanıt verir ve aradaki fark görünüşten ibaret değildir:

featuresSchema yuvasıvarlık zorunluluğu
Bildirdiğiadlandırılmış bir bağlama noktasıneyin mevcut olması gerektiğine dair bir kısıt
Ada başvurulabilir mievet — from: <slot> ve .features.<slot>.provides.*hayır — etiket yalnızca gereksinimi adlandırır
Kardinaliteyuva başına tam olarak bir dolgutürün en az bir eklentisi
Dolguyu kısıtlarselector, inject, sensitivetür dışında hiçbir şey
Serbest bir eklentiyle karşılanır mıhayır — bir yuva adla doldurulurevet — herhangi bir kapsamda, herhangi bir adla
Talep karşılanmadığındarequired: true olduğunda ve hiçbir şey yuvanın adını bağlamadığında dururhiçbir eklenti türü taşımadığında durur

Her iki talep de aynı girdiye, yani örneğin nihai eklenti kümesine göre denetlenir ve her ikisi de kendi tanılamasıyla durur, çünkü bu kümeye farklı sorular sorarlar: adlandırılmış tek bir bağlama noktasının bağlanıp bağlanmadığı ile herhangi bir eklentinin adlandırılmış bir türü taşıyıp taşımadığı. Hiçbiri diğerinin yerine yanıt vermez.

Recipe’in eklenen şeyi okuması gerektiğinde bir yuva kullanın. Component’in sözleşmesi bir yeteneğin mevcut olmasını talep ettiğinde ve bunu hangi örneğin sağladığı önemli olmadığında bir zorunluluk kullanın. core/audit-logging zorunluluğu koyan bir ödeme işleme Component’i, geliştirici eklemeyi hatırlasa da hatırlamasa da her dağıtımda denetim günlüğü alır; core/pci-compliance zorunluluğu koyan PCI uyumlu bir Component, uyumluluk Feature’ı dağıtımda bir yere eklenmeden yayımlanamaz.

Kalıtım. Temel bir Component üzerinde bildirilen bir zorunluluk, onu extends: ile genişleten her Component tarafından devralınır, çünkü metadata annotation’ları extends zinciri boyunca anahtar başına alt öğe kazanacak şekilde birleşir. Bu nedenle bir alt öğe, aynı etiketi farklı bir türle yeniden bildirerek devralınan bir zorunluluğu yeniden hedefleyebilir ya da yeni etiketler altında kendi zorunluluklarını ekleyebilir; temelin bildirdiği bir zorunluluğu ise kaldıramaz.

Topoloji soketleri: usesSchema

Bir Component, usesSchema: bloğu aracılığıyla topolojik soketler bildirebilir; bu, featuresSchema ile paralel, bildirimsel bir YAML eşlemesidir. Her girdi, Component’in bileşenler arası bağımlılıkları kabul ettiği bir soketi adlandırır ve geliştiricinin bu sokete hangi Component biçimlerini bağlayabileceğini belirler. Derleyici, bildirilen soketlerden JSON Schema 2020-12 doğrulama kurallarını otomatik olarak üretir ve Component çözümlemesi sırasında bunları Component’in schema: alanıyla birleştirir; geliştiriciler schema: içinde elle bir uses: sütunu yazmaz, çünkü yapı usesSchema alanından gelir.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Bağlama biçimleri — bir soket bir veya birden çok hedef kabul eder. Yukarıdaki örnekler her soketi tek bir hedefe bağlar, ancak bir soket birden çok hedefe yayılabilir. Bir soket değeri iki biçimden biriyle yazılır:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Bir takma ad her zaman bir girdi nesnesine eşlenir, hiçbir zaman çıplak bir hedef adına eşlenmez: databases: { primary: orders-db } yükleme sırasında reddedilir; target: alanını atlayan bir girdi nesnesi de reddedilir. Uydurulacak bir takma ad olmadan tek bir hedef bağlamak için kompakt biçimi kullanın — primary_datastore: [vector-db-instance] —; bu biçim hedefi bir kez adlandırır ve takma adı ondan türetir.

Her girdi — liste öğesi veya eşleme takma adı — yazılış sırasına göre korunan bir kenar olur. Soketin selector: alanı, onun üzerinden bağlanan her hedefe uygulanır (her kenarın türü statik analiz sırasında bağımsız olarak denetlenir) ve required: true, en az bir hedefin bağlanması gerektiği anlamına gelir.

Alan anlamları:

AlanTürVarsayılanAnlam
requiredboolfalsetrue olduğunda geliştirici bu sokete en az bir bağımlılık bağlamalıdır. false olduğunda soket isteğe bağlıdır.
selectorstring—Bu soket üzerinden bağlanan her kenarın hedefinin karşılaması gereken, Feature appliesTo alanının kullandığı dilbilgisindeki bir etiket seçicisi. Burada yazıldığı haliyle dize olarak okunur ve statik analiz sırasında hedefin etiketlerine karşı değerlendirilir: etiketleri onu karşılamayan bir hedef derlemeyi durdurur; dilbilgisinin reddettiği bir seçici de okuyamadığı gereksinimi adlandırarak derlemeyi durdurur. Boş bir seçici hedefe hiçbir kısıt koymaz.
injectstring[]—İzin verilen inject teslim mekanizmalarının izin listesi (featuresSchema[].inject ile paralel). Yokluğu veya [] (boş) olması kara kutu anlamına gelir — geliştiricinin uses: girdisinde inject: bloğuna izin verilmez; teslimi Recipe denetler. [env, file, arg] (boş olmayan) şeffaf anlamına gelir — geliştirici, bağımlılığın provides değerlerini hangi mekanizmanın teslim edeceğini belirleyebilir. Uygulanır: aşağıdaki “Bir soketin inject izin listesinin uygulandığı yer” bölümüne bakın.
valueSchemaobject—Bu soket üzerinden bağlanan bir kenarda geliştiricinin yazdığı values için isteğe bağlı kenar başına sözleşme (Aggregate içinde yazılır). schema: ile aynı yazım biçimlerinde JSON Schema 2020-12. Atlanması, soketin hiçbir values sözleşmesi bildirmediği anlamına gelir.
infraSchemaobject—Bu soket üzerinden bağlanan bir kenarda operatörün yazdığı infra için isteğe bağlı kenar başına sözleşme (Release içinde yazılır). valueSchema ile aynı yazım biçimleri. Atlanması, soketin hiçbir infra sözleşmesi bildirmediği anlamına gelir.
featuresSchemamap—Bu soket üzerinden bağlanan her bağlantının doldurabileceği ek yuvaları; yuva adına göre anahtarlanır ve her yuva, Component düzeyindeki bir yuvanın aldığı anahtarları alır. Atlanması, bu soket üzerinden kurulan bir bağlantının hiçbir ek taşımadığı anlamına gelir. Aşağıdaki “Her bağlantının doldurduğu yuvalar” bölümüne bakın.

Bir soketin inject izin listesinin uygulandığı yer. İzin listesi, soketin bir tüketicinin teslim biçimini seçip seçemeyeceğine ve seçebiliyorsa hangi biçimleri seçebileceğine dair beyanıdır; bu nedenle kenar ve soketin bildirimi elde olduğunda soket üzerinden bağlanan her uses: kenarına karşı denetlenir. Tek bir kuraldan iki ret doğar ve ikisi de derlemeyi durdurur:

  • İzin listesinin içermediği bir mekanizmayı dayatan bir kenar; soketi, sorunlu mekanizmayı ve soketin neye izin verdiğini adlandırarak derlemeyi durdurur. Kenardaki tüm sorunlu mekanizmalar birlikte bildirilir.
  • İzin listesi olmayan veya boş olan bir soket üzerinden herhangi bir teslimi dayatan bir kenar da derlemeyi durdurur. Bu, kara kutu bildiriminin işini yapmasıdır: “bunu Recipe dahili olarak teslim eder; teslimi dayatmayın” der ve boş bir izin listesi hepsine izin vermek yerine hiçbirine izin vermez.

Soket, onu hangi varlık bildirdiyse o varlık üzerinde okunur; bu her zaman kenarın bağlı olduğu bileşen değildir: bir Feature ekinin uses: alanında yazılan bir kenar, eklenen Feature’ın usesSchema alanına karşı çözümlenir; diğer her kenar — Aggregate içinde yazılan, Release’ten bağlanan veya bir alt aggregate üzerinden ulaşılan — tüketen Component’inkine karşı çözümlenir. extends aracılığıyla devralınan bir soket, tam olarak varlığın kendisinin yazdığı bir soket gibi okunur.

Hiçbir şey dayatmayan bir kenar, soket ne bildirirse bildirsin iki retten de etkilenmez: tüketen Recipe içinde bir bağımlılığın değerlerini .context.uses.<alias>.provides.<name> üzerinden okumak hiçbir inject: bloğu gerektirmez ve her zaman kullanılabilir. Her iki tanılama için errors/fatal-halts.md sayfasına bakın.

Kenar başına bağlantı sözleşmeleri — valueSchema ve infraSchema. Bir soket, bir sokete hangi Components’in bağlanabileceğini belirlemenin ötesinde, her bağlantının hangi yapılandırmayı taşıdığını da bildirebilir. İsteğe bağlı iki soket başına şema, soket üzerinden bağlanan her kenarda bağlantı kapsamlı yapılandırmayı doğrular:

  • valueSchema, bir uses kenarında geliştiricinin yazdığı values bloğunun sözleşmesidir — geliştiricinin Aggregate içinde ifade ettiği bağlantı başına ayar (örneğin bir bağlantı havuzu boyutu veya bir istemci modu).
  • infraSchema, bir uses kenarında operatörün yazdığı infra bloğunun sözleşmesidir — operatörün Release içinde ifade ettiği bağlantı başına operasyonel boyutlandırma.

Her ikisi de schema: alanıyla aynı içerik biçimlerinde JSON Schema 2020-12 kabul eder — satır içi kompakt biçim, satır içi JSON Schema YAML veya bir SchemaLibrary girdisine belgeler arası $ref:. Bunlar, her kenarın yapılandırmasına karşı bağımsız olarak doğrulanan kenar başına sözleşmelerdir; tüketen Component’in kendi values şemasına dahil edilmezler. Bir sütun için kenar başına şemayı atlayan bir soket orada hiçbir sözleşme bildirmez ve o sütun için yazılan her yapılandırma doğrulanmaz. Kenar başına yapılandırma kapalı olarak doğrulanır ve doğrulama her iki sütunda da varsayılanları dikkate alır: şemanın default: verdiği bir anahtar, yazar onu atlasa bile sağlanmış sayılır.

Bildirilen bir default: her iki sütunda da somutlaşır. Yazarın atladığı bir anahtar, tüketen Recipe’nin render bağlamına bildirilen varsayılanını taşıyarak ulaşır; tam olarak atlanan bir bileşen value veya infra anahtarının yaptığı gibi. Bu nedenle varsayılanı soket üzerinde bildirmek yeterlidir ve Recipe şablonu onun için bir yedek ifadeye ihtiyaç duymaz. Yazılan bir değer her zaman bildirilen varsayılana üstün gelir ve yalnızca sağladığı anahtarı doldurur: bir soket sözleşmesinin tek bir anahtarını yazan bir kenar, o sözleşmenin diğer anahtarları için bildirilen varsayılanları yine alır. Varsayılanlar kenarlara bağlanır; bu nedenle bağlanmamış bir soket hiçbir şey katmaz.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Bu soket bildirildiğinde, Aggregate’i pool_size alanını atlayan bir kenar 10 olarak, Release’i storage_class alanını atlayan bir kenar ise standard olarak render edilir. Yazım, kendi sütunu içinde anahtar başına üstün gelir: pool_size: 42 ayarlayan bir Aggregate, tls_mode yine require ile dolarken 42 render eder; storage_class: gp3 ayarlayan bir Release ise geliştirici anahtarlarının hiçbirini etkilemeden gp3 render eder.

Tüketen Component için bir Recipe, çözümlenmiş kenar başına yapılandırmayı zenginleştirilmiş topoloji hattından .context.uses.<alias>.values.<key> ve .context.uses.<alias>.infra.<key> üzerinden okur — bkz. vocabulary/topology-triad.md.

Her bağlantının doldurduğu yuvalar — bir soketin featuresSchema alanı. Bir soket ek yuvaları da bildirebilir; bu durumda onun üzerinden bağlanan her bağlantı, her birinde kendi ekini taşıyabilir: birkaç modele ulaşan bir ağ geçidi her biri için farklı bir kimlik bilgisi tutar, çünkü kimlik bilgisi ağ geçidinde değil bağlantıdadır.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Bir bağlantı, kendi features: alanında yuvanın adı altında bir ek taşıyarak o yuvayı doldurur; bu, Aggregate’in bağlantı girdisinde (Aggregate) ya da Release’in bağlantı girdisinde (Release) yapılır. Ek, tüketen bileşenin eklerinden biri olur ve <alias>.<slot> olarak adlandırılır.

Bildirimin tam olarak yaptıkları:

  • Yuva adları kapalı bir kümedir. Herhangi bir ad altında serbest bir eke izin veren Component’in kendi featuresSchema alanının aksine, bir soketin yuvaları, o soket üzerinden geçen bir bağlantının taşıyabileceği tek adlardır: başka herhangi bir ad, derleme yüklenirken durdurur ve hiçbir featuresSchema bildirmeyen bir soket, bağlantılarında hiçbir eke izin vermez. Ad-hoc bir soket, yani bu usesSchema alanının bildirmediği bir soket, hiçbir yuva bildirmez; dolayısıyla bağlantıları da hiç ek taşımaz. Her bağlantı kendi yuvalarını kendisi doldurur: daha geniş bir kapsamdaki ek hiçbir zaman bir bağlantıya aktarılmaz ve bir bağlantı ekinin birleşik adını yazan bir Release anahtarı derlemeyi durdurur.
  • Diğer anahtarlar her bağlantıyı yuvaya bağlı tutar. Buradaki bir yuva, Component düzeyindeki bir yuvayla aynı anahtarları alır: required, selector, inject, sensitive, description; ve her bağlantı bunlara ayrı ayrı tabi tutulur. selector, bir bağlantının yuvayı doldurduğu Feature’ın etiketleriyle eşleştirilir ve kabul etmediği bir doldurma, doldurmayı yazan belgedeki o bağlantının girdisinde konumlanarak derlemeyi durdurur. required: true, soket üzerinden bağlanan her bağlantı için geçerlidir: yuvayı boş bırakan bir bağlantı, o bağlantıyı adlandırarak durdurur; yanındaki, yuvayı dolduran bir bağlantı ise geçer. sensitive, Component düzeyindeki bir yuvadaki gibi okunur: yuvayı dolduran ek, derleme grafiğinde ve aggrega inspect çıktısında hassas olarak işaretlenir. Bir bağlantıda da, bir bileşende olduğu gibi, bir ekin hangi değerlerinin hassas olarak saklanacağına yalnızca eklenen Feature’ın kendi şeması karar verir. inject, yuvanın malzemesini ileten Workload girdisini bağlı tutar: bir bağlantının eki kendine ait bir inject: bloğu taşımaz (iki belge de bir bağlantı girdisinde buna izin vermez); bu nedenle bir Workload, yuvanın yanında bağlantıyı adlandırarak onu iletir ve bu girdi, Component düzeyindeki bir yuvayı adlandıran bir girdinin o yuvanın izin listesine tabi tutulduğu gibi soket yuvasının izin listesine tabi tutulur.

Bir Feature’ın usesSchema bloğu featuresSchema almaz: bir Feature’ın çizdiği bağlantı hiçbir ek taşımaz ve bir sokette slot bildiren Feature yüklenirken reddedilir. Böyle bir bağlantının ihtiyaç duyduğu kimlik bilgisi, Feature’ın kendi featuresSchema bloğundaki bir slottur.

usesSchema üzerinden şema üretimi. Derleyici, bildirilen soketlerden temel bir JSON Schema 2020-12 parçası üretir ve bunu kullanıcının schema: bildirimiyle birleştirir; bu, featuresSchema alanının kullandığı aynı kalıptır. Üretilen şema hiçbir zaman diske yazılmaz; yalnızca Component doğrulama geçişi sırasında bellekte bulunur. Geliştiricinin Aggregate içindeki uses: eşlemesi birleştirilmiş şemaya göre doğrulanır; soket başına selector: ise düğümler arası tür güvenliği denetimi olarak statik analiz sırasında aday Component etiketlerine göre değerlendirilir.

Seçici semantiği: Split Schema mekanizması. usesSchema[].selector:, Aggrega’nın topolojisini türsüz dize aktarımından öte bir şey yapan unsurdur. selector: "datastore.aggrega.ai/engine=vector" bildiren bir soket, yalnızca eşleşen anahtar-değer çiftiyle etiketlenmiş Components’e bağlantıyı kabul eder; primary_datastore soketini relational bir Component’e bağlamaya çalışan bir ajan, açık bir seçici ihlali tanılamasıyla Static Analyzer’da başarısız olur. Seçici, Kubernetes tarzı bir etiket seçici dizesidir: =, !=, in (...), notin (...), yalın anahtar ve !key biçimleri üzerinde virgülle VE’lenen gereksinimler; Feature appliesTo alanının kullandığı aynı dilbilgisidir. Dilbilgisi için vocabulary/modifier-system.md, motor semantiği için architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” sayfasına bakın. Bu biçimlerin dışındaki bir gereksinim başka bir seçici olarak okunmak yerine reddedilir: boş bir gereksinim (baştaki, sondaki ya da çift virgül), boşluk ya da =, !, (, ) ve virgülden herhangi birini içeren bir anahtar veya kapanış parantezi olmayan bir küme, soket üzerinden kenar bağlayan her derlemeyi gereksinimi adlandırarak durdurur. Dolayısıyla ön yüzleri dışlamak için tasarlanan bir soket selector: "tier!=frontend" olarak yazılır; "!tier=frontend" reddedilir, çünkü ! bir etiket anahtarını adlandırır ve başka hiçbir şeyi adlandırmaz.

Geçici soketler — bir soketi bildirmenin kazandırdıkları ve bir yazarın bildirmeden yapabilecekleri. Bir Aggregate yazarı, kendi bileşeni üzerinde bu usesSchema bloğunun bildirmediği bir soket adı altında bir uses: girdisi yazabilir; hiç usesSchema bildirmeyen bir Component üzerinde de. Kenar oluşturulur. Kataloğun bir soket hakkında sessiz kalması, bağlantının öngörülmediği anlamına gelir, yasak olduğu anlamına gelmez; uygulamanın topolojisinin sahibi geliştiricidir.

Böyle bir ad-hoc soketin vazgeçtiği şey, tam olarak bildirilmiş bir soketin sağladığı şeydir, çünkü bunların hepsi usesSchema girdisinde bulunur: selector yoktur, dolayısıyla kenarın hangi bileşene ulaşabileceğini hiçbir şey kısıtlamaz ve düğümler arası tür güvenliği denetiminin değerlendireceği bir şey yoktur; inject: izin listesi yoktur; kenar başına valueSchema yoktur, dolayısıyla kenar başına values: alanının denetleneceği bir sözleşme ve devralınacak bildirilmiş varsayılanlar yoktur. infraSchema alanından da vazgeçer, ancak böyle bir sokette her durumda hiçbir şey bu sözleşmeye ulaşmaz: kenar başına infra bir Release kenar girdisinde yazılır ve bir Release girdisi yalnızca tüketen Component’in bildirdiği bir soketi adlandırabilir. Değişmeyen şey, kenarın neleri taşıyabileceğidir: her inject girdisinin from: alanı yine hedef Component’in schema.provides alanında bildirdiği bir anahtarı adlandırmalı ve hedef yine var olmalıdır; ikisi de bildirilmiş bir sokette olduğu gibi derlemeyi durdurur.

“inject: izin listesi yok” ifadesini bir blackbox bildirimi olarak değil, bir kısıtlamanın yokluğu olarak okuyun; çünkü ikisi birbirine benzer görünür ama tam tersi davranır. Ad-hoc bir soket üzerinden geçen bir kenar, teslimatı serbestçe belirleyebilir: bir mekanizmanın dışında kalabileceği bir izin listesi yoktur ve hiçbir varlık değerleri dahili olarak ele alacağını taahhüt etmemiştir. Yukarıdaki blackbox reddi, varlığın gerçekten bildirdiği ve bir inject: izin listesi olmadan bıraktığı bir sokete uygulanır; bu eksiklik, varlığın öngördüğü bir bağlantı hakkında bir beyandır ve ad-hoc bir soket böyle bir beyanda bulunmaz.

İletim aynı yoldan yapılır ve işlenen yapıt hiçbir fark kaydetmez. Ad-hoc bir kenarın inject bloğu, bildirilmiş bir soketinki gibi çözümlenir ve iletilir: her from: anahtarı hedefin değerlendirilmiş provides alanından okunur ve tüketen düğümün enjeksiyon bağlamına yazarın seçtiği iletim anahtarı altında yerleşir, oradan da işlenen yapıta ulaşır. Tek bir iletim yolu vardır ve bu yol üzerindeki hiçbir şey soketin bildirilip bildirilmediğine göre dallanmaz. Bildirilmiş bir soketin ekleyebileceği şey içeriktir, yani valueSchema ya da infraSchema alanının doldurduğu kenar başına varsayılanlar; bu nedenle bildirilmiş bir soketin böyle bir sözleşme taşımadığı durumda aynı kenar her iki tür sokette de aynı şekilde işlenir. Bildirim, bağlantı hakkında bir olgudur; işlenen şeye bir girdi değildir.

Ad-hoc bir soketteki kenar başına values: kabul edilir ve tüketen Recipe’e .context.uses.<alias>.values konumunda doğrulanmadan ulaşır: ölçüleceği bir valueSchema olmadığından hiçbir anahtar denetlenmez ve hiçbiri reddedilmez. Bu, ad-hoc soketlere özgü değildir; pillar için hiçbir sözleşme yazmayan bildirilmiş bir soket de kenar başına yapılandırmasını aynı şekilde ele alır. Ad-hoc bir soketin değiştirdiği şey, sözleşmenin soket bildirilmeden eklenememesidir. Böyle bir kenarda .context.uses.<alias>.infra boştur, çünkü kenar başına infra sağlayan yüzey bildirilmemiş bir soketi adlandıramaz.

Yayımlanan graftaki her kenar bu ikisinden hangisi olduğunu kaydeder; böylece bir tüketici bunu hiçbir zaman çıkarsamak zorunda kalmaz ve her bağlantının bildirilmiş bir soketten geçmesini isteyen bir kuruluş bunu bir yönetişim politikası olarak zorunlu kılabilir. Soketi burada bildirmek daha iyi yol olmaya devam eder ve standart kütüphane kataloğunun yaptığı da budur: bildirilmiş bir soket, kenarın hangi bileşenlere ulaşabileceğini kısıtlayan bir selector, bir inject: izin listesi, kendi varsayılanlarına sahip kenar başına bir sözleşme ve bir açıklama taşır — öngörülmüş bir bağlantının, onu kuran varlıkla birlikte sürümlenen, gözden geçirilebilir bir ifadesi. Ad-hoc biçim yeni bir varsayılan değil, bir kaçış yoludur. İki yüzey bilinçli olarak bu şekilde açık değildir — bir Feature ekinin uses alanı yalnızca eklenen Feature’ın bildirdiği bir soketi adlandırabilir ve bir Release’in kenar başına uses alanı yalnızca tüketen Component’in bildirdiği bir soketi adlandırabilir.

Çalışılmış örnek examples/adhoc-uses-socket/, her iki kenar türünü tek bir tüketici üzerinde kurar ve teslim edilen iki değeri, bildirilmemiş bir from: anahtarının ürettiği durdurmayla birlikte, işlenmiş çıktıda yan yana gösterir.

Soket adı yazım hataları bir durdurma olarak değil, bir uyarı olarak ortaya çıkar. Bildirilmemiş bir soket adı geçerli olduğundan, yanlış yazılmış bir soket adı, yazarın kastettiği soketi bağlamak yerine kendi başına bir ad-hoc bağlantıya dönüşür ve üzerinden hiçbir şey akmazken derleme başarılı kalır. Derleyici, bu usesSchema’nın bildirdiği bir addan tek düzenleme uzaklıktaki bir soket adını, her iki yazımı da belirten bir uyarı olarak raporlar; bkz. errors/warnings.md “Uses-socket near-miss lint”. Uyarı, derlemenin sonucunu hiçbir zaman değiştirmez; derleyici, bir yazarın bir sokete ne ad verdiğini denetlemez.

usesSchema ile featuresSchema arasındaki ilişki. İkisi de bildirimsel tablodur ve ikisi de aynı anlambilimle bir inject: izin listesi taşır; ancak bir soket ile bir yuva farklı şeylerdir ve birbirinin yerine kullanılamaz. usesSchema, bileşenler arası kenarları (topoloji grafiğini) yönetir ve hangi soketlerin bir sözleşme taşıdığını bildirir. featuresSchema ise ek yuvalarını yönetir ve bir yuva bir numaralandırma değil, adlandırılmış bir bağlanma noktasıdır: hiçbir yuvanın bildirmediği bir ad altındaki ek, bileşenin kendi bloğunda geçerlidir. (Bir soketin bağlantıları için bildirdiği yuvalar, yukarıda “Her bağlantının doldurduğu yuvalar” bölümünde belirtildiği gibi, tek kapalı kümedir.) İki yüzey bu noktada birbirine yaklaşmıştır; bir bileşenin bildirilmemiş bir soket adı altındaki kendi uses: girdisi de geçerlidir. Ancak ikisi ayrı kalır: bildirilmemiş bir yuva, bildirilmiş yuvaları etkilenmeyen bir Component üzerinde serbest bir ektir; bildirilmemiş bir soket ise seçicisi ve kenar başına sözleşmesi olmayan bir kenardır. Birçok Components ikisini de bildirir; iki tablo birbirinden bağımsız olarak birleşir.

Ek yuvaları: featuresSchema

Bir Component, bir featuresSchema bloğu aracılığıyla ek yuvaları bildirebilir. Her yuva, Component’in bir Feature’ın eklenmesini beklediği bir bağlama noktasını adlandırır (bir kök parola, bir API anahtarı, bir kimlik doğrulama belirteci, bir kimlik bağlaması) ve hangi Feature’ın onu bağlayabileceğini ve dolgunun materyalinin nasıl iletilebileceğini kısıtlar.

Bu bölüm Component’in kendi yuvaları hakkındadır. Bir soketin her bağlantı için bildirdiği yuvalar ise kapalı bir kümedir; Topoloji soketleri altındaki “Her bağlantının doldurduğu yuvalar” bölümüne bakın.

Bir yuva bildirmek ek yüzeyini kapatmaz. Bir yazar, hiçbir yuvanın bildirmediği bir ad altında bir Feature ekleyebilir ve bu ek bir serbest ektir: tamamen geçerlidir, yalnızca bildirilmiş bir yuvaya bağlı değildir. Bu açıklık, tek bir katalog varlığının bir katalog çatallaması olmadan iki farklı dağıtım biçimine hizmet etmesini sağlar:

  • Tüketici başına. Her örnek yuvayı kendi Feature’ı ile doldurur; böylece her tüketici kendi işlenmiş kimlik bilgisini alır.
  • Paylaşılan. Hiçbir örnek yuvayı doldurmaz; bunun yerine tek bir kimlik bilgisi daha geniş bir kapsamda (bir alt sistem veya bir Release sınırı) bir kez eklenir ve altındaki her bileşene basamaklanır; böylece her tüketici bu tek bildirimden doldurulur. Neyin işlendiği gerçekleştirmeye bağlıdır: bir Secret işleyen gerçekleştirmede tüketici başına, her biri aynı materyali taşıyan bir Secret; her tüketiciyi zaten var olan bir Secret’a yönlendiren gerçekleştirmede hiçbiri.

Yazar, ne eklediğine göre bunlar arasında seçim yapar. Katalog varlığı her iki durumda da aynıdır.

Bu açık yüzeydeki bir biçim derlemeyi durdurur: bileşen üzerinde başka bir ad altında yazılmış bir dolgu. Bileşenin kendisi üzerinde (Aggregate’teki kendi features: bloğunda veya Release’in o tek bileşene ait girdisinde) yazılmış bir ek, hiçbir yuvanın bildirmediği bir ad taşıdığında ve Feature’ı, tüm kapsamlar katlandıktan sonra o bileşende hiçbir şeyin bağlamadığı bir yuvanın selector koşulunu karşıladığında derleme durur. Bu, yuvaya yönelik bir dolgunun yanlış ad altında yazıldığında aldığı biçimdir: kendi hâline bırakılsa yuva boş kalırken serbest bir ek olurdu ve boş bırakılan isteğe bağlı bir yuva başarıyla derlenir ve hiçbir şey iletmez. İleti eki, bileşeni, Feature’ı ve o Feature’ın uyduğu her boş yuvayı adlandırır; çözüm, eki yuvanın adı altında eklemektir. Bu yalnızca kimlik bilgileri için değil, her Feature için geçerlidir. Yüzeydeki diğer her şey serbest kalır: Feature’ı bildirilmiş hiçbir yuvaya uymayan bir ek, uyduğu her yuva bağlandıktan sonraki fazladan bir ek ve bileşenin bir alt sistemden veya bir Release sınırından devraldığı bir ek; dolayısıyla yukarıdaki paylaşılan biçim etkilenmez. selector bildirmeyen bir yuva hangi Feature için olduğu hakkında hiçbir şey söylemez; bu nedenle hiçbir ek bu şekilde ona bağlı tutulmaz. Durdurma, errors/fatal-halts.md içinde “An attachment written under another name fits a slot its component leaves empty (Başka bir ad altında yazılmış bir ek, bileşeninin boş bıraktığı bir yuvaya uyuyor)” başlığı altında açıklanır.

İki biçim birlikte kullanılabilir ve daha yakın olan kazanır. Bir yazar ikisini aynı anda yapabilir: bir Feature’ı daha geniş bir kapsamda ekleyerek o kapsam altındaki her bileşene ulaşmasını sağlamak ve farklı bir şeye ihtiyaç duyan tek bileşende yuvayı doldurmak. Bileşen kapsamlı dolgu kazanır; bu alan alan gerçekleşir, dolayısıyla yalnızca değiştirdiği alanları yeniden belirtmesi yeterlidir ve geri kalanlar yine daha geniş ekten gelir. Yuvayı doldurmayan kardeş bileşenler daha geniş eki olduğu gibi korur. Açıklama güdümlü eklerle ve birleştirilmiş Aggregates ile nasıl etkileştiği dahil tam öncelik kuralı vocabulary/labels-and-annotations.md “Attachment precedence” bölümündedir.

Component üzerindeki şema tanımı:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Alan anlamları:

AlanTürVarsayılanAnlam
requiredboolfalseYuvanın sonunda bağlanmış olması gerektiğini bildirir. Bu Component’in bir örneğinde yuvanın adını hiçbir şey bağlamadığında derleme durur; bu, örneğin tüm ek basamaklanmasından sonra tuttuğu ek kümesine göre denetlenir; dolayısıyla örneğin devraldığı bir kapsamda bildirilen bir ek, yuvayı tam olarak örneğin kendisinde yazılmış bir dolgu gibi karşılar. Tanılama bileşeni ve yuvayı adlandırır.
injectstring[]—İzin verilen inject iletim mekanizmalarının izin listesi. [] (boş) kara kutu anlamına gelir: Recipe iletimi dahili olarak denetler ve materyal hiçbir zaman iş yüküne iletilmez. [env, file] şeffaf anlamına gelir: dolgunun materyali listelenen mekanizmalar aracılığıyla iletilebilir. usesSchema[].inject ile aynı anlamlara sahiptir.
descriptionstring—IDE ve hub tarafından görüntülenen insan belgeleri.
selectorstring—Bu yuvayı hangi Feature’ın doldurabileceğini kısıtlayan isteğe bağlı, Kubernetes tarzı etiket seçici; bir usesSchema soketinin selector alanının yuvadaki karşılığıdır, aynı dilbilgisine ve aynı yerel etiket eşleştirme motoruna sahiptir. Statik analiz sırasında eklenen Feature’ın kendi etiketlerine göre değerlendirilir; etiketleri onu karşılamayan bir dolgu derlemeyi durdurur, dilbilgisinin reddettiği bir seçici de okuyamadığı gereksinimi adlandırarak derlemeyi durdurur. Dolguya kısıtlama koymamak için atlayın.
sensitiveboolfalseBu yuvayı bağlayan her şeyin gizli materyal işlediğini bildirir. Belirli bir dolgu hakkında değil, bağlama noktası hakkında bir ifadedir; aşağıdaki “Bir yuvayı hassas olarak bildirmek” bölümüne bakın.

Bir yuva, dolgunun neyi yapılandırdığını değil, hangi dolgunun onu bağlayabileceğini kısıtlar. Bilinçli olarak yuva düzeyinde bir values veya infra sözleşmesi yoktur: bu sütunların sahibi eklenen Feature’ın kendi schema: alanıdır; böylece her sözleşmenin tam olarak bir yeri olur.

Yuva selector alanı, bir Component’in bir FeatureRecipe adlandırmadan bir yuvayı hangi Feature’ın doldurabileceğini daraltma yoludur; örneğin sağlayıcıya özgü bir kimlik bilgisi Feature’ına (feature.aggrega.ai/kind=secret, provider=helm), tıpkı bir usesSchema soket seçicisinin bir bağımlılık kenarının hedefini daraltması gibi. Derleyici seçiciyi yalnızca eklenen Feature’ın etiketlerine göre değerlendirir: dolgunun taşıdığı etiketleri okur ve seçicinin bunları kabul edip etmediğini bildirir. Hangi etiketleri zorunlu kılmanın anlamlı olduğu, derleyicinin dayattığı bir kural değil, bir katalog yazımı tercihidir.

Yuva adı yazım hataları durdurma olarak değil, öneri olarak ortaya çıkar. Bildirilmemiş bir ek adı geçerli olduğundan, yanlış yazılmış bir yuva adı yazarın kastettiği yuvayı doldurmak yerine serbest bir ek olur. Derleyici, bildirilmiş bir yuva adından bir düzenleme uzaklıkta olan bir ek adını, her iki yazımı da adlandıran bir uyarı olarak bildirir; errors/warnings.md içindeki “Attachment-slot near-miss lint” bölümüne bakın. Uyarı derlemenin sonucunu hiçbir zaman değiştirmez; derleyici bir yazarın bir eke ne ad verdiğini denetlemez. Ekin Feature’ının selector koşulunu karşıladığı bir yuvadan bir düzenleme uzaklıktaki bir ad uyarı almaz: o yuva boş kalırsa yukarıda açıklanan durdurma bunun yerine eki bildirir; yuvayı başka bir şey bağlarsa ek sıradan bir fazladan ektir.

Bir yuvayı hassas olarak bildirmek

Bir yuvadaki sensitive: true, tüketicinin kendi talebini belirtir: bu noktayı bağlayan her ne ise gizli malzeme işler.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Bu, bir şema yaprağındaki sensitive: true ile gerçekten farklı bir bilgidir, onun kolaylık amaçlı bir kopyası değildir ve standart kütüphane kataloğu ikisine de ihtiyaç duyar. Başvurulabilir bir kimlik bilgisi provides.name ve provides.key değerlerini yayımlar (kaynağın konumlayıcısı ve içindeki veri anahtarı) ve hiçbiri hassas değildir: bir Kubernetes Secret’ın adı herkese açıktır, içindeki anahtar da öyle. Yine de bu kimlik bilgisinin doldurduğu yuva tartışmasız biçimde gizli malzeme işler. Bir yaprak bu veri gizli malzemedir der; bir yuva bu bağlama noktası gizli malzeme işler der; iki iddia farklı şeyler hakkındadır ve birbirinden bağımsız olarak geçerli olabilir.

Pratik sonucu, talebin dolgu ile değil bağlama noktası ile birlikte taşınmasıdır. Hiç hassas yaprak bildirmeyen bir Feature (hedef motor kimlik bilgisine sahip olduğu ve yazar hiçbir şey yazmadığı için) hassas bir yuvayı yine de hassas bir ek olarak bağlar, çünkü yuva bunu söylemiştir. Tersi de geçerlidir: hassas bir yaprak bildiren bir dolgu, böyle bir bildirim yapmamış bir yuvayı bağladığında ya da hiçbir yuvayı bağlamayan serbest bir ek olduğunda bile hassas bir ektir.

Bildirim, yazılmış herhangi bir bloğu değil ek kademelenmesini izler. Bir yuvanın talebi, tüm kapsamlar katlandıktan sonra bağlı kalan dolgu hangisiyse ona uygulanır; bu nedenle daha geniş bir dolgunun yerini alan bileşen düzeyindeki bir dolgu talebi değişmeden devralır.

Bir yuvadaki sensitive, yaprak düzeyindeki anahtar sözcükle aynı sınırı taşır: işaretler; şifrelemez, doğrulamaz, reddetmez, bir teslim mekanizmasını zorlamaz ve işlenmiş tek bir baytı değiştirmez. Tam açıklama vocabulary/compact-form-authoring.md içinde “What the keyword does not do” başlığı altındadır.

sensitive ve compliance.aggrega.ai/data-class iki farklı eksendir; yan yana belgelenir ve asla birbirine karıştırılmaz. sensitive, tek bir yaprak ya da tek bir yuva üzerindeki bir boolean değerdir: bu veri ya da bu bağlama noktası gizli malzeme işler. compliance.aggrega.ai/data-class ise bütün bir düğüm üzerindeki kademeli bir etikettir (public, internal, restricted) ve bir bileşenin tuttuğu verilere bir yönetişim kimliği verir. Biri veri başına ve ikilidir, diğeri düğüm başına ve sıralıdır; hiçbiri diğerinin yerini tutmaz ve bir varlık ikisini birden taşıyabilir. Etiket vocabulary/labels-and-annotations.md ve architecture/08-credential-model.md içinde “Data governance around credentials” başlığı altında ele alınır.

featuresSchema üzerinden şema izdüşümü

Bildirilen yuvalar, ek bloğunun biçimini tanımlayan bir JSON Schema 2020-12 parçasına yansıtılır. Buna karşı iki tür dolgu doğrulanır: içe aktarılan bir modülün katkıda bulunduğu bir bileşenin ek bloğu, onu içe aktaran kompozisyon oluşturulduğunda, ve daha geniş bir kapsamda bildirilen bir ek, ulaştığı her bileşendeki yuvaya karşı. Aggregate’in kendisinin bildirdiği bir bileşenin ek bloğu ise bunun yerine Aggregate’in belge şeması ve yuvanın inject izin listesiyle ölçülür (aşağıya bakın); parça, her ikisi de herhangi bir dolgu hakkında aynı karara varacak biçimde oluşturulmuştur. İzdüşüm diske hiç dokunmaz; yalnızca bellekte bulunur ve bir Component’in schema: alanının ek sütununu elle yazması hiçbir zaman gerekmez.

Girdi featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Yansıtılan parça (bellekte; kompakt biçim gösterimi):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

İki derinlik birbirinden bağımsızdır. Dış nesne açıktır; bu nedenle bildirilen bir yuva, varlığın sıralamadığı ekleri asla yasaklamaz. Her bildirilen yuvanın kendi parçası ise kapalıdır; bu nedenle bildirilen bir yuvayı bağlayan bir dolgu yine o yuvanın biçimiyle sınırlanır.

Parça yalnızca BİÇİMİ tanımlar. Hangi yuvaların bağlanması gerektiğine dair hiçbir ifade taşımaz, çünkü required olarak işaretlenmiş bir yuva daha geniş bir kapsamdan kademelenen bir ek tarafından bağlanabilir; bu da bu parçanın tanımladığı bloğu boş bırakır. Bu nedenle gereklilik, herhangi bir bloğun bildirdiğine göre değil, bir bileşenin sonunda sahip olduğu ek kümesine göre denetlenir ve iki soru hiçbir zaman çelişmez, çünkü yazılmış bloğa bunlardan yalnızca biri sorulur.

İzin verilen anahtarlar, bir ekin herhangi bir yerde taşıyabileceği anahtarları yansıtır; bu nedenle serbest bir ekte geçerli olan bir anahtar, bir yuva dolgusunda da geçerli kalır. İzin listesindeki her teslim mekanizması bir teslim girdileri listesidir (inject: her yerde aldığı biçimle aynı); yuva, bir girdinin neye benzediğini değil, hangi mekanizma ADLARININ görünebileceğini daraltır.

inject izin listesinin uygulandığı yer

İzin listesi, yuvanın iki tarafını da iki farklı adımda bağlar.

İşleme adımında Recipe’in Workload’una karşı: kapsayıcı ek girdileri aracılığıyla bir yuvaya başvuran bir Workload, varlığın bildirdiği bir yuvayı adlandırmalı ve yuvanın inject izin listesinin izin verdiği bir teslim mekanizmasını seçmelidir; bir blackbox yuvaya (inject: []), izin listesi dışındaki bir mekanizmaya ya da varlığın hiç bildirmediği bir yuvaya yapılan başvuru derlemeyi durdurur. Tanılama iletisi Recipe’i, kapsayıcı yolunu ve sorunlu yuvayı adlandırır ve bir katalog hatası olarak sınıflandırılır: yanlış yapan Recipe’tir.

Aggregate’in kendi ekine karşı, ekleri çözümlendiğinde ve herhangi bir işlemeden önce: bildirilen bir yuvayı bağlayan bir dolgudaki inject: bloğu yalnızca yuvanın izin listesinin izin verdiği mekanizmaları adlandırabilir ve bir blackbox yuva hiçbirine izin vermez; boş izin listesi “bunu Recipe dahili olarak teslim eder; teslimi dayatmayın” der ve onun için teslim yazmak derlemeyi durdurur. Tanılama iletisi ekin üzerinde konumlanır; yuvayı ve sorunlu mekanizmayı, yuva herhangi birine izin veriyorsa izin verdiği mekanizmalarla birlikte adlandırır; Aggregate yanlış yapan olduğu için bir geliştirici hatası olarak sınıflandırılır. Boş bir inject: {} bloğu hiçbir mekanizma adlandırmaz; bu nedenle hiçbir teslimi dayatmaz ve bir blackbox yuva dahil her yuvada kabul edilir — Aggregate’in bildirdiği bir bileşende, içe aktarılan bir modülün katkıda bulunduğu bir bileşende ve daha geniş bir kapsamda bildirilen bir ekte aynı şekilde. Serbest bir ek (hiçbir yuvanın bildirmediği bir ad altındaki ek) böyle bir kısıtlama taşımaz, çünkü izin listesi bloğa değil yuvaya aittir.

Derleme hattı boyunca uçtan uca akış (bir Aggregate ekinin bir kimlik bilgisi Feature’ına, örneğin core/secret-value, ve ardından kimlik bilgisini çalışan iş yüküne teslim eden sağlayıcıya özgü bir FeatureRecipe’e nasıl bağlandığı) examples/05-credential-features içinde adım adım işlenir.

Çağıranın sunduğu anahtar ve sunucunun doğruladığı anahtar

Bir bileşen, anahtar denetleyen başka bir bileşeni çağırdığında her uç anahtarı kendi tarafında, kendisinin bildirdiği bir slotta tutar. Bu, standart kütüphane kataloğunun izlediği bir uzlaşımdır; derleyici bunların hiçbirini zorunlu kılmaz: her bileşenin slotlarını o bileşenin kendi eklerine göre denetler, dizgelerini olduğu gibi aktarır ve bir bileşenin tuttuğunu başka bir bileşenin tuttuğuyla asla karşılaştırmaz.

  • Çağıranın sunduğu anahtar çağıranındır. Çağıranın soketinin her bağlantı için bildirdiği bir slotta durur (yukarıdaki “Her bağlantının doldurduğu slotlar” bölümüne bakın); bu nedenle birkaç hedefe ulaşan bir çağıran her biri için bir anahtar tutar. core/ai-agent/crewai’ın model soketi bu slotu credential olarak bildirir ve Recipes’i onu dolduran her şeyi OPENAI_API_KEY olarak iletir. core/gateway/litellm, core/gateway/kong ve core/gateway/apisix bileşenlerinin models soketleri de bunu bildirir ve Recipes’leri her bağlantının anahtarını, bağlantının takma adıyla adlandırılmış kendine ait bir değişken altında iletir; böylece ağ geçidinin sunduğu her model kendine ait bir anahtar tutar. Bunun yerine bir Component’in kendine ait bir slotta bildirdiği anahtar ise yaptığı her bağlantı için tek bir anahtardır.
  • Sunucunun doğruladığı anahtar, sunucunun kendi slotudur. core/ai-model/vllm, core/ai-model/tei ve core/ai-model/tgi her biri isteğe bağlı bir api_key bildirir ve her birinin Recipes’i onu dolduran her şeyi sunucunun anahtarını okuduğu değişken olarak iletir. LiteLLM modeli ve ağ geçidi, LiteLLM’in ana anahtar (master key) dediği anahtar için api_key bildirir.
  • Hiçbir uç diğerinin eklerini görmez. Bir bağlantı üzerindeki ek, çağıranın eklerinden biridir ve yalnızca çağıranın render’ına ulaşır; bir sunucunun render edilmiş çıktısı ise ona ulaşan bağlantılar ne taşırsa taşısın aynıdır. required olarak işaretlenmiş bir slot, ona bağlı bileşenlere değil, onu bildiren bileşene aittir ve bir ucun slotunu doldurmak diğer uçta hiçbir şeyi doldurmaz; dolayısıyla anahtarı iki uçta da bildirmek bir yineleme değil, asgari gerekliliktir.
  • İki uç da tek bir parametreyi okur; böylece çağıranın sunduğu anahtar ile sunucunun doğruladığı anahtar birbirinden farklı yazılamaz.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Tek bir anahtar denetleyen bir sunucu, çağıranlarını birbirinden ayırt edemez: vLLM, TEI ve TGI her biri tek bir anahtar denetler; bu nedenle sunucuya kaç bağlantı ulaşırsa ulaşsın her çağıran aynı anahtarı sunar. İki ucun tek bir gizli değere mi başvurduğu yoksa her birinin kendi gizli değerini mi tuttuğu, her sağlayıcının bir gizli değeri başvuruyla nerede çözümlediğinden çıkar ve her ucun gerçekleştirimini Manifest seçer; Credential Model iki durumu da ayrıntılı olarak ele alır.

Bir bileşenin kendisi için tuttuğu bir kimlik bilgisi (örneğin kendi oturumlarını imzaladığı bir anahtar), diğerleri gibi kendi featuresSchema: alanındaki bir slottur. Soketlerinden biri üzerinden ulaştığı bir veri deposuna sunduğu parola ise yukarıdaki çağıran anahtarıdır; bu nedenle o bağlantıda credential olarak durur: core/gateway/kong’un backend soketi bunu bildirir ve iş yükü sentezleyen Recipes’i onu KONG_PG_PASSWORD olarak iletir; core/gateway/litellm’in cache_store soketi ise anlamsal önbelleğinin depoya sunduğu parola için bunu bildirir ve parola REDIS_PASSWORD olarak iletilir. Bir bağlantı bir çift sunduğunda (bir erişim anahtarı tanımlayıcısı ve onun gizli değeri), core/ai-agent/agenta-api bileşeninin store soketinde olduğu gibi gizli yarı credential, tanımlayıcı yarı ise credential_id olur.

Kendine enjeksiyon: spec.inject

Bir Component, kendine enjeksiyon teslim mekanizmalarına izin listesi tanımlayan üst düzey bir spec.inject: dizisi bildirebilir. Bu dizi mevcut olduğunda geliştiriciler, Component’in kendi values: veya provides: anahtarlarını doğrudan kendi teslim kanalına (konteynerinin ortam değişkenlerine, bağlanan dosyalarına veya süreç argümanlarına) enjekte etmek için Aggregate içinde bileşen düzeyinde bir inject: bloğu kullanabilir. spec.inject: yoksa veya boşsa bileşen düzeyinde kendine enjeksiyon yasaktır; tüm iç bağlantıları Recipe yönetir. Bu, usesSchema[].inject: [] ve featuresSchema[].inject: [] ifadelerinin sırasıyla bileşenler arası teslime ve kimlik bilgisi teslimine uyguladığı Kara Kutu desenine karşılık gelir.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Her value: şablonu {{ yerine {{"{{"}} ile başlar. Aggregate’in tüm metni, kendine enjeksiyon çözümlemesi çalışmadan önce parametre enterpolasyonu için bir kez şablon olarak okunur ve o noktada .values mevcut değildir; kaçış, kendine enjeksiyon çözümlemesinin değerlendirmesi için {{ ifadesini geri koyar. Bkz. Kendi çift süslü parantezlerini taşıyan metin.

Alan anlamı. spec.inject:, mekanizma adlarından oluşan bir dizidir. Üç değer tanımlıdır:

  • env — konteynerdeki ortam değişkenleri.
  • file — bağlanan dosya yolları.
  • arg — sürecin komut satırı argümanları.

Anlam, usesSchema[].inject ve featuresSchema[].inject ile birebir aynıdır: aynı sözcük dağarcığı, atlandığında aynı Kara Kutu deseni, Aggregate tarafında aynı yazım biçimi. Fark kaynaktadır: usesSchema[].inject, bileşenler arası bir bağımlılığın provides değerlerinin tüketicinin teslim kanalına nasıl aktığını yönetir; featuresSchema[].inject, bir kimlik bilgisinin bir konteynere nasıl ulaştığını yönetir; spec.inject ise Component’in kendi values ve provides değerlerinin Component’in kendi konteynerine nasıl ulaştığını yönetir.

Yazım disiplini. spec.inject: [env, file] bildiren bir core/web-server Component’i saydam teslimi seçer: hangi ortam değişkeni adlarının hangi değerleri taşıyacağını Aggregate yazarı belirler. spec.inject: [] bildiren (veya alanı atlayan) bir Component teslimi opak tutar: hangi alanların hangi konteyner değişkenlerine aktığına Recipe’nin valuesMapping: bölümü karar verir ve geliştirici bunu Aggregate’te geçersiz kılamaz. Kara Kutu deseni kararlı sözleşmeli Components için uygundur (Recipe’si veritabanı parolasını bir POSTGRES_PASSWORD ortam değişkenine nasıl bağlayacağını bilen bir core/postgres-db Component’i); saydam desen ise geliştiricinin amacının teslim ayrıntılarını meşru olarak adlandırdığı Components için uygundur (uygulaması LOG_LEVEL değerini geliştiricinin özelleştirmek istediği standart dışı bir değişken adından okuyan bir core/web-server).

Hata durumları. Bir geliştiricinin Aggregate’i, spec.inject: değeri eksik veya boş olan bir Component üzerinde inject: bloğu kullanırsa derleme, çalışma alanı yüklenirken durur (“Self-inject on a component without an allowlist (İzin listesi olmayan bir bileşende kendine enjeksiyon)”). İzin listesinde olmayan bir mekanizma kullanan bir inject: bloğu aynı koşulla durur ve mekanizmayı ve izin listesinin izin verdiklerini adlandırır (“Self-inject mechanism not in the component’s allowlist (Kendine enjeksiyon mekanizması bileşenin izin listesinde değil)”). Kendine enjeksiyon, bileşenler arası enjeksiyon ve kimlik bilgisi enjeksiyonu arasındaki bir teslim anahtarı çakışması da derlemeyi durdurur (“Duplicate delivery key across inject sources (Enjeksiyon kaynakları arasında yinelenen teslim anahtarı)”). Hata başına ileti biçimleri için errors/fatal-halts.md sayfasına bakın.

Katalog yazımı: temel Components’ı genişletme

Platform mimarları, kurumsal veya topluluk temellerinin üzerine özelleşmiş arayüzler katmanlamak için extends anahtar sözcüğünü kullanır. Genişletme yapıyı birleştirir ve veri sütunlarını bütün olarak devralır. Derleyici zinciri temelden aşağıya doğru dolaşır; iki yarı farklı davranır ve bu fark, yazım modelinin tamamıdır.

Genişletmenin birleştirdikleri. Bu yüzeyler zincir boyunca birleşir; anahtar başına genişleten Component kazanır, listeler ise önce temel olmak üzere yinelenmeden art arda eklenir:

YüzeyNasıl birleşir
metadata.labelsanahtar başına birleştirilir; ortak bir anahtarda genişleten Component’in değeri kazanır
metadata.annotationsanahtar başına birleştirilir, aynı öncelikle — bir temelin varlık zorunluluğunun onu genişleten her Component’e ulaşmasının nedeni budur
spec.featuresSchemaek yuvaları birleşir; genişleten Component’in yeniden bildirdiği bir yuva, temelin aynı adlı girdisinin yerini alır
spec.usesSchematopoloji soketleri birleşir, aynı ad başına değiştirme kuralıyla
spec.injectiki kendi kendine enjeksiyon izin listesi art arda eklenir, önce temel girdiler, yinelenenler atılır
spec.assertionsadlandırılmış kurallar birikir, önce temel kurallar — ve yalnızca bu yüzey ad başına değiştirmeye izin vermez; aşağıdaki “Doğrulama kuralı kalıtımı eklemelidir” bölümüne bakın

Genişleten Component’in eklediği bir soket, kendi kenar başına valueSchema ve infraSchema değerlerini taşıyabilir; bunlar o soketin kenarlarına ilişkin sözleşmelerdir, Component’in kendi sütunlarına eklemeler değildir.

metadata: alanının geri kalanı, onu bildiren belgede kalır. Zincir boyunca aşağıya aktarılan tek meta veriler labels ve annotations alanlarıdır. name, version, description, maintainers, license, repository, home ve keywords genişleten Component’in kendisine aittir ve tam olarak yazıldığı gibi okunur — description: alanını atlayan bir Component, temelininkini ödünç almak yerine açıklamasız kalır. Kimlik ve köken, okuduğunuz belgeye aittir; böylece bir sarmalayıcı hiçbir zaman sarmaladığı şeyle karıştırılmaz.

Genişletmenin bütün olarak devraldıkları. Üç veri sütunu — values, infra, provides — birleştirilmez. Genişleten bir Component hiçbir sütun içeriği yazmaz: schema: inherited sabit işaretini yazar ve temelinin schema: bloğunu tam olarak temelin yazdığı biçimde alır. Herhangi bir derinlikteki zincir boyunca zincirdeki her Component, zincir kökünün bloğunu değiştirmeden taşır; bu nedenle bir yaprak üzerinde aggrega inspect --resolved kökle aynı sütunları gösterir.

Yayımlanan Component şeması, üç olası sonuçtan hangisinin geçerli olduğunu belirler ve diğer ikisini belge yüklenirken reddeder — her biri için farklı bir tanılama iletisiyle, çünkü bunlar farklı hatalardır:

  • schema: altında sütun içeriği bulunan extends: reddedilir. Component’in sözleşmesi temelininkidir; ikinci, farklılaşan bir sözleşmenin yer alabileceği bir yer yoktur.
  • schema: tamamen atlanmış extends: reddedilir. Bir atlama, okuyucunun devralınmış bir sütun bloğunu unutulmuş bir bloktan ayırt edememesine yol açardı.
  • extends: olmadan schema: inherited reddedilir. İşaret, sütunların nereden geldiğini belirtir ve bu Component’in onları alabileceği bir temeli yoktur.

Genişleten bir Component anahtar kümesini yeniden biçimlendiremez. Hiçbir sütun anahtarı bildirmez; bu nedenle temelinin bildirdiği bir anahtarı gizleyemez, atamaz veya türünü değiştiremez ve kendine ait hiçbir anahtar eklemez. Yeni bir sütun anahtarı, sözleşmesi o anahtara sahip olan Component’e aittir. Temel ne sunuyorsa, onu genişleten her şey aynısını sunar.

Bir özelleştirme assertions: aracılığıyla daraltır. Bir özelleştirmenin temelinin sütunlarından daha azını kabul etmesi gerektiğinde — daha dar bir sayısal aralık, devralınmış bir enum: değerinin alt kümesi — bunu kendi assertions: bloğunda belirtir: oradaki bir kural, devralınmış şemanın kabul ettiği bir değeri reddeder. Daraltmanın yeri bu yüzeydir; aşağıdaki “assertions: bloğu” bölümüne bakın.

Bu son iki paragraf tek bir kuraldır ve iki yarıdan yalnızca biri yanıltıcıdır: anahtar kümesini daraltmak olanaksızdır, kısıtlamayı sıkılaştırmak olanaklıdır. Yalnızca birincisini alırsanız bir özelleştirmenin hiçbir şeyi kısıtlayamayacağı sonucuna varırsınız; yalnızca ikincisini alırsanız sözleşmeyi yeniden biçimlendirebileceği sonucuna varırsınız. İkisi de doğru değildir — anahtar kümesi temel tarafından sabitlenir ve bu küme içinde kabul edilen değerler bir yüklemle daraltılabilir.

Doğrulama kuralı kalıtımı eklemelidir ve birikim kökten başlar. Genişleten bir Component’in örneği, Component’in kendi bildirdiği kuralların yanı sıra zincirinin bildirdiği her kurala göre denetlenir; devralınan kurallar önce değerlendirilir. Herhangi bir derinlikteki zincir boyunca kurallar zincir kökünden aşağıya doğru birikir; bu nedenle bir örnek birden fazla kuralı karşılamadığında, zincirde en yukarıda bildirilen kural raporlanır — en temel sözleşme ilk yanıtı verir.

Kalıtım değiştirmek yerine eklediği için, genişleten bir Component devralınmış bir kural adını farklı bir kural bildirmek için yeniden kullanamaz: bu, extends zinciri katalogla çözümlenirken her iki Components’ı ve ortak adı belirten bir tanılama iletisiyle reddedilir. Denetim, temel Component’in elde olmasını gerektirir; bu nedenle katalog doğrulanırken veya bir derleme zinciri çözümlerken raporlanır — genişleten belgeyi tek başına doğrulamak bunu göremez. Kural adı kararlı bir tanımlayıcıdır; bu nedenle ne temelin kuralını atmak ne de onu sessizce yeniden adlandırmak bir seçenektir ve çözüm, genişleten Component’te yeniden adlandırmaktır. Devralınmış bir kuralı kendi adı altında bayt bayt yeniden belirtmek, etkisiz bir işlem olarak kabul edilir.

aggrega pull tabanı getirir. Bir taban, onu genişleten bir Component’e ulaşan her Release’in bağımlılığıdır; başka bir şeyin onu adlandırıp adlandırmaması fark etmez. aggrega pull her extends: öğesini zincirin sonuna kadar izler, hiçbir katalog dizininin içermediği bir tabanı registry’den getirir ve her tabanı, onu adlandıran Component’in spec.extends alanından başvurulacak biçimde Release’in lockfile’ına kaydeder; bir build tabanı oradan okur. Böylece bir Manifest yalnızca bir sarmalayıcının kendi türünü eşler, fazlasını değil — taban ancak bir Aggregate tabanın bir örneğini de bildirdiğinde kendine ait bir eşleme satırına ihtiyaç duyar. Tüm katalog üzerinde çalışan bir aggrega validate de tabanı aynı şekilde okur; bu nedenle bir registry’ye yayımlanmış bir taban, bir pull onu getirene kadar orada aggrega pull adlandırılarak reddedilir.

Şema içerik biçimleri için architecture/13-catalog-and-registry.md §3 bölümüne bakın.

Örnek A: Temel Component (kurumsal temel) Platform mimarı, temel bir kurumsal sunucu tanımlar. Bu temel, gerekli operasyonel bulut ilkel etiketini belirler ve şemadaki güvenlik kısıtlamalarını oluşturur. Sütun bloğu değiştirilmeden devralındığı için buradaki her kısıtlama, genişleten her Component’e tam olarak yazıldığı gibi ulaşır.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Örnek B: Genişleten Component (temeli özelleştirme) Bir ağ geçidi bu temelden özelleştirilir. Temelin sütunlarını bütün olarak alır, kendine ait yapı ekler — bir etiket, bir kendi kendine enjeksiyon mekanizması, üzerinde bir ek yuvası bulunan bir topoloji soketi — ve devralınan zaman aşımını bir doğrulama kuralıyla sıkılaştırır. Temelin audit-window-is-observable kuralını yeniden belirtmez: bu kural devralınır ve önce değerlendirilir; bu nedenle bu ağ geçidinin bir örneği her iki sınırı da karşılamalıdır — en az 100 ve en fazla 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Bu core/gateway/kong arayüzünü fiziksel bir Helm chart’ına karşı uygulayan Recipe için entities/recipe Örnek C’ye (kong-gateway) bakın.

assertions: bloğu

Component.spec.assertions:, Component sözleşmesinin mimari değişmezlerini ifade eden adlandırılmış kurallardan oluşan isteğe bağlı bir eşlemdir — Component’e hangi Recipe bağlanırsa bağlansın geliştiricinin yazdıklarının karşılaması gereken alanlar arası kurallar. Her anahtar, hata iletisinde görünen bir kural tanımlayıcısıdır; her değer bir Go şablonu gövdesidir. Derleyici bunları örnek başına, şema doğrulamasından sonra ve Recipe bağlamasından önce, yazıldıkları sırayla değerlendirir ve karşılanmayan ilk kural, Loud Guardrails sözleşmesi uyarınca o kuralın kendi hata iletisiyle derlemeyi durdurur.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

Yukarıdaki kural, Component sözleşmesinin bir özelliğidir — hangi Recipe bağlanırsa bağlansın (Bitnami chart’ı, elle yazılmış bir alternatif, gelecekteki bir uygulama), çoğaltma modu en az iki ikincil kopya gerektirir.

assertions:, genişleten bir Component’in daralttığı yerdir. Bir temeli extends: ile genişleten bir Component, temelin sütun bloğunu birebir devralır ve kendine ait hiçbir sütun içeriği bildirmez; bu nedenle devralınan şemadan daha azını kabul etmesi gereken bir özelleştirme, kısıtlamayı daraltılmış bir şema yaprağı olarak değil, burada bir yüklem olarak belirtir — devralınan sütunların kabul ettiği bir değeri reddeden bir kural. Örnek çift ve kalıtım davranışının tamamı yukarıdaki “Katalog yazımı: temel Components’ı genişletme” bölümündedir: kurallar zincir boyunca kökten başlayarak birikir ve devralınmış bir kural adının farklı bir kural için yeniden kullanılması, onun yerini almasına izin verilmek yerine reddedilir.

Derleyici, iki kuralın birlikte karşılanıp karşılanamayacağını denetlemez. Bir kural, derleyicinin üzerinde akıl yürüttüğü bir kısıtlama değil, bir şablon yüklemidir; bu nedenle hiçbir değerin aynı anda karşılayamayacağı bir kural çifti — en az 100 isteyen bir temel ve en fazla 50 isteyen bir özelleştirme — katalog yüklenirken hiçbir uyarı üretmez. Bu durum olağan yoldan ortaya çıkar: bir örnek yazılır, derleme iki kuraldan hangisi önce tetiklenirse onda durur ve yazarın okuduğu, o kuralın iletisidir. Bir çelişkinin önceden raporlanmasını beklemeyin; bir özelleştirmenin daraltmasını, temelinin zaten istedikleriyle karşılaştırarak denetleyin.

assertions: bloğunu gerçek alanlar arası kurallar için kullanın. Alan başına kısıtlamalar (aralık, desen, enum) schema: anahtar sözcüklerine; alan başına özel yüklemler kompakt biçimin validate: alanına; koşullu biçim (bir alt ağacın kısıtlamalarının uygulanıp uygulanmayacağı) when: alanına aittir. Yazım dilbilgisinin tamamı — şablon bağlamı alanları, {{ fail }} ileti uzlaşımı, değerlendirme aşaması ve Component ile Recipe rollerini kapsayan örnekler — için templates/assertions-block.md belgesine bakın.