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

Label dan anotasi

Entitas Aggrega membawa dua mekanisme metadata yang secara struktural serupa — metadata.labels dan metadata.annotations — ditambah bidang-bidang pembawa anotasi yang tersebar di berbagai permukaan yang mengalir lintas batas dan permukaan pelekatan fitur. Enam permukaan berbeda menulis atau membawa konten anotasi/label, masing-masing dengan aturan pengaliran yang berbeda, konsumen yang berbeda, dan konvensi prefiks yang berbeda. Halaman ini mendokumentasikan permukaan-permukaan tersebut di satu tempat, mendefinisikan tiga kelompok semantik yang diekspos oleh konteks templat runtime, menyebutkan disiplin prefiks yang sebaiknya diikuti oleh penulis, dan mendokumentasikan kelima permukaan pelekatan Feature secara berdampingan agar terlihat bersama kosakata label/anotasi yang lebih luas.

Enam permukaan yang membawa anotasi dan label

Penulis menjumpai label dan anotasi pada enam permukaan yang berbeda. Masing-masing memiliki cakupan, aturan kaskade, dan konsumen yang berbeda.

#PermukaanCakupanAturan kaskadeKonsumen utama
1metadata.labels entitas katalogIdentitas per entitas (Component, Feature, Aggregate)Tidak berkaskade ke instans; dibawa pada entitas katalog itu sendiriaggrega search -l untuk Components dan Features; label Aggregate dibawa di dokumennya dan tidak ada perintah yang membacanya
2metadata.labels Component (intrinsik)Properti per instans Component (component.aggrega.ai/type dan lain-lain)Berkaskade ke .context.labels per node IR setelah mutasi label-transformPencocokan selektor (deklarasi selector: pada usesSchema, dibawa sebagai x-aggrega-selector: dalam JSON Schema yang disintesis), logika templat Recipe
3metadata.annotations ComponentSifat per instans Component yang ditulis oleh ArchitectBerkaskade ke bucket .context.annotations.catalog per node IRperan putusan tata kelola (kebijakan sifat intrinsik), logika templat Recipe
4annotations: Aggregate / SubsystemMetadata kognitif sisi AggregateBerkaskade ke bucket .context.annotations.aggregate per node IRvaluesMapping: Recipe untuk perutean kognitif
5annotations: batas ReleaseMetadata fisik sisi Ops, termasuk anotasi terkenal aggrega.ai/*Berkaskade ke bucket .context.annotations.release per node IRProviders (helm membaca aggrega.ai/namespace; compose menurunkan nama jaringan dari kunci yang sama); injectMapping: FeatureRecipe untuk perutean lintas batas
6Pengikatan features.annotations ManifestPengikatan kunci anotasi → tipe Feature dengan perutean subkunci yang dikelompokkan per pilar (maps.infra / maps.values) untuk pelekatan Feature berbasis anotasiSubfase ekspansi anotasi dalam resolusi menelusuri batas Release (dari luar ke dalam) dan subsistem Aggregate (dari luar ke dalam); penimpaan per komponen dan pengecualian null untuk seluruh nilai / per subkunci berlaku; penegakan sisi-vs-pilar menentukan pilar mana yang aktif per sisi penulisanEkspansi Feature berbasis anotasi (pelekatan Feature sintetis, dicatat dalam grafik IR dengan origin: annotation)

Permukaan 4 dan 5 berbagi bentuk YAML (sebuah map annotations: pada batas yang berkaskade) tetapi berkaskade ke bucket IR yang berbeda — perbedaan bucket adalah aturan penopang yang diekspos oleh runtime. Permukaan 6 terpisah secara struktural: ia berada pada entitas Manifest, bukan pada konten Aggregate / Release, dan konsumsinya dikendalikan oleh tahap ekspansi berbasis anotasi.

Semantik tiga bucket .context.annotations.*

Saat renderer mengevaluasi templat Recipe, field .context.annotations per node membawa tiga bucket bernama. Setiap bucket adalah map string → string datar dengan kunci berupa nama anotasi; bucket tersebut menentukan siapa yang menulis anotasi dan apa maksudnya.

  • .context.annotations.release — anotasi batas Release (Permukaan 5). Digunakan untuk mengatur realitas fisik; renderer merutekannya ke field infra: jika sesuai. Anotasi umum aggrega.ai/* berada di bucket ini.
  • .context.annotations.catalog — anotasi metadata Component (Permukaan 3). Sifat intrinsik yang tidak dapat diubah, ditulis oleh Architect; terutama dikonsumsi oleh plugin kebijakan Wasm.
  • .context.annotations.aggregate — anotasi subsistem Aggregate (Permukaan 4). Metadata kognitif; renderer merutekannya ke payload values: jika sesuai.

Pemisahan tiga bucket adalah kontrak sosial

Kompiler tidak menegakkan batas bucket. Ketiga bucket memiliki bentuk string → string datar yang sama; templat Recipe dapat membaca ketiganya, dan tidak ada yang mencegah anotasi batas Release ditafsirkan sebagai field metadata kognitif atau anotasi katalog dirutekan ke infra:. Pemisahan ini adalah disiplin penulisan, bukan jaminan kompiler.

Sasaran disiplin — apa yang dimaksudkan untuk diungkapkan oleh bucket:

  • release = “tempat komponen ini berjalan, diatur oleh Ops”
  • catalog = “apa komponen ini, ditulis oleh Architect”
  • aggregate = “apa yang dilakukan komponen ini, ditulis oleh Developer”

Jika penulis mematuhi pemisahan ini, perangkat hilir dapat membaca bucket yang tepat untuk kepentingan yang tepat. Jika penulis melanggarnya (misalnya, menaruh metadata kognitif di anotasi release karena berkas Release lebih praktis), runtime tetap berfungsi tetapi maksud bucket menjadi kabur.

Socket linter — menandai pembacaan lintas bucket

Plugin linter (saran di luar alur; lihat plugins/plugin-contract.md untuk kriteria penempatan) dapat menandai pembacaan lintas bucket ketika templat Recipe mengambil dari bucket yang maksudnya tidak sesuai dengan field yang dirutekan. Kriterianya:

  • Membaca .context.annotations.release untuk mengisi field values: — ditandai (metadata kognitif seharusnya berasal dari bucket aggregate).
  • Membaca .context.annotations.aggregate untuk mengisi field infra: — ditandai (metadata fisik seharusnya berasal dari bucket release).
  • Membaca .context.annotations.catalog untuk mengisi values: atau infra: — biasanya hanya berupa saran (anotasi katalog adalah sifat intrinsik; merutekannya ke pilar tidak lazim tetapi tidak selalu salah).

Linter publikasi tidak memiliki aturan untuk kriteria ini, dan build tidak memeriksanya; plugin linter Anda sendiri dapat melakukannya, melalui socket linter yang dijalankan aggrega lint. Disiplin ini dijaga oleh peninjau dan penulis yang mengikuti konvensi maksud bucket.

Disiplin prefiks

Kunci anotasi dan label mengikuti bentuk <namespace>/<name> yang seragam. Keluarga prefiks di bawah ini menyatakan siapa yang menulis kunci di bawah masing-masing prefiks dan bagaimana masing-masing ditegakkan — satu prefiks dicadangkan, dan build berhenti jika binding Manifest atau label keluaran Recipe mengklaim kunci baru di dalamnya; sisanya adalah konvensi katalog, tanpa apa pun yang menolak suatu kunci. Perbedaan keduanya terletak pada apakah build berhenti, jadi bacalah kolom tengah sebelum kolom lainnya.

PrefiksSiapa yang menulis kunci di siniBagaimana ditegakkanTujuanContoh
aggrega.ai/Hanya platform AggregaDicadangkan, dan ditegakkan. Platform mendefinisikan kunci di sini, dan Anda menulis kunci yang didefinisikannya — misalnya aggrega.ai/namespace pada boundary Release. Mengklaim kunci baru di dalam prefiks ini menghentikan build: baik binding features.annotations pada Manifest di bawah prefiks polos, maupun kunci label keluaran Recipe di bawahnya dalam outputLabels: atau outputComponentLabels:. Anotasi yang ditulis di bawahnya tetapi tidak didefinisikan platform tidak ditolak: build membawanya, dan jika anotasi itu berada pada Release, target yang tidak menindaklanjutinya menyatakannya dengan peringatan. Lihat errors/fatal-halts.md “A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Binding anotasi Manifest mengklaim prefiks yang dicadangkan)” dan “An output-label key uses a reserved namespace (Kunci label keluaran menggunakan namespace yang dicadangkan)”.Anotasi asli platform yang dikonsumsi langsung oleh provideraggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Pustaka standar resmiKonvensi. Tidak ada yang menolak kunci di sini; kosakata ini milik pustaka standar berdasarkan kesepakatan, bukan berdasarkan pemeriksaan.Pintasan anotasi Feature yang di-bind dalam features.annotations pada Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Pustaka standar resmiKonvensi. Tidak ada yang menolak kunci di sini.Label sifat intrinsik Component (kunci selektor component.aggrega.ai/type berada di sini)component.aggrega.ai/type
aggregate.aggrega.ai/Pustaka standar resmiKonvensi. Tidak ada yang menolak kunci di sini.Label identitas tingkat modul Aggregateaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Pustaka standar resmi, dan perusahaan dalam katalog mereka sendiriKonvensi. Tidak ada yang menolak kunci di sini.Label kapabilitas — dimensi perilaku yang menjadi dasar pembeda selektor usesSchema atau appliesTo milik Feature. <role> menamai concern tempat dimensi itu berada: baik peran komponen, maupun concern lintas yang dimiliki bersama oleh beberapa peran.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Perusahaan / komunitasTerbuka. Tulislah di bawah domain yang Anda kendalikan.Anotasi dan label kustomacme.com/billing-tier, corp/cost-center

Penulis anotasi kustom menggunakan domain yang mereka kendalikan (biasanya bergaya reverse-DNS). Menulis langsung di bawah aggrega.ai/ (tanpa sub-prefiks) dicadangkan untuk platform; binding features.annotations pada Manifest juga tidak dapat mem-bind kunci langsung di bawah aggrega.ai/ — lihat entities/manifest.md “Pencadangan prefiks aggrega.ai/”.

Menamai prefiks kapabilitas

Kunci kapabilitas berbentuk <role>.aggrega.ai/<dimension>, dan <role> adalah bagian yang memerlukan pertimbangan. Tiga aturan mengaturnya, dan aturan pertama adalah yang paling sering dipahami terbalik.

  • Namai concern-nya, bukan jenis komponen yang kebetulan pertama kali membawanya. Jika suatu dimensi menggambarkan sesuatu yang dimiliki bersama oleh beberapa jenis komponen, prefiks menamai concern bersama itu sehingga jenis berikutnya yang memerlukannya menggunakan kembali kosakata tersebut alih-alih menciptakan kosakata paralel. component.aggrega.ai/hosting adalah sebuah concern — siapa yang mengoperasikan sumber daya yang mendasarinya — dan menggambarkan database dan API model dengan kata-kata yang sama; dataplane.aggrega.ai/* menamai posisi pada jalur lalu lintas, sehingga proxy, ingress gateway, dan service mesh menggambarkan dirinya dengan cara yang sama. Dimensi yang benar-benar khusus untuk satu peran mengambil nama peran itu, seperti yang dilakukan model.aggrega.ai/capability.
  • Satu kata huruf kecil, tanpa tanda hubung, dalam prefiks. Tanda hubung tempatnya di bagian <dimension>, tempat kata majemuk terbaca wajar (request-mirroring, data-class, upstream-licensing).
  • Dimensi ditambahkan ketika sebuah selektor memerlukannya, dan setiap nilai yang dideklarasikannya memiliki komponen yang membawanya. Setiap kata di sini harus dipelajari oleh penulis katalog dan mungkin dijumpai oleh penulis Feature, sehingga sebuah dimensi layak ada jika membedakan sesuatu yang benar-benar ditanyakan oleh usesSchema atau appliesTo. Nilai yang tidak dibawa komponen mana pun lebih buruk daripada nilai yang tidak ada: selektor yang menamainya lolos parsing, tidak mencocokkan apa pun, dan tidak melaporkan apa pun — sehingga nilai yang tidak dapat ditunjukkan katalog dikeluarkan dari kosakata sampai ada komponen yang membawanya. Kunci yang nilainya merupakan pernyataan suatu estate tentang cara menggunakan komponennya sendiri, alih-alih properti produk, adalah pengecualian, dan compliance.aggrega.ai/data-class adalah kasus tersebut: kelas data suatu komponen bergantung pada cara estate menggunakan komponen itu, sehingga tidak ada Component pustaka standar yang membawa nilainya dan tidak ada socket atau Feature pustaka standar yang memilih berdasarkan nilai tersebut. Kunci dan nilainya dideklarasikan agar Components milik estate dan kebijakan yang dilampirkannya berbagi satu ejaan; selektor atau kebijakan yang menamai suatu nilai hanya cocok dalam katalog yang Components-nya membawa nilai itu. policy-data-class-route menunjukkan satu Component seperti itu dan kebijakan yang membacanya.

Pencadangan dan kunci yang didefinisikan platform bukanlah hal yang sama

Pencadangan berlaku pada root aggrega.ai/ yang polos. Setiap namespace <scope>.aggrega.ai/ di bawahnya adalah ruang kunci tersendiri yang tidak dimiliki platform, dan hal inilah yang menjaga kosakata katalog tetap dapat diperluas: katalog perusahaan dapat menulis acme.aggrega.ai/team tanpa bertentangan dengan apa pun yang dicap oleh build.

Meskipun demikian, beberapa kunci di dalam namespace terbuka tersebut didefinisikan oleh platform dan dibaca oleh build, dan hal itu tidak membuat namespace-nya dicadangkan:

  • component.aggrega.ai/type wajib ada pada metadata.labels setiap Component dan mengambil salah satu dari sekumpulan nilai tetap. Selektor mencocokkan berdasarkan kunci ini; compiler tidak bercabang berdasarkan nilai yang dimilikinya.
  • features.aggrega.ai/requiredType.<label>, yang ditulis pada metadata.annotations milik Component, menyatakan bahwa Feature dengan tipe yang dinamai harus dilampirkan. Build memeriksa mandat ini terhadap himpunan lampiran final setiap node dan berhenti jika tidak ada yang memenuhinya — lihat errors/fatal-halts.md “Required feature not attached (Feature yang diwajibkan tidak dilampirkan)”. Perhatikan bentuk jamaknya: features.aggrega.ai/ adalah namespace tersendiri, berbeda dari feature.aggrega.ai/ tunggal dalam tabel di atas, yang membawa pintasan binding Manifest.

Pahami perbedaannya seperti ini: prefiks yang dicadangkan menolak kunci yang Anda coba definisikan di dalamnya, sedangkan kunci yang didefinisikan platform adalah satu kunci bernama yang dikenali build, yang berada dalam namespace yang selebihnya bebas Anda tulisi. Setiap kunci lain di bawah component.aggrega.ai/, features.aggrega.ai/, dan lainnya adalah metadata yang dibawa build tanpa diinterpretasikan.

Satu kunci seperti itu pada metadata.annotations milik Component dibaca oleh linter publikasi standar, bukan oleh build: observability.aggrega.ai/metrics-credential menyatakan cara metrik produk diautentikasi — none, metrik disajikan tanpa kredensial; target-key, metrik menggunakan kunci yang diwajibkan Component dari setiap pemanggil; separate-token, metrik menggunakan token tersendiri. Build membawanya seperti anotasi lainnya. Linter membacanya untuk menentukan apakah kredensial koneksi scrape dibandingkan dengan kunci pemanggil target, dan mengharuskannya selaras dengan kunci provides metrics_credential_required yang dideklarasikan Component — lihat “The discipline rules” dalam cli/aggrega-lint.md.

Label provenans yang dikeluarkan pada output hasil render

Selain anotasi masuk yang dikonsumsi oleh provider, Aggrega juga mengeluarkan label provenans ke setiap manifest Kubernetes yang di-render oleh provider helm dan setiap layanan compose yang dikeluarkan, dan provider helm-chart menulis kumpulan yang sama, sebagaimana provider helm menuliskannya, pada setiap artefak yang dimuatnya dengan $import:. Kumpulan label ini memungkinkan perkakas hilir (dasbor biaya, tumpukan observabilitas, pengontrol GitOps) menelusuri kembali sumber daya runtime ke konten katalog yang menghasilkannya. Templat milik sub-chart helm-chart sendiri disalin sebagaimana ditulis penulisnya, sehingga membawa label apa pun yang ditulis penulis tersebut.

Kumpulan yang dikeluarkan provider helm dan compose — pada helm, tiga kunci ditulis sebagai anotasi, bukan label, seperti yang disebutkan tabel:

LabelSumberSelalu dikeluarkan?
app.kubernetes.io/nameIdentitas Component — nama yang Anda tulis, atau untuk komponen yang disumbangkan oleh Aggregate yang diimpor, nama berkualifikasinya dengan pemisah modul yang dituliskan secara eksplisit (lihat di bawah); atau, untuk sumber daya yang dihasilkan oleh FeatureRecipe, pengenal yang diturunkan untuk lampiran tersebutYa pada manifest Kubernetes; tidak dikeluarkan pada layanan compose (label standar ini khusus K8s)
aggrega.ai/component-idIdentitas Component — nama yang Anda tulis, atau untuk komponen yang disumbangkan oleh Aggregate yang diimpor, nama berkualifikasinya dengan pemisah modul yang dituliskan secara eksplisit (lihat di bawah); atau, untuk sumber daya yang dihasilkan oleh FeatureRecipe, pengenal yang diturunkan untuk lampiran tersebutYa
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> dari Recipe penghasil (atau FeatureRecipe penghasil untuk sumber daya yang dikeluarkan FR)Jika entitas penghasil memiliki nama dan versi yang ditetapkan; anotasi pada helm
aggrega.ai/boundary-pathJalur boundary tempat komponen dirutekanJika jalur boundary tidak kosong; anotasi pada helm
aggrega.ai/aggregate-nameAggregate metadata.nameJika ditetapkan
aggrega.ai/compiler-versionVersi compiler yang dicap pada saat buildJika ditetapkan
aggrega.ai/providerProvider yang merender sumber daya (helm, helm-chart, compose)Ya
aggrega.ai/provider-versionVersi provider tersebutYa
aggrega.ai/environmentRelease metadata.environmentYa — setiap Release mendeklarasikannya
aggrega.ai/sync-waveBilangan bulat syncWave per boundary, urutan alat GitOps menerapkan sumber dayaJika bukan nol; anotasi pada helm, di samping argocd.argoproj.io/sync-wave

Nama agregat, lingkungan, versi kompiler, serta nama dan versi penyedia adalah string yang dipilih oleh Anda atau oleh build, dan tidak satu pun dari string tersebut tunduk pada aturan nilai label Kubernetes di tempat string itu ditulis. Pada helm, setiap label tersebut membawa nilai sebagaimana ditulis jika nilai itu sudah merupakan nilai label yang valid — huruf, angka, -, _, dan ., sebuah huruf atau angka di kedua ujungnya, paling banyak 63 karakter — dan jika tidak, nilai yang ditulis ulang menjadi nilai yang valid, dengan nilai aslinya ditambahkan sebagai anotasi di bawah kunci yang sama: sebuah Aggregate bernama imported/flow diberi label aggrega.ai/aggregate-name: imported-flow dan anotasi aggrega.ai/aggregate-name: imported/flow. Nilai yang sudah sesuai tidak menambahkan anotasi. Compose membawa nilai aslinya sebagai label. Aturan penulisan ulang dinyatakan di providers/well-known-annotations.md “Label asal-usul yang dikeluarkan oleh penyedia”.

Untuk sumber daya yang dikeluarkan oleh FeatureRecipe, nilai aggrega.ai/component-id dibangun dari lampiran, bukan dari nama komponen host — untuk setiap cara FeatureRecipe dapat mengirimkan sumber daya tersebut, baik dengan menyintesis workload, mengeluarkan kumpulan artefak mandiri, maupun me-render chart atau fragmen yang disediakan penulisnya. Dengan demikian, kueri yang memilih sumber daya suatu lampiran berdasarkan identitas mengembalikan semuanya, dan tidak satu pun yang tidak dapat dibedakan dari sumber daya yang dikeluarkan sendiri oleh komponen host. Cara nilai dibangun bergantung pada tempat Feature dilampirkan; bagaimanapun juga, hasilnya adalah string label Kubernetes yang valid.

Untuk komponen yang disumbangkan oleh Aggregate yang diimpor, identitasnya adalah nama berkualifikasi komponen tersebut dengan pemisah yang menggabungkan modul dengan komponen dituliskan — data-layer.main-db dicap sebagai data-layer-zdmain-db — karena titik bukan karakter yang dapat dimuat dengan aman oleh nama sumber daya atau alamat klaster. Nama yang Anda tulis tanpa pemisah dicap byte demi byte.

Identitas menyatakan milik apa sebuah sumber daya. Itu pertanyaan yang berbeda dari apa nama sebuah sumber daya, dan untuk satu jenis pengiriman keduanya memiliki jawaban yang berbeda:

  • Jika FeatureRecipe menyintesis workload, Aggrega membangun sumber daya tersebut sendiri, sehingga juga menamainya berdasarkan identitas: identitas mencapai metadata.name, label selektor, dan nama file yang dikeluarkan, selain labelnya. Identitas ini adalah nama di dalam klaster, bukan hanya label.
  • Jika FeatureRecipe mengirimkan chart atau fragmen yang ditulis penulisnya, nama-namanya menjadi milik siapa pun yang menulisnya. Nama rilis Helm yang menjadi dasar render templat tersebut — dan prefiks pada file yang dikeluarkan oleh render itu — tetap milik komponen host. Chart lazimnya menamai sumber dayanya berdasarkan nama rilis, sehingga mengubahnya akan mengganti nama sumber daya yang dideklarasikan oleh chart itu sendiri, di klaster tempat sumber daya tersebut sudah di-deploy, karena alasan yang tidak ada hubungannya dengan chart. Label tetap memuat identitas lampiran itu sendiri, yang membuat sumber daya lampiran tetap dapat ditemukan.
  • Jika Feature dilampirkan ke boundary, tidak ada komponen host yang namanya dapat menggantikan, sehingga identitas yang disusun menjadi dasar penamaan di sana sekaligus label.

Bagaimanapun juga, nilainya disusun dari bagian-bagian yang Anda tulis, digabungkan dengan --, di belakang awalan tetap yang menyatakan yang mana di antara keduanya. Dua awalan digunakan, dan identitas komponen yang Anda tulis tidak boleh diawali dengan salah satunya — itulah yang menjaga agar nama yang Anda tulis dan nama yang disusun Aggrega tidak pernah tertukar satu sama lain.

Jika Feature dilampirkan ke komponen, bagian-bagiannya adalah awalan tetap cfr, identitas komponen tempat Feature dilampirkan, dan kunci tempat Feature dilampirkan. Feature yang dilampirkan ke komponen api di bawah mon menghasilkan cfr--api--mon. Komponen host menjadi bagian dari nilai karena satu nama Feature yang dilampirkan ke beberapa komponen mengeluarkan kumpulan sumber daya terpisah pada masing-masing, dan setiap kumpulan memerlukan identitasnya sendiri: melampirkan mon ke api dan worker menghasilkan cfr--api--mon dan cfr--worker--mon, bukan satu nilai untuk keduanya. Lampiran yang dinamai persis seperti komponen yang menjadi host-nya menghasilkan nilai yang berbeda dari nilai komponen itu sendiri karena alasan yang sama — mon yang dilampirkan ke mon menghasilkan cfr--mon--mon.

Jika Feature dilampirkan ke boundary — layanan gateway compose-bridge adalah contoh kanoniknya — bagian-bagiannya adalah awalan tetap bfr, lalu setiap segmen jalur boundary dimulai dari yang terluar, lalu nama tempat Feature dilampirkan. Feature bernama gateway pada boundary di bridge menghasilkan bfr--bridge--gateway; Feature yang sama pada boundary di prod/eu menghasilkan bfr--prod--eu--gateway.

Karakter yang tidak dapat dibawa nilai ditulis dalam bentuk uraian, bukan diganti, dan karena nilai itu merupakan nama di dalam kluster sekaligus label, nilai itu dibatasi pada karakter yang diterima setiap jenis nama sumber daya Kubernetes: huruf kecil, angka, dan tanda hubung. Jadi tanda hubung yang Anda tulis tetap tanda hubung, huruf kecil atau angka tetap apa adanya, dan apa pun selainnya — termasuk huruf kapital, yang diterima nilai label tetapi ditolak nama sumber daya — menjadi escape pendek: lampiran bernama my_zone menyumbang my-zuzone, dan komponen myApi dengan lampiran worker menghasilkan cfr--my-zx000041pi--worker. Nilai ber-escape itulah yang dipakai untuk memberi label dan memilih sumber daya lampiran di setiap target, yang dipakai untuk menamai dan menyimpan berkas workload yang disintesis lampiran, dan yang menjadi dasar penurunan nama release lampiran boundary. Huruf kapital adalah satu-satunya karakter yang ditambahkan aturan nama sumber daya pada apa yang akan diuraikan oleh label saja, sehingga nilai gabungan yang bagian-bagiannya tidak memuat huruf kapital — cfr--api--mon, bfr--prod--eu--gateway — adalah nilai yang akan dibawa oleh label saja. Karena itu, dua lampiran yang dapat Anda bedakan menghasilkan dua nilai — apa pun nama yang Anda berikan dan seberapa dalam pun boundary berada — karena -- adalah deretan yang tidak dapat dimuat oleh bagian tertulis mana pun, sehingga menggeser pembagian antarbagian mengubah nilai alih-alih bertabrakan dengannya.

Seberapa panjang nilai yang disusun boleh menjadi adalah jawaban target, bukan angka yang dipegang Aggrega: target tempat sumber daya di-render ditanya, dan nilai dipendekkan sampai target tersebut menerimanya. Nilai label Kubernetes memuat paling banyak 63 karakter, dan nama rilis Helm yang diturunkan dari identitas yang sama dibatasi lebih ketat lagi, sehingga lampiran yang sama dapat menjadi lebih pendek di bawah satu target dibandingkan di bawah target lain. Nilai yang muat dikeluarkan persis seperti yang disusun, yang merupakan kasus biasa dan kasus untuk setiap lampiran dalam katalog pustaka standar. Nilai yang tidak muat dipendekkan: setiap bagian mempertahankan awalnya, dan digest sepuluh karakter dari seluruh identitas ditambahkan di belakang penanda yang tidak dihasilkan oleh nama mana pun yang dapat Anda tulis — sehingga nilai yang dipendekkan dapat dikenali sebagai demikian dan tidak pernah dapat dibaca sebagai nilai yang muat. Karena itu, lampiran gateway yang bersarang dalam dapat di-render sebagai bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Dua nilai yang dipendekkan sangat kecil kemungkinannya untuk bertemu, dan jika terjadi, build berhenti alih-alih membiarkan keduanya berbagi nama.

Lihat errors/fatal-halts.md “The same name is derived more than once inside the output (Nama yang sama diturunkan lebih dari sekali di dalam output)” untuk pasangan mana yang menyebabkan berhenti dan cara memisahkannya.

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

Untuk detail pengeluaran per provider (di mana label ditempatkan pada output hasil render, dan bagaimana setiap provider menserialisasikannya), lihat providers/well-known-annotations.md “Provenance labels emitted by providers”.

Label output yang dideklarasikan Recipe

Selain set provenance milik compiler, penulis Recipe dapat mendeklarasikan label mereka sendiri untuk dicap pada output yang dirender oleh Recipe tersebut, melalui Recipe.spec.outputLabels:. Label ini menempuh jalur emisi yang sama dengan label provenance — label ini digabungkan ke dalam set label yang sama dan mendarat di mana pun provenance mendarat — tetapi label ini dimiliki oleh penulis, bukan oleh compiler. Penggunaan yang dimaksudkan adalah sifat realisasi: properti tentang cara sebuah Recipe tertentu merealisasikan suatu komponen (misalnya hosting: managed versus hosting: self-hosted untuk Recipe layanan terkelola versus Recipe chart yang di-host sendiri untuk tipe komponen yang sama), yang ditampilkan pada output agar perkakas biaya, kebijakan, dan inventaris dapat melakukan kueri terhadapnya.

Namespace aggrega.ai/ dan app.kubernetes.io/ dicadangkan untuk set provenance; kunci di bawah salah satu prefiks tersebut ditolak saat pemuatan — di outputLabels: dan di outputComponentLabels:, blok pendamping yang menyebutkan kunci label komponen dan mencap nilai yang dideklarasikan oleh komponen itu sendiri. Dengan demikian, set label output yang telah divalidasi selalu terpisah dari kunci provenance, sehingga keduanya tidak pernah bertabrakan pada output gabungan. Pengujiannya dilakukan pada akar polos: kunci yang memiliki cakupan seperti component.aggrega.ai/hosting berada dalam namespace tersendiri dan dapat ditulis secara literal atau dipromosikan. Penampilan per provider (objek helm dan pod-template pada sintesis; objek pada source-render dan artefak; label layanan compose; tag per sumber daya terraform pada isi artefak .tf.json) sesuai dengan penempatan provenance, dan didokumentasikan secara lengkap di halaman entitas Recipe pada bagian “Kolom outputLabels:” dan “Kolom outputComponentLabels:”.

Lampiran Feature — lima permukaan

Features dilampirkan ke Components melalui lima permukaan penulisan yang berbeda, masing-masing dengan cakupan, pengguna yang dituju, dan prioritas urutan yang berbeda dalam Model Bawang 5 Tingkat. Urutan lampiran lengkap dan Model Bawang itu sendiri didokumentasikan di architecture/10-compilation-pipeline.md; tabel di bawah ini merinci kelima permukaan tersebut secara berdampingan.

TingkatPermukaanDitulis olehCakupanAturan kaskade
1Blok features: komponen AggregateDeveloperPer instans komponen (granular)Tidak ada — langsung dari penulis
2Blok features: subsistem AggregateDeveloperCakupan subsistem (lintas bagian dalam Aggregate)Berlaku turun ke setiap komponen dalam subsistem
3Batas Release components.<id>.featuresOpsPer instans komponen (granular, sisi Ops)Tidak ada — langsung dari penulis
4Blok features: batas ReleaseOpsCakupan batas (lintas bagian dalam batas)Berlaku turun ke setiap komponen dalam batas
5Ekspansi features.annotations ManifestOperator PlatformDigerakkan anotasi (lampiran sintetis)Berlaku turun melalui pohon batas (sisi Release) atau pohon subsistem (sisi Aggregate); penimpaan per komponen dan pengecualian null per subkunci berlaku

Kelima permukaan bersifat akumulatif; lampiran yang ada di permukaan mana pun berkontribusi pada set fitur terselesaikan milik Component. Jika nama instans Feature yang sama muncul di lebih dari satu permukaan, kontribusinya digabungkan menjadi satu lampiran alih-alih saling menggantikan, dan ketidakcocokan tipe di antaranya menghentikan build dengan galat feature-merge-conflict.

Kelima permukaan ini disengaja sesuai pemisahan tanggung jawab dalam arsitektur — Developer (tingkat 1-2), Ops (tingkat 3-4), Operator Platform (tingkat 5) — dan bukan redundan. Penulis memilih permukaan yang sesuai dengan siapa pemilik lampiran dan pada cakupan apa.

Label mana yang menentukan apakah suatu Feature berlaku

Suatu Feature menyatakan di mana ia dapat dilampirkan dengan spec.appliesTo dan spec.appliesToAnyOf, dan build menilai deklarasi tersebut terhadap label final dari node tempat lampiran itu mendarat. Melampirkan Feature ke node yang labelnya tidak memenuhi deklarasi tersebut akan menghentikan build; Feature yang tidak mendeklarasikan keduanya tidak menyatakan persyaratan apa pun dan berlaku di mana saja.

Set label final disusun dalam dua langkah, dan tidak satu pun dari keduanya adalah yang paling sering diasumsikan penulis.

  1. Node mengambil labelnya dari entitas katalog Component yang disebut oleh type: miliknya. Label merupakan properti tipe komponen, bukan instansnya: Aggregate tidak dapat memberi label pada instans komponen, dan Release pun tidak. metadata.labels milik Aggregate sendiri mendeskripsikan Aggregate sebagai modul yang dapat digunakan ulang dan tidak diturunkan ke komponen di dalamnya. Jadi, dua instans dari satu tipe membawa label yang identik, dan mengubah label suatu node berarti mengubah tipe yang dirujuknya — atau mengubah entitas tipe tersebut.
  2. Lampiran label-transform kemudian dapat menulis ulang label tersebut. Jika konfigurasi workspace melampirkan plugin tata kelola dalam peran label-transform, plugin itu berjalan saat konstruksi topologi dan dapat menambah, mengubah, atau menghapus label node sebelum apa pun dinilai terhadapnya. Plugin itu tidak dapat menyentuh hal lain, sehingga label adalah satu-satunya bagian node yang dapat diubahnya — dan justru bagian itulah yang menentukan keberlakuan.

Karena itu, usulan yang dibuat berdasarkan label yang dideklarasikan satu dokumen adalah perkiraan, bukan prediksi. Membaca metadata.labels suatu entitas Component memberi tahu Anda label awal node bertipe tersebut, yang cukup sering merupakan jawaban yang benar sehingga berguna, tetapi keliru dalam dua hal spesifik: dokumen yang hanya memiliki nama yang sama dengan suatu node adalah subjek berbeda dengan label berbeda, dan lampiran label-transform dapat mengubah set tersebut terlepas dari dokumen mana pun. Alat yang menawarkan saran lampiran hanya dari sumber bekerja berdasarkan perkiraan tersebut; penilaian yang dibuat build didasarkan pada set final.

Prioritas lampiran

Jika dua kontribusi menyediakan field yang sama dari lampiran yang sama, empat aturan menentukan mana yang dibawa oleh output hasil render. Aturan-aturan ini diterapkan dalam urutan berikut, dan urutan inilah yang membuat hasilnya dapat diprediksi:

  1. Asal. Kontribusi yang ditulis secara eksplisit mengalahkan kontribusi yang digerakkan anotasi, apa pun cakupan tempat masing-masing dideklarasikan. Menuliskan suatu field dalam blok features: adalah cara penulis menimpa apa yang akan dikontribusikan anotasi, dan anotasi tidak pernah diam-diam menggeser sesuatu yang ditulis secara manual. Compiler mencatat anotasi yang ditekan di samping nilai yang menang dan melaporkannya sebagai peringatan, sehingga penimpaan tersebut terlihat dan tidak membingungkan.
  2. Kepemilikan pilar. Setiap domain mengisi pilarnya sendiri: permukaan Aggregate mengontribusikan values, permukaan Release mengontribusikan infra. Karena kedua sisi tidak pernah menulis pilar yang sama, kontribusi developer dan kontribusi operator tidak dapat memperebutkan field yang sama — tidak ada pertanyaan prioritas developer lawan operator yang perlu dijawab.
  3. Otoritas komposisi. Deklarasi dalam Aggregate yang sedang Anda deploy mengungguli deklarasi di dalam Aggregate yang dikomposisikannya, bahkan jika Aggregate yang dikomposisikan mendeklarasikannya pada cakupan yang lebih sempit. Komposisi tetap berwenang: suatu modul tidak dapat mengalahkan Aggregate yang menggunakannya hanya dengan memilih cakupan yang lebih sempit.
  4. Spesifisitas. Dalam satu tingkat penulisan dan satu pilar, cakupan yang lebih sempit menyempurnakan cakupan yang lebih luas, field demi field. Lampiran bercakupan komponen menimpa lampiran selebar subsistem atau selebar batas dengan nama instans yang sama — tetapi hanya untuk field yang benar-benar disebutkannya. Field yang tidak disertakan cakupan yang lebih sempit mempertahankan nilai dari cakupan yang lebih luas, sehingga lampiran bersama dapat menyediakan konfigurasi umum sementara satu komponen menyesuaikan satu field-nya. Dua kontribusi pada cakupan yang sama diselesaikan berdasarkan urutan penulisan, dengan yang belakangan menang, yang memungkinkan subsistem dalam menyempurnakan subsistem luar dan batas yang lebih dalam menyempurnakan batas yang lebih dangkal.

Prioritas mengatur nilai field. Prioritas tidak mengubah urutan evaluasi: urutan compiler melipat permukaan-permukaan tersebut, dan urutan ia mengeksekusi injectMapping pra-render setiap lampiran, adalah urutan lima tingkat tetap yang didokumentasikan di architecture/10-compilation-pipeline.md. Blok inject yang ditulis pada suatu lampiran mengikuti urutan evaluasi tersebut, bukan peringkat cakupan di atas, sehingga satu lampiran tidak pernah membawa dua urutan yang bersaing.

Jenis mana yang membawa metadata.labels dan metadata.annotations

metadata.labels terdapat pada Component, Feature, Aggregate, dan empat jenis pustaka; metadata.annotations pada jenis yang sama kecuali Aggregate. Manifest, Release, Recipe, FeatureRecipe, dan Plugin tidak membawa keduanya.

Ringkasan kaskade

Aturan kaskade pada keenam permukaan, sebagaimana dievaluasi oleh compiler:

  1. Label entitas katalog (Permukaan 1) tetap berada pada entitas katalog. Label ini tidak mengalir ke instans; konsumen membacanya dengan memeriksa konten katalog secara langsung.
  2. Component metadata.labels (Permukaan 2) mengalir ke .context.labels per node setelah tahap label-transform opsional pada saat konstruksi topologi.
  3. Component metadata.annotations (Permukaan 3) mengalir ke bucket .context.annotations.catalog per node.
  4. Aggregate / Subsystem annotations: (Permukaan 4) berkaskade melalui hierarki subsistem, terakumulasi dari subsistem terluar ke dalam, ke bucket .context.annotations.aggregate per node.
  5. Release boundary annotations: (Permukaan 5) berkaskade melalui hierarki boundary dari boundary terluar ke dalam, ke bucket .context.annotations.release per node.
  6. Manifest features.annotations (Permukaan 6) tidak berkaskade langsung ke data IR per node; subfase ekspansi berbasis anotasi pada tahap resolusi mengonsumsi binding tersebut untuk menyintesis lampiran Feature per node, yang dicatat oleh graf IR (--ir-graph) dengan origin: annotation. Lampiran sintetis ini secara struktural tidak dapat dibedakan dari lampiran eksplisit setelah tahap resolusi kecuali melalui provenans tersebut — lihat providers/well-known-annotations.md untuk penjelasan lengkap tentang ekspansi dan architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion” untuk mekanisme saat pemuatan katalog dan saat inspeksi.

Untuk desain kanonis anotasi berkaskade, lihat architecture/06-data-taxonomy-and-composition.md §2 (Flow 5).

Rujukan silang