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

Release

Release varlığının kavramsal rolü (Alan 4 — bir Aggregate’i bir Manifest’e bağlayan ve bileşenleri fiziksel sınırlara eşleyen dağıtım yönlendiricisi) architecture/04-entity-taxonomy.md sayfasında anlatılır. Zamansal sıralama mekanizması (sınır başına syncWave), Dinamik Adresleme Polyfill’i ve Parametre Yukarı Taşıma kalıbı architecture/12-day-two-lifecycles.md sayfasında anlatılır. Bu sayfa, Release yazım yüzeyini kapsar.

Release’in rolü

Release, bir aggregate öğesini bir manifest öğesine bağlar ve bileşenleri fiziksel dağıtım sınırlarına (ör. aws-eks-production) eşler. Derlemenin tek giriş noktasıdır: aggrega build --release release.yaml.

Release, fiziksel gerçeklikleri yalnızca parameters bloğuna enjekte ederek soyut aggregate sözleşmesini yerine getirir ve fiziksel boyutlandırmayı (CPU’lar veya portlar gibi) infra paralel ad alanı üzerinden enjekte eder.

Her Release, Manifest’ini adlandıran bir manifest: alanı bildirir (Release, üst öğenin manifest işaretçisini devralan extends: kullanmadığı sürece). aggrega build CLI’ı bu alanı doğrudan okur; --manifest adında bir CLI bayrağı yoktur, bu nedenle bağımlılık belirtimi Release’in kendisiyle birlikte Git’e işlenmiş olarak kalır ve dağıtım geçmişi Release’in kendi Git geçmişi üzerinden denetlenebilir hâle gelir.

aggregate: ve manifest: alanları, dilin geri kalanının başvuruları çözümlediği şekilde, kimlikle veya göreli yollu dosyayla çözümlenir; hiçbir zaman Release’e göreli bir dosya adı kökü olarak çözümlenmez. ./ veya ../ ile başlayan bir değer açık bir yerel dosyadır ve doğrudan Release’e göre okunur. Yalın bir belirteç bir kimliktir: başvurulan varlığın metadata.name değeri. Bir manifest: kimliği, Release’in kendi dizini taranarak çözümlenir (Manifest, dağıtım tarafındaki operatör yapılandırmasıdır, bu nedenle katalog veya kayıt defteri katmanı yoktur). Bir aggregate: kimliği ise tam kademe boyunca çözümlenir: önce Release’in dizini, sonra katalog, sonra kayıt defteri. Böylece bir Release yayımlanmış bir Aggregate’i kimliğiyle adlandırabilir ve aynı yayımlanmış modül, ister bir Release’in üst düzey spec.aggregate değeri ister başka bir Aggregate içindeki bir alt aggregate olsun, aynı şekilde çözümlenir. Bu kimlik-veya-yol modeli, paylaşılan bir Aggregate’in başvuruyu bir dosya adına bağlamadan birçok Release varyantını desteklemesini ve yayımlanmış bir Aggregate’in doğrudan adıyla dağıtılmasını sağlar.

Bir yol çalışma alanının içinde kalır. ./ veya ../ ile başlayan bir değer çalışma alanının barındırdığı bir dosyayı adlandırır; bir Release’in yazdığı diğer her yol da öyledir: aşağıda anlatılan extends: ve parameters $import: dahil. Yazıldığı hâliyle çalışma alanının dışına çıkan ya da yol üzerindeki bir sembolik bağlantının dışarı taşıdığı bir yol, adlandırdığı dosyadan herhangi bir şey okunmadan önce reddedilir. Çalışma alanının dışında tutulan bir Aggregate’i dağıtmak için onu kimliğiyle adlandırın ve onu barındıran dizini çalışma alanı yapılandırmasında bir katalog dizini olarak listeleyin; Manifest, bir extends: ile adlandırılan Release ve parametre dosyası Release’in yanında okunur ve hiçbir zaman adla aranmaz, bu nedenle çalışma alanının içinde tutulurlar. Komut satırında adlandırdığınız veya çalışma alanı yapılandırmasının adlandırdığı, çalışma alanının dışındaki bir Release kendi başına bir köktür: yazdığı her yol ve extends: zincirinin ulaştığı bir Release’in yazdığı her yol, o Release’i barındıran dizinin içindeki bir dosyaya çıkmalıdır; o dizinin dışına çıkan ya da bir bağlantının dışarı taşıdığı bir yol aynı şekilde reddedilir. Böyle bir Release’in adlandırdıklarını onun yanında tutun veya onu her ikisini de barındıran çalışma alanında derleyin. Bkz. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Başka bir dosyaya yapılan bir başvuru, içinde kalması gereken dizinin dışına çıkıyor)”.

Release, derlenmiş yapıtların hedefini belirler; provider yönlendirmesi ise Release’in işaret ettiği Manifest’e aittir (rol ayrımı için bkz. Manifest ve Release: sorumlulukların ayrılması).

Ortam meta verileri

Her Release meta veri bloğu bir environment: alanı kabul eder; bu alan, Release’in dağıtıldığı ortamı tanımlayan serbest biçimli bir dizedir (tipik değerler: production, staging, dev). Alan bilgi amaçlıdır: type: string dışında hiçbir numaralandırma, şema düzeyinde desen veya varlıklar arası doğrulama taşımaz. Derleyici, değerini helm sağlayıcısının işlediği her Kubernetes manifestinde, Aggrega köken etiketi takımının geri kalanıyla birlikte aggrega.ai/environment etiketi olarak yayar — geçerli bir Kubernetes etiket değeriyse yazıldığı gibi, değilse geçerli bir değere yeniden yazılarak ve tam değer aggrega.ai/environment ek açıklamasında taşınarak (böylece eu/prod, eu-prod etiketini alır); helm-chart sağlayıcısı aynı etiketleri bir alt chart’a yerleştirdiği, $import: ile yüklenmiş her yapıta ekler, alt chart’ın kendi şablonları ise yazarlarının yazdığını taşır. Compose sağlayıcısı aynı değeri, ürettiği her serviste aggrega.ai/environment etiketi olarak taşır.

