Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Anotasi yang dikenal luas

Providers membaca anotasi tertentu untuk mengonfigurasi konteks khusus platform — yang ditetapkan pada batas Release atau entri komponen Release, atau dideklarasikan dalam Aggregate pada subsistem atau instance komponen. Compiler itu sendiri agnostik terhadap nilai anotasi ini — compiler meneruskannya sebagai string buram. Setiap provider mendeklarasikan anotasi mana yang dibacanya, pada cakupan mana, dan nilai bawaan apa yang berlaku ketika anotasi tersebut tidak ada. Deklarasi itu berada pada spec.provider.wellKnownAnnotations milik Plugin perenderan provider, dan sengaja dibuat sempit: sebuah provider mencantumkan suatu kunci hanya di tempat ia membacanya. Provider yang tidak membaca satu pun dari anotasi tersebut sebagai gantinya mendeklarasikan spec.provider.readsNoWellKnownAnnotations: true.

Matriks dukungan dalam bab ini dihasilkan dari deklarasi-deklarasi tersebut, pada tingkat rincian yang dibawa oleh deklarasi — per provider per jenis input, karena sebuah provider dapat membaca suatu kunci ketika menyintesis unit deployment namun tidak memiliki cara untuk membacanya ketika merender artefak yang di-vendor. Susunlah berdasarkan matriks di sini: sebuah sel menyatakan apa yang dibaca provider tersebut pada jalur tersebut, karena sebuah sel tidak dapat menyatakan apa pun yang tidak dideklarasikan provider. Deklarasi yang menyebut jenis input yang tidak dirender oleh kontrak perilaku render provider itu sendiri ditolak ketika entitas Plugin dibaca, sehingga kedua klaim tersebut tidak dapat saling bertentangan.

Kosakata yang dicadangkan adalah himpunan yang lebih luas, dan sebagai gantinya berada di dua tempat — bab ini, yang menyebut setiap kunci yang dicadangkan termasuk yang tidak dibaca oleh provider mana pun, dan himpunan prefiks yang dicadangkan yang diperiksa oleh lint publikasi.

Invarian

  1. Compiler tidak pernah menafsirkan atau memvalidasi nilai anotasi provider yang sudah dikenal: compiler membawa kunci dan nilainya melalui kaskade, dan memberi peringatan jika suatu target tidak bertindak berdasarkan kunci tersebut.
  2. Setiap provider mendokumentasikan anotasi mana yang dibacanya dan nilai default apa yang diterapkannya.
  3. Anotasi berlaku secara seragam di dalam sebuah boundary. Jika suatu nilai berbeda per komponen, nilai tersebut ditempatkan dalam anotasi tingkat komponen (yang menimpa anotasi boundary) atau dalam infra komponen.
  4. Anotasi well-known Provider tidak pernah menduplikasi label komponen. Label Component menjelaskan apa sebuah komponen itu. Anotasi boundary menjelaskan di mana sebuah komponen di-deploy.
  5. Recipes tidak menangani anotasi well-known provider. Provider menerapkan konteks penempatan (namespace, prefiks registry, service account) secara otomatis setelah Recipe menghasilkan kontennya.
  6. Prefiks aggrega.ai/ dicadangkan untuk pustaka standar. Anotasi kustom perusahaan menggunakan prefiksnya sendiri.
  7. Anotasi tingkat Component dalam Release menimpa anotasi tingkat boundary (deep-merge, komponen yang menang). Jika sebuah provider merakit keluaran beberapa boundary menjadi satu artefak, provider tersebut dapat mensyaratkan agar sebuah anotasi di-resolve secara seragam di seluruh boundary itu — provider helm-chart mengambil nama umbrella chart dari aggrega.ai/chart-name, dan bila lebih dari satu boundary berkontribusi pada chart yang sama dan me-resolve anotasi tersebut ke nilai yang berbeda, build dihentikan dengan menyebutkan boundary yang tidak sepakat, karena satu chart tidak dapat memiliki dua nama.
  8. Anotasi yang dideklarasikan Aggregate menjangkau kunci yang sama dengan prioritas di bawah anotasi Release. Kunci yang dideklarasikan pada subsistem atau pada instance komponen — dalam Aggregate itu sendiri, atau dalam modul yang diimpornya, tempat kunci itu menjangkau komponen-komponen milik modul itu sendiri — berlaku untuk komponen di mana pun Release tidak menetapkan nilai untuk kunci tersebut; jika Release menetapkannya, pada boundary atau pada entri komponen, yang diterapkan adalah nilai Release. Anotasi milik entitas katalog itu sendiri tidak pernah menetapkannya. aggrega.ai/chart-name adalah pengecualian dari jangkauan Aggregate: kunci ini menamai sebuah rakitan, bukan komponen, dan dibaca dari boundary Release yang berkontribusi padanya.

Matriks anotasi lengkap

Cara membaca matriks ini

Enam tabel kategori di bawah ini menyebutkan setiap anotasi dalam kosakata aggrega.ai/ yang dicadangkan, apa yang dikendalikannya, dan apa yang dilakukan provider bila anotasi itu tidak ada. Apakah suatu provider menerapkan suatu kunci merupakan pertanyaan yang lebih rinci, karena sebuah provider merender lebih dari satu jenis input — artefak yang di-vendor (sourced), Workload yang disintesis sendiri oleh provider (synthesized), atau artifacts: milik sebuah Recipe sebagai seluruh output sebuah node (artifacts-only) — dan sebuah kunci dapat dibaca pada salah satu jalur tersebut sementara tidak terjangkau pada jalur lain. Provider mana yang merender jenis input mana dijelaskan di ../../architecture/16-recipe-input-composition.md; apa yang diterapkan masing-masing dijelaskan di Dukungan per provider dan jenis input di bawah, yang merupakan pernyataan otoritatif halaman ini.

Setiap sel dalam kisi tersebut memuat salah satu dari tiga tingkat:

  • Diterapkan — provider menerapkan kunci tersebut pada jenis input ini, dan output yang dirender berubah secara deterministik sebagai akibatnya.
  • Diterapkan secara bersyarat — compiler mengeluarkan override yang bersifat aditif di samping artefak target alih-alih menyunting artefak itu, sehingga apakah nilainya berlaku bergantung pada apakah artefak tersebut menyediakan kunci yang cocok miliknya sendiri. Efektif dalam praktik, tetapi tidak pernah dijamin. Tidak ada provider yang mengimplementasikan sel bersyarat, dan permukaan deklarasi tidak menyediakan cara untuk menyatakannya, sehingga kisi yang dihasilkan di bawah hanya mengeluarkan dua tingkat lainnya. Tingkat ini disebutkan karena jalurnya memang ada untuk artefak yang di-vendor, dan kosakata dua tingkat akan memaksa matriks ini mengklaim jaminan yang tidak dapat diberikannya atau menyangkal bahwa jalur itu ada sama sekali.
  • Tidak diterapkan — tidak ada provider yang menerapkan kunci tersebut pada jalur ini: target tidak memiliki slot render untuknya di sana, sehingga mekanisme penempatan tidak berkontribusi apa pun pada apa yang dirender, dan kolom Default pada tabel kategori menyebutkan apa yang Anda dapatkan sebagai gantinya. Nilainya tetap melewati build sebagai string opak, tanpa diubah. Tingkat ini dinamai menurut mekanismenya, bukan menurut nasib nilainya, karena keduanya merupakan pertanyaan yang berbeda dan hanya yang pertama yang dapat dijawab oleh sebuah sel: apa yang diterapkan provider merupakan properti dari slot render target tersebut, yang persis dinyatakan oleh deklarasi di balik setiap sel.

