Release
Peran konseptual entitas Release (Domain 4 — router deployment yang mengikat sebuah Aggregate ke sebuah Manifest dan memetakan komponen ke dalam batas fisik) dijelaskan di architecture/04-entity-taxonomy.md. Mekanisme pengurutan temporal (syncWave per batas), Dynamic Addressing Polyfill, dan pola Parameter Hoisting dijelaskan di architecture/12-day-two-lifecycles.md. Halaman ini membahas antarmuka penulisan Release.
Peran Release
Release mengikat sebuah aggregate ke sebuah manifest dan memetakan komponen ke batas deployment fisik (misalnya, aws-eks-production). Release adalah satu-satunya titik masuk untuk kompilasi: aggrega build --release release.yaml.
Release memenuhi kontrak aggregate abstrak dengan menyuntikkan realitas fisik secara ketat ke dalam blok parameters, dan menyuntikkan ukuran fisik (seperti CPU atau port) melalui namespace paralel infra.
Setiap Release mendeklarasikan field manifest: yang menyebutkan Manifest-nya (kecuali Release tersebut menggunakan extends:, yang mewarisi penunjuk manifest milik induknya). CLI aggrega build membaca field ini secara langsung; tidak ada flag CLI --manifest, sehingga spesifikasi dependensi tetap di-commit ke Git bersama Release itu sendiri, yang membuat riwayat deployment dapat diaudit melalui riwayat Git milik Release itu sendiri.
Field aggregate: dan manifest: di-resolve berdasarkan identitas atau berdasarkan file path relatif, dengan cara yang sama seperti bagian lain bahasa ini me-resolve referensi — tidak pernah sebagai stem nama file yang relatif terhadap release. Nilai ./ atau ../ adalah file lokal eksplisit, yang dibaca langsung secara relatif terhadap Release. Token polos adalah sebuah identitas — metadata.name dari entitas yang dirujuk. Identitas manifest: di-resolve dengan memindai direktori milik Release itu sendiri (sebuah Manifest adalah konfigurasi operator sisi deployment, sehingga tidak memiliki tingkat katalog atau registry). Identitas aggregate: di-resolve melalui kaskade lengkap — direktori Release, lalu katalog, lalu registry — sehingga sebuah Release dapat menyebut Aggregate yang dipublikasikan berdasarkan identitas, dan modul terpublikasi yang sama di-resolve baik sebagai spec.aggregate tingkat atas sebuah Release maupun sebagai sub-aggregate di dalam Aggregate lain. Model identitas-atau-path ini memungkinkan sebuah Aggregate bersama mendukung banyak varian Release tanpa mengikat referensi ke nama file, dan memungkinkan Aggregate yang dipublikasikan di-deploy langsung berdasarkan nama.
Sebuah path tetap berada di dalam workspace. Nilai ./ atau ../ menyebut file yang dimuat workspace, begitu pula setiap path lain yang ditulis sebuah Release — extends: miliknya dan $import: parameter, di bawah. Path yang keluar dari workspace sebagaimana tertulis, atau yang dibawa keluar oleh symbolic link di sepanjang jalannya, ditolak sebelum apa pun dibaca dari file yang disebutnya. Untuk men-deploy Aggregate yang disimpan di luar workspace, sebut Aggregate tersebut berdasarkan identitas dan daftarkan direktori yang memuatnya sebagai direktori katalog dalam konfigurasi workspace; sebuah Manifest, Release yang disebut oleh extends:, dan file parameter dibaca di samping Release dan tidak pernah dicari berdasarkan nama, sehingga semuanya disimpan di dalam workspace. Release yang Anda sebut pada baris perintah, atau yang disebut oleh konfigurasi workspace, di luar workspace adalah root tersendiri: setiap path yang ditulisnya — dan setiap path yang ditulis oleh Release yang dituju rantai extends: miliknya — harus mengarah ke file di dalam direktori yang memuat Release tersebut, dan path yang keluar dari direktori itu, atau yang dibawa keluar oleh link, ditolak dengan cara yang sama. Simpan apa yang disebut oleh Release semacam itu di sampingnya, atau build Release tersebut di workspace yang memuat keduanya. Lihat errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Referensi ke file lain mengarah ke luar direktori tempat referensi itu harus tetap berada)”.
Release menentukan tujuan artefak hasil kompilasi; dispatch provider merupakan bagian dari Manifest yang ditunjuk oleh Release (lihat Manifest vs. Release: pemisahan concern untuk pembagian peran).
Metadata lingkungan
Setiap blok metadata Release menerima field environment: — string bebas yang mengidentifikasi lingkungan tempat Release di-deploy (nilai umum: production, staging, dev). Field ini bersifat informatif: tidak memiliki enumerasi, tidak memiliki pola tingkat skema, dan tidak memiliki validasi lintas entitas selain type: string. Compiler mengeluarkan nilainya sebagai label aggrega.ai/environment pada setiap manifest Kubernetes yang dirender oleh provider helm, bersama dengan rangkaian label provenans Aggrega lainnya — sebagaimana tertulis jika merupakan nilai label Kubernetes yang valid, dan jika tidak, ditulis ulang menjadi nilai yang valid dengan nilai persisnya dibawa sebagai anotasi aggrega.ai/environment (sehingga eu/prod diberi label eu-prod); provider helm-chart menambahkan label yang sama ke setiap artefak yang dimuat melalui $import: yang ditempatkannya di sub-chart, sedangkan templat milik sub-chart itu sendiri membawa apa yang ditulis oleh penulisnya. Provider compose membawa nilai yang sama sebagai label aggrega.ai/environment pada setiap service yang dikeluarkannya.
Lima pola praktis mendorong penulisan environment::
-
Atribusi biaya OTel/FinOps. Dasbor biaya cloud (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) memfilter pod Kubernetes berdasarkan tag lingkungan. Label
aggrega.ai/environment: productionmengalir ke label pod melalui injeksi label oleh provider Helm; laporan biaya mengelompokkan pengeluaran berdasarkanaggrega.ai/environmenttanpa penandaan manual per sumber daya. -
Pemfilteran trace dan log OTel. Dasbor observabilitas (Datadog, New Relic, Honeycomb, Grafana Tempo) memfilter telemetri berdasarkan label lingkungan.
aggrega.ai/environment: stagingmemungkinkan operator membatasi kueri log dan pencarian trace ke staging tanpa memfilter berdasarkan konvensi namespace atau nama chart — satu label kanonis di seluruh permukaan hasil render. -
Penargetan operator Kubernetes. Controller GitOps (ArgoCD, Flux) dan operator kebijakan (Kyverno, OPA Gatekeeper) terkadang memfilter sumber daya berdasarkan label lingkungan untuk kebijakan khusus lingkungan (misalnya, “sumber daya khusus production memerlukan label approved-image-source”). Label
aggrega.ai/environmentmenyediakan selector stabil yang berbeda dari konvensi namespace atau pola penamaan. -
Diferensiasi production multi-region. Tim yang menjalankan Release
production-us-eastbersama Releaseproduction-eu-west— keduanya denganmetadata.environment: production— mendapatkan labelaggrega.ai/environment: productionyang sama di seluruh region. Dikombinasikan dengan label region terpisah, hal ini memungkinkan rollup biaya lintas region (“total pengeluaran production”) dan drill-down per region. -
Pelingkupan kepatuhan. Pengumpulan bukti SOC 2, PCI, dan HIPAA dilingkupi berdasarkan lingkungan (audit khusus production, dll.). Label
aggrega.ai/environmentdigunakan oleh perangkat pengumpulan bukti kepatuhan (Vanta, Drata) untuk memfilter sumber daya berdasarkan lingkup audit.
Skema mewajibkan environment: pada setiap Release; nilainya bersifat informatif, dan compiler membacanya hanya untuk menulis label aggrega.ai/environment.
Batasan tingkat skema
Dua jaminan struktural melindungi Aggregate sebagai Single Source of Truth:
values:dilarang. Untuk melindungi Aggregate sebagai Single Source of Truth, skema Release secara mekanis melarang blokvalues:— Operator tidak dapat mendeklarasikanvaluespada Component atau Feature mana pun dari sebuah Release. Larangan ini berlaku juga untuk edgeuses: entriusesper-edge pada Release membawainfradan lampiran yang ditulisnya pada koneksi, dan lampiran tersebut juga membawainfra— tidak pernahvalues(nilai per-edge yang ditujukan bagi developer, serta nilai lampiran pada sebuah koneksi, tetap berada di Aggregate). Variasi per lingkungan untuk nilai yang ditujukan bagi Developer mengalir melalui Parameter Hoisting: Developer mengekspos fieldparameters.*bertipe di Aggregate, templatvaluesmilik Component mereferensikannya, dan Release memenuhi parameter tersebut untuk lingkungannya. Lihat architecture/06-data-taxonomy-and-composition.md §8 Constraint 4 untuk larangan tingkat skema yang dinyatakan secara eksplisit. Permukaan edgeusesmilik Release — apa yang dapat dikonfigurasi dan dihubungkannya — didokumentasikan dalam Konfigurasi koneksi per-edge di bawah.extends+aggregate:ditolak. Untuk mencegah Releases “pengubah aggregate” yang tidak dapat dilacak, ketika sebuah Release menggunakanextends, deklarasi pointeraggregateditolak oleh skema Release. Release turunan harus dipetakan ke Developer Intent yang sama persis dengan induknya. Namun,manifestmenjadi opsional, sehingga memungkinkan “Late Binding” — Operator dapat mewarisi seluruh topologi fisik tetapi mengganti Manifest secara presisi.
Blok parameters:
Sebuah Release memenuhi kontrak parameter bertipe yang dideklarasikan oleh Aggregate. spec.parameters: adalah permukaan penulisan — sebuah map YAML yang kuncinya cocok dengan deklarasi parameters.* milik Aggregate dan yang nilainya menyediakan pemenuhan per lingkungan.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: 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 environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"Setiap nilai melewati pemeriksaan skema yang dideklarasikan Aggregate pada lapisan kontrak parameter, dan build berhenti ketika sebuah Release menghilangkan parameter yang wajib (E0165, parameter-missing) atau menyediakan nilai yang ditolak oleh kontrak slot-nya (E0164, parameter-contract-violation). Parameter yang dideklarasikan dengan default: menerima nilai default ketika Release menghilangkan slot tersebut; kontrak bertipe adalah satu-satunya kosakata penulisan.
Dua mode penulisan — dispatch berdasarkan bentuk konten. parameters: menerima map YAML inline (Mode 1, ditunjukkan di atas) atau satu kunci $import: yang menunjuk ke berkas lokal (Mode 2):
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yamlPath $import: relatif diselesaikan dari direktori yang memuat Release yang menuliskannya, dari mana pun perintah dijalankan, sehingga baris perintah dan editor membaca berkas yang sama; path absolut menyebut tempatnya sendiri, dan keduanya harus mengarah ke berkas di dalam workspace — atau, untuk Release yang disebut di luar workspace, di dalam direktori yang memuatnya. Kedua mode ini saling eksklusif di lokasi ini, dan hanya satu berkas yang dapat diimpor. Pelapisan parameter multi-berkas merupakan ranah rantai extends: pada Release: Release induk menyediakan himpunan parameter dasar dan Release anak memperluas dan menimpanya per lingkungan. Lihat Composite Release / pewarisan extends: lebih lanjut di bawah untuk polanya.
Batas antara parameter dan infra. Parameter membawa intensi kognitif Developer yang dinyatakan sebagai slot bertipe yang dideklarasikan Aggregate; Release memenuhinya. infra: pada Release membawa ukuran fisik dari Operator (jumlah replika, batas CPU/memori, kelas penyimpanan) yang dilekatkan pada komponen tertentu atau lampiran Feature. Parameter mengalir ke templat values: milik Aggregate melalui .parameters.X; infra: mengalir ke templat valuesMapping: milik Recipe melalui .infra.X. Lihat architecture/06-data-taxonomy-and-composition.md §3 untuk taksonomi pilar data dan templates/parameters-context.md untuk siklus hidup parameter di sepanjang pipeline.
Boundary dan cakupan default
Sebuah Release mengelompokkan komponen ke dalam boundary — unit deployment fisik, masing-masing dengan direktori output dan kaskade anotasinya sendiri. Kasus satu boundary adalah yang paling umum, sehingga tidak memerlukan seremoni apa pun.
Cakupan tunggal (default). Tulis komponen langsung di bawah spec.components: dan hilangkan blok boundaries:. Compiler menggabungkannya ke dalam boundary default yang disintesis, yang outputnya datar — artefak ditempatkan langsung di bawah dist/ (per provider, melalui default subDirectory yang aman di bawah ini: dist/compose/, dist/helm/, …), tanpa segmen nama boundary di path. Ini adalah deployment paling sederhana: aggrega build atas target Compose datar atau satu cluster tanpa memberi nama boundary.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Beberapa cakupan. Jika sebuah Release mencakup lebih dari satu pengelompokan fisik — cluster, region, atau sync wave yang terpisah — deklarasikan boundary bernama di bawah boundaries:. Setiap boundary membawa directory:, kaskade anotasi, dan syncWave: miliknya sendiri, dan komponen dialamatkan di dalam boundary-nya.
Saling eksklusif. spec.components: dan spec.boundaries: saling eksklusif di root Release — sebuah Release menulis salah satunya, tidak pernah keduanya. Dokumen yang mendeklarasikan keduanya berhenti saat dimuat dengan error envelope. Permukaan components tingkat atas membawa bentuk operator per komponen yang sama dengan yang dibawa components milik sebuah boundary (infra:, annotations:, uses:).
Boundary yang dideklarasikan dengan nama default. Output datar adalah sifat dari default yang disintesis, bukan dari namanya. Release yang secara eksplisit mendeklarasikan boundary bernama default di bawah boundaries: adalah boundary bernama biasa: outputnya mengikuti directory: miliknya (dengan default dist/boundaries/default/), persis seperti boundary lain yang dideklarasikan.
Lihat architecture/06-data-taxonomy-and-composition.md §7 untuk pola cakupan default.
Segregasi spasial dan jalur output
Setiap boundary mendeklarasikan directory output fisik untuk artefak hasil kompilasinya; komponen di dalam boundary dapat menimpanya melalui subDirectory per komponen. Compiler menghitung jalur artefak akhir dengan menggabungkan keduanya, dalam bentuk berpemisah garis miring di setiap platform: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Satu direktori, satu ejaan. Jalur hasil evaluasi dibersihkan satu kali, sehingga
out/a,out//a,./out/adanout/a/adalah satu direktori. Boundary yang jalurnya, setelah dibersihkan, menjadi direktori yang sama dan dirender melalui provider yang sama dirakit bersama, persis seperti boundary yang ditulis dengan jalur identik. - Jalur tetap berada di bawah root output. Jalur yang naik keluar dari root output (
..,../escape,a/../..), jalur absolut, atau jalur yang sama sekali tidak menyebut direktori — kosong, atau setelah dibersihkan menjadi root output itu sendiri — menghentikan build sebelum apa pun ditulis. Pesannya menyebut Release, boundary, field yang salah (directory:atausubDirectory:) dan nilai hasil evaluasinya, karena nilai tersebut sering merupakan hasil sebuah template. - Default yang aman. Jika
subDirectorydihilangkan atau kosong, compiler secara otomatis menerapkansubDirectory: "{{ .capability }}"— artefak setiap kapabilitas rendering (Helm, Helm-chart, Compose, Terraform, CloudFormation) ditempatkan di subfoldernya sendiri, sehingga mencegah tabrakan artefak campuran di alat CI/CD hilir.subDirectory: ""yang ditulis secara eksplisit dibaca persis seperti yang dihilangkan, sehingga juga menggunakan default ini. - Penimpaan datar. Untuk menonaktifkan subdirektori sepenuhnya (semua artefak langsung di bawah
directory), tetapkansubDirectory: ".". TemplatesubDirectoryyang dievaluasi menjadi string kosong — misalnya"{{ .parameters.sub }}"dengansubditetapkan ke""— juga menonaktifkannya. - Variabel template.
directorydievaluasi dengan{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}, dan{{ .parent_boundary.* }}untuk data yang mengalir dari boundary yang melingkupinya.subDirectorydievaluasi dengan himpunan yang sama ditambah{{ .component_id }}(hanya untuk penimpaan per komponen). Compiler mengevaluasi template jalur denganmissingkey=error— merujuk variabel yang tidak dideklarasikan akan menghentikan build dengan diagnostik yang tepat. Lihat variabel template jalur untuk matriks per konteks dan aturan aliran dari boundary induk.
Anotasi boundary mengalir ke bawah ke setiap komponen yang dikandungnya; infra tetap sepenuhnya lokal pada komponen yang ditargetkannya. Map boundaries yang rekursif memungkinkan penyarangan sembarang (boundary di dalam boundary di dalam boundary) sementara invarian aliran anotasi dan infra lokal tetap berlaku di setiap tingkat.
Contoh lengkap:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: 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 defaultAnotasi yang dialirkan oleh mekanisme ini muncul di template Recipe hilir melalui .context.annotations.release; lihat Penulisan Recipe dan Template Expansion Matrix untuk cara renderer menggunakannya.
Nilai anotasi terstruktur. Ketika binding Manifest mendeklarasikan beberapa jalur routing pilar infra untuk satu kunci anotasi, nilai anotasi di sisi Release dapat berupa objek terstruktur yang membawa nilai untuk beberapa field skema Feature dalam satu deklarasi:
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 boundaryNilai terstruktur mengalir dengan deep merge per subkunci; subkunci di tingkat yang lebih dekat menimpa subkunci induk. null per subkunci mengecualikan satu subkunci sementara subkunci sejajarnya tetap berlaku. Sisi Release hanya mengaktifkan subkunci yang pilar binding-map-nya adalah infra; subkunci yang dirutekan ke values ditempatkan pada anotasi sisi Aggregate. Untuk penjelasan lengkap tentang nilai terstruktur — komposisi lintas sisi, validasi tipe per subkunci, disiplin default yang longgar — lihat providers/well-known-annotations.md §“Structured annotation values”.
Anotasi umum. Selain kunci ad hoc, pustaka standar Aggrega mendefinisikan sekumpulan anotasi umum di bawah namespace aggrega.ai/ dan feature.aggrega.ai/, yang dikelompokkan ke dalam kategori penempatan, jaringan, keamanan, dan observabilitas. Penulis yang menambahkan anotasi ke boundary Release sebaiknya merujuk providers/well-known-annotations.md untuk matriks lengkap beserta aturan penggunaan per provider — halaman tersebut mendokumentasikan provider mana yang menerapkan setiap kunci umum dan perilaku apa yang dihasilkannya ketika kunci tersebut ada.
Konfigurasi koneksi per edge
Sebuah komponen boundary dapat membawa blok uses: yang mengonfigurasi atau menghubungkan edge topologi di dalam socket yang dideklarasikan oleh usesSchema katalog Component. Ini adalah permukaan per koneksi milik operator, yang dibatasi agar developer tetap memegang kepemilikan atas arsitektur yang mereka tulis:
- Mengonfigurasi edge yang sudah ada. Tetapkan
infraper edge pada edge yang sudah dideklarasikan oleh developer. Entri menyebutkan alias developer dan menyediakaninfra; entri tersebut menyebutkan target yang sama dengan yang dihubungkan developer atau menghilangkan target.infradivalidasi terhadapinfraSchemamilik socket. - Menghubungkan socket yang belum terikat. Buat edge ke socket yang dideklarasikan oleh
usesSchemamilik Component tetapi dibiarkan tidak terhubung oleh developer, yang mengarah ke komponen yang sudah ada. Edge yang dibuat juga dapat membawainfraper edge. - Melampirkan pada koneksi. Bawa lampiran di bawah
features:milik entri, dengan kunci berupa slot yang dideklarasikan socket dalamfeaturesSchema-nya — slot yang sama yang diisi oleh entri koneksi developer. Setiap lampiran membawatype,descriptionopsional, daninfra, dan tidak pernahvalues. Di bawah slot yang sudah diisi developer pada koneksi yang sama, entri tersebut menentukan ukuran lampiran itu: tulisinfrasaja, karena tipe dan nilainya berasal dari Aggregate (typeyang ditulis di sini harus sesuai dengan milik Aggregate, atau build berhenti pada entri ini dengan menyebutkan keduanya). Di bawah slot yang dibiarkan kosong oleh developer, lampiran tersebut adalah milik Release sendiri dantypewajib diisi. Dalam kedua kasus, pengisian tunduk padaselectormilik slot, dan dihitung untuk slotrequired, persis seperti pengisian developer.
Permukaan ini bersifat create-not-retarget: sebuah Release dapat menambahkan edge ke socket yang belum terikat, tetapi tidak dapat mengalihkan edge yang sudah dideklarasikan developer. Entri per edge yang menyebutkan target yang berbeda dari edge developer menghentikan build; entri yang menyebutkan target yang sama (atau menghilangkannya) mengonfigurasi edge tersebut. Release juga tidak dapat mendeklarasikan values pada edge atau pada lampiran yang ditulisnya di sana (nilai yang ditujukan untuk developer tetap berada di Aggregate), mengikat socket yang tidak dideklarasikan oleh usesSchema, atau mengarahkan edge ke komponen yang tidak ada — masing-masing merupakan penghentian fatal. Demikian pula entri yang menetapkan infra atau features pada koneksi yang tidak ada setelah semua edge digambar, kecuali komponen konsumen dinonaktifkan dengan active: false. Lihat errors/fatal-halts.md §“When building the topology”.
Tiga penghentian lagi menjaga lampiran sebuah koneksi tetap berada pada koneksinya:
- Nama yang tidak memiliki slot yang dideklarasikan socket menghentikan build, persis seperti pada entri koneksi Aggregate, pada entri ini di Release, dengan menyebutkan slot yang dideklarasikan socket dan slot mana pun yang berjarak satu suntingan dari nama tersebut.
- Lampiran yang hanya dibuat oleh Release, yang ditulis tanpa
type, berhenti pada entri koneksi, dengan menyebutkan slotnya. Lampiran yang dibuat Release tidak membawavalues, sehingga cocok untuk Feature yangvalues-nya tidak mewajibkan apa pun; Feature yang skemanya mewajibkan suatu nilai berhenti karena nilai yang hilang pada entri yang sama. Features kredensial pustaka standar yang membawa locator pemanggil tidak mewajibkan apa pun dalamvalues: masing-masing juga menerimanya dalaminfra(lihat di bawah). - Nama gabungan yang ditulis di mana pun selain pada koneksi menghentikan build. Lampiran koneksi menjadi lampiran dari komponen konsumen dengan nama
<alias>.<slot>(lihat entri koneksi Aggregate), dan baik kuncifeatures:milik entri komponen maupun milik boundary menerima titik. Entri komponen yang menulis nama itu, atau boundary yang menulisnya sehingga mencapai komponen yang koneksinya membawanya — komponen yang ditempatkan dalam boundary tersebut atau dalam boundary yang bersarang di dalamnya, termasuk milik sub-modul yang dirutekan — berhenti dengan menyebutkan kedua ejaan, sekali untuk setiap komponen yang dicapainya. Slot socket diisi pada setiap koneksi dan tidak pernah oleh lampiran yang mengalir turun dari cakupan yang lebih luas.
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-secretKredensial pada koneksi yang dihubungkan Release menyebutkan secret-nya dalam infra. Koneksi yang dihubungkan Release tidak memiliki entri di Aggregate, sehingga tidak ada yang menulis values kredensial di sana, dan Release tidak menulis values di mana pun. Karena itu, setiap Feature kredensial pustaka standar yang membawa locator pemanggil — core/referenced-secret, core/referenced-secret-set, core/secret-value dan core/secret-provided — menerimanya dalam infra maupun dalam values: origin, atau entries untuk core/referenced-secret-set, dengan bentuk yang sama dan deklarasi sensitive: true yang sama di kedua pilar. Setiap realisasi membaca pilar mana pun yang membawanya.
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 namesLocator ditulis tepat dalam satu pilar per lampiran. Lampiran yang membawanya di kedua pilar — values milik Aggregate dan infra milik Release untuk slot yang sama — atau tidak di keduanya berhenti pada asersi milik Feature itu sendiri (E0033), dengan menyebutkan Feature, lampiran, dan komponennya, serta menyatakan mana dari dua kasus tersebut yang terjadi. Aturan ini milik entitas katalog Features tersebut, bukan milik compiler, yang mengevaluasi asersinya seperti mengevaluasi asersi Feature mana pun. Field selain locator tetap pada pilarnya: key tetap menjadi leaf values, sehingga lampiran yang hanya dibuat Release membaca data key default Feature, yaitu value. Larangan values: tidak berubah — locator milik operator adalah infra.
core/secret-provided adalah satu-satunya yang tidak cocok untuk koneksi: Feature ini memublikasikan nilainya agar dikirimkan oleh blok inject: milik lampiran itu sendiri, dan lampiran koneksi tidak membawa blok inject: di kedua dokumen, sehingga pada koneksi tidak ada blok inject: yang mengirimkannya. Gunakan core/referenced-secret atau core/secret-value di sana.
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 }infra per edge yang telah di-resolve mengalir ke konteks render komponen konsumen di .context.uses.<alias>.infra.<key>; nilai ini tidak pernah muncul dalam konteks komponen target, sehingga output yang di-render dari sebuah target tidak berubah terhadap konsumen yang mengonfigurasi edge ke dalamnya. Lampiran pada koneksi juga mendarat pada komponen konsumen, sebagai salah satu lampirannya: infra-nya digabungkan dengan values milik Aggregate untuk slot yang sama, dan FeatureRecipe-nya di-render terhadap keduanya. Recipe komponen konsumen membacanya di bawah koneksinya, di .context.uses.<alias>.features.<slot>, dan Workload-nya mengirimkannya dengan menyebutkan koneksi di samping slot — lihat Mengirimkan kredensial yang dibawa koneksi.
Field aggregates: — merutekan sub-modul bersarang ke dalam boundary
Ketika Aggregate mendeklarasikan sub-modul bersarang melalui spec.aggregates:, Release menentukan boundary tempat komponen setiap sub-modul ditempatkan dengan mendeklarasikan aggregates: di samping components: di dalam boundary target:
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: 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 boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Tempatkan setiap sub-aggregate yang tercantum di bawah Aggregate.spec.aggregates: tepat di satu boundary.
Perutean menempatkan komponen. Setiap komponen dari sub-modul yang dirutekan ditempatkan di boundary yang merutekannya dan mengambil directory, subDirectory, syncWave, serta kaskade anotasi boundary tersebut — konteks yang sama dengan yang diterima komponen yang dinamai langsung di bawah components:, termasuk provenans aggrega.ai/boundary-path yang dicapkan pada artefak yang dihasilkan. Karena itu, merutekan sebuah sub-modul dan menyebut setiap komponennya dengan path bertitik yang terkualifikasi dengan body kosong menghasilkan artefak yang identik; perutean adalah cara yang lebih singkat untuk menyatakannya, dan satu-satunya cara untuk menyatakannya tanpa mengetahui isi sub-modul.
Sebuah komponen hanya menjadi milik tepat satu boundary, dan build berhenti ketika sebuah dokumen menempatkannya dua kali — sub-modul yang sama dirutekan ke dua boundary, sebuah sub-modul dirutekan ke satu boundary sementara salah satu komponennya dinamai di boundary lain, atau sebuah komponen dinamai baik secara langsung maupun melalui entri perutean. Diagnostik menyebutkan kedua lokasi, karena mana yang dipertahankan adalah keputusan penulis. Merutekan sebuah sub-modul ke sebuah boundary dan menyebut salah satu komponennya di bawah boundary yang sama bukanlah konflik: perutean menempatkan komponen tersebut dan entri yang dinamai mengonfigurasinya.
Sub-aggregate yang tidak ditempatkan Release di mana pun menghentikan build. Penempatan dibaca dari kedua penulisan, sehingga build hanya berhenti ketika tidak satu pun menjangkau sub-modul: tidak ada boundary yang merutekannya di bawah aggregates:, dan tidak ada boundary yang menyebut komponennya di bawah components: dengan path bertitik yang terkualifikasi. Masing-masing penulisan sendiri sudah menempatkannya, dan sub-modul yang semua komponennya dinamai satu per satu tidak memerlukan entri perutean. Perbaikannya berada di blok aggregates: milik Aggregate yang mengimpor sub-modul tersebut — Aggregate yang di-deploy oleh Release, untuk sub-modul yang diimpornya secara langsung, dan dokumen sub-modul pengimpor itu sendiri untuk sub-modul bersarang. Diagnostik menyebut entri tersebut dengan key yang dipakai dokumen pengimpor, sehingga untuk sub-modul bersarang ia terbaca sebagai nama lokal, bukan path bertitik.
Dua kasus sengaja tidak menghentikan build. Sub-modul yang tidak menyumbang komponen tidak memiliki apa pun untuk ditempatkan. Sub-modul yang toggle active:-nya bernilai false tidak pernah dikomposisikan, sehingga tidak ada komponennya yang perlu ditempatkan.
Penempatan sebagian tidak menghentikan build menurut aturan ini: sebuah sub-modul dianggap ditempatkan begitu salah satu komponennya menjangkau sebuah boundary, sehingga menyebut salah satunya sudah memenuhi sub-modul tersebut. Bukan berarti sisanya boleh diabaikan. Setiap komponen yang tidak dinamai boundary kemudian tidak ditempatkan oleh apa pun, dan aturan komponen di bawah melaporkannya pada key-nya sendiri — sehingga sub-modul yang ditempatkan sebagian menghentikan build sekali untuk setiap komponen yang tertinggal, bukan pada sub-modul. Dua penulisan yang menempatkan seluruh sub-modul dalam satu baris adalah entri perutean dan penyebutan setiap komponen; apa pun di antara keduanya hanya menempatkan apa yang disebutnya.
Komponen yang tidak ditempatkan Release di mana pun juga menghentikan build, satu tingkat lebih dalam. Aturan di atas menanyakan apakah sebuah sub-modul menjangkau sebuah boundary; aturan ini menanyakan hal yang sama untuk setiap komponen dalam komposisi. Sebuah komponen menjangkau boundary dengan dinamai di bawah components: boundary tersebut, atau dengan berada di dalam sub-modul yang dirutekan oleh sebuah boundary. Komponen yang tidak memenuhi keduanya akan di-render di luar setiap boundary yang dideklarasikan Release, mengambil directory, subDirectory, syncWave, kaskade anotasi, dan infra: per komponen dari ketiadaan — sehingga build berhenti dan menyebut komponen tersebut alih-alih menghasilkan artefak yang tidak pernah dijangkau konfigurasi boundary.
Kedua aturan membagi wilayah dengan menanyakan tentang sub-modul komponen, bukan sekadar apakah komponen itu memilikinya. Komponen dari sub-modul yang tidak ditempatkan Release di mana pun diserahkan kepada aturan sub-modul, yang melaporkan satu kesalahan penulisan itu sekali pada entri aggregates:, bukan sekali per komponen yang dimuat modul. Komponen dari sub-modul yang ditempatkan Release sebagian menjadi urusan aturan ini, karena aturan sub-modul menganggap modul seperti itu sudah ditempatkan dan tidak melaporkan apa pun — sehingga setiap komponen yang tidak dinamai boundary dilaporkan di sini, pada key-nya sendiri di dalam dokumen yang mendeklarasikannya. Dengan demikian, menempatkan sub-modul sebagian menyebut tepat apa yang Anda maksudkan, dan memberi tahu Anda tentang setiap komponen yang tidak Anda sebut.
Dan entri boundary yang menyebut komponen yang tidak dimuat oleh Aggregate yang di-deploy menghentikan build. Dua aturan di atas membaca penempatan dari sisi komponen — apakah ada yang menempatkannya. Aturan ini membacanya dari sisi Release: apakah nama tersebut ter-resolve. Entri yang tidak ter-resolve ke apa pun tidak menempatkan apa pun, sehingga subDirectory, anotasi, infra: per komponen, dan uses:-nya mengonfigurasi komponen yang tidak ada, dan build berhenti alih-alih menghasilkan deployment yang tidak pernah dijangkau entri tersebut. Kedua penulisan diperiksa: nama di bawah components: sebuah boundary dibaca sebagai id yang dimiliki komponen setelah komposisi selesai, dan nama di bawah components: sebuah entri perutean dibaca sebagai nama lokal yang dimilikinya di dalam sub-modul tersebut. Diagnostik melaporkan id yang dituju entri, yang pada penulisan perutean bukan nama di dalam file — file menuliskan bagian lokalnya dan sub-modul menyediakan prefiksnya.
Sebuah nama ditolak karena tidak ter-resolve ke apa pun dan tidak pernah karena bentuknya: nama bertitik adalah hal biasa, karena komponen satu modul lebih dalam membawa prefiks modul tersebut. Komponen yang toggle active:-nya bernilai false tetap dapat dinamai — menonaktifkan sebuah komponen tidak mengharuskan pengeditan Release yang mengonfigurasinya.
Subsistem tidak menyumbang apa pun pada path terkualifikasi, sehingga boundary menyebut komponen dengan nama polosnya bagaimanapun Aggregate mengelompokkannya. Hanya komposisi sub-modul yang mengkualifikasi sebuah id. Komponen dari Aggregate yang di-deploy adalah store, baik penulis menuliskannya di tingkat teratas maupun di dalam subsistem bernama data; komponen satu modul lebih dalam adalah data.store, dan data di sana adalah prefiks modul, bukan prefiks subsistem mana pun. Jadi entri boundary yang ditulis data.store untuk komponen yang berada di subsistem bernama data tidak menunjuk apa pun: entri itu sendiri berhenti berdasarkan aturan di atas, dan komponen yang dimaksud juga tidak menjangkau boundary mana pun. Mengoreksi entri menjadi store menyelesaikan keduanya.
Karena itu, menempatkan sub-modul memerlukan boundaries:. Bentuk single-scope tidak memiliki permukaan perutean — aggregates: adalah key dari boundary, bukan dari spec: — dan map components: tingkat teratas hanya menerima nama yang tidak terkualifikasi, sehingga Release yang men-deploy Aggregate yang mengimpor sub-modul mendeklarasikan boundaries:.
Perutean rekursif. aggregates: bersifat rekursif — setiap entri di bawah aggregates: sebuah boundary dapat mendeklarasikan map aggregates: bersarang untuk komposisi modul yang bersarang dalam.
Blok perutean per aggregate. Entri perutean menerima tepat dua key dan tidak lebih: components:, untuk mengonfigurasi komponen individual dari sub-modul tersebut, dan aggregates: bersarang untuk modul yang bersarang lebih dalam. annotations: milik boundary, dan infra: per komponen milik entri di bawah components: entri perutean itu sendiri.
Di dalam entri perutean, sebuah komponen diberi key dengan nama yang dimilikinya di dalam sub-modulnya — consumer, bukan data.consumer — karena hanya itulah namanya di sana. Path bertitik yang terkualifikasi adalah cara map components: milik boundary sendiri menyebut komponen yang sama; kedua penulisan tidak dapat saling menggantikan, dan entri perutean menolak key bertitik.
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 financeKomponen dan Features milik sub-aggregate tidak dideklarasikan ulang di Release — Release merutekannya alih-alih menyatakannya kembali, dan menyebut salah satunya hanya untuk mengonfigurasinya.
Pengurutan temporal — syncWave per boundary
Setiap boundary dalam Release secara opsional mendeklarasikan field bilangan bulat syncWave:, yang memberi Operator kendali eksplisit atas urutan deployment tanpa menyentuh Aggregate milik Developer. Nomor wave merupakan properti boundary itu sendiri; setiap komponen yang terdapat di dalam subtree boundary mewarisi nilai wave boundary-nya saat artefak diemisikan.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: 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: {}Semantik nilai wave. syncWave: adalah bilangan bulat bertanda (positif, nol, atau negatif). Nilai default ketika field ini dihilangkan adalah 0. Nilai wave tidak diwarisi dari boundary induk — setiap boundary yang menginginkan wave non-default mendeklarasikannya secara eksplisit. Components tidak dapat menimpa wave boundary-nya (wave merupakan properti unit spasial, bukan properti komponen individual).
Emisi per provider. Compiler mengemisikan nilai wave boundary ke dalam output yang dirender dalam bentuk asli provider. Tiga bentuk dibahas di bawah ini; apa yang dilakukan wave pada setiap provider pustaka standar, termasuk terraform, ditabulasikan di providers/reference-matrix.md “What a boundary’s syncWave does on each provider”.
- Kubernetes (provider helm / helm-chart). Jika wave bukan
0, setiap resource Kubernetes yang dirender provider helm untuk boundary membawa anotasi standar GitOpsargocd.argoproj.io/sync-wave: "<N>"; hook Helm juga membawa anotasihelm.sh/hook-weight: "<N>"sehingga nilai wave yang sama menggerakkan pengurutan pre/post-install milik Helm sendiri. ArgoCD membaca anotasi sync-wave dan Helm membaca weight sebuah hook, dan masing-masing mengurutkan penerapan resource sesuai dengannya. Provider helm-chart menyalin templat chart sumber sebagaimana ditulis oleh penulisnya, sehingga resource milik sub-chart itu sendiri membawa wave hanya jika templat tersebut menuliskannya; artefak yang dimuat melalui$import:yang ditambahkannya membawaargocd.argoproj.io/sync-wavedan tidak membawahelm.sh/hook-weight(lihatproviders/helm-chart.md). - Compose. Setiap service dalam file compose tempat sebuah boundary dirender menunggu, melalui
depends_on, service dari wave tepat sebelumnya yang berkontribusi ke file yang sama — dengan syarat kesehatan target jika target mendeklarasikanhealthcheck, dan dengan syarat target telah dimulai jika tidak. Jadi wave mengurutkan service dalam satu file dan tidak ada yang di luarnya: boundary yang dirender ke filedocker-compose.yamlterpisah adalah proyek compose terpisah, dan pengurutannya menjadi urusan operator. Edgeuses:tetap menyatakan pengurutan per edge di samping wave. Lihatproviders/compose.md. - CloudFormation. Setiap resource dalam template stack yang dirakit bergantung, melalui
DependsOn, pada resource dari wave tepat sebelumnya yang berkontribusi ke stack yang sama — sehingga wave menetapkan urutan pembuatan resource dan, secara terbalik, urutan penghapusannya. Ini bukan pengurutan kesiapan: template stack tidak memiliki konsep resource yang siap melayani.DependsOnmilik sebuah fragmen diperluas, bukan diganti. Components yang dirakit ke stack lain berada di luar jangkauan, dan pengurutan dua stack menjadi urusan operator. Lihatproviders/cloudformation.md.
Unit penulisan wave vs unit yang dapat di-deploy. Boundary adalah unit penulisan wave. Unit yang dapat di-deploy adalah jalur perakitan mana pun tempat komponen diemisikan — secara default 1:1 dengan boundary, tetapi dua boundary bersaudara yang berbagi directory: digabung menjadi satu output rakitan (satu Chart.yaml, satu docker-compose.yaml). Ketika hal itu terjadi, output rakitan dapat membawa resource dari beberapa wave; ArgoCD Application yang membacanya mengurutkan, di dalam Application tersebut, setiap resource berdasarkan anotasi sync-wave yang dibawa resource itu — pada helm setiap resource yang dirender untuk wave bukan nol, dan pada helm-chart hanya artefak yang dimuat melalui $import:, sedangkan templat milik sub-chart itu sendiri membawa apa yang ditulis penulisnya. Pengurutan lintas Application di antara jalur-jalur menjadi urusan CI operator.
Kasus penggunaan. Pengurutan wave penting setiap kali startup satu boundary bergantung pada selesainya boundary lain terlebih dahulu. Pola kanonis: boundary infra pada wave 0 (VPC + database), boundary migrations pada wave 1 (job migrasi skema), dan boundary apps pada wave 2 (aplikasi yang mengonsumsi skema yang telah dimigrasi). Tanpa wave eksplisit, ketiganya di-deploy secara bersamaan dan aplikasi mengalami crash-loop sambil menunggu migrasi selesai.
Untuk kerangka arsitektural lengkap — model eksekusi DAG, alasan menempatkan pengurutan temporal pada Release alih-alih pada Aggregate, serta perbedaan antara unit penulisan wave dan unit yang dapat di-deploy — lihat architecture/12-day-two-lifecycles.md §1.
Pemasangan Feature
Release dapat memasang Features baik pada cakupan boundary (kebijakan luas) maupun pada cakupan khusus komponen (penargetan presisi), dengan eksekusi mengikuti Model Bawang 5 Tingkat yang didefinisikan di architecture/10-compilation-pipeline.md. Features yang dideklarasikan di Release menyumbangkan type, infra, dan uses; Features tersebut tidak dapat mendeklarasikan values (lihat Batasan tingkat skema di atas).
Feature yang dipasang pada boundary diberi kunci berupa nama instans yang Anda pilih, dan nama tersebut tidak boleh . atau ... Pada provider yang memberi setiap kontributor direktorinya sendiri — terraform, di bawah modules/, dan helm-chart, di bawah charts/ — berkas Feature tingkat boundary ditulis di direktori yang dinamai hanya dengan nama instans, dan tidak satu pun dari kedua nama tersebut merupakan direktori tersendiri: build berhenti, dengan menyebutkan Release, boundary, dan instansnya. Nama yang sekadar mengandung titik, seperti audit.v2, adalah nama biasa.
features: adalah satu-satunya permukaan pemasangan Release, pada kedua cakupan — sebagaimana pada Aggregate. Kredensial adalah Feature yang membawa label feature.aggrega.ai/kind: secret, sehingga kredensial yang dipasang oleh Operator dipasang di bawah features: seperti Feature lainnya, dan menyebutkan secret-nya di infra persis seperti kredensial pada koneksi (lihat Konfigurasi koneksi per edge) — pada komponen yang dibiarkan Aggregate tanpa kredensial, atau sebagai penentuan ukuran untuk pemasangan yang dideklarasikan Aggregate tanpa menyebutkan secret. Tidak ada kata kunci pemasangan kedua pada cakupan mana pun; dokumen yang mendeklarasikannya ditolak saat dimuat dengan galat envelope yang menyebutkan properti yang tidak terduga tersebut.
Feature yang dipasang di seluruh boundary dapat membawa blok uses:, dan blok tersebut diproyeksikan ke setiap komponen yang dirutekan ke dalam boundary: setiap komponen memperoleh edge dependensi ke target yang disebutkan oleh feature tersebut dan diinjeksi dengan provides dari target-target itu. Hal ini mengekspresikan dependensi bersama satu kali di boundary — “setiap komponen dalam boundary ini berkomunikasi dengan cache / collector / message bus bersama” — alih-alih mengulang edge uses: yang sama pada setiap komponen. Pemasangan Feature tingkat subsistem di Aggregate memproyeksikan uses:-nya dengan cara yang sama ke seluruh komponen subsistem. uses adalah deklarasi pengawatan topologi, bukan nilai, sehingga diizinkan di Release. Proyeksi ini tidak bergantung pada cakupan eksekusi Feature yang dipasang: Feature yang FeatureRecipe-nya dirender satu kali per boundary tetap memproyeksikan uses:-nya per komponen, sementara sumber daya bersama itu sendiri dirender satu kali.
Feature yang dipasang pada satu komponen membawa blok uses: yang sama dan mengawatkan edge yang sama dari komponen tersebut: komponen memperoleh edge dependensi ke setiap target yang disebutkan, diinjeksi dengan provides dari target-target itu, dan edge mencatat pemasangan sebagai asalnya persis seperti bentuk seluruh boundary. Keduanya adalah satu deklarasi dengan dua jangkauan — pasang di boundary untuk mengawatkan setiap komponen di dalamnya, pasang pada komponen untuk mengawatkan komponen itu saja — dan pilihan di antara keduanya adalah soal jangkauan, bukan soal apa yang dilakukan pengawatan. Keduanya tidak menciptakan komputasi: target harus sudah menyebutkan komponen yang dideklarasikan Aggregate, dan target yang tidak demikian menghentikan build. Koneksi yang ditarik oleh Feature tidak membawa pemasangan sendiri: entrinya menerima target dan inject, dan kunci features: di sana ditolak saat Release dimuat.
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: {}Cara menuliskan target. Target edge menyebutkan komponen dari graf yang dirakit, sehingga ditulis dengan jalur bertitik yang terkualifikasi — data.store, bukan store — setiap kali target tersebut termasuk dalam sub-modul yang dirutekan. Hal itu berlaku bahkan ketika pemasangan itu sendiri berada di bawah entri perutean, yang kunci components:-nya bersifat lokal modul: kunci menyatakan komponen mana yang menjadi tempat pemasangan dan target menyatakan komponen mana yang dicapai edge, dan hanya yang kedua merupakan nama seluruh graf. Target yang ditulis dengan nama lokal modul tidak cocok dengan komponen mana pun dan berhenti dengan diagnostik yang sama seperti yang dihasilkan edge menggantung mana pun.
Release komposit dan pewarisan extends:
Sebuah Release dapat mendeklarasikan spec.extends: yang menunjuk ke Release dasar yang permukaan penulisannya diwarisi olehnya.
Referensi tersebut adalah path ke sebuah file di samping Release yang mendeklarasikannya — ./base-release.yaml, atau ../shared/base-release.yaml. Release berada di sisi deployment dan tidak diindeks katalog, sehingga referensi extends: tidak pernah di-resolve melalui katalog. Path relatif adalah satu-satunya bentuk yang diterimanya: referensi yang ditulis sebagai koordinat registri ditolak, demikian pula nama polos, masing-masing dengan bentuk path relatif disebutkan dalam diagnostik. extends: milik Manifest adalah padanan terdekat yang dibaca secara berbeda — ia menerima path relatif atau metadata.name polos dari sebuah Manifest di samping Release — sehingga kedua bentuk tidak dapat dipertukarkan, dan nama polos yang dapat di-resolve pada Manifest tidak di-resolve di sini. Setiap tautan dalam rantai dibaca dengan cara yang sama: Release induk yang disimpan di direktori lain menyebut induknya sendiri dengan path di samping dirinya, di mana pun Release yang Anda sebutkan berada, persis seperti $import: parameternya di-resolve di sampingnya. Path harus mengarah ke Release di dalam workspace, sebagaimana setiap path yang ditulis Release — atau, untuk Release yang disebutkan di luar workspace, di dalam direktori yang memuat Release tersebut, yang berlaku bagi setiap tautan rantainya: path yang naik keluar, atau yang dibawa keluar oleh sebuah tautan, ditolak sebelum file yang disebutkannya dibaca.
Compiler mengikuti rantai saat Release dimuat — menolak rantai yang kembali ke file yang sudah ada di dalamnya, rantai yang melampaui batas kedalaman, dan referensi yang tidak menunjuk apa pun — lalu melipat rantai tersebut menjadi satu Release yang ter-resolve.
Apa yang Anda warisi dapat Anda ganti per kunci. Nilai Anda yang menang, sampai ke tingkat terdalam, hingga Anda mencapai nilai yang merupakan satu kesatuan tak terbagi — skalar, list, template — yang Anda ambil atau ganti secara utuh. Anda menghapus sesuatu yang diwarisi dengan menuliskannya sebagai null. Ini adalah aturan yang sama yang diikuti oleh Component, Feature, dan Manifest yang memperluas, sehingga penulis yang sudah mengenal salah satunya sudah mengenal semuanya.
Diterapkan pada Release: boundaries digabungkan per nama boundary dan sebuah boundary per kunci, components per nama komponen, infra secara mendalam, features per nama instance lalu per pilar; uses sebuah komponen per socket lalu per koneksi, di mana target yang ditulis turunan menggantikan yang diwarisi, infra koneksi digabungkan per kunci, dan features-nya digabungkan per slot lalu per pilar dengan aturan yang sama yang diikuti features milik komponen itu sendiri; directory, subDirectory, syncWave, serta penunjuk Aggregate dan Manifest adalah skalar yang menggantikan.
Dua hal tidak ikut diwariskan:
- Identitas dan provenans. Tidak ada field
metadatayang diwarisi.metadata.environmentadalah yang perlu diperhatikan: field ini wajib bagi setiap Release dan pada dasarnya bersifat per Release, sehingga turunan dirender dengan environment-nya sendiri dalam label provenansnya, bukan environment induknya. - Penunjuk Aggregate diwarisi, bukan dapat ditimpa. Turunan tidak dapat mendeklarasikan
aggregate:— skema menolakextends:danaggregate:dalam satu dokumen — sehingga turunan men-deploy Developer Intent yang sama dengan dasarnya.
Turunan dapat menghilangkan manifest:, sehingga mewarisi milik dasarnya, atau menimpanya untuk Late Binding.
Satu bentuk routing di sepanjang rantai. boundaries: dan components: saling eksklusif dalam satu Release, dan hal itu juga berlaku di sepanjang rantai: dasar yang mendeklarasikan boundary bernama dan turunan yang mendeklarasikan komponen tingkat atas ditolak, dan diagnostiknya menyebutkan kedua file dan kedua kunci. Pilih satu bentuk routing dan gunakan sepanjang rantai.
Pola jembatan pengembangan lokal. Kasus penggunaan utamanya adalah developer yang menjalankan Aggregate produksi timnya secara lokal tanpa mem-fork Aggregate atau menduplikasi topologi boundary. Tim menerbitkan Release produksi; Release lokal melakukan extends: terhadapnya dan hanya menimpa penunjuk Manifest, menukar Recipes yang ditargetkan untuk cloud dengan padanan lokal:
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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/v1beta1kind: Releasemetadata: 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 insteadlocal-release mewarisi topologi boundary, lampiran Feature, dan override komponen dari dasarnya; developer menyimpan satu local-release.yaml dan menjalankan aggrega build --release local-release.yaml tanpa menduplikasi konfigurasi produksi apa pun.
Tulis directory: berdasarkan parameter. Karena direktori diwarisi seperti skalar lainnya, turunan yang mewarisi direktori tanpa variabel template akan dirender ke path yang sama dengan dasarnya, dan tidak ada opsi baris perintah yang mengalihkannya. Hal itu sah jika memang itu yang Anda maksud — misalnya hanya menukar Recipes untuk membandingkan output-nya — sehingga build melaporkannya dan melanjutkan alih-alih menolak. Menulis direktori berdasarkan parameter, seperti di atas, menjaga topologi di satu tempat dan tetap mengirim output setiap Release ke tempatnya sendiri.
Pelapisan parameter multi-file. Pewarisan Release adalah tempat untuk pelapisan parameter multi-file. Release dasar menyediakan set parameter umum; turunan per environment melakukan extends: terhadap dasar dan menimpa slot yang berbeda:
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifestSetiap turunan melihat parameter warisan dasarnya digabungkan dengan parameternya sendiri. Parameter bernilai map digabungkan secara mendalam dengan kunci turunan yang menang; parameter bernilai skalar diganti oleh turunan; kunci yang ditulis turunan sebagai null dihapus alih-alih diisi kosong.
Dasar dapat mengimpor parameternya dan turunan tetap dapat menimpa kunci tertentu. Dua mode penulisan yang dijelaskan pada parameters: di atas — inline, atau satu $import: — adalah aturan tentang satu dokumen, bukan tentang rantai: setiap Release di sepanjang rantai mendeklarasikan salah satu mode, dan impor masing-masing di-resolve terhadap direktori yang memuat Release tersebut sebelum rantai dilipat. Jadi dasar yang mengimpor file bersama dan turunan yang menulis beberapa kunci secara inline digabungkan per kunci, persis seperti dua blok inline:
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported fileMode error. Rantai extends: yang siklik, penunjuk induk yang hilang, dan deklarasi aggregate: di sisi turunan semuanya menghentikan pemuatan workspace dengan diagnostik eksplisit yang menyebutkan Release yang bermasalah dan pelanggaran tingkat skema. Lihat errors/fatal-halts.md untuk bentuk pesan per error.