environment: yazımını beş pratik kullanım deseni yönlendirir:

  1. OTel/FinOps maliyet ataması. Bulut maliyet panoları (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) Kubernetes pod’larını ortama göre etiketle filtreler. aggrega.ai/environment: production etiketi, Helm sağlayıcısının etiket enjeksiyonu aracılığıyla pod etiketlerine aktarılır; maliyet raporları, kaynak başına elle etiketleme yapmadan harcamayı aggrega.ai/environment ile gruplar.

  2. OTel iz ve günlük filtreleme. Gözlemlenebilirlik panoları (Datadog, New Relic, Honeycomb, Grafana Tempo) telemetriyi ortam etiketine göre filtreler. aggrega.ai/environment: staging, operatörlerin günlük sorgularını ve iz aramalarını, ad alanı uzlaşımlarına veya chart adlarına göre filtrelemeden staging ortamıyla sınırlamasını sağlar: işlenmiş yüzeyin tamamında tek bir kanonik etiket.

  3. Kubernetes operatörü hedefleme. GitOps denetleyicileri (ArgoCD, Flux) ve ilke operatörleri (Kyverno, OPA Gatekeeper), ortama özgü ilkeler için kaynakları zaman zaman ortam etiketine göre filtreler (örneğin, “yalnızca üretim ortamındaki kaynaklar onaylı bir imaj kaynağı etiketi gerektirir”). aggrega.ai/environment etiketi, ad alanı uzlaşımlarından veya adlandırma desenlerinden ayrı, kararlı bir seçici sağlar.

  4. Çok bölgeli üretim ayrımı. Bir production-us-east Release’ini bir production-eu-west Release’iyle birlikte çalıştıran ve her ikisinde de metadata.environment: production bulunan bir ekip, bölgeler genelinde aynı aggrega.ai/environment: production etiketini elde eder. Ayrı bir bölge etiketiyle birleştirildiğinde bu, bölgeler arası maliyet toplamayı (“toplam üretim harcaması”) ve bölge başına ayrıntılı incelemeyi mümkün kılar.

  5. Uyumluluk kapsamı belirleme. SOC 2, PCI ve HIPAA kanıt toplama, kapsamı ortama göre belirler (yalnızca üretim denetimi vb.). aggrega.ai/environment etiketi, kaynakları denetim kapsamına göre filtrelemek için uyumluluk kanıtı toplama araçları (Vanta, Drata) tarafından kullanılır.

Şema her Release’te environment: alanını zorunlu tutar; değer bilgi amaçlıdır ve derleyici onu yalnızca aggrega.ai/environment etiketini yazmak için okur.

Şema düzeyindeki kısıtlamalar

İki yapısal güvence, Aggregate’i Tek Doğruluk Kaynağı olarak korur:

  • values: yasaktır. Aggregate’i Tek Doğruluk Kaynağı olarak korumak için Release şeması bir values: bloğunu mekanik olarak yasaklar — Operatör, bir Release’ten herhangi bir Component ya da Feature üzerinde values bildiremez. Yasak uses kenarlarını da kapsar: bir Release’in kenar başına uses girdisi infra taşır ve bağlantı üzerinde yazdığı eklemeler de infra taşır — asla values değil (geliştiriciye yönelik kenar başına değerler ve bir bağlantı üzerindeki eklemenin değerleri Aggregate’te kalır). Geliştiriciye yönelik değerlerin ortama göre değişimi Parametre Yükseltme yoluyla akar: Geliştirici, Aggregate’te tipli bir parameters.* alanı sunar, Component’in values şablonu buna başvurur ve Release, parametreyi kendi ortamı için karşılar. Açıkça belirtilen şema düzeyindeki yasak için architecture/06-data-taxonomy-and-composition.md §8 Kısıtlama 4 bölümüne bakın. Release’in uses kenar yüzeyi — neyi yapılandırabileceği ve bağlayabileceği — aşağıdaki Kenar başına bağlantı yapılandırması bölümünde belgelenmiştir.
  • extends + aggregate: reddedilir. İzlenemeyen “aggregate değiştiren” Releases’i önlemek için, bir Release extends kullandığında bir aggregate işaretçisi bildirmek Release şeması tarafından reddedilir. Alt release, üst öğesiyle tam olarak aynı Geliştirici Niyeti’ne eşlenmelidir. Ancak manifest isteğe bağlı hâle gelir ve “Geç Bağlama”nın önünü açar — Operatör’ün tüm fiziksel topolojiyi devralırken Manifest’i cerrahi bir hassasiyetle değiştirmesine olanak tanır.

parameters: bloğu

Bir Release, Aggregate’in bildirdiği tipli parametre sözleşmesini karşılar. spec.parameters: yazım yüzeyidir: anahtarları Aggregate’in parameters.* bildirimleriyle eşleşen ve değerleri ortama özgü karşılamayı sağlayan bir YAML eşlemesidir.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Her değer, parametre sözleşmesi katmanında Aggregate’in bildirdiği şema denetiminden geçer ve bir Release zorunlu bir parametreyi atladığında (E0165, parameter-missing) ya da yuvasının sözleşmesinin reddettiği bir değer sağladığında (E0164, parameter-contract-violation) derleme durur. default: ile bildirilen parametreler, Release yuvayı atladığında varsayılan değeri alır; tipli sözleşme tek yazım sözcük dağarcığıdır.

İki yazım kipi: içerik biçimine göre yönlendirme. parameters:, satır içi bir YAML eşlemesini (Kip 1, yukarıda gösterilen) ya da yerel bir dosyayı gösteren tek bir $import: anahtarını (Kip 2) kabul eder:

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Göreli bir $import: yolu, komut nereden çalıştırılırsa çalıştırılsın, onu yazan Release’i barındıran dizinden çözümlenir; böylece komut satırı ve düzenleyici aynı dosyayı okur. Mutlak bir yol kendi konumunu belirtir ve her ikisi de çalışma alanı içindeki bir dosyaya ya da çalışma alanı dışında adlandırılmış bir Release için, onu barındıran dizin içindeki bir dosyaya götürmelidir. Bu noktada iki kip birbirini dışlar ve yalnızca tek bir dosya içe aktarılabilir. Çok dosyalı parametre katmanlama, Release extends: zincirlerinin alanıdır: üst Release temel bir parametre kümesi sağlar, alt Release ise ortama göre genişletir ve geçersiz kılar. Bu kalıp için aşağıdaki Composite Release / extends: kalıtımı bölümüne bakın.

Parametreler ile infra arasındaki sınır. Parametreler, Developer’ın bilişsel niyetini Aggregate’in bildirdiği tipli yuvalar olarak taşır; Release bunları karşılar. Release üzerindeki infra:, belirli bileşenlere ya da Feature eklemelerine bağlı olarak Operator’ün fiziksel boyutlandırmasını (replika sayıları, CPU/bellek sınırları, depolama sınıfları) taşır. Parametreler .parameters.X aracılığıyla Aggregate’in values: şablonlarına akar; infra: ise .infra.X aracılığıyla Recipe’in valuesMapping: şablonuna akar. Veri sütunu taksonomisi için architecture/06-data-taxonomy-and-composition.md §3 belgesine, parametrenin işlem hattı boyunca yaşam döngüsü için templates/parameters-context.md belgesine bakın.

Sınırlar ve varsayılan kapsam

Bir Release, bileşenleri sınırlar halinde gruplar: her biri kendi çıktı dizinine ve ek açıklama basamaklanmasına sahip fiziksel dağıtım birimleri. Tek sınırlı durum yaygın olandır, bu nedenle herhangi bir tören gerektirmez.

Tek kapsam (varsayılan). Bileşenleri doğrudan spec.components: altında yazın ve boundaries: bloğunu atlayın. Derleyici bunları, çıktısı düz olan sentezlenmiş bir default sınırına katlar: yapıtlar doğrudan dist/ altına yerleşir (sağlayıcı başına, aşağıdaki güvenli subDirectory varsayılanı aracılığıyla: dist/compose/, dist/helm/, …) ve yolda sınır adı bölümü bulunmaz. Bu en basit dağıtımdır: sınırları adlandırmadan düz bir Compose ya da tek kümeli bir hedef üzerinde aggrega build.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Birden çok kapsam. Bir Release birden fazla fiziksel gruplamaya yayıldığında (ayrı kümeler, bölgeler ya da eşitleme dalgaları) boundaries: altında adlandırılmış sınırlar bildirin. Her sınır kendi directory:, ek açıklama basamaklanması ve syncWave: değerini taşır; bileşenler kendi sınırları içinde adreslenir.