Ada dua cakupan, dan hanya salah satunya yang menjadikan jenis input sebagai sumbu yang bermakna:

  • Bercakupan node — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account, dan aggrega.ai/kubernetes-version membentuk output yang dirender milik satu komponen, yang dihasilkan oleh jalur yang dipilih jenis inputnya. Kunci-kunci ini adalah kolom kisi.
  • Bercakupan assembly dan referensi — aggrega.ai/chart-name di-resolve sekali ketika sebuah umbrella chart dirakit, dan ketiga kunci aggrega.ai/aws-* di-resolve ketika sebuah referensi melintasi boundary. Jenis input bukan sumbu bagi keduanya: nilainya dibaca pada assembly atau pada referensi, bagaimanapun setiap node yang berkontribusi dirender. Kunci-kunci ini memiliki tabel tersendiri di Kunci yang di-resolve per assembly dan per referensi.

Kategori 1 — Penempatan

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/namespacehelm (sourced, synthesized); compose (sourced, synthesized)Namespace Kubernetes (helm); nama jaringan Docker (compose)Tidak disuntikkan jika tidak ada (helm); jaringan yang dinamai menurut path file compose, dipakai bersama oleh setiap node dalam file itu yang tidak memiliki anotasi (compose)
aggrega.ai/project-namedicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk nama proyek Docker Compose—
aggrega.ai/regiondicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk region cloud pada cakupan penempatan—
aggrega.ai/account-iddicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk pengenal akun cloud pada cakupan penempatan—
aggrega.ai/kubernetes-versionhelm (sourced)Versi Kubernetes dari cluster tempat komponen di-deploy, yang dibaca oleh chart yang dirender dari sumber sebagai .Capabilities.KubeVersionVersi yang menjadi sasaran render helm template bawaan dari rilis helm yang sama: versi pustaka klien Kubernetes yang digunakan untuk membangun provider

aggrega.ai/namespace sengaja dirancang untuk dua tujuan. Anotasi ini menyatakan maksud isolasi logis yang sama — “sumber daya boundary ini berada dalam cakupan tersendiri yang dapat dialamatkan” — dalam bentuk asli setiap target: metadata.namespace Kubernetes untuk helm, nama jaringan Docker untuk compose. Penulis Recipe menetapkan satu anotasi; setiap provider mewujudkannya sesuai dengan target. Untuk kasus compose, nama jaringan di-resolve per node dari anotasi pada node tersebut, dengan path file compose sebagai cadangan bila node tidak memiliki anotasi — sehingga boundary tanpa anotasi yang berbagi satu file compose juga berbagi satu jaringan, dan aggrega.ai/namespace-lah yang memisahkannya. Mana pun dari keduanya yang menyediakan identitas, identitas itu kemudian dituliskan dalam karakter yang diterima nama jaringan compose — setiap karakter lain dituliskan sebagai escape alih-alih diganti, sehingga dua identitas yang berbeda sedikit pun tetap berada di dua jaringan, dan huruf besar-kecil identitas dipertahankan sebagaimana ditulis. Referensi provider compose mendokumentasikan penurunan ini secara lengkap, termasuk cara membaca nama yang dienkode dan konsekuensi dari penggantian nama.

aggrega.ai/kubernetes-version menyatakan properti dari cluster tempat komponen di-deploy, bukan lokasi komponen di dalamnya: templat chart memilih versi API, sebuah field, atau seluruh mekanisme berdasarkan versi yang menjadi sasaran render, dan build tidak memiliki cluster untuk ditanyai. Provider helm membaca nilai ini seperti helm template --kube-version membaca flag-nya dan menghentikan build pada nilai yang bukan versi; bila tidak ada yang disebutkan, chart dirender untuk versi yang menjadi sasaran render helm template dari rilis helm yang sama. Referensi provider helm mendokumentasikan bentuk yang diterima dan nilai default-nya.

Kategori 2 — Registry

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/image-registryhelm, compose — hanya synthesizedPrefiks registry untuk image kontainer, diterapkan pada setiap referensi image kontainer yang disintesisTanpa prefiks
aggrega.ai/image-pull-secrethelm — hanya synthesizedNama imagePullSecrets Kubernetes, digabungkan ke entri yang sudah ada pada pod yang disintesisTidak ada

Kategori 3 — Jaringan

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/cluster-domaindicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk sufiks DNS bagi penemuan layanan lintas namespace—
aggrega.ai/ingress-classdicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk IngressClass Kubernetes pada sumber daya Ingress—
aggrega.ai/service-meshdicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk anotasi injeksi sidecar mesh—

Kategori 4 — Keamanan

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/service-accounthelm — hanya synthesizedServiceAccount Kubernetes untuk Pod yang disintesis; menimpa workload.serviceAccount milik Recipe bila keduanya ditetapkanworkload.serviceAccount milik Recipe, atau tidak ditetapkan bila Recipe tidak mendeklarasikannya
aggrega.ai/pod-security-standarddicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk tingkat Pod Security Standards—
aggrega.ai/iam-roledicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk peran identitas cloud yang terikat pada sebuah workload—

Kategori 5 — Pengemasan

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/chart-namehelm-chart — per assemblyNama umbrella chartNama Aggregate dan jalur perakitan umbrella yang digabungkan — lihat Resolusi nama chart
aggrega.ai/chart-versiondicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk versi chart Helm—
aggrega.ai/stack-namedicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk stack yang dinamai secara eksplisit—
aggrega.ai/tf-backenddicadangkan; tidak dibaca oleh provider mana punDicadangkan untuk pengenal backend state Terraform—

Kategori 6 — Target cloud

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/aws-accountcloudformation — per referensi lintas boundaryAkun AWS tempat stack (boundary) di-deployAkun yang sama — referensi lintas stack diselesaikan melalui impor stack-export dalam akun yang sama
aggrega.ai/aws-regioncloudformation — per referensi lintas boundaryRegion AWS tempat stack (boundary) di-deployRegion yang sama — referensi lintas stack diselesaikan melalui impor stack-export dalam region yang sama
aggrega.ai/aws-assume-role-arncloudformation — per referensi lintas boundaryARN role IAM yang diasumsikan oleh pembacaan stack lintas akun untuk menjangkau nilai yang diekspor stack peerTidak ada role yang diberikan pada referensi lintas akun

