Aggregate
Aggregate varlığının kavramsal rolü (Alan 1 — geliştiricinin bildirimsel topoloji planı) architecture/04-entity-taxonomy.md sayfasında anlatılır. Bileşim kalıpları (alt sistemler, iç içe aggregate’ler, Zero-Port Convention, Parameter Hoisting) architecture/06-data-taxonomy-and-composition.md sayfasında anlatılır. Bu sayfa, Aggregate kataloğu yazım yüzeyini, özellikle katalog dağıtımı için yeniden kullanılabilir Aggregate modüllerinin yazılmasını ele alır.
Component kapsamı: varsayılan alt sistem
Bir Aggregate, bileşenleri alt sistemler halinde düzenler: kesişen kaygılar için (bir veri katmanı, bir uç katmanı) kendi açıklama (annotation) kademelenmesini taşıyan adlandırılmış gruplamalar. Çoğu Aggregates tek bir gruplamaya sahiptir, bu nedenle bu gruplama herhangi bir tören gerektirmez.
Tek kapsam (varsayılan). Bileşenleri doğrudan spec.components: altında yazın ve subsystems: bloğunu atlayın:
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0Derleyici bunları sentezlenmiş bir default alt sistemine katlar. Düğüm kimliği değişmez — api, api olarak kalır, asla default.api olmaz — bu nedenle bu şekilde yazılmış bir Aggregate, açık tek alt sistemli biçimle birbirinin yerine kullanılabilir ve ona yapılan adreslemeler (uses: hedeflerinde, tanılamalarda) yalın spec.components.<name> yolunu kullanır. Sentezlenmiş kapsam, dışa aktarılan IR’de dürüstçe kaydedilir (sentezlenmiş alt sistem işaretçisi taşıyarak), ancak bir yazarın yazdığı veya okuduğu yollarda asla görünmez.
Birden çok kapsam. Bileşenler birbirinden ayrı kesişen gruplara ayrıldığında, subsystems: altında adlandırılmış alt sistemler bildirin. Her alt sistem kendi bileşenlerini ve açıklama kademelenmesini taşır ve başka alt sistemleri iç içe barındırabilir.
Karşılıklı dışlayıcılık. spec.components: ve spec.subsystems:, Aggregate kökünde karşılıklı olarak birbirini dışlar — birini ya da diğerini yazın, asla ikisini birden değil. Her ikisini de bildiren bir belge, yükleme sırasında bir zarf hatasıyla durur. (Bir geliştiricinin açıkça default olarak adlandırdığı bir alt sistem, sıradan bir bildirilmiş alt sistemdir ve nitelikli spec.subsystems.default.components.<name> yolunda adreslenir — sentezlenmiş kapsamın yoksayılması ada değil, kökene dayanır.)
Yeniden kullanılabilir Aggregate modülleri
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ün adı, bir nokta ve modülün dışa aktardığı takma adlardan biridir; derleyici kenarı, takma adın adlandırdığı iç bileşene bağlar. Bir modülün içine başka herhangi bir adla — bileşenin modül içindeki adıyla ya da içinde iç içe bulunan bir modüle giden bir yolla — uzanan bir hedef, modülü ve modülün dışa aktardığı takma adları adlandırarak derlemeyi durdurur; bkz. A uses target names a module’s component the module does not export (Hedef, modülün dışa aktarmadığı bir modül bileşenini adlandırıyor).
Neden açık bir exportedComponents: listesi. Bir modülün yazarları, bileşenlerinden hangilerinin genel arayüzü oluşturacağına ve hangilerinin uygulama ayrıntısı olarak kalacağına karar verir. Üst öğe yalnızca listenin yayımladığını adlandırabildiğinden, yayımlanan her ad hâlâ bir bileşeni gösterdiği sürece modülün iç yapısı hiçbir üst öğeyi bozmadan yeniden düzenlenebilir — bir bileşen yeniden adlandırılabilir, bir bileşen ikiye bölünebilir, bir worker yönetilen bir hizmetle değiştirilebilir. Listenin maliyeti yayımlanan her bileşen için bir girdidir ve içe aktaranların kullanması gereken ad bileşenin kendi adıysa bileşen bu adla yayımlanabilir (store: store). Aynı kural bir bileşimin içinde de geçerlidir: bir modül, içe aktardığı bir modüle o modülün dışa aktarılmış takma adları üzerinden ulaşır. Bir Release, bir modülün iki bileşenini birbirine bağlayabilir, çünkü bu bağlantı hiçbir modülün arayüzünü geçmez.
İç içe bir modülün arayüzünü yeniden dışa aktarmak. Bir exportedComponents: girdisi, doğrudan bildirilmiş bir bileşen yerine iç içe bir alt aggregate’in dışa aktarılmış takma adını gösterebilir — bu, bir modülün içe aktardığı bir modülün bir kısmını kendi arayüz adı altında ve isteğe bağlı olarak yeni bir adla yeniden yayımlamasıdır. Böyle yeniden dışa aktarılmış bir takma adı hedefleyen bir uses: kenarı, zincir boyunca geçişli olarak somut iç düğüme çözümlenir; böylece bir modül daha derin modülleri, onların iç düzenini açığa çıkarmadan kendi genel arayüzünde birleştirir ve bir tüketicinin hedefin ne kadar derinde iç içe olduğunu bilmesi hiçbir zaman gerekmez. Kararlı arayüz disiplini her adımda geçerlidir: her modül yalnızca yayımlamayı seçtiğini yeniden dışa aktarır. Hiçbir iç düğüme çözümlenmeyen yeniden dışa aktarılmış bir hedef, doğrudan sarkan bir hedefle aynı şekilde açıkça durdurulur; kendi üzerine kapanan bir yeniden dışa aktarım zinciri ise sonsuza dek izlenmek yerine reddedilir.
Bir modülün bildirimleri, Aggregate’inkiler gibi denetlenir. Bir modülün belgesi yalnızca onu içe aktaran bileşim derlendiğinde okunur ve bildirimleri o noktadan itibaren, her iç içe geçme derinliğinde denetlenir. Bir modül bileşeninin kendi inject: bloğu, türünün spec.inject izin listesine ve bir teslim anahtarını iki kez talep etmeyi ve türün yayımlamadığı bir anahtarı okumayı yasaklayan kurallara tabidir. Modülün kendi alt sistemlerinden birinde yazılan bir ekleme yalnızca Feature’ının bildirdiği bir soketi adlandırabilir; Release’in bir modülün katkıda bulunduğu bir bileşene karşı yazdığı bir ekleme de öyle.
Bir modülün alt sistem eklemeleri bileşenlerine ulaşır. Bir modülün kendi alt sistemlerinden birinde eklediği bir Feature, Aggregate’teki bir alt sistem eklemesiyle tam olarak aynı şekilde, modülün o alt sistemin altında bildirdiği her bileşene, iç içe alt sistemler dahil, kademeli olarak uygulanır — ve yalnızca bu bileşenlere; içe aktaran bir Aggregate’in aynı adlı bir alt sistemin altındaki bileşenine asla uygulanmaz. Bileşenin kendi eklemelerinin hemen ardından, dış alt sistemler iç olanlardan önce olmak üzere değerlendirilir. Her ikisinin de yazdığı bir alanda bileşenin aynı adlı kendi eklemesi kazanır ve onun dışarıda bıraktığı alanlar alt sistemin değerlerini korur. Ulaştığı her bileşen onu Feature’ın appliesTo koşuluna göre denetler. Bir modülün kendi bildirimleriyle ilgili bir bulgu, modülü ve belgesindeki anahtarı — örneğin .spec.subsystems.<subsystem>.features.<attachment> — adlandırır; böylece düzenleme, onu içe aktaran Aggregate’te değil, bildirimin bulunduğu modülde yapılır.
Katalog konumu
Yeniden kullanılabilir bir Aggregate modülü, aggregate/ tür dizini altında, metadata.name değerinin segment segment belirttiği yolda, yaprakta bir sürüm diziniyle bulunur:
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definitionBir modül adı, satıcıyı veya yazarı adlandıran baştaki bir {publisher} segmentini taşıyabilir — standart kütüphane için core, bir kuruluş için acme — ve yayımlanan standart kütüphane modülleri bu şekilde adlandırılır: core/agenta, aggregate/core/agenta/1.0.0/aggregate.yaml konumundadır. Tek bir belirteçten oluşan bir ad bir düzey daha sığ, aggregate/{module-name}/{version}/aggregate.yaml konumunda bulunur. Her iki biçim de geçerlidir; ad, yazarın yazdığıdır ve dizin onu yansıtır. Bu yansıtma, derleyicinin denetlediği bir şey değil, bir katalog uzlaşımıdır — bir modül, dosyasının bulunduğu yere göre değil, bildirdiği ada göre bulunur.
OCI URI: hub.aggrega.ai/aggregate/{module-name}:{version}, küçük harfe çevrilmiş olarak — böylece core/agenta adlı bir modül hub.aggrega.ai/aggregate/core/agenta:1.0.0 adresine, db-module adlı bir modül ise hub.aggrega.ai/aggregate/db-module:1.0.0 adresine yayımlanır.
Modül deseni
Alt modül (aggregate/child-database-module/1.0.0/aggregate.yaml, hub.aggrega.ai/aggregate/child-database-module:1.0.0 olarak yayımlanır):
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"Üst Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_dbModül etiketleri
Bir Aggregate kataloğa yeniden kullanılabilir bir modül olarak yayımlandığında, YAML zarfında metadata.labels taşıyabilir — örneğin aggregate.aggrega.ai/tier: infrastructure veya aggregate.aggrega.ai/compliance: pci-dss. Bu etiketler modülün kimliğini tanımlar ve yayımlanan modül belgesinde taşınır; henüz hiçbir komut bunları okumaz. Katalog araması Aggregates’i dizinlemez ve derleme grafiği ne bir modülün etiketlerini ne de katalog adını taşır; bu nedenle bir yönetişim politikası bir modülün bileşenlerini geldikleri modüle göre seçemez.
Kritik ayrım. Aggregate etiketleri, katalogdaki yeniden kullanılabilir modülün kimliğini tanımlar. Alt bileşen düğümlerine kademeli olarak aktarılmaz. Bileşen etiketleri yalnızca Domain 2’deki Component katalog varlığından gelir. Bir geliştirici aggregate.aggrega.ai/tier: infrastructure etiketli bir modülü içe aktarırsa, o modülün içindeki bileşenler yalnızca kendi katalogda tanımlı etiketlerini korur (ör. component.aggrega.ai/type: stateful-server). Aggregate etiketi hiçbir zaman IR düğümünün labels sözlüğüne eklenmez.
Bileşik Aggregates / modül deseni tartışmasının tamamı (Components için alt bileşen yasağı kuralı dahil) ve subsystems kesişen gruplama mekanizması için architecture/06-data-taxonomy-and-composition.md §6 bölümüne bakın. Tipli parameters sözleşmesinin yazım yüzeyi için vocabulary/data-pillars sayfasına bakın.
Tipli parametre sözleşmeleri
Aggregate’in spec.parameters: bloğu, Release’in karşıladığı parametreler için tipli sözleşmeyi bildirir. Her parametre yuvası bildirilmiş bir type, isteğe bağlı bir description, isteğe bağlı bir default, isteğe bağlı değer uzayı kısıtlamaları ve (nesne tipli yuvalar için) iç içe yapı taşır. Derleyici, Release tarafından sağlanan her değeri çözümleme sırasında, parametre enterpolasyonu çalışmadan önce sözleşmeye karşı doğrular.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}Her başvurudaki tırnaklama kasıtlıdır: yukarı taşınan değerin hangi tiple geleceğini belirleyen odur. Bkz. templates/parameters-context.md.
Parametre yuvası sözcük dağarcığı
Tipli parameters: bloğu kompakt biçim sözcük dağarcığını kabul eder: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate ve validateMessage (özel bir denetim ve onun bildirdiği ileti), items (diziler için), properties (nesneler için), valuesType (tipli değer eşlemeleri için) ve required: true (yuva başına işaretçi). Bu anahtar sözcüklerden üçü değer olarak düz bir ayar yerine bir sözleşme alır — items, valuesType ve properties altındaki her girdi — ve bir parametre yuvasında bu iç içe sözleşme, çevresindeki yuvayla aynı tipli biçimde yazılır: valuesType: boolean değil, valuesType: { type: boolean }. Enterpolasyondan önce derleyici, birleştirilmiş parametre eşlemesini doğrudan bu bildirimlere karşı denetler: hiçbir yuvanın bildirmediği bir parametre reddedilir, required: true ile işaretlenmiş ve ne Release’in doldurduğu ne de bir default’un sağladığı bir yuva derlemeyi durdurur ve sağlanan her değer, yuvasının bildirilmiş type’ına, enum üyeliğine, bir dize yuvasında minLength ve maxLength sınırlarına, pattern düzenli ifadesine ve format’ına, ayrıca min ve max sınırlarına — sayısal bir yuvanın değerine, bir dize yuvasının uzunluğuna ve bir dizi yuvasının öğe sayısına — karşı denetlenir. Nesne ve dizi yuvaları özyinelemelidir: properties altındaki her girdi ve items’a karşı her öğe aynı şekilde denetlenir, bir valuesType sözleşmesi properties’in adlandırmadığı anahtarları yönetir ve hiçbir bildirimin adlandırmadığı iç içe bir anahtar reddedilir. Bir schema: sütununun bu anahtar sözcükleri farklı yazdığı yerler dahil olmak üzere tam anahtar sözcük dağarcığı için bkz. vocabulary/compact-form-authoring.md.
Aşağıdaki anahtar sözcükler, herhangi bir Release değeri okunmadan önce bildirimin kendisinde de denetlenir; böylece hiçbir şeyi kısıtlayamayacak bir yuva, hiçbir Release onu sağlamasa bile derlemeyi durdurur:
- Uzunluk sınırları sıfır veya daha fazladır. Bir parametrenin kendi bildirimindeki negatif bir
minLengthveyamaxLength, Aggregate yüklendiğinde Aggregate’in şeması tarafından parametre ve anahtar adlandırılarak reddedilir. İç içe bir sözleşmede —items,propertiesveyavaluesTypealtında — bir uzunluk sınırı yazıldığı gibi okunur ve Aggregate yüklendiğinde bu alt sınıra tabi tutulmaz; bu yüzden orada da sıfır veya daha fazla olarak yazın: negatif birminLengthhiçbir şey dayatmaz, negatif birmaxLengthise her değeri reddeder. minvemaxbir şeyi sınırlamalıdır. Boolean veya nesne yuvasında bu çift hiçbir şeyi sınırlamaz; bu nedenle orada yazılmış birminveyamax, Aggregate yüklendiğinde parametre ve anahtar adlandırılarak reddedilir.- Bir desen derlenebilmelidir. Her
pattern, parametre sözleşmesi okunduğunda — yuvanın kendisinde ve herhangi bir derinlikteki her iç içe sözleşmede — düzenli ifade olarak derlenir ve derlenemeyen bir desen parametre, desen ve neden adlandırılarak reddedilir. Sözleşme, Aggregate’e ulaşan her derleme, çekme ve Release doğrulamasında okunur; bu Aggregate ister Release’in kendi Aggregate’i ister o Aggregate’in içe aktardığı bir modül olsun. Değer denetimi ardından sağlanan her değeri aynı derlenmiş ifadeyle eşleştirir. - Bir biçim, derleyicinin denetlediği biçimlerden biri olmalıdır.
format, JSON Schema’nın yazdığı şekilde yazılmışemail,uri,hostname,ipv4,ipv6,uuid,date-timevedateadlarından birini belirtir. Başka herhangi bir ad —emialgibi bir yazım hatası ya dapasswordgibi JSON Schema’nın tanımlamadığı bir ad — Aggregate yüklendiğinde parametre adlandırılıp desteklenen adlar listelenerek reddedilir: yuvanın kendisinde Aggregate’in şeması tarafından, herhangi bir derinlikteki iç içe bir sözleşmede ise parametre sözleşmesi okunduğunda. Adlandırılan biçime sahip olmayan sağlanmış bir dize ardından parametre, değer ve biçim adlandırılarak reddedilir. Her adın neyi denetlediğivocabulary/compact-form-authoring.mdiçinde yer alır.
Nesne tipli ve dizi tipli parametreler
Parametre yuvaları, iç içe nesneler ve tipli öğe dizileri dahil olmak üzere kompakt biçimin desteklediği her tipi kabul eder:
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Release, nesne tipli parametreleri yapılandırılmış YAML ile karşılar; derleyici yapıyı enterpolasyondan önce bildirilmiş şemaya karşı doğrular. Nesnenin alanlarına başvuran şablonlar standart Go şablon sözdizimini kullanır: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} vb.
Parametre sözleşmesi doğrulaması
Önce sözleşmenin kendisi, okunduğu anda denetlenir: yukarıdaki “Parametre yuvası sözcük dağarcığı” altında anlatılan uzunluk sınırı ve desen denetimleri. Derleyici ardından parametre işleme sırasında üç alt adım çalıştırır:
- Varsayılan doldurma —
default:tanımlı olan ve Release tarafından değer sağlanmamış yuvalar varsayılan değerlerini alır. İç içe nesne parametreleri, atlanmış, açıkça boş bırakılmış ve kısmen yazılmış üst yuvalar için üç durumlu bir yazım anlamı taşır: üst yuvayı atlamak alt öğelerin varsayılanlarını doldurur, üst yuvayı{}olarak yazmak açık boşluğu korur (alt öğelerin varsayılanlarını bastırır), üst yuvayı boş olmayan bir eşleme olarak yazmak ise yalnızca Release’in sağlamadığı alt öğeleri doldurur. YAML örnekleri ve “her biçim ne zaman kullanılır” karar kılavuzu içintemplates/parameters-context.mdsayfasına bakın. - Sözleşme doğrulaması — birleştirilmiş eşlemedeki her değer, ister Release sağlamış ister bir
default:doldurmuş olsun, bildirilentype/enum/min/max/pattern/ iç içe yapı kısıtlarına göre doğrulanır. Doğrulama hataları, sorunlu yuvayı, sağlanan değeri ve ihlal edilen kısıtı adlandıran açık bir hatayla derlemeyi durdurur.default:değeri olmayan eksik zorunlu parametreler de yuva adıyla benzer bir durdurmaya yol açar. - İnterpolasyon — derleyici, Aggregate’in tüm metnini YAML olarak okumadan önce bir şablon olarak değerlendirir ve her
{{ .parameters.<slot> }}başvurusunu — genellikle component / feature / alt aggregatevalues:dizelerinin içinde — çözümlenmiş değerle değiştirir; metindeki diğer her{{de şablon sözdizimi olarak okunur, bu nedenle kendi çift süslü parantezlerini taşıyan bir değer — örneğin bir akış platformunun dışa aktarılmış tanımı — her{{ifadesini, Kendi çift süslü parantezlerini taşıyan metin bölümünün anlattığı gibi{{"{{"}}olarak yazar. Bu geçişten sonra değer şablonu yüzeyleri önceden interpolasyonu yapılmış sabit değerleri tüketir ve şablon bağlamlarında.parametersalmaz.
Birleştirilmiş parametre eşlemesi, yol şablonu değerlendirmesini desteklemek için işleme boyunca canlı kalır. Release sınırlarındaki, operatör tarafından yazılmış directory: ve subDirectory: şablonları, işleme zamanında kapalı bir izin listesine göre .parameters.<slot> değerini doğrudan okur; yol üretimi, ortam başına artefakt düzeni için bölge / ortam sözcük dağarcığına ihtiyaç duyar ve bu asimetrik yetki, söz konusu operatör kaygısını Aggregate’in values alanı üzerinden gidip gelmeden operatör yüzeyi içinde tutar. Eşleme, her işleme aşaması tamamlanana kadar okunabilir kalır ve yalnızca çözümlendiği derlemeden erişilebilir; geliştirici tarafından yazılmış values: alanlarını tüketen recipe’ler interpolasyon sonrası dizeleri görürken, yol şablonları işleme boyunca canlı .parameters verisini görür. Yol şablonu kullanılabilirlik matrisi için templates/expansion-matrix.md 3. satıra, yol şablonu değişken izin listesi için path-template-variables.md sayfasına bakın.
Daha kapsamlı parametre yukarı taşıma kontrol listesi (Aggregate bildirimi → values başvurusu → Release karşılaması → Recipe tüketimi) ve sütunlar arası mekanikler için vocabulary/data-pillars.md §“Parameters” ve §“The parameter-hoisting checklist” bölümlerine bakın. İnterpolasyon sırasında sunulan şablon bağlamı alanları ve yol şablonu istisnası için templates/parameters-context.md sayfasına bakın.
Bir uses kenarı, Aggregate’in bildirdiği bir çağrıdır
Bir uses kenarı, Aggregate’in bir bileşenin başka bir bileşeni çağırdığına dair ifadesidir. Derleyici, hedefin yayımladığı değerleri çağırana aktarır ve hiçbir şeyi kısıtlamaz: tek başına bir kenar ne çağıranı kabul eder ne de başka birini reddeder; kenarı olmadan hedefin adresine ulaşan bir iş yükü de hedefe yine aynı şekilde ulaşır.
Bir bileşeni kimin çağırabileceğini ve onun neyi çağırabileceğini kısıtlamak, operatörün Release’te ortam başına verdiği bir karardır. Bir Release, standart kütüphane kataloğunun core/caller-allowlist Feature’ını bir bileşene eklediğinde, derleme tam olarak uses kenarları o bileşeni gösteren bileşenleri, o bileşenin kendi pod’larını ve eklemenin adlandırdığı kaynakları kabul eden bir ağ politikası yazar. Bunun giden yöndeki karşılığı olan core/egress-allowlist, eklendiği bileşenin yalnızca kendi uses kenarlarının gösterdiği bileşenlere, kendi pod’larına, kümenin DNS’ine ve Release’in listelediği adres aralıklarına ulaşmasına izin verir. Aggregate’in kenar olarak bildirmediği bir çağrı bu durumda, ağ eklentisinin ağ politikasını uyguladığı her yerde, küme tarafından her iki uçta da reddedilebilir. Bu nedenle bileşenlerinizin yaptığı her çağrı için, hiçbir değer enjekte etmeyen çağrılar dahil, bir kenar yazın: eksik bir kenar, çitle çevrilmiş bir bileşenin reddedebileceği bir çağrıdır. model-server-caller-allowlist, yalnızca önündeki ağ geçidi üzerinden erişilebilen bir model sunucusunu gösterir.
Bir bağlantının kendi ekleri: bir uses girdisinde features
Bir bileşenin ayrıntılı uses: biçiminde çizdiği bağlantı kendi başına bir girdidir ve target, inject ve values yanında features: altında ekler taşıyabilir. Her biri soketin bildirdiği bir yuva ile anahtarlanır: tüketen Component, soketin featuresSchema alanında o soket üzerinden bağlanan her bağlantının doldurabileceği yuvaları listeler (bkz. Topoloji soketleri). Bir bileşen, eriştiği her bileşen için farklı bir kimlik bilgisini bu yolla tutar: iki modeli iki anahtarla çağıran bir ağ geçidi ya da bir modele kendi anahtarını sunan bir ajan gibi.
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }Bir bağlantıdaki ek; type (zorunlu), isteğe bağlı bir description ve Feature için values taşır. uses ve inject taşımaz: bir bağlantıdaki ek iç içe geçmez ve malzemesinin tüketiciye nasıl ulaşacağına bir inject bloğu değil, tüketen bileşenin Recipe’i karar verir. Bunlardan birini yazan bir belge, yüklenirken anahtarı adlandırarak reddedilir.
Yalnızca soketin bildirdiği yuvalar. Soketin featuresSchema alanında listelenmeyen bir ad altındaki ek, yüklenirken derlemeyi durdurur; bağlantıyı, soketi, bileşeni ve soketin bildirdiği yuvaları adlandırır; ad bunlardan birine tek bir düzenleme uzaklıktaysa, olası amaçlanan yazım olarak o yuvayı da belirtir. Doldurulmuş bir yuva ardından her bağlantıda yuvanın kendi bildirimine tabi tutulur: Feature’ın etiketlerinin karşılamadığı bir selector bu girdide durur ve herhangi bir bağlantıda boş bırakılan required bir yuva o bağlantıyı adlandırarak durur. Hiç yuva bildirmeyen bir soket, bağlantılarında hiçbir eki kabul etmez; geçici bir soket de (Component bildirmeden Aggregate’in bağladığı bir soket) hiç yuva bildirmediğinden kabul etmez. Bir alt modülün kattığı bileşen de aynı kurala tabidir ve bulgu alt modülün kendi belgesini gösterir. Bkz. A connection carries an attachment under a name its socket declares no slot for (Bir bağlantı, soketinin yuva bildirmediği bir ad altında ek taşıyor).
Bir Feature’ın çizdiği bağlantı ek taşımaz. Eklenmiş bir Feature’ın kendi uses: bloğu (bir bileşende ya da bir alt sistemde) aynı biçimde yazılır ama belge yüklenirken features: alanını reddeder. Böyle bir bağlantının ihtiyaç duyduğu kimlik bilgisi, Feature’ın kendi featuresSchema alanında bildirdiği ve Feature’ın yanına eklenen bir yuvayı doldurur; bkz. Bir Feature’ın kendi kimlik bilgisi.
Ekin aldığı ad. Her bağlantı eki, tüketen bileşenin <alias>.<slot> adlı bir eki olur: bağlantının altında yazıldığı takma ad, bir nokta ve yuva; yukarıda gpt.credential. Nokta, derleyicinin oluşturduğu adlara ayrılmış ayırıcıdır ve bir Aggregate’teki hiçbir takma ad, yuva ya da ek adı onu içeremez; bu yüzden oluşturulan ad, bileşenin kendi features: bloğunda yazılan bir adla asla aynı olmaz; bunu bir bileşende ya da bir sınırda yazan bir Release reddedilir (bkz. Kenar başına bağlantı yapılandırması). Bu ad, Manifest’in örnek başına katmanının eki anahtarladığı ad (bkz. Düz URI eşlemesi), tanılamaların ve IR grafiğinin eki raporladığı ad ve ekin FeatureRecipe’inin .attachment_name olarak okuduğu değerdir (bkz. Bir bağlantının ekinden türetilen adlar).
Bundan sonra her ek gibi çözümlenir: Manifest onun Feature türünü bir FeatureRecipe’e bağlar, values alanı Feature’ın şemasına göre doğrulanır (bir hata, onları yazan bağlantı girdisinde raporlanır) ve FeatureRecipe’i ekin kendi values ve infra alanlarına göre işlenir. Onu bileşenin kendi eklerinden iki şey ayırır:
- Tüketen Recipe’in
.featuresalanında yer almaz. O sütun yalnızca bileşenin kendi bloğunda yazılan ekleri taşır; bu yüzden kendi eklerini türe göre.featuresiçinde arayan bir Recipe’e bir bağlantının kimlik bilgisi asla verilmez. Bir Recipe, bir bağlantının ekini bağlantının kendisinden,.context.uses.<alias>.features.<slot>konumunda,.featuresalanının taşıdığı biçimde okur; çözümlenmişprovidesalanı da dahil (bkz. Bir bağlantının ekleri). - Yalnızca tüketiciye düşer. Bir hedefin işlenmiş çıktısı, ona ulaşan bağlantılar ne taşırsa taşısın aynıdır.
Yazılan bloğun grafikteki kopyası. IR grafiği her bileşenin uses: bloğunu yazıldığı gibi tutar ve orada bir bağlantı eki type ve description alanlarını tutar, values alanlarının hiçbirini tutmaz. Değerler bir kez, tüketicinin taşıdığı ekte görünür; orada Feature’ın hassas olarak bildirdiği bir değer gizlenir.
Bir Release, burada bildirilen bir eki infra ile boyutlandırabilir ya da eriştiği bir bağlantıya kendi ekini ekleyebilir; bkz. Kenar başına bağlantı yapılandırması.
Bir bileşeni veya modülü kapatmak: active:
Bir bileşen örneği ve bir alt aggregate modülü, o varlığın derlenmiş topolojinin bir parçası olup olmadığına karar veren bir active: anahtarını kabul eder. Yazılmazsa varlık mevcuttur; varsayılan ve olağan durum budur.
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: falseDoğrudan bir boolean yazın ya da boolean’a çözümlenen, .parameters üzerinde bir şablon yazın. Anahtarın var olma nedeni şablon biçimidir: bir Release’in bir parametreyi karşılayarak bir varlığın varlığına karar vermesini sağlar; böylece tek bir Aggregate, hangi parçaları dağıttıklarıyla farklılaşan ortamları kapsar — Release, Aggregate’in bildirmediği hiçbir şeyi bildirmeden.
False değerli bir anahtarın kaldırdıkları. Varlık, grafik oluşturulmadan önce budanır ve budama zincirleme ilerler: bir bileşen kendi uses: kenarlarını ve eklenmiş Features’ını da beraberinde götürür; bir modül ise katkıda bulunduğu her şeyi — bileşenlerini, onların kenarlarını, eklerini — götürür. Budanan varlığın getirdiği hiçbir şey işlenmez. Budamanın ulaşmadığı şey, varlığını sürdüren bir yerden ona yapılan bir başvurudur; bu da sonraki paragrafın konusudur.
Budanmış bir bileşeni hâlâ işaret eden, varlığını sürdüren bir bileşen derlemeyi durdurur. api, redis’e bir uses: kenarı bildiriyorsa ve redis kapatılmışsa, derleme kenarın kaybolmasına izin vermek yerine durur; aksi hâlde api’nin enjekte edilen değerleri dağıtım zamanında sessizce boş kalırdı. İkisinden hangisinin bu ortama ait olduğuna karar verin: hedefi yeniden açın, tüketiciyi aynı parametrenin arkasına alarak ikisinin birlikte çıkmasını sağlayın ya da kenarı tüketicinin uses: bloğundan kaldırın.
Yazılan bir anahtar bir boolean değere çözümlenmelidir ve boş bir değer boolean değildir. Anahtar, şablonu çözümlendikten sonra katı biçimde okunur ve boolean olarak ayrıştırılamayan bir değişmez değer, herhangi bir varsayılana düşmek yerine derlemeyi durdurur. Dikkat edilmesi gereken durum, değeri olmayan bir parametreyi okuyan bir anahtardır: hiçbir şeye çözümlenmez ve hiçbir şeyi “mevcut” olarak okumak, tam da o parametrenin arkasına koşulladığınız varlığı dağıtırdı. Bu nedenle active: anahtarını ardından hiçbir şey olmadan yazmak, anahtarı hiç yazmamakla aynı değildir: yalnızca kimsenin yazmadığı bir anahtar varsayılan olarak mevcut kabul edilir. Her ortamın bir yanıtı olması için parametreye spec.parameters içinde bir default: verin ya da parametreyi Release’te karşılayın. Bir varlığı koşulsuz olarak mevcut kılmak için active: anahtarını boşaltmak yerine kaldırın. Bu durma, durma koşulları başvurusunda “An active: toggle does not resolve to true or false (Bir active: anahtarı true ya da false değerine çözümlenmiyor)” başlığı altında açıklanmıştır.
Kapatılmış bir bileşen bir Release’ten adlandırılabilir kalır. Bir Release onu yine de bir sınırda adlandırabilir ve bu bilinçlidir: bir bileşeni kapatmak bir yazım eylemidir ve onu yapılandıran Release’in aynı düzenlemede yeniden yazılması beklenmez.
Alt sistemler ve bileşenler üzerindeki ek açıklamalar
Alt sistemler ve bileşen örneklerinin her ikisi de bir annotations: alanı taşır. Aggregate yüzeyinde geliştiricinin yazdığı ek açıklamalar, Aggregate tarafındaki ek açıklama kademesini yönlendirir: bir alt sistem ek açıklaması, iç içe geçmiş her alt sisteme ve içerilen her bileşene yayılır; daha yakın düzeydeki geçersiz kılmalar anahtar bazında uygulanır. Manifest’in mappings.features.annotations eşlemi, ek açıklama anahtarlarını derleme zamanında sentetik Feature eklerine çeviren bağlamaları bildirir. Aggregate-as-Authoring-Surface değişmezi, bu ek açıklamaları bağlamanın maps.values yolları üzerinden yönlendirmeyle sınırlar; yalnızca maps.infra yolları bildiren bir bağlama Aggregate tarafından değil, Release tarafından tetiklenir.
Değer biçimleri
Her ek açıklama anahtarı dört biçimden birini alır ve “sessizim”, “bir değer bildiriyorum” — bir skaler ya da yapılandırılmış bir nesne — ve “dışarıda kalıyorum” durumlarını birbirinden ayırır:
- Bulunmayan anahtar — kapsam bu ek açıklama için hiçbir değer bildirmez. İç içe alt sistemler ve içerilen bileşenler, bir üst kapsamdaki her bağlamayı devralır.
- Skaler bir dize — tek bir değer. Manifest bağlaması toplamda tam olarak bir yol bildirmelidir; skaler değer o yola yönlendirilir.
- Yapılandırılmış bir nesne — alt anahtardan alt değere bir eşlem. Nesnenin her alt anahtarı, Manifest bağlamasının
mapsalanı üzerinden bildirilen sütundaki karşılık gelen Feature şema alanına yönlendirilir. - Açık YAML
null— kapsam, bu anahtar için devralınan her bağlamayı kendi alt ağacından kaldırır. Kardeş bileşenler ve kardeş alt sistemler devraldıklarını korur; bağlamayı yalnızca dışarıda kalmayı seçen kapsam kaybeder.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideÇok alanlı Features için yapılandırılmış değerler
Birden çok yapılandırılabilir alanı olan bir Feature, yapılandırılmış bir ek açıklama değerine uygundur: tek bir ek açıklama anahtarı, tek bir bildirimde birkaç Feature şema alanı için değer taşır. Aggregate tarafı yalnızca bağlama eşlemindeki sütunu values olan alt anahtarları tetikler; infra alanına yönlendirilen alt anahtarlar Release tarafındaki ek açıklamalara aittir.
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-outYapılandırılmış değerler alt anahtar bazında derin birleştirmeyle kademelenir: daha yakın düzeydeki alt anahtarlar üst alt anahtarları geçersiz kılar; bir alt anahtardaki açık bir null, kardeş alt anahtarlar yerinde kalırken devralınan alt anahtarı o kapsam için bastırır. Yapılandırılmış değerlerin tam anlatımı için — Release tarafındaki infra alt anahtarlarıyla taraflar arası birleşim, alt anahtar bazında tür doğrulaması, bildirilmiş bir type olmayan şema alanları için gevşek varsayılan disiplini — bkz. providers/well-known-annotations.md §“Structured annotation values”.
Anahtar bazında bağımsızlık
Her ek açıklama anahtarı birbirinden bağımsız olarak devralır, geçersiz kılar ve dışarıda kalır. annotations.feature.myco/db-pool: null bildiren bir bileşen yalnızca o anahtardan çıkar; kapsayan alt sistemden devralınan diğer anahtarlar o bileşene yayılmayı sürdürür. Aynı alt sistemdeki kardeş bileşenler kendi ek açıklama eşlemlerini bağımsız olarak korur; bir bileşenin dışarıda kalması kardeşlerini etkilemez.
Üst düzey bileşen ek açıklamaları
Üst düzey bileşenler (bir alt sistemin içinde değil, doğrudan spec.components altında bildirilenler) devralınan bir kademe taşımaz. Bunların annotations: alanı değerleri doğrudan bileşen kapsamında bildirir; genişletme, Manifest’in eşleşen bir bağlama taşıdığı her bildirilmiş ek açıklamadan sentetik Feature ekleri üretir.
Bağlamalara uygulanan Aggregate tarafı kademe kuralı, taraf-sütun ayrımı ve bağlamaların ek açıklamaları sentetik Feature eklerine çevirdiğini gösteren uçtan uca çalışılmış bir örnek için bkz. providers/well-known-annotations.md §“Aggregate-side annotation cascade”.
YAML çapa kalıpları (defs: bloğu)
Aggregate şeması isteğe bağlı, kök düzeyde bir defs: bloğunu kabul eder: yalnızca standart YAML çapaları (&anchor) ve başvuruları (*anchor) için bir barındırıcı olarak kullanılan YAML dizelerinden oluşan bir liste. Bloğun içeriği derleyici tarafından hiçbir zaman okunmaz; blok, yazarların çapa tanımlarını tek bir yerde bildirip Aggregate’in geri kalanında bunlara başvurabilmesi için vardır ve böylece derleyicinin üzerinde dolaştığı düz O(1) sözlüğü kaybetmeden tekrarlanan değerler DRY tutulur. Mekanizma, Manifest varlığındaki eşdeğer defs: bloğunu yansıtır.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_levelÇapalar YAML ayrıştırma zamanında çözümlenir; bu nedenle derleyici values bloğunu okuduğunda *default_log_level, "info" dizesidir. defs: bloğu, çapa tanımları için uzlaşımsal yerdir; YAML çapaların herhangi bir yerde bildirilmesine izin verir, ancak bunları bir arada tutmak Aggregate’in geri kalanını okunabilir kılar. Blok isteğe bağlıdır; çapaya ihtiyaç duymayan Aggregates onu tamamen atlar.