Karşılıklı dışlama. spec.components: ve spec.boundaries:, Release kökünde birbirini dışlar: bir Release ikisinden birini yazar, asla ikisini birden yazmaz. Her ikisini de bildiren bir belge, yükleme sırasında bir zarf hatasıyla durur. Üst düzey components yüzeyi, bir sınırın components alanının taşıdığı bileşen başına operatör biçiminin aynısını taşır (infra:, annotations:, uses:).

default adlı bildirilmiş bir sınır. Düz çıktı, adın değil sentezlenmiş varsayılanın bir özelliğidir. boundaries: altında açıkça default adlı bir sınır bildiren bir Release’te bu sınır sıradan bir adlandırılmış sınırdır: çıktısı, tıpkı diğer bildirilmiş sınırlar gibi directory: değerini izler (varsayılanı dist/boundaries/default/).

Varsayılan kapsam kalıbı için architecture/06-data-taxonomy-and-composition.md §7 belgesine bakın.

Uzamsal ayrım ve çıktı yolları

Her boundary, derlenmiş yapıtları için fiziksel bir çıktı directory değeri bildirir; bir boundary içindeki bileşenler bunu bileşen başına bir subDirectory ile geçersiz kılabilir. Derleyici nihai yapıt yolunu bunları birleştirerek, her platformda eğik çizgiyle ayrılmış biçimde hesaplar: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Tek dizin, tek yazım. Değerlendirilen yol bir kez temizlenir; bu nedenle out/a, out//a, ./out/a ve out/a/ tek bir dizindir. Yolları temizlendiğinde aynı dizine çıkan ve aynı sağlayıcı üzerinden render edilen boundary’ler, tıpkı aynı yollarla yazılmış boundary’ler gibi birlikte birleştirilir.
  • Yol, çıktı kökünün altında kalır. Çıktı kökünün dışına çıkan bir yol (.., ../escape, a/../..), mutlak bir yol ya da hiçbir dizini adlandırmayan bir yol (boş olan veya temizlendiğinde çıktı kökünün kendisine çıkan) hiçbir şey yazılmadan önce derlemeyi durdurur. Mesaj; Release’i, boundary’yi, hatalı alanı (directory: veya subDirectory:) ve alanın değerlendirildiği değeri adlandırır, çünkü bu değer çoğu zaman bir şablonun sonucudur.
  • Güvenli varsayılan. subDirectory atlanırsa veya boşsa derleyici otomatik olarak subDirectory: "{{ .capability }}" uygular; her render yeteneğinin yapıtları (Helm, Helm-chart, Compose, Terraform, CloudFormation) kendi alt klasörüne yerleşir ve böylece sonraki CI/CD araçlarında karışık yapıt çakışmaları önlenir. Açıkça yazılmış bir subDirectory: "", tam olarak atlanmış bir değer gibi okunur; dolayısıyla bu varsayılanı o da alır.
  • Düz geçersiz kılma. Alt dizinleri tamamen devre dışı bırakmak için (tüm yapıtlar doğrudan directory altında) subDirectory: "." ayarlayın. Boş bir dizeye değerlendirilen bir subDirectory şablonu da (örneğin sub değeri "" olarak ayarlanmış "{{ .parameters.sub }}") bunları devre dışı bırakır.
  • Şablon değişkenleri. directory; {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }} ve kapsayan bir boundary’den basamaklanan veriler için {{ .parent_boundary.* }} ile değerlendirilir. subDirectory aynı küme ile birlikte {{ .component_id }} (yalnızca bileşen başına geçersiz kılmalar) ile değerlendirilir. Derleyici yol şablonlarını missingkey=error ile değerlendirir; bildirilmemiş bir değişkene başvurmak, derlemeyi kesin bir tanılama ile durdurur. Bağlam başına matris ve üst boundary basamaklanma kuralları için yol şablonu değişkenleri sayfasına bakın.

Boundary ek açıklamaları, içerilen her bileşene aşağı doğru basamaklanır; infra ise kesinlikle onu hedefleyen bileşene yerel kalır. Özyinelemeli boundaries eşlemesi, ek açıklama basamaklanması ve yerel infra değişmezleri her düzeyde geçerliyken keyfi iç içe yerleştirmeye (boundary içinde boundary içinde boundary) izin verir.

Çalışılmış örnek:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Bu mekanizmayla basamaklanan ek açıklamalar, sonraki Recipe şablonlarında .context.annotations.release aracılığıyla görünür; render edicilerin bunları nasıl tükettiği için Recipe yazımı ve Şablon genişletme matrisi sayfalarına bakın.

Yapılandırılmış ek açıklama değerleri. Bir Manifest bağlaması tek bir ek açıklama anahtarı için birden çok infra-pillar yönlendirme yolu bildirdiğinde, Release tarafındaki ek açıklama değeri, tek bir bildirimde birkaç Feature şema alanı için değer taşıyan yapılandırılmış bir nesne olabilir:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

Yapılandırılmış değerler, alt anahtar başına derin birleştirme ile basamaklanır; daha yakın düzeydeki alt anahtarlar üst alt anahtarları geçersiz kılar. Alt anahtar başına null, kardeş alt anahtarlar yerinde kalırken tek bir alt anahtarı devre dışı bırakır. Release tarafı yalnızca bağlama eşlemesindeki pillar’ı infra olan alt anahtarları tetikler; values hedefine yönlenen alt anahtarlar Aggregate tarafındaki ek açıklamalara aittir. Yapılandırılmış değerlerin tam anlatımı (taraflar arası birleşim, alt anahtar başına tür doğrulaması, gevşetilmiş varsayılan disiplini) için providers/well-known-annotations.md §“Structured annotation values” bölümüne bakın.

İyi bilinen ek açıklamalar. Geçici anahtarların ötesinde Aggrega standart kütüphanesi, aggrega.ai/ ve feature.aggrega.ai/ ad alanları altında yerleşim, ağ, güvenlik ve gözlemlenebilirlik kategorilerine ayrılmış bir dizi iyi bilinen ek açıklama tanımlar. Bir Release boundary’sine ek açıklama ekleyen yazarlar, tam matris ve sağlayıcı başına tüketim kuralları için providers/well-known-annotations.md sayfasına başvurmalıdır; sayfa, her iyi bilinen anahtarı hangi sağlayıcıların uyguladığını ve anahtar mevcut olduğunda hangi davranışı ürettiklerini belgeler.

Kenar başına bağlantı yapılandırması