Setiap boundary CloudFormation dirender menjadi satu stack. Ketika sebuah edge uses melintas dari satu boundary ke boundary lain, provider cloudformation perlu mengetahui letak stack peer untuk membentuk referensi: dua stack dalam akun dan region yang sama bertukar nilai melalui ekspor dan impor stack; peer di akun atau region yang berbeda memerlukan pembacaan stack-output lintas akun, secara opsional di bawah role yang diasumsikan. Anotasi ini membawa konteks penempatan tersebut. Masing-masing dibaca pada saat provider membentuk referensi semacam itu, dan diselesaikan melalui kaskade anotasi biasa pada saat itu — nilai yang ditetapkan pada komponen mengalahkan nilai yang ditetapkan pada boundary, dan nilai yang ditetapkan Release mengalahkan nilai yang dideklarasikan Aggregate. Karena itu, nilai tingkat boundary adalah cara umum untuk menyatakannya, bukan satu-satunya cara. Anotasi ini berupa string penunjuk skalar yang opak — provider meneruskannya ke referensi yang dibangunnya dan tidak pernah menyelesaikannya terhadap status AWS yang aktif; akun, region, dan role diberikan oleh Release atau dideklarasikan dalam Aggregate, dan lingkungan runtime menyelesaikan pembacaan fisik akhir. Ketika semua anotasi tidak ada, provider memperlakukan peer sebagai akun yang sama dan region yang sama serta tidak memberikan role.

Dukungan menurut provider dan jenis input

Kunci-kunci bercakupan node, per provider per jenis input. Header kolom menghilangkan prefiks aggrega.ai/ yang dimiliki setiap kunci. applied dan — membawa tingkatan yang didefinisikan di atas, dengan — berarti tidak diterapkan; n/a berarti provider sama sekali tidak merender jenis input tersebut, sehingga tidak ada jalur di sana tempat kunci dapat diterapkan atau terlewat.

ProviderJenis inputnamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Setiap provider yang didistribusikan bersama compiler memiliki baris di sini, termasuk provider yang sama sekali tidak membaca anotasi penempatan — kumpulan baris yang kosong tidak akan dapat dibedakan dari provider yang belum pernah dideskripsikan. Provider yang disediakan secara terpisah menyatakan apa yang dibacanya dengan cara yang sama dan tidak dicantumkan di sini, karena halaman yang dipublikasikan tidak dapat menyebutkan provider yang belum pernah dilihatnya.

Sebuah Recipe dapat menyatakan lebih dari satu jenis input sekaligus — misalnya workload: dengan artifacts: di sampingnya. Bacalah grid per jenis: output hasil sintesis dari node semacam itu adalah baris synthesized, dan file artefaknya adalah kasus artefak. Baris artifacts-only adalah jenis input ketika sebuah Recipe menyatakan artifacts: dan tidak ada yang lain.

Anda tidak perlu memeriksa grid untuk mengetahuinya. Menetapkan kunci yang tidak dibaca oleh target salah satu render Anda pada jenis input mana pun dari render tersebut akan menghasilkan peringatan yang menyebutkan kunci, target, dan setiap jenis input yang dinyatakan render tersebut, sehingga sel yang Anda masuki secara tidak sengaja akan memberitahukan dirinya pada saat Anda melakukan build, alih-alih menunggu Anda terpikir untuk melihat ke sini:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Pada render yang menyatakan lebih dari satu jenis input, peringatan berlaku untuk render tersebut secara keseluruhan, bukan untuk salah satu bagiannya. Karena jenis-jenis tersebut tersusun secara penjumlahan, target yang membaca kunci pada salah satu jenis saja memang menerapkannya, dan output render tersebut membawa hasilnya — sehingga tidak ada peringatan yang dimunculkan. Peringatan hanya muncul ketika setiap jenis yang dinyatakan render tersebut melewatkan kunci, dan peringatan itu menyebutkan semuanya:

warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it

Jadi, workload: di samping source: sudah cukup untuk membuat aggrega.ai/service-account berlaku pada node tersebut, dan build tidak memberikan pesan apa pun tentangnya — yang merupakan laporan yang jujur, karena nilai tersebut mencapai bagian hasil sintesis dan muncul dalam manifest yang dihasilkan.

Bacalah grid per render, bukan per komponen. Sebuah fitur yang dilampirkan ke node menghasilkan resource-nya melalui target yang disebutkan oleh FeatureRecipe miliknya sendiri, pada jenis input yang dinyatakan FeatureRecipe tersebut — sehingga fitur itu berada di barisnya sendiri dalam grid ini, yang tidak harus sama dengan baris komponen induknya. Komponen yang menyintesis Workload-nya sementara fitur yang dilampirkan menyumbangkan artifacts: di sampingnya membaca baris synthesized untuk manifest komponen itu sendiri dan baris artifacts-only untuk file lampiran, dan kunci yang diterapkan pada yang pertama dapat terlewat pada yang kedua. Peringatan mengikuti pembagian yang sama dan memberi tahu Anda tentang masing-masing secara terpisah, karena keduanya adalah file yang berbeda. Fitur yang dilampirkan ke boundary, bukan ke komponen bernama, membaca grid dengan cara yang sama.

Nilai tersebut tetap diteruskan tanpa diubah — build tidak dihentikan, karena boundary yang mencakup komponen pada target yang heterogen akan selalu memiliki render yang tidak dapat menindaklanjuti kunci tertentu, dan itu adalah Release biasa, bukan kesalahan. Anotasi boundary berkaskade, sehingga satu baris yang ditulis menghasilkan satu peringatan per render yang tidak dapat menindaklanjutinya, dan dengan cara itulah Anda melihat bagian mana dari output Anda yang terpengaruh. Peringatan ini termasuk dalam kelas unsupported-field dan dibungkam dengan flag kelas tersebut; Peringatan memuat detailnya. Dua batasan yang perlu diketahui: hanya kunci aggrega.ai/ tanpa sub-prefiks yang diperiksa, karena kunci bersub-prefiks adalah kosakata Anda sendiri, dan provider yang sama sekali tidak menyatakan klaim dukungan tidak menghasilkan peringatan, karena tidak ada yang dapat dibandingkan dengan apa yang Anda tulis. Provider yang menyatakan bahwa ia tidak membaca satu pun dari kunci ini tidak diam dengan cara itu: readsNoWellKnownAnnotations: true pada entitas Plugin miliknya adalah klaim yang tidak mencakup kunci apa pun, sehingga setiap kunci tanpa sub-prefiks yang mencapai salah satu rendernya memicu peringatan. Provider terraform mendeklarasikannya.

