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

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ından parameters: altında satır içi olarak veya harici bir parametre dosyasını gösteren parameters: { $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: 2 değerini workers: 10 olarak 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çi parameters: eşlemesinin yerine koyar. Çok dosyalı katmanlama, Release’in extends: zincirleriyle ifade edilir.
  • values (Bilişsel niyet - Geliştiriciye ait)
    • Kapsam: Aggregate içinde components ve bunların features eklerinde, 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.
  • uses (Yapısal topoloji - Bildirimsel durum)
    • Kapsam: Aggregate içinde components ve bunların features eklerinde, 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 usesSchema bildirimi tarafından doğrulanır.
  • infra (Fiziksel gerçeklik - Ops’a ait)
    • Kapsam: Release içinde bir sınırın components öğelerinde ve bunların features eklerinde 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ın features ekleri bir infra alanı içermez ve additionalProperties: false ile birlikte şema doğrulamasında infra’yı reddeder. Kataloğun birleşik schema: bildirimi tarafından doğrulanır.
  • inject (Teslim sözleşmesi - Buyurgan komut)
    • Kapsam: Bir bileşen örneğinde, uses iç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, arg veya ö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 ve from: ya da value: öğelerinden tam olarak birini taşır.
  • .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.uses gibi) taşır ve doğrudan Ops şablon motoruna aktarılır.

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ıştaki values: ş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’in infra bloğu ve sınır katmanları üzerinden akar; böylece geliştiricinin Aggregate’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.
  • Akış 2: Bilişsel uygulama niyeti (Components içindeki values): İçsel uygulama mantığını tanımlar. Component’in schema: 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ştirici values değ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 fiziksel infra boyutlandı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çin infra boyutlandı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 infra yayı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ı yerel infra alanları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şenin values yü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 bir port alanı 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ın schema: 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 versa

Derleyici 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, | quote ve | toYaml gibi 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 (subsystems dizisi): Geliştiriciler subsystems kullanarak 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; annotations değerlerini aşağı doğru .context.annotations.aggregate kovası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, inject desteğ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.
aggregate.yaml
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 parameters aktarabilir. Sıkı bağlılığı önlemek için alt Aggregates, kararlı bir genel arayüz adı belirleyen bir exportedComponents: sözleşmesi sunar. Üst öğe modülün bileşenlerine yalnızca bu arayüz üzerinden ulaşır: bir uses: 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.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type etiketi 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österilen spec.aggregates + exportedComponents deseni.

    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 subsystems olmadan spec.components altında yazılır. Derleyici bunları yükleme sırasında sentezlenmiş bir default alt 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 boundaries olmadan spec.components altında yazılır. Derleyici bunları çıktısı düz olan sentezlenmiş bir default sınırına katar — yapıtlar sınır adı segmenti olmadan doğrudan dist/ 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 üzerinde aggrega build. (Bir geliştiricinin bildirdiği ve default olarak adlandırdığı bir sınır sıradan bir adlandırılmış sınırdır ve kendine ait bir directory: olmadığında diğerleri gibi dist/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 subsystems içine taşır ya da Ops açık boundaries ekler. İ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.

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, values bloğuna workers: {{ .parameters.env_workers }} yazar ve değer bildirildiği tamsayı olarak gelsin diye tırnak içine almaz.
    • Neden: Aggregate env_workers değ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 çevreleyen values: şema doğrulamasından önce gerçekleşir. Bu, Aggregate’in yeniden kullanılabilirliğini korur: Ops tamsayıyı Release’in parameters: alanı üzerinden sağlar, derleyici bunu türü belirtilmiş parameters: bildirimine göre doğrular, çözümlenen değeri belgeye yerleştirir ve Component’in schema: bildirimi ortaya çıkan tamsayıyı başarıyla doğrular.
  • 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 Feature type’ının (feature.aggrega.ai/kind: secret etiketli olan) adlandırılması ve bir gizli bilgi deposuna yönelik sorgunun o eklentinin kendi values alanıyla tanımlanmasıdır. Bu bir uzlaşımdır, derleyici denetimi değildir — derleyici bir values yaprağı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.
  • Kısıtlama 2: Yeteneklerden bağımsız Components

    • Desteklenmeyen kalıp: Mimar, Component’in schema: bildirimine aws_instance_type: string yazar.
    • 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 .context ek açıklamalarında yer alır.
  • 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 Recipe içine {{ if eq .context.labels.gpu "true" }} yazar.
    • Neden: .context kanalı, sütun başına schema: doğrulamasını atlar. Çekirdek altyapı mantığı için doğrulanmamış etiketlere güvenmek platformu kırılgan hâle getirir. .context nesnesi meta veri etiketlemesi taşır (ör. faturalandırma, SOC2); yapısal yönlendirme şemayla doğrulanan sütunlara aittir.
  • 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: 4 değerini workers: 10 olarak değiştirmek).
    • Neden: Aggregate, geliştirici niyeti için tek doğruluk kaynağıdır. Bir değer Aggregate iç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ı bunu values bloklarını yasaklayarak uygular ve Ops’u parameters sözleşmesini karşılamak ve fiziksel infra’yı tanımlamakla sınırlar.
  • Kısıtlama 5: Aggregate üzerinde örnek düzeyinde etiketler

    • Desteklenmeyen kalıp: Geliştirici, Aggregate içindeki bir bileşen örneğine labels: {} 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şına infra ve özellik geçersiz kılmalarını iç içe yerleştirme olanağını korur.

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-external etiketli bir düğüme bağlanıyorsa, o hedef düğümün kimliği ortamın parameters.approved_egress dizisinde 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-allowlist Feature’ı, helm üzerinde o bileşenin işlediği her iş yükü için bir Kubernetes NetworkPolicy işler ve çıkışa yalnızca kendi pod’larına, uses kenarları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: true ile 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ı olmayan compose ü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-external olarak 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-trusted olarak 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-trusted olarak 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. İşleme sırasında derleyici yürütmesi (devir teslim)

  1. Derleyici legacy-oracle için Recipe’yi değerlendirir. legacy_oracle_ip: "10.0.4.55" sağlayan bir Release için primary_endpoint değeri oracle://10.0.4.55:1521/PROD_DB olur.
  2. helm üzerinde referans Workload, externalName: 10.0.4.55 ve 1521 portuyla tek bir ExternalName Service, legacy-oracle, işler; compose üzerinde hiçbir şey işlemez.
  3. Derleyici ardından my-agent için Recipe’yi işler. Onun .context.uses kanalı Oracle düğümünün provides değerlerini taşır ve inject sözleşmesi ORACLE_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.

  1. Platform Aggregate’i: Altyapı ekibi, bileşenleri core/aws-vpc, core/eks-cluster ve core/istio-base olan standart bir Aggregate.yaml yazar.
  2. 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.
  3. 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 Release dosyasındaki bir sınırla hedefler.