Bir sınır bileşeni, Component’in katalog usesSchema alanının bildirdiği soketler içindeki topoloji kenarlarını yapılandıran ya da bağlayan bir uses: bloğu taşıyabilir. Bu, operatörün bağlantı başına yüzeyidir ve geliştiricinin yazdığı mimarinin sahipliğini korumasını sağlayacak şekilde sınırlandırılmıştır:

  • Var olan bir kenarı yapılandırma. Geliştiricinin önceden bildirdiği bir kenarda kenar başına infra ayarlayın. Girdi, geliştiricinin takma adını belirtir ve infra sağlar; geliştiricinin bağladığı hedefin aynısını belirtir ya da hedefi atlar. infra, soketin infraSchema şemasına göre doğrulanır.
  • Bağlanmamış bir soketi bağlama. Component’in usesSchema alanının bildirdiği ama geliştiricinin bağlamadan bıraktığı bir sokete, var olan bir bileşeni gösteren bir kenar oluşturun. Oluşturulan kenar kenar başına infra da taşıyabilir.
  • Bir bağlantıya ekleme yapma. Eklentileri girdinin features: alanı altında, soketin featuresSchema içinde bildirdiği bir yuvaya göre anahtarlanmış olarak taşıyın; bunlar geliştiricinin bağlantı girdisinin doldurduğu yuvaların aynısıdır. Her biri type, isteğe bağlı bir description ve infra taşır, values ise asla taşımaz. Geliştiricinin aynı bağlantıda önceden doldurduğu bir yuvanın altında girdi, o eklentiyi boyutlandırır: yalnızca infra yazın, çünkü tür ve değerler Aggregate’ten gelir (burada yazılan bir type Aggregate’tekiyle uyuşmalıdır, aksi halde derleme bu girdide her ikisini de belirterek durur). Geliştiricinin boş bıraktığı bir yuvanın altında eklenti Release’in kendisine aittir ve type zorunludur. Her iki durumda da doldurma, tıpkı geliştiricininki gibi, yuvanın selector alanına tabidir ve required bir yuvaya sayılır.

Bu yüzey oluştur-ama-yeniden-hedefleme ilkesindedir: bir Release bağlanmamış bir sokete kenar ekleyebilir, ancak geliştiricinin önceden bildirdiği bir kenarı yeniden yönlendiremez. Geliştiricinin kenarından farklı bir hedef belirten kenar başına girdi derlemeyi durdurur; aynı hedefi belirten (ya da hedefi atlayan) bir girdi o kenarı yapılandırır. Release ayrıca bir kenarda ya da orada yazdığı bir eklentide values bildiremez (geliştiriciye yönelik değerler Aggregate’te kalır), usesSchema alanının bildirmediği bir soketi bağlayamaz ya da bir kenarı var olmayan bir bileşene yönlendiremez; bunların her biri ölümcül bir durmadır. Tüketen bileşen active: false ile kapatılmadıkça, tüm kenarlar çizildikten sonra var olmayan bir bağlantıda infra ya da features ayarlayan bir girdi de öyledir. Bkz. errors/fatal-halts.md §“When building the topology”.

Üç durma daha, bir bağlantının eklentilerini kendi bağlantısında tutar:

  • Soketin yuva bildirmediği bir ad, tıpkı Aggregate’in bağlantı girdisinde olduğu gibi, Release’teki bu girdide derlemeyi durdurur; soketin bildirdiği yuvaları ve bunlardan adın bir düzenleme uzaklığında olanları belirtir.
  • Yalnızca Release’in yaptığı, type olmadan yazılmış bir eklenti, yuvayı belirterek bağlantı girdisinde derlemeyi durdurur. Release’in yaptığı bir eklenti hiç values taşımaz; bu nedenle values alanı hiçbir şey gerektirmeyen bir Feature’a uygundur; şeması bir değer gerektiren bir Feature ise aynı girdide eksik değer nedeniyle durur. Standart kitaplığın çağıranın konum belirleyicisini taşıyan kimlik bilgisi Features’ları values içinde hiçbir şey gerektirmez: her biri onu infra içinde de kabul eder (aşağıya bakın).
  • Bağlantı dışında herhangi bir yerde yazılan bileşik ad derlemeyi durdurur. Bir bağlantı eklentisi, tüketen bileşenin <alias>.<slot> adlı bir eklentisi olur (bkz. Aggregate’in bağlantı girdisi) ve hem bir bileşen girdisinin kendi features: anahtarları hem de bir sınırınkiler nokta kabul eder. Bu adı yazan bir bileşen girdisi ya da onu, bağlantısı bu eklentiyi taşıyan bir bileşene ulaşacak şekilde yazan bir sınır (o sınıra veya onun içine iç içe yerleştirilmiş bir sınıra yerleştirilen bir bileşen, yönlendirilmiş bir alt modülünkiler de dahil), ulaştığı her bileşen için bir kez olmak üzere her iki yazımı da belirterek durur. Bir soketin yuvası her bağlantıda doldurulur, daha geniş bir kapsamdan basamaklanan bir eklentiyle asla doldurulmaz.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Release’in bağladığı bir bağlantıdaki kimlik bilgisi, sırrını infra içinde belirtir. Release’in bağladığı bir bağlantının Aggregate’te girdisi yoktur; bu yüzden orada kimlik bilgisinin values alanını yazan hiçbir şey yoktur ve Release hiçbir yerde values yazmaz. Bu nedenle çağıranın konum belirleyicisini taşıyan her standart kitaplık kimlik bilgisi Feature’ı (core/referenced-secret, core/referenced-secret-set, core/secret-value ve core/secret-provided) onu values içinde olduğu gibi infra içinde de kabul eder: origin ya da core/referenced-secret-set için entries; her iki sütunda aynı biçim ve aynı sensitive: true bildirimiyle. Her gerçekleştirme, onu hangi sütun taşıyorsa onu okur.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Konum belirleyici, eklenti başına tam olarak bir sütunda yazılır. Onu her ikisinde de (aynı yuva için Aggregate’in values alanında ve Release’in infra alanında) ya da hiçbirinde taşımayan bir eklenti, Feature’ın kendi doğrulamasında (E0033) Feature’ı, eklentiyi ve bileşeni belirterek ve ikisinden hangisi olduğunu söyleyerek durur. Kural derleyiciye değil, o Features’ların katalog varlıklarına aittir; derleyici onların doğrulamasını herhangi bir Feature’ınkini değerlendirdiği gibi değerlendirir. Konum belirleyici dışındaki alanlar kendi sütunlarını korur: key bir values yaprağı olarak kalır; bu yüzden yalnızca Release’in yaptığı bir eklenti Feature’ın varsayılan veri anahtarını, value değerini okur. values: yasağı değişmez: operatörün konum belirleyicisi infra alanıdır.

core/secret-provided bir bağlantıya uymayan tek seçenektir: değerini, eklentinin kendi inject: bloğunun teslim etmesi için yayımlar; bir bağlantının eklentisi ise iki belgenin hiçbirinde inject: bloğu taşımaz, dolayısıyla bir bağlantıda onu hiçbir inject: bloğu teslim etmez. Orada core/referenced-secret veya core/secret-value kullanın.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

Çözümlenen kenar başına infra, tüketen bileşenin render bağlamına .context.uses.<alias>.infra.<key> konumunda akar; hedef bileşenin bağlamında hiçbir zaman görünmez, bu nedenle bir hedefin render edilen çıktısı, ona kenar yapılandıran tüketicilere göre değişmez. Bir bağlantıdaki eklenti de tüketen bileşene, onun eklentilerinden biri olarak yerleşir: bu eklentinin infra’sı aynı yuva için Aggregate’in values değeriyle birleşir ve FeatureRecipe’i her ikisine göre render edilir. Tüketen bileşenin Recipe’i onu bağlantısının altında, .context.uses.<alias>.features.<slot> konumunda okur ve Workload’u onu yuvanın yanında bağlantıyı adlandırarak teslim eder — bkz. Bir bağlantının taşıdığı kimlik bilgisini teslim etme.