Mengapa artefak vendor menerapkan lebih sedikit kunci. Anotasi bercakupan node diterapkan di tempat provider memiliki slot render untuknya. Ketika provider menyintesis unit deployment sendiri, provider memiliki setiap field hasilnya, sehingga prefiks registry, pull secret, dan service account semuanya memiliki tempat untuk diletakkan. Artefak vendor — chart Helm, file compose, modul Terraform — justru membawa antarmuka konfigurasinya sendiri, dan compiler tidak membaca antarmuka tersebut, sehingga tidak dapat mengetahui kunci artefak mana yang sesuai dengan prefiks registry atau service account. Penempatan yang dikendalikan oleh panggilan render di sekitarnya tetap berlaku, itulah sebabnya aggrega.ai/namespace diterapkan pada chart yang dirender dari sumber. Penempatan yang berarti memutuskan di mana sebuah nilai berada di dalam artefak milik pihak lain tidak berlaku, dan penulis memberikannya melalui nilai artefak itu sendiri. Inilah sebabnya baris sourced jarang terisi sementara baris synthesized penuh, dan inilah bentuk yang dapat diharapkan dari setiap kunci yang ditambahkan kemudian.

Kunci yang di-resolve per perakitan dan per referensi

Empat kunci yang disertakan tidak berlingkup node, sehingga kunci-kunci tersebut berada di luar grid di atas alih-alih digabungkan ke dalamnya: jenis input bukan sumbu yang bermakna bagi kunci-kunci ini, dan memberi masing-masing satu baris per jenis input akan mengulang satu sel sebanyak tiga kali serta menyiratkan perbedaan yang tidak ada. Masing-masing mendeklarasikan lingkup boundary, dan tabel di bawah dihasilkan dari deklarasi tersebut.

AnotasiDiterapkan olehTujuanDefault
aggrega.ai/chart-namehelm-chartNama Helm chart payung yang dirakit.Nama Aggregate dan jalur perakitan chart payung — direktori keluarannya di bawah dist/, seperti boundaries/data/helm-chart — digunakan, masing-masing dienkode lalu digabungkan.
aggrega.ai/aws-accountcloudformationAkun AWS tempat stack (boundary) di-deploy. Referensi lintas boundary membacanya untuk menentukan apakah stack rekan berada di akun yang sama.Rekan diperlakukan sebagai berada di akun yang sama, dan referensi lintas stack di-resolve melalui impor stack-export di akun yang sama, bukan melalui pembacaan stack-output lintas akun.
aggrega.ai/aws-regioncloudformationRegion AWS tempat stack (boundary) di-deploy. Referensi lintas boundary membacanya untuk menentukan apakah stack rekan berada di region yang sama.Rekan diperlakukan sebagai berada di region yang sama, dan referensi lintas stack di-resolve melalui impor stack-export di region yang sama.
aggrega.ai/aws-assume-role-arncloudformationARN peran IAM yang diasumsikan oleh pembacaan stack lintas akun untuk menjangkau nilai yang diekspor oleh stack rekan.Tidak ada peran yang diberikan, dan referensi lintas akun tidak membawa assume-role.

Kapan masing-masing di-resolve, hal yang tidak dibawa oleh deklarasi itu sendiri. aggrega.ai/chart-name di-resolve sekali per perakitan chart payung, dari kaskade anotasi boundary; setiap kontributor pada satu perakitan harus me-resolve-nya ke nilai yang sama, dan ketidaksesuaian menghentikan build dengan menyebutkan boundary yang terlibat. Ketiga kunci aggrega.ai/aws-* di-resolve per referensi lintas boundary dengan prioritas komponen di atas boundary, sehingga nilai komponen mengalahkan nilai boundary; Kategori 6 di atas menjelaskan referensi yang dibentuk oleh masing-masing kunci.

Nama tercadang yang tidak dibaca provider mana pun

Sebelas kunci dalam matriks di atas ditandai tercadang; tidak dibaca provider mana pun: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name, dan aggrega.ai/tf-backend.

Menetapkan salah satu kunci ini pada Release atau dalam Aggregate tidak berpengaruh pada output yang dirender. Tidak ada provider yang membacanya, dan tidak ada default yang diterapkan atas namanya — khususnya, tidak ada sufiks DNS yang diterapkan untuk aggrega.ai/cluster-domain, sehingga Recipe yang memerlukan domain kluster harus menyediakannya sebagai nilai biasa alih-alih mengandalkan anotasi ini. Penulis Recipe yang memerlukan salah satu perilaku ini mengekspresikannya sebagai nilai Recipe atau field infra komponen.

Tidak ada provider yang mendeklarasikan kesebelas kunci ini. wellKnownAnnotations milik provider hanya mencantumkan apa yang dibacanya, sehingga tidak satu pun dari kesebelas kunci itu muncul di sana — pembaca yang membuka Plugin helm, helm-chart, compose, atau cloudformation melihat kunci yang berfungsi dan tidak ada yang lain. Itulah tujuan deklarasi yang sempit: kunci yang dideklarasikan adalah kunci yang berfungsi, dan lingkup di sampingnya menyatakan pada jalur mana.

Dua dari nama tercadang ini mirip dengan kunci yang aktif dan tidak dapat dipertukarkan dengannya. aggrega.ai/region dan aggrega.ai/account-id menamai region dan akun pada lingkup penempatan dan tidak menjangkau provider mana pun; kunci yang dibaca provider cloudformation adalah aggrega.ai/aws-region dan aggrega.ai/aws-account yang berada di namespace cloud pada Kategori 6. Jika yang Anda maksud adalah konteks penempatan lintas stack CloudFormation, tuliskan bentuk aws- — pasangan tanpa prefiks itu dicadangkan untuk mencegah tabrakan, tidak terhubung ke apa pun. Dua nama tercadang lainnya ditangani oleh permukaan lain alih-alih oleh anotasi: aggrega.ai/stack-name dicadangkan, sementara nama stack tempat boundary cloudformation dirender diturunkan secara deterministik dari identitas release dan boundary; dan peran identitas cloud suatu workload disediakan sebagai field biasa yang ditetapkan operator pada Feature yang menghasilkan binding, bukan melalui aggrega.ai/iam-role.

Nama-nama ini tetap dicadangkan, dan tetap dicantumkan di sini, karena prefiks aggrega.ai/ dicadangkan: katalog perusahaan tidak boleh menggunakan ulang salah satu kunci ini untuk maknanya sendiri, karena platform memegang kunci tersebut untuk maknanya sendiri. Matriks ini dan himpunan prefiks tercadang yang diperiksa oleh lint publikasi bersama-sama merupakan register pencadangan, dan keduanya dijaga agar memuat himpunan nama yang sama oleh pemeriksaan yang membaca keduanya dan gagal ketika keduanya berbeda. Karena itu, menuliskan salah satu dari kesebelas kunci tidak menggagalkan validasi maupun memicu aturan “jangan gunakan prefiks aggrega.ai/ polos” — kunci itu sekadar tidak berpengaruh.

