Veri taksonomisi ve bileşim
Birleşik veri taksonomisi ve bileşim kuralları
Öngörülebilir bir şema oluşturmak ve bilişsel sürtünmeyi ortadan kaldırmak için platform, tam olarak beş evrensel olarak anlaşılır anahtar kelime ve katı biçimde eşleme (sözlük) tabanlı bir YAML yapısı kullanır; yapısal kökte iç içe diziler yerine eşlemeler bulunur.
1. 5 anahtar kelimeli eşleme standardı ve tam şema simetrisi
Doğrudan yapısal sözcük dağarcığı: Şema tasarımının temel kurallarından biri, kök veri yapılarının tekil, yapısal anahtar kelimeler olması gerektiğidir. Gündelik İngilizce ifadeler (depends_on veya runs_within gibi) kullanmak bir YAML DSL’ini geliştirici için daha doğal okunur hâle getirebilse de bu anahtarları programatik Go şablonlarına eşlerken yapısal karmaşıklık getirir. Doğrudan 1:1 değişken eşlemesini korumak ve alana özgü dil (DSL) parçalanmasını önlemek için temel katalog varlıklarının (Component, Feature) JSON şemaları, yazılan tüm örnek yuvalarında kullanılan aynı temel yapısal anahtar kelime kümesiyle yönlendirilen neredeyse tam bir yapısal simetri ifade eder. Kimlik bilgisi Features’ları (feature.aggrega.ai/kind: secret etiketli) bu aynı paradigmayı paylaşır — sırlar için ayrı bir şema yoktur.
parameters(Küresel ortam sözleşmesi)- Kapsam:
Aggregate’in kökünde tanımlanır;Release(CI/CD) tarafındanparameters:altında satır içi olarak veya harici bir parametre dosyasını gösterenparameters: { $import: <path> }aracılığıyla karşılanır. - Anlam: Uygulamanın bilişsel veya mantıksal durumunu ortamlar arasında dinamik olarak değiştiren harici argümanlar (ör.
workers: 2değeriniworkers: 10olarak değiştirmek). Enterpolasyondan önce doğrulanan bir türlendirilmiş sözleşmeyi destekler (türlendirilmiş sözleşmenin tam sözdizimi için bkz. data-pillars). Parametre değerlerini ayrı bir dosyada tutan GitOps iş akışları için Release,$import:biçimini kullanır; derleyici dosyanın içeriğini yükler ve satır içiparameters:eşlemesinin yerine koyar. Çok dosyalı katmanlama, Release’inextends:zincirleriyle ifade edilir.
- Kapsam:
values(Bilişsel niyet - Geliştiriciye ait)- Kapsam:
Aggregateiçindecomponentsve bunlarınfeatureseklerinde, kimlik bilgisi Features’ları dahil, tek tip olarak kullanılır. - Anlam: Temel bilişsel durum, iş mantığı ve operasyonel yapılandırma. Go derleyicisi için opaktır ancak kataloğun birleşik
schema:bildirimi (kompakt biçim veya JSON Schema 2020-12) tarafından sıkı biçimde doğrulanır.
- Kapsam:
uses(Yapısal topoloji - Bildirimsel durum)- Kapsam:
Aggregateiçindecomponentsve bunlarınfeatureseklerinde, kimlik bilgisi Features’ları dahil, tek tip olarak kullanılır. - Anlam: Ağ kenarlarını ve bağımlılıkları tanımlayan bildirimsel bir olgu ifadesi (ör. “Bu ajan bu veritabanını kullanır”). Ara Gösterim (IR) grafiğini çizmek için Go derleyicisi tarafından yerel olarak ayrıştırılır. Düğümler arası tür güvenliğini zorunlu kılmak için kataloğun birleşik
usesSchemabildirimi tarafından doğrulanır.
- Kapsam:
infra(Fiziksel gerçeklik - Ops’a ait)- Kapsam:
Releaseiçinde bir sınırıncomponentsöğelerinde ve bunlarınfeatureseklerinde tek tip olarak kullanılır. - Anlam: Late Binding sırasında enjekte edilen fiziksel ayak izi ve mekanik boyutlandırma (ör.
cpu_limit: "4",port: 5432). Aggregate’in bileşen örnekleri ve bunlarınfeaturesekleri birinfraalanı içermez veadditionalProperties: falseile birlikte şema doğrulamasındainfra’yı reddeder. Kataloğun birleşikschema:bildirimi tarafından doğrulanır.
- Kapsam:
inject(Teslim sözleşmesi - Buyurgan komut)- Kapsam: Bir bileşen örneğinde,
usesiçindeki açık hedef tanımlarında ve eklenmişfeaturesüzerinde, kimlik bilgisi Features’ları dahil, kullanılır. - Anlam: Teslimatın niyetini belirleyen açık, buyurgan bir komut (ör. “Derleyici, bu eşlenmiş değeri bir ortam değişkeni olarak enjekte et”). Fiziksel bir çıktı, çözümlenmiş bir uç nokta veya alınmış bir kimlik bilgisi için soyut sözleşmeyi (
env,file,argveya özel mekanizmalar) kurar; bu bağlamanın tam olarak nasıl yürütüleceğine ilişkin fiziksel mekanik ise tamamen alttaki Ops Recipe’sine devredilir. Her mekanizma bir girdi listesidir ([{ in: API_HOST, from: "host" }]); her girdi yerel tanımlayıcısınıin:ile adlandırır vefrom:ya davalue:öğelerinden tam olarak birini taşır.
- Kapsam: Bir bileşen örneğinde,
.context(Genel meta veri borusu)- Kapsam: Derleyici tarafından Ops
Recipeşablonlarına sessizce enjekte edilir. - Anlam: Derleyicinin grafın geri kalanından düğüm için bir araya getirdiklerini (
.context.usesgibi) taşır ve doğrudan Ops şablon motoruna aktarılır.
- Kapsam: Derleyici tarafından Ops
1:1 eşleme gerçekliği
Gündelik edatları katı altyapı anahtar kelimeleriyle değiştirerek doğrudan bir 1:1 eşleme elde edilir. Ops mühendisinin dilbilgisi çevirmesi gerekmez; yalnızca geliştiricinin yazdığı anahtarların aynısına başvurur.
Yapısal biçimler: kökte eşlemeler, yüklerde diziler. Kök topoloji blokları — components, features, aggregates, subsystems, boundaries — kullanıcının yazdığı anahtarların kararlı örnek kimlikleri olarak hizmet ettiği YAML eşlemeleridir. Bu konumlarda diziler geçerli değildir; eşleme anahtarı, derleyicinin çapraz başvurular (target: my-db), grafik düğümü oluşturma ve Manifest çözümlemesi için kullandığı kimliktir. Opak yük bloklarının (values, infra, parameters) içinde diziler tamamen serbesttir — geliştiriciler bir Component’in values alanına tools_allowed: ["sql", "web"] veya hostnames: ["stripe.com", "twilio.com"] yazabilir. Aggregate şeması bu yük bloklarını additionalProperties: true olarak bildirir; böylece bunlar Go derleyicisi için opaktır ve tamamen kataloğun gömülü schema: bildirimi tarafından doğrulanır. Bu, çerçeve oynaklığını (yeni yapay zekâ API biçimleri, yeni bulut yerel yük biçimleri) bağımsız olarak gelişebileceği Katalog alanına yerleştirirken Go derleyicisinin yapısal kökte yalnızca adreslenebilir anahtarlarla kalmasını sağlar.
2. Bilgi akışları: Kim, ne zaman ve ne için?
Şablon ad alanı çakışmalarını ve fiziksel altyapı yapılandırmalarının bilişsel uygulama mantığına istenmeden sızmasını önlemek için mimari, verileri açıkça altı ayrı akışa ayırır:
- Akış 1: Ortam enjeksiyonu (
parameters): CI/CD hattı dağıtım gerçekliklerini enjekte eder. Derleyici, Release tarafından sağlanan her değeri türlendirilmişparameters:sözleşmesine karşı doğrular, ardından aşağı akıştakivalues:şema doğrulamasını çalıştırmadan önce çözümlenmiş Go şablon değişkenlerini enterpole eder.- Önerilen kullanım:
parameters, ortamlar arasında değişen bilişsel uygulama mantığı için ayrılmıştır (ör.LOG_LEVEL=debug,ENABLE_BETA=true). Operasyonel boyutlandırma ve fiziksel altyapı konuları — replikalar, CPU sınırları, AWS ARN’leri, ingress ana bilgisayar adları —Release’ininfrabloğu ve sınır katmanları üzerinden akar; böylece geliştiricininAggregate’i uygulama niyetine odaklı kalır. - Pragmatik kaçış yolu: Katı ayrımın pratik olmadığı daha küçük ekipler, hızlı prototipleme veya eski CI/CD entegrasyonları için
parameters, küresel ortam yapılandırmalarını yığın boyunca taşıyabilir. Derleyici şema doğrulamasından geçen her şeyi kabul eder; yukarıdaki öneri bir derleyici kuralı değil, bir toplumsal sözleşmedir.
- Önerilen kullanım:
- Akış 2: Bilişsel uygulama niyeti (Components içindeki
values): İçsel uygulama mantığını tanımlar. Component’inschema:bildirimi (kompakt biçim veya JSON Schema 2020-12) bu yük için sıkı tür denetimi ve doğrulama sağlar, geliştiricilere anında “Shift-Left” geri bildirimi verir ve istenen yapılandırmaların alttaki altyapı API’siyle eşleşmesini güvence altına alır. - Akış 3: Operasyonel Feature niyeti (Features içindeki
values): Aggregate’te geliştirici, davranışı uygulama niyeti olan altyapı yeteneklerini talep eder ve iç kodu değiştirmeden sıkı türlendirilmiş kimlik bilgilerini sorgular. Tüm girdileri operasyonel olan bir Feature, geliştiricivaluesdeğeri taşımaz: operasyon ekibi onu Release’te,infra’sıyla birlikte ekler (Akış 4). - Akış 4: Fiziksel altyapı boyutlandırması (
infra): Geliştiriciyi tamamen atlayarak fizikselinfraboyutlandırması, ortama özgüRelease’ten doğrudan yerel kapsamlı Components’a ve bunlara eklenmiş Features’a, kimlik bilgisi Features dahil, açıkça yansıtılır. Sözlüklerin olduğu gibi yayınlanmasından kaynaklanan kapalı şema doğrulama çakışmalarını önlemek içininfraboyutlandırması, onu hedefleyen açık bileşene sıkı biçimde yerelleştirilir. Bu, hesaplama sınırlarını, replikaları ve mekanik kaynak gereksinimlerini Ops alanında tutar. - Akış 5: Basamaklı ek açıklamalar (Bağlamsal meta veriler): Geniş bağlamsal veriler (operasyonel alanlar, ad alanları veya faturalama kodları gibi) basamaklı ek açıklamalarla ele alınır ve
infrayayınlama kirliliği önlenir. Bunlar kökenlerine göre kovalara ayrılır ve aşağıda her kovanın amaçlanan kullanımı bir toplumsal sözleşmedir: bir Recipe şablonu üçünü de okuyabilir ve derleyici bu ayrımı zorlamaz (bkz. labels-and-annotations):.context.annotations.release(Domain 4 sınırları): Yalnızca fiziksel gerçeklikleri yönetmek için kullanılır. Ops bu ek açıklamaları Go şablonları aracılığıyla açıkça katı yerelinfraalanlarına yönlendirir (ör. bölgesel bir ad alanını bir hesaplama bileşenine eşleyerek)..context.annotations.aggregate(Domain 1 alt sistemleri): Yalnızca bilişsel ve operasyonel mantığı yönetmek için kullanılır. Bu ek açıklamalar açıkça bileşeninvaluesyüklerine yönlendirilir (ör. bir ekip faturalama kodunu bir uygulama yapılandırmasına kadar basamaklı olarak aktararak)..context.annotations.catalog(Domain 2 kataloğu): Mimar tarafından yazılan değişmez içsel özellikler; öncelikle programatik Wasm politika değerlendirmesi için kullanılır.
- Akış 6: Meta veri borusu (
.context): Küresel kurumsal gereksinimleri (SOC2 etiketleri) doğrudan fiziksel altyapı şablonlarına uygular.
3. Ağ soyutlaması: “Zero-Port” uzlaşımı
- En iyi uygulama: Geliştiriciler portları
Aggregate’ten çıkarmalıdır. Ops Recipe’si dahili yönlendirmeyi dinamik olarak yönetir. - Kaçış yolu: Bir uygulamanın dahili kodu değiştirilemezse, platform mimarı
schema:bildiriminde açıkça birportalanı sunar. Mimari not: “Zero-Port” uzlaşımı, platformun daha geniş sorumluluk ayrımının en belirgin örneğidir. Aynı felsefe — fiziksel mekaniği geliştiriciden uzakta soyutlamak — CPU istekleri, bellek sınırları, operasyonel alanlar ve disk boyutlandırması için de geçerlidir. Fiziksel bir altyapı kısıtı geliştiricinin uygulama yüküne sızmak zorunda olduğunda (eski kod veya katı donanım gereksinimleri nedeniyle), her zaman mimarınschema:bildirimindeki, yani geliştiricinin yükünün doğrulandığı bildirimdeki açık bir “kaçış yolu” ile yönetilmelidir.
“Zero-Port” adı bu uzlaşımı ifade eder; ilke, eski bir uygulamanın sabit kodladığı her fiziksel altyapı kısıtına genelleşir. Aşağıdaki şema, açıkça infra sızıntısı ekseninde yer aldığı için çalışılmış örnek olarak tcp_keepalive_seconds’ı — uygulamanın soket katmanında beklediği bir çekirdek/ağ zamanlaması — kullanır.
Şema (Domain 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }Geliştirici YAML’ı (Domain 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaDerleyici davranışı: Go derleyicisi tcp_keepalive_seconds: 120 değerini IR grafiğine aktarır. Ops Recipe’si ardından Kubernetes pod spesifikasyonunu veya bulut sağlayıcısının yük dengeleyici boşta kalma zaman aşımını yapılandırmak için {{ .values.tcp_keepalive_seconds }} değerini okur ve şemayı ihlal etmeden eski sistem boşluğunu başarıyla kapatır.
4. Enjeksiyon sözleşmesi ve önceden çözümlenmiş eşleme
Beş yapısal anahtar kelime arasında inject, kardeşlerinden farklı bir biçim taşır. parameters, values, uses ve infra bildirimsel durumdur — geliştirici uygulamanın ne olduğu ve neye bağlı olduğu hakkında olgular yazar. inject buyurgan bir komuttur — geliştirici bir değerin çalışan kapsayıcıya nasıl teslim edileceğini belirler; soyut veri kaynaklarını (bir hedefin provides anahtarları, bileşenin kendi değerleri, bir kimlik bilgisi Feature’ının kasa yanıtı) somut teslim mekanizmalarına (env, file, arg veya Component’in bildirdiği özel bir mekanizma) eşler.
Bu ayrışma yapısaldır. Geliştiricinin Aggregate’i, veritabanının fiziksel adresini, sır deposunun kasa yolunu veya bulut sağlayıcısının ana bilgisayar adı biçimini belirtmeden “veritabanı ana bilgisayarını DB_HOST ortam değişkeni olarak enjekte et” der. Ops Recipe’si çözümlenmiş dizeyi .context.inject aracılığıyla alır ve arama zincirini yazmadan tüketir.
Önceden çözümlenmiş eşleme. İşleme sırasında derleyici her enjeksiyon kaynağını — bileşenin kendi provides değerlerine karşı öz enjeksiyon değişmezlerini ve from: başvurularını, uses[].inject aracılığıyla bileşenler arası başvuruları, FeatureRecipe’nin injectMapping yakalamalarını — .context.inject konumundaki tek bir düzleştirilmiş sözlüğe çözümler. Temel Recipe’nin valuesMapping şablonu çalıştığında her enjeksiyon anahtarı son dize değerini taşır. Recipes, çözümleme zincirinde dolaşmadan eşleme üzerinde doğrudan yineler ({{ range $k, $v := .context.inject.env }}).
Geliştiricinin, bileşenin kendi değerleri için verdiği adlar. Component spec.inject bildirdiğinde, geliştiricinin kendi inject: bloğu, bileşenin kendi değerlerinin ve provides’ının teslim borusuna hangi adlar altında ulaşacağını seçer. Derleyici, .context.self_inject konumunda Recipe’ye her girdinin şablonunun okuduğu tek kendi değeri bildirir — mekanizma başına her ad provides.<key> ile, tam olarak bir kendi değerini okuyup başka hiçbir şey okumayan bir şablon için values.<key> ile ya da boş bir dizeyle eşlenir — ve bunu bir bağlantının adlarının .context.uses.<alias>.inject konumunda aldığı biçimde yapar. Standart kütüphane kataloğunun, geliştiricinin imajını çalıştıran bir Recipe için uzlaşımı, bileşenin kendi değerleri için aksi halde seçeceği adları varsayılan olarak ele almak ve bir kendi değerini yalnızca ona eşlenen hiçbir girdi yoksa varsayılan adı altında sağlamaktır. Bu bir derleyici kuralı değil, bir katalog uzlaşımıdır: kurumsal bir katalog, bileşenlerinin kendi değerlerini dilediği şekilde sağlayabilir. Derleyici eşlemeyi geliştiricinin yazdığı metinden okur ve adlara hiçbir anlam yüklemez.
Enjeksiyon sözleşmesinin tam belirtimi — çift durumlu bağlam semantiği, anahtar çakışma kuralları, FeatureRecipe yakalama modeli ve çalışılmış örnekler — topology-triad içinde yer alır.
5. Şablon motoru (Ops DX)
Platform Ops mühendisleri çeviri şablonlarını yazar ve tescilli bir şablon dili olmadan standart altyapı şablonlamasının tüm gücüne ihtiyaç duyar. Aggrega’nın şablonları Go text/template’tir:
- “Sihirli” dizeler yok: Derleyici, geliştiricinin eşleme anahtarlarını aynen korur. Ops, standart Go eşleme dizinlemesiyle özelliklere güvenle erişir:
{{ (index .features "public-route").infra.hostname }}. - Sprig kütüphanesi: Derleyici, Helm standardı olan Sprig kütüphanesini yerel olarak kaydeder ve
| default,| quoteve| toYamlgibi işlem hatlarına anında erişim sağlar. - MappingLibrary parçaları: Birden fazla Recipes’in yeniden kullandığı bir eşleme parçası bir MappingLibrary’de bulunur ve her Recipe’ye
$import:ile alınır. Helm’in chart şablonu yardımcıları (include,tpl,required,warn) kayıtlı değildir; kayıtlı olanlar sprig-functions sayfasında listelenir.
6. Bileşim kuralları: Aggregates, alt sistemler ve Components
- Mantıksal gruplama (
subsystemsdizisi): Geliştiricilersubsystemskullanarak mantıksal meta verileri (ekip sahipliği, uyumluluk etiketleri) ve kesişen özellikleri onlarca bileşene aynı anda uygulayabilir. Alt sistemler, mantıksal/niyet düzleminde özyinelemeli klasörler gibi davranır;annotationsdeğerlerini aşağı doğru.context.annotations.aggregatekovasına basamaklı olarak aktarır ve fiziksel sınırları dayatmadan içerilen tüm bileşenlere özellik ekler. Alt sistem düzeyindeki özellikler, Domain 1’de (Geliştirici niyeti) yer aldıkları için bileşen düzeyindeki özelliklerle aynı şemayı izler (type,values,uses,injectdesteğiyle). Derleyici, grafik sonlandırma sırasında alt sistem özelliklerini içerilen her bileşenin özellik listesine düzleştirir; yürütme sırasında bunları bileşenin kendi özelliklerinden sonra ve Release tarafından eklenen tüm özelliklerden önce konumlandırır.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Bileşik Aggregates DESTEKLENİR (Modül deseni): Aggregates hem bir Release’in derlediği kök Aggregate hem de yeniden kullanılabilir modül olarak işlev görür. Üst Aggregate, alt Aggregate’i tıpkı bir bileşen gibi bildirebilir ve ona
parametersaktarabilir. Sıkı bağlılığı önlemek için alt Aggregates, kararlı bir genel arayüz adı belirleyen birexportedComponents:sözleşmesi sunar. Üst öğe modülün bileşenlerine yalnızca bu arayüz üzerinden ulaşır: biruses:hedefi modülü ve dışa aktarılan takma adlarından birini adlandırır ve derleyici kenarı takma adın gösterdiği iç bileşene bağlar; modülün içine başka herhangi bir adla uzanan bir hedef ise modülü ve dışa aktardığı takma adları belirterek derlemeyi durdurur. Bir modül de iç içe bir modülün dışa aktarılan bileşenini kendi arayüz adı altında — isteğe bağlı olarak yeniden adlandırarak — yeniden dışa aktarabilir ve derleyici bu tür bir yeniden dışa aktarma zincirini geçişli olarak alttaki iç düğüme kadar çözümler; böylece modüller, bir üst öğenin hedefin ne kadar derinde iç içe olduğunu bilmesine gerek kalmadan herhangi bir derinlikte birleşir. Hiçbir iç düğüme çözümlenmeyen bir hedef yine yüksek sesle durur ve kendi üzerine kapanan bir yeniden dışa aktarma zinciri sonsuza dek izlenmek yerine reddedilir.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components alt bileşen içeremez: Components atomik yapı taşlarıdır. Bileşim, alt sistemler ve alt aggregate’ler aracılığıyla Aggregate düzeyinde gerçekleşir. Bir uygulama birden çok fiziksel kapsayıcı gerektiriyorsa (bir API + bir sidecar gibi), bu fiziksel iç içelik Component tanımında değil, Ops Recipe şablonunun içinde yaşar.
-
Component başına tek bir tutarlı hizmet — tek iş yükü sınırı: Bir Component tek bir tutarlı hizmeti modeller — tek bir açığa çıkan hizmeti ya da bir hizmetin iş yük(ler)ini, yalnızca dahili yardımcı iş yükleriyle birlikte.
component.aggrega.ai/typeetiketi o tek hizmetin operasyonel biçimini adlandırır. Tek bir Component içindeki birden çok fiziksel iş yükü, bağımsız olarak kullanılabilir parçası olmayan tek bir tutarlı ürün oluşturduklarında sorun değildir: chart’ı bir denetleyici artı bir webhook artı bir enjektör çalıştıran bir hizmet yine tek bir Component’tir. Ölçüt çoklu iş yükü değil, bağımsız kullanılabilirliktir.Sınır, bir paketin başka bir bileşenin tek başına anlamlı biçimde kullanabileceği (
use) bir şey içerdiği yerde çizilir — özellikle Aggrega’nın zaten kendi Component’i olarak modellediği bir veritabanı, bir önbellek veya bir mesaj aracısı gibi yabancı altyapı. Böyle bir paket tek bir Component değildir; her hizmetin kendi türü, kendi kenarları ve kendi politika ve ölçekleme yüzeyi olan adreslenebilir bir düğüm olması için hizmet başına bir Component birleştiren bir alt aggregate modülüdür — yukarıda gösterilenspec.aggregates+exportedComponentsdeseni.Net bir kural olarak ifade edilen sezgisel yöntem: Chart, başka bir bileşenin tek başına anlamlı biçimde kullanabileceği ya da Aggrega’nın zaten bir Component’i olduğu bir şey içeriyor mu? Evet ise onu bir yığın olarak modelleyin — hizmet başına Components birleştiren bir alt aggregate modülü. Yalnızca bu tek hizmete hizmet ediyorsa onu tek bir Component olarak modelleyin.
Çok hizmetli bir ürünün tamamını tek bir opak Component olarak sarmak belgelenmiş bir anti-desendir. Derleyici kendi görüşü olmayan bir derleyicidir ve bunu kabul eder — şema doğrulamasından geçen her şeyi işler — ancak standart kütüphane bunun yerine hizmet başına Components’ı bir modülde birleştirir; çünkü yekpare bir sarmalama, bağımsız olarak modellenebilen hizmetleri topolojiden, seçiciden ve hizmet başına politika ve ölçeklemeden gizler. Bu ayrıntı düzeyi disiplini bir toplumsal sözleşmedir — bkz.
../language-reference/vocabulary/social-contracts.md(Component ayrıntı düzeyi).
7. Varsayılan kapsam — gruplamanın kademeli açılması
subsystems (Aggregate’te) ve boundaries (Release’te) gruplama yapılarıdır, ancak bir geliştiricinin bunları baştan bildirmesi gerekmez. Her varlık iki yazım biçimi sunar ve bunlar birbirini dışlar: bileşenler adlandırılmış kapsamlar altında gruplanarak yazılır ya da bileşenler doğrudan en üst düzeyde yazılır — ikisi asla aynı anda olmaz. Hem en üst düzey components hem de adlandırılmış kapsamlar bildiren bir belge, yükleme sırasında bir zarf hatasıyla durur.
Düz biçim (en üst düzey components) için derleyici yükleme sırasında gerçek bir default kapsamı sentezler ve en üst düzey bileşenleri bunun içine katar; böylece sonraki her geçiş tek tip, kapsam taşıyan bir yapı görür. Sentezlenen kapsam gizli bir kapsayıcı değildir: IR’de kökeni işaretlenmiş gerçek bir düğümdür ve bir geliştiricinin açıkça default olarak adlandırdığı bir kapsamdan ayırt edilebilir. Yalnızca yazarın yolları okuduğu yerlerde gizlenir — tanılama ve adresleme, geliştiricinin gerçekte yazdığı kök biçimli .spec.components[…] yolunu gösterir.
- Düz Aggregate (en üst düzey bileşenler): Bileşenler
subsystemsolmadanspec.componentsaltında yazılır. Derleyici bunları yükleme sırasında sentezlenmiş birdefaultalt sistemine katar. Alt sistem kapsamı ek açıklamaları ve alt sistem düzeyindeki özellikler yalnızca bildirilmiş alt sistemlere uygulanır; düz biçim hiçbirini taşımaz. - Düz Release (en üst düzey bileşenler): Bileşenler
boundariesolmadanspec.componentsaltında yazılır. Derleyici bunları çıktısı düz olan sentezlenmiş birdefaultsınırına katar — yapıtlar sınır adı segmenti olmadan doğrudandist/altına düşer (sağlayıcı başına:dist/compose/,dist/helm/, …). Bu en basit durumdur: sınırları adlandırmadan düz bir Compose veya tek kümeli hedef üzerindeaggrega build. (Bir geliştiricinin bildirdiği vedefaultolarak adlandırdığı bir sınır sıradan bir adlandırılmış sınırdır ve kendine ait birdirectory:olmadığında diğerleri gibidist/boundaries/default/altına çıktı üretir.) - Yükseltme yolu: Düz bir mimari gruplama gerektiren bir mimariye dönüştüğünde (farklı ad alanları, ayrı mantıksal gruplamalar, çok sınırlı dağıtım), geliştirici en üst düzey bileşenleri açık
subsystemsiçine taşır ya da Ops açıkboundariesekler. İki biçim birbirini dışladığı için bu, düz biçimden kapsamlı biçime bir geçiştir — ikisinin karışımı değil — ve düğüm kimliği geçiş boyunca korunur.
Gerekçe kademeli açılmadır: önemsiz kullanım durumları (tek hizmetli bir demo, hızlı bir yerel prototip) için zorunlu gruplama istemek gereksiz sürtünme yaratır. “10 dakikada sıfırdan çalışır hâle” katılım testi, bir geliştiricinin bir bileşen, bir Manifest ve bir Release içeren minimal bir Aggregate yazabilmesini ve önce alt sistemleri ya da sınırları anlamak zorunda kalmadan çalışan bir çıktı alabilmesini gerektirir. Varsayılan kapsam giriş rampasıdır; bildirilen kapsamlar ise bir mimarinin büyüdükçe vardığı yerdir.
8. Mimari kısıtlamalar ve önerilen kalıplar
Aşağıdaki girdiler bir önerilen desen ve beş kısıttır. Şemalar Kısıt 4 ve 5’i zorlar — Release’in values bloğu yoktur ve bir Aggregate’in bileşen örneğinin labels anahtarı yoktur; diğerleri derleyicinin denetlemediği uzlaşımlardır.
-
Önerilen kalıp: şablon dizeleri aracılığıyla parametre yükseltme
- Örnek: Geliştirici,
valuesbloğunaworkers: {{ .parameters.env_workers }}yazar ve değer bildirildiği tamsayı olarak gelsin diye tırnak içine almaz. - Neden: Aggregate
env_workersdeğerini türü belirtilmiş bir parametre (type: integer) olarak bildirirse, derleyici önce Release’in sağladığı değeri sözleşmeye göre doğrular. Parametre sözleşmesi doğrulaması enterpolasyondan önce gerçekleşir; enterpolasyon da çevreleyenvalues:şema doğrulamasından önce gerçekleşir. Bu, Aggregate’in yeniden kullanılabilirliğini korur: Ops tamsayıyıRelease’inparameters:alanı üzerinden sağlar, derleyici bunu türü belirtilmişparameters:bildirimine göre doğrular, çözümlenen değeri belgeye yerleştirir ve Component’inschema:bildirimi ortaya çıkan tamsayıyı başarıyla doğrular.
- Örnek: Geliştirici,
-
Kısıtlama 1: Kimlik bilgileri değer değil, eklentidir
- Önerilmeyen kalıp: Geliştirici bir bileşene
values: { password: "123" }yazar. - Neden: Standart kütüphanenin uzlaşımı, bir kimlik bilgisinin
features:altında bir eklenti olarak istenmesi, bir kimlik bilgisi Featuretype’ının (feature.aggrega.ai/kind: secretetiketli olan) adlandırılması ve bir gizli bilgi deposuna yönelik sorgunun o eklentinin kendivaluesalanıyla tanımlanmasıdır. Bu bir uzlaşımdır, derleyici denetimi değildir — derleyici birvaluesyaprağının ne anlama geldiğini yorumlamaz ve satır içi bir sabit değeri olduğu gibi taşır. İyi yazılmış biçimi kullanılabilir ve türü belirli kılan, eklenti yüzeyidir.
- Önerilmeyen kalıp: Geliştirici bir bileşene
-
Kısıtlama 2: Yeteneklerden bağımsız Components
- Desteklenmeyen kalıp: Mimar, Component’in
schema:bildirimineaws_instance_type: stringyazar. - Neden: Components, uzlaşım gereği yeteneklerden bağımsızdır. Fiziksel donanım hedefleri, çekirdek bilişsel uygulama mantığının içinde değil, Ops Recipes’te veya genel
.contextek açıklamalarında yer alır.
- Desteklenmeyen kalıp: Mimar, Component’in
-
Kısıtlama 3: Meta veriler üzerinde koşullu mantık
- Desteklenmeyen kalıp: Ops, dağıtım stratejisini temelden değiştirmek için bir
Recipeiçine{{ if eq .context.labels.gpu "true" }}yazar. - Neden:
.contextkanalı, sütun başınaschema:doğrulamasını atlar. Çekirdek altyapı mantığı için doğrulanmamış etiketlere güvenmek platformu kırılgan hâle getirir..contextnesnesi meta veri etiketlemesi taşır (ör. faturalandırma, SOC2); yapısal yönlendirme şemayla doğrulanan sütunlara aittir.
- Desteklenmeyen kalıp: Ops, dağıtım stratejisini temelden değiştirmek için bir
-
Kısıtlama 4: Release, geliştirici değerlerini geçersiz kılamaz
- Desteklenmeyen kalıp: Ops,
Releaseüzerinden bir geliştiricinin bilişsel mantığını geçersiz kılmaya çalışır (ör.workers: 4değeriniworkers: 10olarak değiştirmek). - Neden:
Aggregate, geliştirici niyeti için tek doğruluk kaynağıdır. Bir değerAggregateiçinde sabit kodlanmışsa ortamlar arasında değişmez. Bir değerin ortama göre değişmesi gerekiyorsa geliştirici parametre yükseltmeyi kullanır.Releaseşeması bunuvaluesbloklarını yasaklayarak uygular ve Ops’uparameterssözleşmesini karşılamak ve fizikselinfra’yı tanımlamakla sınırlar.
- Desteklenmeyen kalıp: Ops,
-
Kısıtlama 5: Aggregate üzerinde örnek düzeyinde etiketler
- Desteklenmeyen kalıp: Geliştirici,
Aggregateiçindeki bir bileşen örneğinelabels: {}yazar. - Neden: Etiketler, platform mimarının yazdığı, katalog düzeyindeki değişmez özelliklerdir — politika motorlarının ve seçicilerin okuduğu anlamsal kimliktir. Release, bileşenleri açık, eşleme tabanlı kimlik hedeflemesiyle (
components: { "my-agent": {} }) sınırlara yönlendirir; bu da etiket yazarlığını geliştiricinin Aggregate’ine karıştırmadan bileşen başınainfrave özellik geçersiz kılmalarını iç içe yerleştirme olanağını korur.
- Desteklenmeyen kalıp: Geliştirici,
9. Güvenlik çevresi & açık çıkış trafiği korkulukları (çevre dışı hedefler)
Hiçbir uygulama boşlukta var olmaz. Derlenmiş bir Aggrega mimarisi, katı biçimde eşlenmiş bir grafiği temsil eder. Ancak modern yapay zekâ sistemleri bu derlenmiş çevrenin dışındaki varlıklarla sürekli etkileşim kurar — örneğin herkese açık SaaS LLM’ler (Anthropic, OpenAI), genel herkese açık API’ler (Stripe, Twilio) veya eski brownfield veritabanları (şirket içi Oracle).
Bu dış sistemleri güvenli biçimde entegre etmek için Aggrega, güvenlik sınırını yürütme mekaniğinden kesin olarak ayırır. Güvenlik sınırı evrensel Component kuralı ve açık çıkış trafiği korkuluğu tarafından yönetilir.
1. Evrensel Component kuralı
Bir uygulama bir varlıkla etkileşim kuruyorsa — bu ister yerel bir veritabanı, ister yönetilen bir bulut kaynağı, ister bir SaaS LLM, ister genel bir herkese açık API uç noktası olsun — o varlık Aggregate içinde ayrı bir Component olarak BİLDİRİLMELİDİR. Bu kural bir uzlaşımdır: derleyici uygulamanın yaptığı bir çağrıyı göremez, bu yüzden hiçbir şey onu denetlemez.
Harici SaaS API’lerini ve eski veritabanlarını ara temsil (IR) grafiğinde birinci sınıf düğümler olarak ele alan geliştiriciler, Zero-Trust proxy yapılandırmalarını doğrudan giden çağrıya ekleyebilme olanağı kazanır. Örneğin Stripe API’sini ayrı bir düğüm olarak modelleyen bir geliştirici, ona bir header-injector özelliği ekleyebilir ve böylece oluşturulan yapılandırmanın, çağıran ajanın ham API belirtecini kendi belleğinde tutmasını engellemesini sağlar.
2. Açık çıkış trafiği korkuluğu (altyapı uygunluğu)
Aggrega, ağ çıkış trafiğini yönetmek için sabit kodlanmış derleyici mantığına güvenmek yerine çevre güvenliğini tamamen kuruluşun bağımsız politika motorlarına ve Wasm işleme eklentilerine devreder. Bu, oluşturulan yapılandırmaların açık çıkış trafiği onaylarına kesin olarak uymasını sağlar.
- Katalog kancası (Alan 2): Bir mimar herkese açık bir SaaS bileşeni tanımladığında (ör.
core/external-service), ona değişmez bir kurumsal etiket ekler (ör.security.enterprise.com/zone: "untrusted-external"). - Politika korkuluğu (derleme zamanı): Herhangi bir yapılandırma oluşturulmadan önce OPA veya Kyverno politika motoru grafiği değerlendirir. Kuruluş basit bir kural yazar: “Bir iç düğüm
untrusted-externaletiketli bir düğüme bağlanıyorsa, o hedef düğümün kimliği ortamınparameters.approved_egressdizisinde açıkça listelenmelidir.” Bir geliştirici verileri onaylanmamış bir dış hedefe yönlendirmeye çalışırsa politika motoru derlemeyi durdurur. - Yapılandırma üretimi (işleme zamanı): Politika geçerse çıkış kuralı, operatörün eklediklerinden işlenir. Release’te çağıran bileşene eklenen
core/egress-allowlistFeature’ı,helmüzerinde o bileşenin işlediği her iş yükü için bir KubernetesNetworkPolicyişler ve çıkışa yalnızca kendi pod’larına,useskenarlarının hedeflerinin pod’larına (bu pod’ların bildirdiği portlarda), kümenin DNS’ine ve ekin, kümenin çalıştırmadığı bir hedef — örneğin herkese açık bir SaaS API’si — için listelediği adres aralıklarına izin verir. Release,infra.control_plane_present: trueile kümenin ağ eklentisinin ağ politikasını uyguladığını onaylamadıkça derleme durur; ayrıca adres aralığı listelenmemiş böyle bir harici bağlantıyı adlandırarak durur; ağ politikası olmayancomposeüzerinde ek derlemeyi durdurur. Geliştirici hiçbir zaman güvenlik duvarı kuralı yazmaz.
Bu, bildirilen topolojiyi değerlendiren bir yönetişim karar rolü aracılığıyla, açıkça bildirilen altyapının çekirdek Go derleyicisinin “harici”nin ne anlama geldiğini anlamasına gerek kalmadan çıkış trafiği politikasına uymasını garanti eder. (Not: Gerçek sıfır güven çıkış trafiği, hedef kümenin çalışma zamanında Default Deny CNI çalıştırmasına dayanır; oluşturulan yapılandırmalar yalnızca yetkilendirilmiş istisnaları eşler).
Her dış hizmet için bir Component
Her dış hizmet, çok hedefli bir diziye sıkıştırılmadan ayrı bir bileşen olarak bildirilir. Bir uygulama beş farklı üçüncü taraf API’sini çağırıyorsa geliştirici beş ayrı core/external-service bileşeni bildirir. Politika motorlarının ve Wasm eklentilerinin her giden hedefi ayrı ayrı hedefleyebilmesini sağlayan, bu hizmet başına bildirimdir — her dış bağımlılığa farklı çıkış trafiği politikaları, farklı proxy özellikleri veya farklı gözlemlenebilirlik kancaları eklenebilir.
Güvenliği yürütmeden ayırmak (“brownfield” senaryosu)
Anlamsal etiketin (ör. untrusted-external) yürütmeyi değil, ağ güvenliği politikasını belirlediğini belirtmek kritik önemdedir. Aggrega’nın kaynağı sağlayan yapıtları işleyip işlemediğinden bağımsızdır.
- Senaryo A (herkese açık SaaS API’si): Katalogda
untrusted-externalolarak etiketlenir (politikanın çıkış trafiği korkuluklarını tetikler). Bir referans iş yüküyle gerçekleştirilir (hesaplama kaynağı sağlanmaz; bkz. §10). - Senaryo B (dahili eski veritabanı):
internal-trustedolarak etiketlenir (çıkış trafiği korkuluklarını atlar, VPC içinde kalır). Bir referans iş yüküyle gerçekleştirilir (hesaplama kaynağı sağlanmaz; bkz. §10). - Senaryo C (kendi barındırılan veritabanı):
internal-trustedolarak etiketlenir. Helm işleyici eklentisi aracılığıyla yürütülür (fiziksel olarak bir Kubernetes StatefulSet’i olarak sağlanır).
10. Derlemenin sağlamadığı hizmetler: referans Workloads
Bir uygulama şirket içi eski bir veritabanıyla veya herkese açık bir SaaS API’siyle (Stripe gibi) etkileşim kurduğunda, evrensel Component kuralı bu dış varlıkların Aggregate içinde ayrı bileşenler olarak bildirilmesini gerektirir. Ancak Aggrega, bunlar için fiziksel bir Kubernetes Pod’u veya AWS RDS örneği yapıtı oluşturmaya çalışmamalıdır.
Böyle bir bileşeni gerçekleştiren Recipe, form: reference biçiminde bir Workload bildirir: bir endpoint — bir ana makine veya URL —, isteğe bağlı olarak bir port ve hiç kapsayıcı yok. Derleyici ikisini de belirlenimci işaretçi dizeleri olarak aktarır ve hiçbir zaman çözümlemez. Bir sağlayıcının referans Workload için ne işlediği sağlayıcının kendisine aittir: helm, uç noktanın ana makinesini taşıyan bir ExternalName Service üretir; böylece kümedeki iş yükleri, uç noktası bir DNS adı olan bir hizmete kararlı bir küme içi adla ulaşabilir; compose bunun için hiçbir şey işlemez. Kubernetes bir externalName’i DNS adı olarak ele aldığından, IP adresi olarak yazılmış bir uç noktaya Service üzerinden değil, tüketicinin aldığı adresten ulaşılır.
Her iki sağlayıcıda da Recipe’nin provides: değerleri, sağlanan bir bileşeninkilerle tamamen aynı şekilde .context.uses ve inject sözleşmesi üzerinden her tüketiciye ulaşır. Bu nedenle bir tüketicinin bağlantıları, hedefi sağlanandan referansa geçtiğinde değişmez: yalnızca Manifest’in hedefi eşlediği Recipe değişir.
Adım adım yürütme ardışık düzeni
1. Alan 1 (Aggregate): Geliştirici niyeti Geliştirici eski bir Oracle veritabanı ister. Nerede bulunduğu umurunda değildir; yalnızca çağıran ajanının bağlantı dizesini bir ortam değişkeni olarak almayı beklediğini belirtir. IP statik olduğundan ve önceden bilindiğinden onu parametreler aracılığıyla iletir.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Alan 4 (Manifest): Yönlendirme Ops, eski veritabanı türünü bağlantı dizesini biçimlendiren Recipe’ye eşler. Manifest bir Recipe’yi adlandırır, başka bir şey yapmaz; adlandırdığı Recipe form: reference biçiminde bir Workload bildirir ve düğümün hesaplama kaynağı sağlamasını engelleyen de bu biçimdir. Eşleme hedef ne olursa olsun tam olarak tek bir biçime sahip olduğundan yönlendirme tamamen düz ve öngörülebilir kalır.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Alan 3 (Referans Recipe): Devir teslimin yapılandırılması Ops mühendisi Recipe’yi yazar. Recipe, locals bloğunda geliştiricinin values alanından primary_endpoint bağlantı dizesini oluşturur, bunu provides altında yayımlar ve veritabanının ana makinesini gösteren bir referans Workload bildirir.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. İşleme sırasında derleyici yürütmesi (devir teslim)
- Derleyici
legacy-oracleiçin Recipe’yi değerlendirir.legacy_oracle_ip: "10.0.4.55"sağlayan bir Release içinprimary_endpointdeğerioracle://10.0.4.55:1521/PROD_DBolur. helmüzerinde referans Workload,externalName: 10.0.4.55ve1521portuyla tek bir ExternalName Service,legacy-oracle, işler;composeüzerinde hiçbir şey işlemez.- Derleyici ardından
my-agentiçin Recipe’yi işler. Onun.context.useskanalı Oracle düğümününprovidesdeğerlerini taşır ve inject sözleşmesiORACLE_DSN’i bunlara göre zaten çözümlemiştir.
5. Alan 3 (çağıran Recipe): Sözleşmenin yerine getirilmesi Python çalışanı için standart Helm tarifi, aldığı inject eşlemesini, derlemenin sağladığı bir veritabanı için yapacağı gibi aynen okur.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Şema köprüsüyle sütunlar arası aktarım: Niyetten altyapıya köprü kurmak
Özelleşmiş altyapı ayarlarını alt bileşenler aracılığıyla güvenle açığa çıkaran schema-bridge kalıbı için inheritance-and-interface sayfasına bakın — Component’in schema: alanında bildirilen, geliştiriciye dönük bir values: alanı; Recipe’nin valuesMapping: şablonu bunu infra: biçimli işlenmiş çıktıya aktarır.
12. Greenfield sağlama (“platform Aggregates”)
Platform mühendisliğinde tekrarlayan bir tuzak, yönlendiriciyi (Release dosyasını) ağır Day-0 küme sağlama işlerini üstlenmeye zorlamaktır (ör. uygulamayı dağıtmadan önce yeni bir AWS EKS kümesi ayağa kaldırmak). Bu, uzun ve okunması zor yönlendirme dosyalarına yol açar.
Aggrega bunu “sonsuza dek kaplumbağalar” ilkesiyle ele alır. Release şeması altyapı kurmak için hiçbir blok taşımaz; küme sağlama platform Aggregates ile modellenir.
Bir AWS EKS kümesi, bir Istio kontrol düzlemi ve bir AWS VPC nihayetinde yalnızca fiziksel bulut kaynakları olduğundan, tam olarak uygulama bileşenleri gibi modellenir.
- Platform Aggregate’i: Altyapı ekibi, bileşenleri
core/aws-vpc,core/eks-clustervecore/istio-baseolan standart birAggregate.yamlyazar. - Platform Release’i: Ekip bu aggregate’i dağıtır. Bu platform bileşenlerine bağlanan işleyici, temel altyapıyı ayağa kaldırmak için gereken yapıtları üretir.
- Uygulama Release’i: Uygulama geliştiricisi yapay zekâ ajanını dağıtmaya hazır olduğunda Ops ekibi yeni oluşturulan kümeyi uygulamanın kendi
Releasedosyasındaki bir sınırla hedefler.