aggregates: alanı — iç içe alt modülleri sınırlara yönlendirme

Aggregate, spec.aggregates: aracılığıyla iç içe alt modüller bildirdiğinde, her alt modülün bileşenlerinin hangi sınıra yerleşeceğine Release, hedef sınırın içinde components: ile yan yana aggregates: bildirerek karar verir:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Aggregate.spec.aggregates: altında listelenen her alt aggregate’i tam olarak bir sınıra yerleştirin.

Yönlendirme bileşenleri yerleştirir. Yönlendirilen bir alt modülün her bileşeni, onu yönlendiren sınıra yerleşir ve o sınırın directory, subDirectory, syncWave ve anotasyon kademesini alır — components: altında doğrudan adlandırılan bir bileşenin aldığı bağlamın aynısı; buna üretilen yapıtlara damgalanan aggrega.ai/boundary-path köken bilgisi de dahildir. Bu nedenle bir alt modülü yönlendirmek ile her bileşenini boş gövdeli nitelikli noktalı yolla adreslemek aynı yapıtları üretir; yönlendirme bunu söylemenin daha kısa yolu ve alt modülün içeriğini bilmeden söylemenin tek yoludur.

Bir bileşen tam olarak bir sınıra aittir ve bir belge bir bileşeni iki kez yerleştirdiğinde derleme durur — aynı alt modülün iki sınıra yönlendirilmesi, bir alt modülün bir sınıra yönlendirilirken bileşenlerinden birinin başka bir sınırda adlandırılması ya da bir bileşenin hem doğrudan hem de bir yönlendirme girdisi üzerinden adlandırılması. Tanılama iki konumu da adlandırır, çünkü hangisinin tutulacağı yazarın kararıdır. Bir alt modülü bir sınıra yönlendirmek ve bileşenlerinden birini o aynı sınır altında adlandırmak bir çakışma değildir: yönlendirme bileşeni yerleştirir, adlandırılan girdi ise onu yapılandırır.

Release’in hiçbir yere yerleştirmediği bir alt aggregate derlemeyi durdurur. Yerleşim her iki yazım biçimi üzerinden okunur; bu nedenle derleme yalnızca alt modüle hiçbiri ulaşmadığında durur: hiçbir sınır onu aggregates: altında yönlendirmez ve hiçbir sınır bileşenlerinden herhangi birini components: altında nitelikli noktalı yolla adlandırmaz. İki yazım biçiminden her biri tek başına onu yerleştirir ve bileşenlerinin tümü tek tek adlandırılan bir alt modülün yönlendirme girdisine ihtiyacı yoktur. Düzeltme, alt modülü içe aktaran Aggregate’in aggregates: bloğuna aittir — doğrudan içe aktarılan bir alt modül için Release’in dağıttığı Aggregate, iç içe bir alt modül için ise içe aktaran alt modülün kendi belgesi. Tanılama bu girdiyi içe aktaran belgenin yazdığı anahtarla adlandırır; bu yüzden iç içe bir alt modül için noktalı yol yerine yerel ad olarak okunur.

İki durum bilinçli olarak durdurmaz. Hiç bileşen katkısı olmayan bir alt modülün yerleştirilecek bir şeyi yoktur. active: anahtarı false olarak çözümlenen bir alt modül hiç oluşturulmamıştır; bu yüzden bileşenlerinden hiçbiri yerleştirilecek şekilde var olmaz.

Kısmi yerleşim bu kuralı durdurmaz: bir alt modül, bileşenlerinden herhangi biri bir sınıra ulaştığında yerleştirilmiş sayılır; bu yüzden bunlardan birini adlandırmak alt modülü karşılar. Bu, geri kalanının dışarıda bırakılabileceği anlamına gelmez. Sınırın adlandırmadığı her bileşen o durumda hiçbir şey tarafından yerleştirilmez ve aşağıdaki bileşen kuralı bunu kendi anahtarında bildirir — böylece kısmen yerleştirilmiş bir alt modül, derlemeyi alt modülde değil, geride bıraktığı her bileşen için bir kez durdurur. Bütün bir alt modülü tek satırda yerleştiren iki yazım biçimi yönlendirme girdisi ve her bileşeni adlandırmaktır; ikisinin arasındaki her şey yalnızca adlandırdığını yerleştirir.

Release’in hiçbir yere yerleştirmediği bir bileşen de derlemeyi durdurur, bir düzey içeride. Yukarıdaki kural bir alt modülün bir sınıra ulaşıp ulaşmadığını sorar; bu kural aynı soruyu kompozisyonun içerdiği her bileşen için sorar. Bir bileşen, o sınırın components: alanı altında adlandırılarak ya da bir sınırın yönlendirdiği bir alt modülün içinde bulunarak bir sınıra ulaşır. Hiçbirine ulaşmayan bir bileşen Release’in bildirdiği her sınırın dışında işlenir ve directory, subDirectory, syncWave, anotasyon kademesi ile bileşen başına infra: değerlerini hiçbir yerden almaz — bu yüzden derleme, sınır yapılandırmasının hiç ulaşmadığı yapıtları üretmek yerine durur ve bileşeni adlandırır.

İki kural, alanı yalnızca bileşenin bir alt modülü olup olmadığını sorarak değil, bileşenin alt modülü hakkında soru sorarak paylaşır. Release’in hiçbir yere yerleştirmediği bir alt modülün bileşeni, alt modül kuralına bırakılır; bu kural o tek yazım hatasını modülün içerdiği her bileşen için bir kez değil, aggregates: girdisinde bir kez bildirir. Release’in kısmen yerleştirdiği bir alt modülün bileşeni ise bu kurala aittir, çünkü alt modül kuralı böyle bir modülü yerleştirilmiş olarak okur ve hakkında hiçbir şey söylemez — bu yüzden sınırın adlandırmadığı her bileşen burada, onu bildiren belgenin içindeki kendi anahtarında bildirilir. Bu nedenle bir alt modülü kısmen yerleştirmek tam olarak adlandırmak istediğiniz şeyi adlandırır ve adlandırmadığınız her bileşeni size bildirir.

Ve dağıtılan Aggregate’in içermediği bir component’i adlandıran bir boundary girdisi derlemeyi durdurur. Yukarıdaki iki kural yerleşimi component’in tarafından okur: onu herhangi bir şey yerleştirdi mi? Bu kural ise onu Release’in tarafından okur: ad çözümleniyor mu? Hiçbir şeye çözümlenmeyen bir girdi hiçbir şey yerleştirmez; dolayısıyla onun subDirectory, açıklamaları, component başına infra: ve uses: değerleri orada olmayan bir component’i yapılandırır ve derleme, girdinin hiç ulaşmadığı bir dağıtımı üretmek yerine durur. Her iki yazım da denetlenir: bir boundary’nin components: altındaki bir ad, component’in birleştirme tamamlandığında taşıdığı kimlik olarak okunur; bir yönlendirme girdisinin components: altındaki bir ad ise o sub-module içinde taşıdığı yerel ad olarak okunur. Tanılama, girdinin adreslediği kimliği bildirir; bu, yönlendirilen yazımda dosyadaki ad değildir: dosya yerel yarıyı yazar, önekini sub-module sağlar.