Versi chart payung yang dihasilkan boundary helm-chart selalu 0.1.0; ini adalah nilai tetap, bukan default aggrega.ai/chart-version.

Catatan: binding features.annotations pada Manifest yang menggunakan prefiks aggrega.ai/ ditolak saat pemuatan; prefiks tersebut dicadangkan secara eksklusif untuk anotasi well-known provider yang didokumentasikan dalam bab ini. Penulis binding Feature berbasis anotasi menggunakan feature.aggrega.ai/ untuk pintasan pustaka standar atau domain kustom untuk pintasan perusahaan.

Catatan: null eksplisit pada anotasi Release menghapus binding yang diwarisi dari boundary atau komponen yang menimpanya (opt-out Feature berbasis anotasi). Komponen sejajar dalam boundary yang sama yang tidak melakukan opt-out tetap mempertahankan binding yang diwarisi; kunci yang tidak ada tetap mewarisi dari kaskade induk seperti biasa.

Anotasi yang ditulis di katalog dan dibaca oleh compiler

Semua yang dijelaskan di atas adalah anotasi provider: ditulis pada Release atau dideklarasikan dalam Aggregate, diteruskan oleh compiler sebagai string yang tidak ditafsirkan, dan dibaca oleh provider. Kosakata kedua yang jauh lebih kecil berjalan ke arah sebaliknya — ditulis oleh Architect pada metadata.annotations milik entitas katalog itu sendiri, dibaca oleh compiler, dan tidak pernah dilihat oleh provider. Invarian 1 di atas membahas kosakata provider dan tidak berlaku untuk anotasi ini; compiler membaca tepat kunci-kunci yang tercantum di sini dan tidak ada yang lain.

Kunci-kunci ini berada di bawah sub-prefiks <scope>.aggrega.ai/, bukan prefiks aggrega.ai/ polos, sehingga berada di luar daftar reservasi yang dimuat matriks di atas dan di luar aturan prefiks yang dicadangkan yang diterapkan lint publikasi pada kunci berprefiks polos.

AnotasiDitulis padaDibaca olehTujuan
features.aggrega.ai/requiredType.<label>metadata.annotations Componentcompiler, atas graf yang sudah finalMendeklarasikan mandat keberadaan: setiap instans Component ini harus membawa setidaknya satu lampiran yang tipenya sama dengan nilai anotasi. <label> adalah sufiks pilihan penulis yang menamai persyaratan tersebut dalam diagnostik; ini bukan nama slot dan tidak ada yang mereferensikannya. Ulangi kunci dengan label berbeda untuk mendeklarasikan beberapa mandat.

Mandat dipenuhi oleh lampiran pada cakupan mana pun — blok features: tingkat komponen atau tingkat subsistem, blok tingkat boundary atau tingkat komponen pada Release, atau ekspansi berbasis anotasi — karena mandat menguji himpunan lampiran akhir instans, bukan asal setiap lampiran. Mandat yang tidak terpenuhi menghentikan build dengan menyebut label dan tipe yang diwajibkan; nilai yang bukan URI tipe Feature, atau kunci tanpa label setelah prefiks, menghentikan build dengan diagnostik deklarasi cacat yang berbeda. Pembahasan penulisan selengkapnya, beserta perbedaan mandat dengan slot featuresSchema, ada di entities/component.md “Presence mandates”.

Label provenans yang dikeluarkan oleh provider

Anotasi di atas mengalir ke dalam build — Release atau Aggregate menulisnya, provider mengonsumsinya. Provider juga mengeluarkan sekumpulan label paralel keluar dari build, melampirkannya pada output yang dirender agar perkakas hilir dapat menelusuri sumber daya runtime kembali ke konten katalog yang menghasilkannya. Label provenans ini tidak ditulis pada Release; label tersebut diturunkan dari keadaan build itu sendiri (identitas Recipe, jalur boundary, nama aggregate, lingkungan, sync wave, versi compiler) dan dikeluarkan oleh provider pada saat render.

Set yang diemisikan provider, dilampirkan ke setiap manifest Kubernetes yang dirender provider helm, ke setiap artefak yang dimuat dengan $import: yang ditambahkan provider helm-chart ke sub-chart, dan ke setiap layanan yang diemisikan oleh compose — templat milik sub-chart helm-chart sendiri disalin sebagaimana ditulis penulisnya, sehingga templat tersebut membawa apa pun yang ditulis penulis itu:

LabelSumberEmisi
app.kubernetes.io/nameID node (atau, untuk sumber daya yang dikeluarkan FeatureRecipe, pengenal yang diturunkan untuk lampiran tersebut — lihat di bawah)Hanya helm dan helm-chart — label standar Kubernetes, tidak dikeluarkan pada layanan compose
aggrega.ai/component-idID node (atau, untuk sumber daya yang dikeluarkan FeatureRecipe, pengenal yang diturunkan untuk lampiran tersebut — lihat di bawah)Ketiga provider
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> dari Recipe penghasil (atau FeatureRecipe penghasil untuk sumber daya yang dikeluarkan FR)Ketiga provider, jika entitas penghasil memiliki nama dan versi yang ditetapkan; berupa anotasi pada helm dan helm-chart
aggrega.ai/boundary-pathJalur boundary tempat komponen dirutekanKetiga provider, jika jalur boundary tidak kosong; berupa anotasi pada helm dan helm-chart
aggrega.ai/aggregate-nameAggregate metadata.nameKetiga provider, jika ditetapkan
aggrega.ai/compiler-versionVersi compiler yang dicap pada saat buildKetiga provider, jika ditetapkan
aggrega.ai/providerProvider yang merender resource tersebutKetiga provider
aggrega.ai/provider-versionVersi provider tersebutKetiga provider
aggrega.ai/environmentRelease metadata.environmentKetiga provider — setiap Release mendeklarasikannya
aggrega.ai/sync-waveBilangan bulat syncWave per boundaryKetiga provider, jika bukan nol; berupa anotasi pada helm dan helm-chart