Bir ad, hiçbir şeye çözümlenmediği için reddedilir, biçimi yüzünden asla reddedilmez: noktalı bir ad olağandır, çünkü bir modül içerideki bir bileşen o modülün önekini taşır. active: anahtarı false olarak çözümlenen bir bileşen adlandırılabilir kalır — bir bileşeni kapatmak, onu yapılandıran Release’i düzenlemeyi gerektirmez.

Bir alt sistem nitelikli yola hiçbir şey katmaz; bu nedenle bir sınır, Aggregate onu nasıl gruplarsa gruplasın bir bileşeni yalın adıyla adresler. Bir kimliği yalnızca alt modül bileşimi niteler. Dağıtılan Aggregate’in bir bileşeni, yazar onu ister en üst düzeyde ister data adlı bir alt sistemin içinde yazmış olsun, store olur; bir modül içerideki bir bileşen ise data.store olur ve oradaki data herhangi bir alt sistemin değil, modülün önekidir. Dolayısıyla alt sistem olarak data adını taşıyan bir yerde duran bir bileşen için data.store şeklinde yazılmış bir sınır girdisi hiçbir şeyi adreslemez: girdinin kendisi yukarıdaki kural uyarınca derlemeyi durdurur ve hedeflendiği bileşen de hiçbir sınıra ulaşmaz. Girdiyi store olarak düzeltmek her ikisini de çözer.

Bu nedenle bir alt modülü yerleştirmek boundaries: gerektirir. Tek kapsamlı biçimin yönlendirme yüzeyi yoktur — aggregates: bir sınırın anahtarıdır, spec: anahtarı değildir — ve en üst düzeydeki components: eşlemesi yalnızca nitelenmemiş adları kabul eder; bu yüzden alt modülleri içe aktaran bir Aggregate’i dağıtan bir Release boundaries: bildirir.

Özyinelemeli yönlendirme. aggregates: özyinelemelidir — bir sınırın aggregates: alanı altındaki her girdi, derin iç içe modül bileşimi için kendisi de iç içe bir aggregates: eşlemesi bildirebilir.

Aggregate başına yönlendirme bloğu. Bir yönlendirme girdisi tam olarak iki anahtar kabul eder, başka hiçbir şeyi kabul etmez: o alt modülün tek tek bileşenlerini yapılandırmak için components: ve daha derinde iç içe geçmiş modüller için iç içe bir aggregates:. annotations: sınıra aittir; bileşen başına infra: ise yönlendirme girdisinin kendi components: alanı altındaki bir girdiye aittir.

Bir yönlendirme girdisinin içinde bir bileşen, kendi alt modülü içinde taşıdığı adla anahtarlanır — data.consumer değil, consumer — çünkü orada sahip olduğu tek ad budur. Nitelikli noktalı yol, bir sınırın kendi components: eşlemesinin aynı bileşeni adresleme biçimidir; iki yazım biçimi birbirinin yerine kullanılamaz ve bir yönlendirme girdisi noktalı bir anahtarı reddeder.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

Alt aggregate’in kendi bileşenleri ve Features öğeleri Release’te yeniden bildirilmez — Release onları yeniden ifade etmek yerine yönlendirir ve birini yalnızca yapılandırmak için adlandırır.

Zamansal sıralama — boundary başına syncWave

Release’teki her boundary isteğe bağlı olarak bir tamsayı syncWave: alanı bildirir; bu alan, Developer’ın Aggregate’ine dokunmadan Operator’a dağıtım sırası üzerinde açık denetim sağlar. Dalga numarası boundary’nin kendisine ait bir özelliktir; artifact’ler üretilirken boundary’nin alt ağacında bulunan her bileşen, kendi boundary’sinin dalga değerini devralır.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Dalga değeri semantiği. syncWave: işaretli bir tamsayıdır (pozitif, sıfır veya negatif). Alan belirtilmediğinde varsayılan değer 0 olur. Dalga değerleri üst sınırdan devralınmaz; varsayılan dışında bir dalga isteyen her sınır bunu açıkça bildirir. Components, sınırlarının dalgasını geçersiz kılamaz (dalga, tek tek bileşenlerin değil, uzamsal birimin bir özelliğidir).

Sağlayıcıya göre üretim. Derleyici, boundary’nin dalga değerini işlenmiş çıktıya sağlayıcıya özgü biçimde yazar. Bu biçimlerden üçü aşağıda ayrıntılı olarak ele alınmıştır; dalganın terraform dahil her standart kütüphane sağlayıcısında ne yaptığı providers/reference-matrix.md “What a boundary’s syncWave does on each provider” bölümünde tablo hâlinde verilmiştir.

  • Kubernetes (helm / helm-chart sağlayıcısı). Dalga 0 olmadığında, helm sağlayıcısının boundary için işlediği her Kubernetes kaynağı, GitOps standardı olan argocd.argoproj.io/sync-wave: "<N>" ek açıklamasını taşır; Helm hook’ları ayrıca helm.sh/hook-weight: "<N>" ek açıklamasını taşır, böylece aynı dalga değeri Helm’in kendi pre/post-install sıralamasını da yönlendirir. ArgoCD sync-wave ek açıklamasını, Helm ise bir hook’un ağırlığını okur ve her biri kaynakların uygulanmasını buna göre sıralar. helm-chart sağlayıcısı bir kaynak chart’ın şablonlarını yazarlarının yazdığı gibi kopyalar; bu nedenle bir alt chart’ın kendi kaynakları dalgayı yalnızca bu şablonların onu yazdığı yerlerde taşır; sağlayıcının eklediği, $import: ile yüklenmiş bir yapıt ise argocd.argoproj.io/sync-wave taşır, helm.sh/hook-weight taşımaz (bkz. providers/helm-chart.md).
  • Compose. Bir boundary’nin işlendiği compose dosyasındaki her servis, depends_on aracılığıyla, aynı dosyaya katkıda bulunan hemen önceki dalganın servislerini bekler — hedef bir healthcheck bildiriyorsa hedefin sağlık durumuna, bildirmiyorsa başlamasına bağlı olarak. Dolayısıyla dalga yalnızca tek bir dosyanın servislerini sıralar, o dosyanın dışındaki hiçbir şeyi sıralamaz: ayrı docker-compose.yaml dosyalarına işlenen boundary’ler ayrı compose projeleridir ve bunların sıralanması operatörün sorumluluğundadır. uses: kenarları, dalgayla birlikte kenar başına sıralamayı ifade etmeye devam eder. Bkz. providers/compose.md.
  • CloudFormation. Birleştirilmiş yığın şablonundaki her kaynak, DependsOn aracılığıyla, aynı yığına katkıda bulunan hemen önceki dalganın kaynaklarına bağımlıdır; böylece dalga, kaynakların oluşturulma sırasını ve tersine, silinme sırasını belirler. Bu bir hazır olma sıralaması değildir: bir yığın şablonunda bir kaynağın hizmet verebilir durumda olması kavramı yoktur. Bir parçanın kendi DependsOn değeri değiştirilmez, genişletilir. Farklı bir yığında birleşen Components erişim dışındadır ve iki yığını sıralamak operatörün sorumluluğundadır. Bkz. providers/cloudformation.md.

Dalga yazım birimi ile dağıtılabilir birim. Boundary, dalga yazım birimidir. Dağıtılabilir birim ise bileşenlerin üretildiği birleştirme yoludur — varsayılan olarak boundary ile 1:1 eşleşir, ancak aynı directory: değerini paylaşan iki kardeş boundary tek bir birleştirilmiş çıktıda birleşir (tek bir Chart.yaml, tek bir docker-compose.yaml). Bu durumda birleştirilmiş çıktı birden fazla dalgadan kaynak taşıyabilir; onu okuyan bir ArgoCD Application, Application içinde her kaynağı o kaynağın taşıdığı sync-wave ek açıklamasına göre sıralar — helm’de sıfır olmayan bir dalga için işlenen her kaynak, helm-chart’ta ise yalnızca $import: ile yüklenmiş bir yapıt bu ek açıklamayı taşır; alt chart’ın kendi şablonları yazarlarının yazdığını taşır. Yollar arasında Application’lar arası sıralama operatörün CI sorumluluğundadır.

Kullanım durumları. Dalga sıralaması, bir boundary’nin başlatılması başka birinin önceden tamamlanmasına bağlı olduğunda önem kazanır. Tipik örüntü: dalga 0’da bir infra boundary’si (VPC + veritabanı), dalga 1’de bir migrations boundary’si (şema geçişi işi) ve dalga 2’de bir apps boundary’si (geçirilmiş şemayı kullanan uygulama). Açık dalgalar olmadan üçü de eşzamanlı dağıtılır ve uygulama geçişin tamamlanmasını beklerken çökme döngüsüne girer.

Tam mimari çerçeve için — DAG yürütme modeli, zamansal sıralamanın Aggregate yerine Release’e yerleştirilmesinin gerekçesi ve dalga yazım birimi ile dağıtılabilir birim ayrımı — bkz. architecture/12-day-two-lifecycles.md §1.

Feature ekleme

Release, Features’ı hem boundary kapsamında (geniş politika) hem de bileşene özgü kapsamda (hassas hedefleme) ekleyebilir; yürütme, architecture/10-compilation-pipeline.md içinde tanımlanan 5 Katmanlı Soğan Modeli’ni izler. Release içinde bildirilen Features type, infra ve uses katkısında bulunur; values bildiremezler (yukarıdaki Şema düzeyi kısıtlamalara bakın).

Bir boundary’ye eklenen Feature, sizin seçtiğiniz bir örnek adıyla anahtarlanır ve bu ad . veya .. olamaz. Her katkıda bulunana kendi dizinini veren bir provider’da (terraform’da modules/ altında, helm-chart’ta charts/ altında) boundary düzeyindeki bir Feature’ın dosyaları yalnızca örnek adıyla adlandırılmış bir dizine yazılır ve bu iki addan hiçbiri kendi başına bir dizin değildir: derleme durur ve Release’i, boundary’yi ve örneği adlandırır. audit.v2 gibi yalnızca nokta içeren bir ad sıradan bir addır.

features:, Aggregate’te olduğu gibi Release’in de her iki kapsamdaki tek ekleme yüzeyidir. Bir kimlik bilgisi, feature.aggrega.ai/kind: secret etiketini taşıyan bir Feature’dır; bu nedenle Operator tarafından eklenen bir kimlik bilgisi, diğer her Feature gibi features: altında eklenir ve gizli değerini, bir bağlantıdakinin yaptığı gibi infra içinde adlandırır (bkz. Kenar başına bağlantı yapılandırması): Aggregate’in kimlik bilgisi olmadan bıraktığı bir bileşende ya da Aggregate’in bir gizli değer adlandırmadan bildirdiği bir eklemenin boyutlandırması olarak. Hiçbir kapsamda ikinci bir ekleme anahtar sözcüğü yoktur; böyle bir anahtar sözcük bildiren bir belge, yükleme sırasında beklenmeyen özelliği adlandıran bir zarf hatasıyla reddedilir.

Boundary genelinde eklenen bir feature bir uses: bloğu taşıyabilir ve bu blok, boundary’ye yönlendirilen her bileşene yansıtılır: her bileşen, feature’ın adlandırdığı hedeflere bir bağımlılık kenarı kazanır ve bu hedeflerin provides değerleri ona enjekte edilir. Bu, paylaşılan bir bağımlılığı aynı uses: kenarını her bileşende tekrarlamak yerine boundary’de bir kez ifade eder: “bu boundary’deki her bileşen paylaşılan önbellek / toplayıcı / mesaj veri yolu ile konuşur”. Aggregate’teki alt sistem düzeyinde bir Feature eklemesi de uses: bloğunu aynı şekilde alt sistemin bileşenlerine yansıtır. uses bir değer değil, bir topoloji bağlantı bildirimidir; bu yüzden Release’te izin verilir. Yansıtma, eklenen Feature’ın yürütme kapsamından bağımsızdır: FeatureRecipe’i boundary başına bir kez işlenen bir Feature da uses: bloğunu yine bileşen başına yansıtır, paylaşılan kaynağın kendisi ise bir kez işlenir.

Tek bir bileşene eklenen bir feature aynı uses: bloğunu taşır ve aynı kenarı o tek bileşenden kurar: bileşen her adlandırılmış hedefe bir bağımlılık kenarı kazanır, bu hedeflerin provides değerleri ona enjekte edilir ve kenar, boundary genelindeki biçimde olduğu gibi eklemeyi kökeni olarak kaydeder. İkisi, iki genişlikte tek bir bildirimdir: içindeki her bileşeni bağlamak için boundary’ye, yalnızca o bileşeni bağlamak için bir bileşene eklenir; aralarındaki seçim bağlantının ne yaptığıyla değil, yalnızca erişimle ilgilidir. Hiçbiri hesaplama kaynağı oluşturmaz: hedef, Aggregate’in bildirdiği bir bileşeni zaten adlandırmalıdır; adlandırmayan bir hedef derlemeyi durdurur. Bir Feature’ın kurduğu bağlantı kendi eklemelerini taşımaz: girdisi target ve inject alır ve oradaki bir features: anahtarı Release yüklenirken reddedilir.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Bir hedef nasıl yazılır. Bir kenar hedefi, birleştirilmiş grafın bir bileşenini adlandırır; bu nedenle hedef yönlendirilmiş bir alt modüle ait olduğunda nitelikli noktalı yolla yazılır: store değil, data.store. Bu, eklemenin kendisi components: anahtarları modüle yerel olan bir yönlendirme girdisinin altında bulunduğunda da geçerlidir: anahtar eklemenin hangi bileşende olduğunu, hedef ise kenarın hangi bileşene ulaştığını söyler ve yalnızca ikincisi graf genelinde geçerli bir addır. Modüle yerel bir adla yazılan bir hedef hiçbir bileşenle eşleşmez ve sarkan her kenarın ürettiği aynı tanılamayla durur.

Bileşik Release ve extends: kalıtımı

Bir Release, yazım yüzeyini devraldığı bir temel Release’i gösteren spec.extends: bildirebilir.