Nilai aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider, dan aggrega.ai/provider-version berasal dari string yang tidak diwajibkan oleh build untuk mematuhi aturan nilai label Kubernetes — sebuah Aggregate bernama imported/flow, sebuah lingkungan bernama eu/prod, versi (devel) dari build pengembangan. Pada helm dan helm-chart, setiap label ini membawa nilainya apa adanya ketika nilai tersebut sudah merupakan nilai label yang valid: huruf, angka, -, _, dan ., huruf atau angka di kedua ujung, paling banyak 63 karakter. Jika tidak, label membawa nilai yang ditulis ulang ke bentuk tersebut — setiap karakter lain menjadi -, rangkaian - diringkas menjadi satu, kedua ujung dipangkas hingga huruf atau angka, dan hasilnya dipotong menjadi paling banyak 63 karakter — dan nilai apa adanya ditambahkan sebagai anotasi di bawah kunci yang sama. Karena itu, sebuah Aggregate bernama imported/flow diberi label aggrega.ai/aggregate-name: imported-flow dan anotasi aggrega.ai/aggregate-name: imported/flow; nilai yang tidak memiliki satu pun karakter yang dipertahankan label dibawa oleh anotasi saja. Selector mencocokkan nilai label sebagaimana muncul dalam output yang dirender, dan tooling yang memerlukan nama persisnya membaca anotasi jika ada. Compose, yang nilai labelnya tidak dibatasi, membawa nilai apa adanya sebagai label.

Catatan emisi per provider

  • helm — label ditempatkan di metadata.labels pada setiap sumber daya Kubernetes yang dirender (Deployment, Service, PVC, dll.), dan kunci yang tidak dapat dibawa oleh nilai label — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave, serta nilai apa adanya dari setiap label yang ditulis ulang seperti dijelaskan di atas — di metadata.annotations. Jalur mode sourced (render Helm SDK dengan injeksi label pasca-render), mode synthesized (sintesis workload), dan artifacts: menghasilkan kumpulan yang sama.
  • helm-chart — label dan anotasi yang sama ditempatkan pada setiap artefak yang dimuat dengan $import: yang ditambahkan provider ke templates/ milik sub-chart. Templat milik chart sumber sendiri, dan artefak berkonten inline yang ditempatkan di akar sub-chart, tidak membawa satu pun di antaranya — lihat helm-chart.md.
  • compose — label ditempatkan di services.<name>.labels pada setiap layanan compose yang dikeluarkan. Mode sourced (injeksi label pasca-penggabungan pada dokumen base + valuesMapping yang telah digabungkan) dan mode synthesized (sintesis workload yang langsung menetapkan blok label layanan) sama-sama menghasilkan kumpulan yang sama. app.kubernetes.io/name yang khusus Kubernetes dihilangkan dari output compose.

Untuk sumber daya yang dikeluarkan FeatureRecipe, nilai aggrega.ai/component-id dibangun dari lampiran, bukan dari nama komponen host — untuk setiap cara FeatureRecipe dapat mengirimkan sumber daya tersebut, sehingga sumber daya suatu lampiran tidak pernah tidak dapat dibedakan berdasarkan label dari sumber daya milik komponen host sendiri. Apakah identitas itu juga menjadi dasar penamaan sumber daya tersebut bergantung pada cara pengirimannya: workload yang disintesis Aggrega dinamai berdasarkan identitas tersebut, sedangkan chart atau fragmen yang disediakan penulis lampiran mempertahankan nama rilis Helm dan prefiks file output milik komponen host, karena templat milik penulis itu sendiri dirender terhadap nama tersebut. Cara nilai itu disusun — dua pembukaannya, bagian-bagiannya dan penggabungannya dengan --, cara karakter yang tidak dapat dimuat label dituliskan, cara nilai yang terlalu panjang untuk targetnya dipendekkan, serta nama mana yang menjadi dan tidak menjadi dasarnya — tidak bergantung pada provider, sehingga dijelaskan satu kali di vocabulary/labels-and-annotations.md “Provenance labels emitted on rendered output” alih-alih diulang di sini. Halaman ini mencakup separuh lainnya: di mana label ditempatkan pada output yang dirender oleh setiap provider.

aggrega.ai/recipe-uri merujuk ke name:version milik FeatureRecipe itu sendiri, bukan identitas Recipe yang mengonsumsinya — perkakas hilir yang membaca label untuk mengidentifikasi entitas penghasil mendapatkan provenans yang benar, baik untuk output yang dikeluarkan komponen maupun yang dikeluarkan FR.

Anotasi sync-wave

Kunci aggrega.ai/sync-wave di atas dipasangkan dengan anotasi sync-wave yang dibaca oleh perangkat hilir untuk mengurutkan apa yang diterapkannya. Pada compose, kunci tersebut adalah label, yang mengekspos nilai wave untuk kueri selektor; pada helm dan helm-chart, kunci tersebut adalah anotasi, dan anotasi pasangannya menampilkan nilai di tempat yang secara konvensi dibaca oleh masing-masing perangkat.

AnotasiEmisiDikonsumsi oleh
argocd.argoproj.io/sync-wavehelm, pada setiap resource Kubernetes yang direndernya, dan helm-chart, pada setiap artefak yang dimuat dengan $import: — di mana syncWave bernilai bukan nol pada boundary yang berkontribusiUrutan sync-wave ArgoCD
helm.sh/hook-weighthanya helm, pada manifest hasil templat chart yang sudah membawa anotasi helm.sh/hook ketika syncWave bernilai bukan nolUrutan hook-weight Helm dalam satu fase hook

Emisi helm.sh/hook-weight bergantung pada jalur

Satu hal halus yang perlu diperhatikan oleh penulis chart: helm.sh/hook-weight hanya diemisikan pada manifest yang dirender melalui jalur templat chart — direktori templates/ milik chart yang dirender melalui Helm SDK. Manifest yang dihasilkan melalui jalur artefak — pada provider helm setiap entri blok artifacts: milik Recipe, berupa konten inline atau dimuat dengan $import:, dan pada helm-chart entri yang dimuat dengan $import: — membawa anotasi argocd.argoproj.io/sync-wave dan set label provenance lengkap, tetapi tidak menerima helm.sh/hook-weight — bahkan ketika artefak tersebut membawa anotasi helm.sh/hook.

Perbedaan ini bersifat struktural: helm.sh/hook dan helm.sh/hook-weight adalah primitif pengurutan runtime Helm yang berlaku untuk resource hook hasil templat chart. Artefak penulis Recipe adalah resource tambahan yang dideklarasikan pada lapisan Recipe; secara default, artefak tersebut tidak ikut serta dalam siklus hidup hook Helm.

Jika Anda memerlukan urutan hook-weight Helm pada resource hook, tulis resource tersebut sebagai templat chart di bawah direktori source: milik Recipe yang dirender provider helm, bukan sebagai entri artifacts:; templat sub-chart helm-chart disalin sebagaimana ditulis dan tidak menerima satu pun dari kedua anotasi tersebut. Templat chart tersebut akan menerima argocd.argoproj.io/sync-wave dan helm.sh/hook-weight yang sesuai dengan nilai syncWave dari boundary yang berkontribusi.

Contoh penulisan

Penempatan dan konfigurasi registri pada tingkat batas:

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
aggrega.ai/image-registry: registry.corp.com
aggrega.ai/image-pull-secret: corp-registry-creds
components:
api: {}
worker: {}