Başvuru, onu bildiren Release’in yanındaki bir dosyaya giden bir yoldur — ./base-release.yaml veya ../shared/base-release.yaml. Release dağıtım tarafındadır ve kataloğa dizinlenmez; bu nedenle bir extends: başvurusu hiçbir zaman katalog üzerinden çözümlenmez. Kabul ettiği tek biçim göreli yoldur: kayıt defteri koordinatı olarak yazılmış bir başvuru reddedilir, yalın bir ad da reddedilir; her ikisinde de tanılama iletisi göreli yol biçimini belirtir. Bir Manifest’in extends: alanı farklı okunan yakın komşudur — göreli bir yolu veya Release’in yanındaki bir Manifest’in yalın metadata.name değerini alır — bu nedenle iki biçim birbirinin yerine kullanılamaz ve bir Manifest’te çözümlenecek yalın bir ad burada çözümlenmez. Zincirin her halkası aynı şekilde okunur: başka bir dizinde tutulan bir üst Release, sizin adını verdiğiniz Release nerede olursa olsun, kendi üst öğesini kendi yanındaki bir yolla adlandırır; tıpkı parametrelerindeki $import: ifadesinin onun yanında çözümlenmesi gibi. Yol, bir Release’in yazdığı her yol gibi çalışma alanı içindeki bir Release’e çıkmalıdır — ya da çalışma alanı dışında adı verilen bir Release için, zincirinin her halkasının bağlı olduğu, o Release’i içeren dizinin içine: dışarı tırmanan veya bir halkanın dışarı taşıdığı yol, adını verdiği dosya okunmadan önce reddedilir.

Derleyici, Release yüklenirken zinciri izler — zaten zincirde bulunan bir dosyaya dönen zinciri, derinlik sınırını aşan zinciri ve hiçbir şeyi göstermeyen başvuruyu reddeder — ve ardından zinciri tek bir çözümlenmiş Release’e katlar.

Devraldığınızı anahtar anahtar değiştirebilirsiniz. Bölünemez tek bir şey olan bir değere — bir skaler, bir liste, bir şablon — ulaşana kadar en alta kadar sizin değeriniz kazanır; böyle bir değeri bütün olarak alır ya da değiştirirsiniz. Devraldığınız bir şeyi null yazarak kaldırırsınız. Bu, genişleten bir Component, Feature ve Manifest’in izlediği kuralın aynısıdır; dolayısıyla birini tanıyan yazar hepsini tanımış olur.

Bir Release’e uygulandığında: boundaries sınır adına göre, bir sınır da anahtara göre birleşir; components bileşen adına göre, infra derinlemesine, features örnek adına ve ardından sütuna göre birleşir; bir bileşenin uses alanı sokete ve ardından bağlantıya göre birleşir; burada alt öğenin yazdığı bir target devralınanın yerine geçer, bağlantının infra alanı anahtar anahtar birleşir ve onun features alanı, bir bileşenin kendi features alanının izlediği kuralla aynı şekilde yuvaya ve ardından sütuna göre birleşir; directory, subDirectory, syncWave ile Aggregate ve Manifest işaretçileri, yerine geçen skaler değerlerdir.

İki şey aktarılmaz:

  • Kimlik ve köken. Hiçbir metadata alanı devralınmaz. Bilinmesi gereken metadata.environment alanıdır: her Release için zorunludur ve doğası gereği Release’e özgüdür; bu nedenle bir alt öğe, köken etiketlerinde üst öğesinin değil kendi ortamıyla işlenir.
  • Aggregate işaretçisi geçersiz kılınamaz, devralınır. Alt öğe aggregate: bildiremez — şema, tek bir belgede extends: ile aggregate: alanını birlikte reddeder — bu nedenle bir alt öğe, temeliyle aynı Developer Intent’i dağıtır.

Alt öğe manifest: alanını atlayıp temelinkini devralabilir ya da Geç Bağlama için geçersiz kılabilir.

Zincir boyunca tek yönlendirme biçimi. boundaries: ve components: tek bir Release içinde birbirini dışlar ve bu bir zincir boyunca da geçerlidir: adlandırılmış sınırlar bildiren bir temel ile üst düzey bileşenler bildiren bir alt öğe reddedilir ve tanılama her iki dosyayı ve her iki anahtarı belirtir. Tek bir yönlendirme biçimi seçin ve en alta kadar onu kullanın.

Yerel geliştirme köprüsü kalıbı. Tipik kullanım durumu, ekibinin üretim Aggregate’ini Aggregate’i çatallamadan ya da sınır topolojisini çoğaltmadan yerel olarak çalıştıran bir geliştiricidir. Ekip bir üretim Release’i yayımlar; yerel bir Release onu extends: ile genişletir ve yalnızca Manifest işaretçisini geçersiz kılarak buluta yönelik Recipes’i yerel eşdeğerleriyle değiştirir:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release, temelinin sınır topolojisini, Feature eklerini ve bileşen geçersiz kılmalarını devralır; geliştirici tek bir local-release.yaml tutar ve hiçbir üretim yapılandırmasını çoğaltmadan aggrega build --release local-release.yaml komutunu çalıştırır.

directory: alanını bir parametreye göre yazın. Dizin diğer her skaler gibi devralındığından, şablon değişkeni taşımayan bir dizini devralan alt öğe temelinin işlendiği yola işlenir ve hiçbir komut satırı seçeneği onu yönlendirmez. Kastettiğiniz buysa — örneğin çıktılarını karşılaştırmak için yalnızca Recipes’i değiştirmek — bu meşrudur; bu nedenle derleme reddetmek yerine bunu bildirir ve devam eder. Dizini yukarıdaki gibi bir parametreye göre yazmak topolojiyi tek yerde tutar ve yine de her Release’in çıktısını kendine ait bir yere gönderir.

Çok dosyalı parametre katmanlama. Çok dosyalı parametre katmanlamanın yeri Release kalıtımıdır. Temel bir Release ortak parametre kümesini sağlar; ortama özgü alt öğeler temeli extends: ile genişletir ve farklılaşan yuvaları geçersiz kılar:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Her alt öğe, temelinden devralınan parametreleri kendi parametreleriyle birleştirilmiş olarak görür. Eşlem değerli parametreler alt anahtarın kazandığı derin birleştirmeyle birleşir; skaler değerli parametrelerin yerini alt öğe alır; bir alt öğenin null olarak yazdığı anahtar boş bir değere ayarlanmaz, kaldırılır.

Bir temel parametrelerini içe aktarabilir ve bir alt öğe yine de tek tek anahtarları geçersiz kılabilir. Yukarıda parameters: altında anlatılan iki yazım modu — satır içi ya da tek bir $import: — bir zincirle değil tek bir belgeyle ilgili kuraldır: zincirdeki her Release bir modu ya da diğerini bildirir ve her birinin içe aktarması, zincir katlanmadan önce o Release’i barındıran dizine göre çözümlenir. Dolayısıyla paylaşılan bir dosyayı içe aktaran bir temel ile birkaç anahtarı satır içi yazan bir alt öğe, tıpkı iki satır içi blok gibi anahtara göre birleşir:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Hata modları. Döngüsel extends: zincirleri, eksik üst işaretçileri ve alt taraftaki aggregate: bildirimleri, sorunlu Release’i ve şema düzeyindeki ihlali belirten açık tanılamalarla çalışma alanı yüklemesini durdurur. Hata başına ileti biçimleri için errors/fatal-halts.md sayfasına bakın.