Penggantian per komponen (komponen lebih diutamakan daripada batas pada kunci anotasi yang sama):

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
components:
api: {}
legacy-thing:
annotations:
aggrega.ai/namespace: legacy-east # override — this component deploys elsewhere

Kaskade anotasi sisi Aggregate

Anotasi juga berada pada permukaan penulisan Aggregate — pada cakupan subsistem (spec.subsystems.<name>.annotations) dan pada cakupan instans komponen (spec.subsystems.<name>.components.<name>.annotations atau spec.components.<name>.annotations untuk komponen tingkat atas). Kaskade sisi Aggregate membawa anotasi yang ditulis oleh Developer turun melalui pohon subsistem ke komponen yang dikandungnya.

Aturan kaskade

Anotasi tingkat subsistem merambat ke setiap subsistem bersarang dan setiap komponen yang dikandung dalam subpohon subsistem tersebut. Anotasi tingkat yang lebih dekat menimpa anotasi tingkat yang lebih luar dengan granularitas per kunci: anotasi tingkat komponen menimpa anotasi tingkat subsistem yang diwarisi untuk kunci yang sama tanpa memengaruhi kunci saudara atau komponen saudara.

Kunci anotasi pada suatu cakupan berada dalam salah satu dari tiga keadaan:

  • Kunci tidak ada — cakupan tidak mendeklarasikan nilai untuk anotasi ini. Subsistem bersarang dan komponen yang dikandung mewarisi binding apa pun dari cakupan leluhur.
  • Nilai string — cakupan mendeklarasikan sebuah nilai. Subsistem bersarang dan komponen yang dikandung mewarisi nilai ini kecuali mereka mendeklarasikan nilainya sendiri atau memilih keluar.
  • YAML null eksplisit — cakupan menghapus binding yang diwarisi untuk kunci ini dari subpohonnya. Komponen saudara dan subsistem saudara mempertahankan pewarisan independennya; hanya subpohon cakupan yang memilih keluar yang kehilangan binding tersebut.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Anotasi Provider yang dideklarasikan di Aggregate

Kunci-kunci dalam matriks di atas juga diturunkan secara berjenjang melalui Aggregate, dan penyedia menerapkan apa yang ditinggalkan kaskade tersebut pada setiap komponen. aggrega.ai/namespace milik sebuah subsistem menempatkan setiap komponen di bawahnya; nilai milik instance komponen itu sendiri menempatkan komponen tersebut sebagai gantinya. Modul yang diimpor oleh Aggregate membawa kaskadenya sendiri: subsistem dan instance komponennya menjangkau komponen milik modul itu sendiri, dan tidak ada apa pun yang dideklarasikan oleh Aggregate pengimpor yang menjangkau ke dalam modul.

Release berada di atas Aggregate untuk setiap kunci. Jika Release menetapkan sebuah kunci untuk sebuah komponen — pada boundary-nya atau pada entri milik komponen itu sendiri — nilai milik Release yang diterapkan; jika Release tidak menetapkannya, nilai milik Aggregate yang diterapkan. Kedua sisi dilapiskan kunci demi kunci, sehingga Release yang hanya menetapkan aggrega.ai/namespace membiarkan aggrega.ai/image-registry yang dideklarasikan Aggregate tetap berlaku.

Sebuah null eksplisit dalam Release hanya menarik kembali nilai milik Release sendiri. Entri komponen yang menulis aggrega.ai/namespace: null menghapus namespace yang semestinya diserahkan oleh boundary Release-nya, dan komponen tersebut lalu mengambil nilai yang dideklarasikan Aggregate-nya — atau tidak ada nilai, jika Aggregate juga tidak mendeklarasikannya. Release tidak dapat menghapus nilai yang dideklarasikan Aggregate; Release hanya dapat menetapkan nilainya sendiri di atasnya.

# Aggregate
spec:
subsystems:
billing:
annotations:
aggrega.ai/namespace: billing # api and worker render into billing
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0
annotations:
aggrega.ai/namespace: billing-batch # worker renders into billing-batch
# Release
spec:
boundaries:
production:
components:
api:
annotations:
aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing
worker: {}

aggrega.ai/chart-name adalah satu-satunya kunci di luar jangkauan ini: kunci ini menamai umbrella chart yang dirakit dari beberapa komponen, sehingga kunci ini dibaca dari boundary Release yang berkontribusi pada chart tersebut, tidak pernah dari anotasi sebuah komponen.

Template Recipe atau FeatureRecipe membaca bucket anotasi berdasarkan nama — .context.annotations.aggregate, .context.annotations.release, dan .context.annotations.catalog masing-masing memuat apa yang ditulis oleh sisi tersebut — sehingga template yang membaca kunci penempatan dari satu bucket hanya melihat nilai dari sisi tersebut.

Partisi sisi terhadap pilar

Invarian Aggregate-as-Authoring-Surface membatasi anotasi sisi Aggregate pada pilar values. Binding anotasi Manifest mendeklarasikan jalur perutean di bawah maps.infra (perutean sisi Release) atau maps.values (perutean sisi Aggregate); anotasi sisi Aggregate yang binding-nya hanya mendeklarasikan jalur maps.infra menghentikan build dengan diagnostik yang jelas yang menyebutkan kunci anotasi, pilar yang dirutekan, dan sisi penulisan. Aturan simetris berlaku untuk sisi Release: anotasi sisi Release hanya dapat dirutekan melalui maps.infra; anotasi sisi Release terhadap binding yang hanya untuk values memicu error yang sejajar. Setiap diagnostik dicatat di bawah domain dokumen tempat nilai anotasi ditulis — [DEVELOPER_ERROR] dari Aggregate, [OPS_ERROR] dari Release — sehingga bagian awalnya menyebutkan permukaan yang perlu dibuka.

Binding yang mendeklarasikan jalur di kedua pilar merutekan subset yang kompatibel dengan sisinya pada setiap tahap: anotasi sisi Aggregate hanya memicu jalur pilar values, dan anotasi sisi Release hanya memicu jalur pilar infra. Komposisi lintas sisi — values dari Aggregate, infra dari Release — menghasilkan satu lampiran Feature per pasangan (Component, Feature) dengan kedua pilar terisi dan provenans per leaf yang mencatat sisi mana yang menyumbangkan setiap leaf.

Contoh penulisan — anotasi subsistem dirutekan ke values

# Manifest binding
spec:
mappings:
features:
type:
core/db-pool: db-pool-helm:1.0.0
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- pool # routes to values.pool
# Aggregate
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool"
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0

Setelah ekspansi anotasi, baik api maupun worker membawa lampiran Feature sintetis feature.myco/db-pool yang field values.pool-nya bernilai "shared-pool". Graf build (aggrega validate --release <release> --ir-graph) mencatat setiap leaf dengan origin: annotation, side: aggregate, dan annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.

Nilai anotasi terstruktur

Sebuah Feature dengan beberapa bidang yang dapat dikonfigurasi mengundang satu kunci anotasi yang membawa nilai untuk beberapa bidang tersebut sekaligus. Bentuk anotasi terstruktur memungkinkan satu kunci dirutekan ke beberapa jalur binding dalam satu deklarasi:

# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)
boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100

Binding Manifest mendeklarasikan perutean keempat subkunci dalam daftar maps: yang dikelompokkan per pilar:

# Manifest
spec:
mappings:
features:
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- db_name
- read_replicas
infra:
- pool_size
- max_connections

Bentuk nilai anotasi adalah salah satu dari tiga bentuk:

  • String skalar — satu nilai. Binding harus mendeklarasikan tepat satu jalur secara total; skalar dirutekan ke jalur tersebut.
  • Objek terstruktur — peta dari subkunci ke subnilai. Jalur setiap subkunci harus muncul dalam daftar maps.infra atau maps.values milik binding; subnilai dirutekan ke bidang skema Feature yang disebutkan pada pilar yang dideklarasikan.
  • YAML null eksplisit — keluar sepenuhnya dari binding yang diwarisi untuk cakupan kaskade ini.

Setiap subkunci dalam nilai terstruktur diselesaikan terhadap daftar maps milik binding secara independen. Subkunci yang tidak ada di maps.infra maupun maps.values menghentikan build dengan galat yang jelas yang menyebutkan subkunci yang bermasalah dan jalur yang dideklarasikan.

Penggabungan kaskade untuk nilai terstruktur

Anotasi terstruktur berkaskade dengan penggabungan mendalam per subkunci. Anotasi cakupan kaskade anak digabungkan dengan anotasi induk per subkunci; tingkat yang lebih dekat menimpa induk pada granularitas subkunci:

subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "data-default"
read_replicas: 3
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-override" # overrides parent at this subkey only
# read_replicas not listed → inherits 3 from parent
analytics:
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out: removes inherited subkey
# db_name not listed → inherits "data-default" from parent

Anotasi efektif setelah kaskade:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas dikeluarkan pada cakupan ini

Tingkat kaskade anak yang nilainya skalar (terhadap induk terstruktur) menggantikan sepenuhnya alih-alih digabungkan. Ketidakcocokan bentuk antar tingkat kaskade diselesaikan dengan memenangkan nilai tingkat yang lebih dekat; kompiler tidak memberi peringatan atas ketidakcocokan bentuk.

Null seluruh nilai vs null per subkunci

Kaskade membawa dua mekanisme opt-out pada granularitas yang berbeda:

# Whole-value null — opts out wholesale at this scope
components:
api:
annotations:
feature.myco/db-pool: null

Seluruh binding anotasi ditekan pada komponen ini; tidak ada lampiran Feature sintetis yang disintesis dari kunci anotasi ini pada cakupan ini. Komponen saudara tetap mempertahankan binding yang diwarisinya.

# Per-subkey null — opts out just one subkey
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-db"
read_replicas: null

Anotasi tetap berkontribusi pada cakupan ini, tetapi subkunci read_replicas ditekan. Subkunci lain (yang dideklarasikan pada cakupan ini atau diwarisi dari tingkat kaskade induk) tetap berlaku.

Panduan penulisan: gunakan null seluruh nilai untuk menonaktifkan lampiran Feature yang digerakkan anotasi pada suatu cakupan. Gunakan null per subkunci bila Anda ingin mempertahankan sebagian besar kontribusi anotasi tetapi menekan satu atau beberapa bidang tertentu.

Partisi sisi vs pilar per subkunci

Invarian Aggregate-sebagai-Permukaan-Penulisan berlaku per subkunci bila nilai anotasi terstruktur. Pilar setiap subkunci (menurut deklarasi maps milik binding) harus kompatibel dengan sisi penulisan:

  • Anotasi sisi Aggregate hanya dapat membawa subkunci yang dirutekan ke maps.values.
  • Anotasi sisi Release hanya dapat membawa subkunci yang dirutekan ke maps.infra.

Subkunci yang dirutekan ke pilar yang tidak kompatibel menghentikan build dengan galat yang jelas yang menyebutkan subkunci dan pilar tertentu. Rantai galat mengumpulkan semua subkunci yang tidak kompatibel per anotasi sebelum berhenti — operator melihat setiap masalah per siklus build alih-alih berputar dalam siklus perbaiki-build ulang-perbaiki-build ulang.

Validasi tipe per subkunci

Nilai runtime setiap subkunci divalidasi terhadap tipe yang dideklarasikan di spec.schema milik Feature target pada pilar yang dirutekan. Tipe yang didukung adalah string, integer, number, boolean, object, array, null. Subnilai yang tipe YAML-nya tidak cocok dengan tipe yang dideklarasikan skema menghentikan build dengan galat yang jelas yang menyebutkan subkunci, tipe aktual, dan tipe yang dideklarasikan.

Pencocokan tipe bersifat ketat — tanpa koersi. String "20" terhadap bidang skema bertipe integer akan menghentikan build; penulis mendeklarasikan tipe dengan benar pada skema Feature atau menggunakan anotasi skalar yang diteruskan sebagai string.

Tuas penulisan untuk validasi ketat. Properti tanpa type yang dideklarasikan di spec.schema milik Feature menerima bentuk nilai runtime apa pun, termasuk peta bersarang. Bila skema tidak mendeklarasikan batasan, build tidak mengarang batasan. Penulis yang menginginkan validasi tipe per subkunci yang ketat mendeklarasikan type pada setiap properti di spec.schema. Lapisan rendering FeatureRecipe di hilir menangani bentuk apa pun yang dibawa kontribusi anotasi.

Komposisi lintas sisi

Bila anotasi sisi Aggregate (subkunci values) dan anotasi sisi Release (subkunci infra) sama-sama menargetkan lampiran Feature yang sama pada Component yang sama, build menggabungkan kontribusinya menjadi satu lampiran Feature dengan kedua pilar terisi. Provenans per daun mencatat sumber setiap subkunci — lampiran yang disintesis membawa values.db_name yang diatribusikan ke situs penulisan Aggregate dan infra.pool_size yang diatribusikan ke situs penulisan Release.

Pola komposisi lintas sisi adalah bentuk penulisan kanonis untuk Features dengan bidang campuran niat Developer dan ukuran Operator: Aggregate mendeklarasikan pilihan kognitif (basis data mana, berapa banyak replika di tingkat aplikasi); Release mendeklarasikan ukuran fisik (seberapa besar pool, berapa banyak koneksi di tingkat infrastruktur). Satu binding Manifest mengikat keduanya dengan satu set deklarasi maps.