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

Feature

Peran konseptual entitas Feature (sifat operasional modular dalam Domain 2) dijelaskan di architecture/04-entity-taxonomy.md. Perbedaan antara Features operasional dan Features kredensial (yang diberi label feature.aggrega.ai/kind: secret) dijelaskan di architecture/08-credential-model.md. Kosakata label semantik yang digunakan oleh selektor Feature dijelaskan di entities/component. Halaman ini membahas permukaan penulisan katalog Feature.

Lokasi katalog

Tidak seperti Components (yang menggunakan URI tiga segmen dengan subdirektori kategori), Features diorganisasikan secara datar: satu direktori per Feature di bawah penerbitnya, yang berisi satu direktori per versi.

aggrega-catalog/
└── feature/
└── {publisher}/ # e.g., `core`, `acme`
├── secret-value/
│ └── 1.0.0/
│ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature)
├── data-masking/
│ └── 1.0.0/
│ └── feature.yaml
└── ...

URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (misalnya, hub.aggrega.ai/feature/core/data-masking:1.0.0).

Kontrak penulisan

Features mendeklarasikan:

  • metadata.labels: Gunakan feature.aggrega.ai/kind: secret untuk menandai sebuah Feature sebagai Feature kredensial. Label tersebut adalah metadata deskriptif bagi penulis, bagi situs katalog, dan bagi pemilih label; tidak ada cabang kompilator yang membacanya, dan apa yang dihasilkan sebuah lampiran ditentukan oleh FeatureRecipe yang dipetakan Manifest untuk tipenya, bukan oleh label tersebut. Feature kredensial dan Feature biasa dilampirkan dengan cara yang sama, pada permukaan lampiran yang sama, pada cakupan apa pun. Keluarga kredensial pustaka standar terbagi menurut hasil: core/secret-value mengirimkan sebuah nilai ke dalam pipa injeksi; core/referenced-secret menamai sebuah sumber daya rahasia yang dapat direferensikan (sebuah Kubernetes Secret, sebuah secret AWS Secrets Manager, sebuah entri Vault), baik yang dibuat oleh keluaran FeatureRecipe-nya maupun yang sudah ada, dan mendeklarasikan kontrak keluaran schema.provides — name (penunjuk lokasi sumber daya yang netral terhadap penyedia) dan key (bidang data di dalamnya) — yang dibaca konsumen sebagai .features.<slot>.provides.<key> untuk mereferensikan sumber daya tersebut tanpa menurunkan ulang namanya; core/referenced-secret-set mewujudkan satu sumber daya yang membawa sekumpulan kunci data yang diberikan pemanggil dan hanya memublikasikan penunjuk lokasinya, bagi konsumen yang targetnya sudah mengetahui nama kunci yang dibacanya; core/secret-provided mengekspos nilai dari sebuah secret yang sudah ada; core/generated-secret tidak menghasilkan apa pun, karena mesin target sendiri yang membuat dan mengelola kredensial tersebut, sehingga ia tidak mendeklarasikan values maupun provides dan FeatureRecipes-nya murni pengkabelan yang tidak merender byte apa pun. Dua sumbu membedakan anggota-anggotanya: siapa yang menyediakan materialnya — penulis menuliskannya atau menyebutkan dari mana mengambilnya, atau mesin target memilikinya sepenuhnya, seperti pada core/generated-secret — dan apa yang dihasilkan lampiran, yaitu nilai yang diinjeksikan, sumber daya yang dapat direferensikan, atau tidak ada yang dirender sama sekali. Setiap anggota setara dengan anggota lainnya pada permukaan lampiran yang sama, sehingga sebuah slot kredensial selalu terikat dan yang berbeda antar-Releases adalah apa yang mengikatnya. Feature kredensial yang mendeklarasikan kontrak schema.provides mewajibkan setiap FeatureRecipe yang mengimplementasikannya untuk memublikasikan kunci-kunci tersebut — jika tidak, build akan berhenti — dan selector pada slot featuresSchema menargetkan anggota keluarga yang dibutuhkannya.
  • usesSchema (opsional): Mendeklarasikan soket topologis yang dapat dikonsumsi Feature (misalnya, soket path / key milik Feature kredensial yang menargetkan sebuah vault). Lihat architecture/13-catalog-and-registry.md §2 untuk mekanisme Split Schema.
  • schema: Memvalidasi blok values dan infra pada lampiran Feature — maksud kognitif yang dikonfigurasi Developer pada setiap lampiran di dalam Aggregate (values adalah domain Developer, dan skema Release melarang values: pada lampiran Feature) dan kapasitas yang ditentukan Operator per lingkungan di dalam Release (infra). Bidang yang mendeklarasikan default: divalidasi terhadap nilai tersebut sekaligus diisikan ke dalam pilar yang dirender ketika tidak ada yang menuliskannya; lihat Cakupan Feature dan bentuk penulisannya. Menerima JSON Schema 2020-12 yang dinyatakan dalam singkatan YAML bentuk ringkas (bawaan; lihat vocabulary/compact-form-authoring.md) atau dalam YAML JSON Schema lengkap, dengan $ref: lintas dokumen ke entri SchemaLibrary untuk bentuk bersama (lihat vocabulary/cross-document-ref.md). Sebuah daun yang membawa material rahasia mendeklarasikan sensitive: true — Features kredensial di pustaka standar menandai daun yang menyimpan material tersebut dan dengan sengaja membiarkan penunjuk lokasi yang dipublikasikannya tidak ditandai, karena nama sumber daya dan kunci data sama-sama bersifat publik. Kata kunci tersebut, beserta batas atas dari apa yang dicapai dengan mendeklarasikannya, dijelaskan di vocabulary/compact-form-authoring.md “Declaring a leaf sensitive”.
  • featuresSchema (opsional): Mendeklarasikan slot lampiran yang dibutuhkan Feature untuk operasinya sendiri — sebuah Feature mendeklarasikan slot persis seperti sebuah Component, sehingga Feature yang sendirinya membutuhkan kredensial (misalnya kunci API milik Feature sidecar Datadog) menamai titik pengikatannya alih-alih menggunakan slot milik Component induknya. Lihat Kredensial milik sebuah Feature untuk sebuah Feature yang mendeklarasikan slotnya sendiri dan sebuah FeatureRecipe yang membaca apa yang mengisinya. Setiap slot menerima bidang yang sama dengan slot featuresSchema milik Component, dengan semantik yang sama — termasuk selector opsional (pemilih label bergaya Kubernetes yang membatasi Feature mana yang boleh mengisi slot, padanan slot untuk pemilih soket usesSchema; pengisian yang labelnya tidak memenuhinya akan menghentikan build, dan pemilih dievaluasi terhadap label Feature yang dilampirkan dan tidak terhadap hal lain), sensitive opsional (menyatakan bahwa apa pun yang mengikat slot tersebut menangani material rahasia — sebuah pernyataan tentang titik pengikatan, bukan tentang pengisian tertentu), dan keterbukaan yang sama: mendeklarasikan sebuah slot tidak pernah melarang lampiran dengan nama yang tidak dideklarasikan oleh slot mana pun. Tabel bidang lengkap, deklarasi sensitivitas tingkat slot dan perbedaannya dengan deklarasi pada daun skema, serta dua bentuk yang digunakan untuk men-deploy satu entitas yang mendeklarasikan slot, semuanya terdapat di entities/component.md “Attachment Slots”.
  • appliesTo / appliesToAnyOf: Pemilih label yang mengendalikan Components mana yang dapat dilampiri Feature. Dievaluasi oleh mesin pencocokan label bawaan kompilator selama tahap analisis statis. Lihat Lampiran berbasis label di bawah dan architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” untuk referensi sintaks pemilih.
  • interoperability (opsional): Blok bersarang yang membawa conflictsWith — Features yang tidak dapat mencapai sebuah komponen bersama Feature ini. Build berhenti sebelum perenderan ketika satu komponen akhirnya membawa keduanya, pada cakupan mana pun masing-masing dilampirkan. Lihat Blok interoperability di bawah untuk penjelasan lengkapnya.

Perenderan struktural sebuah Feature terikat pada FeatureRecipe yang bersesuaian, yang memetakan antarmuka Feature ke implementasi infrastruktur yang konkret.

Pemasangan berbasis label

Dua selector applies pada skema Feature mengendalikan Components mana yang dipasangi Feature tersebut, dievaluasi oleh mesin pencocokan label bawaan compiler selama tahap analisis statis:

  • appliesTo — string label selector bergaya Kubernetes; permukaan komposisi AND. Persyaratan yang dipisahkan koma semuanya harus terpenuhi, dengan kosakata operator lengkap: key=value, key!=value, key in (v1, v2), key notin (v1, v2), key saja (label ada), !key (label tidak ada). Feature yang mendeklarasikan appliesTo: "datastore.aggrega.ai/engine=vector" hanya terpasang pada Components yang berlabel pasangan kunci-nilai yang persis sama; appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)" menyatakan “server atau worker mana pun yang tidak menyimpan data terbatas” dalam satu string selector.
  • appliesToAnyOf — permukaan komposisi OR. Daftar item selector yang cukup dipenuhi oleh satu item mana pun yang cocok. Setiap item berupa selector bentuk string (tata bahasa yang sama dengan appliesTo; persyaratan di dalam string digabungkan dengan AND) atau map kunci-nilai datar untuk pencocokan kesamaan saja. Digunakan ketika sebuah Feature cocok untuk beberapa bentuk komponen yang tidak saling terkait — misalnya, Feature observabilitas yang berlaku untuk { component.aggrega.ai/type: worker } ATAU { component.aggrega.ai/type: task } tanpa memaksa keduanya ke dalam satu string selector.

Tanpa bentuk any-of, Architect harus menduplikasi YAML Feature yang sama untuk setiap bentuk komponen tidak terkait yang cocok dengan Feature tersebut. Kedua bentuk dapat dikomposisikan: sebuah Feature dapat mendeklarasikan keduanya, dan hasilnya digabungkan dengan AND di antara kedua bentuk — string appliesTo harus terpenuhi dan setidaknya satu item appliesToAnyOf harus cocok. Selector yang dihilangkan atau kosong tidak mendeklarasikan batasan apa pun dan cocok dengan setiap himpunan label.

String selector dibaca terhadap keenam bentuk tersebut setiap kali pemasangan Feature dievaluasi, dan persyaratan di luar bentuk-bentuk itu menghentikan build alih-alih dibaca sebagai selector lain: persyaratan kosong (koma di awal, di akhir, atau ganda, atau string yang hanya berisi pemisah), kunci yang mengandung spasi atau salah satu dari =, !, (, ) dan koma, serta himpunan in ( atau notin ( yang tidak ditutup. Itulah yang menangkap kesalahan yang jika tidak akan diam-diam memilih kebalikan dari yang dimaksud: appliesTo: "!tier=frontend", yang ditulis untuk menjauhkan Feature dari frontend, ditolak karena ! hanya menamai kunci label — tier!=frontend adalah cara mengecualikan suatu nilai — dan tier in frontend ditolak, yang benar adalah tier in (frontend). Nilai adalah teks setelah operatornya, karakter apa pun yang dikandungnya, sehingga tier==frontend meminta label yang nilainya =frontend. Penghentian tersebut menyebutkan Feature, selectornya, dan persyaratan yang tidak dapat dibaca. Feature yang tidak dipasang di mana pun tidak pernah dievaluasi, sehingga selector yang salah bentuk padanya tidak dilaporkan hingga ada pemasangan yang menamainya.

Lihat architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” untuk referensi sintaks selector — tata bahasa yang diterima selector Feature sama dengan tata bahasa yang diterima selector soket usesSchema, yaitu bentuk string yang dikenal pengguna Kubernetes dari kubectl get -l.

Blok interoperability

Skema Feature mendeklarasikan blok spec.interoperability opsional yang memuat satu kontrol: Features lain mana yang dapat berdampingan dengan Feature ini pada sebuah komponen.

interoperability.conflictsWith — daftar Features yang saling eksklusif dengan Feature yang sedang didefinisikan, masing-masing ditulis dengan cara yang sama seperti type sebuah lampiran menamai sebuah Feature. Daftar ini mencegah pembuatan konfigurasi yang tidak kompatibel — misalnya, melampirkan mesh khusus TCP sekaligus proxy yang memahami HTTP pada komponen yang sama.

Build berhenti sebelum merender apa pun ketika satu komponen akhirnya membawa Feature ini dan sebuah Feature yang dinamai dalam daftarnya. Yang diperhitungkan adalah jangkauan: sebuah lampiran menjangkau komponen tempat lampiran itu ditulis, serta setiap komponen di dalam subsistem atau batas tempat lampiran itu ditulis, termasuk batas bersarang; lampiran yang ditulis pada entri komponen Release, atau yang dihasilkan oleh ekspansi berbasis anotasi, menjangkau komponennya dengan cara yang sama. Jadi, konflik yang dideklarasikan menghentikan build ketika kedua Features dilampirkan pada komponen yang sama, ketika salah satunya berada pada sebuah batas dan yang lain pada komponen di dalamnya, ketika salah satunya berada pada batas luar dan yang lain pada batas yang bersarang di dalamnya yang memuat sebuah komponen, dan ketika salah satunya berada pada sebuah subsistem dan yang lain pada komponen dalam subsistem tersebut. Dua Features yang dilampirkan pada batas bersaudara yang tidak berbagi komponen tidak pernah bertemu, dan batas yang tidak memuat komponen tidak menjangkau apa pun — keduanya tidak menghentikan build.

  • Satu deklarasi sudah cukup. Build berhenti ketika daftar salah satu Feature menamai yang lain; Feature kedua tidak perlu mencantumkan Feature pertama sebagai balasan.
  • Nama, apa pun versinya. Setiap entri dan tipe setiap lampiran dibandingkan setelah versi apa pun dihapus, sehingga entri core/fixed-replica-controller cocok dengan lampiran core/fixed-replica-controller:2.0.0, dan entri yang membawa versi cocok dengan setiap versi Feature yang dinamainya.
  • Hanya nama yang dibaca. Compiler membandingkan nama yang dideklarasikan oleh penulis Feature dengan Features yang dibawa sebuah komponen — jenis evaluasi yang sama seperti appliesTo, atas data yang ditulis oleh penulisnya. Apakah dua Features tidak kompatibel merupakan penilaian penulis, dan daftar itulah tempat penilaian tersebut dicatat.

Penghentian ini menyebutkan Feature yang daftarnya menamai yang lain, setiap tempat masing-masing dari keduanya dilampirkan — pada komponen dalam Aggregate, pada sebuah subsistem, pada batas Release beserta jalurnya, pada entri komponen Release, atau melalui ekspansi berbasis anotasi dari anotasi bernama — serta komponen tempat keduanya bertemu. Pasangan yang bertemu pada beberapa komponen dilaporkan sekali untuk masing-masing komponen. Lihat errors/fatal-halts.md untuk pesannya.

Contoh:

apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/autoscaler
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=server"
schema:
values:
metric_target: { type: string, enum: [cpu, memory, custom], required: true }
infra:
min_replicas: { type: integer, min: 1, required: true }
max_replicas: { type: integer, min: 1, required: true }
interoperability:
conflictsWith:
- core/fixed-replica-controller

Feature ini hanya dilampirkan pada Components bertipe server dan mendeklarasikan ketidakcocokan dengan Feature pengendali replika lainnya: build yang di dalamnya ada komponen yang akhirnya membawa keduanya akan berhenti sebelum merender. FeatureRecipe yang memerlukan nama komponen tempat ia dilampirkan — misalnya untuk mengarahkan autoscaler ke targetnya — membacanya dari konteks templatnya dan menuliskannya di mana pun keluarannya memerlukannya: .context.instance_id adalah identitas komponen, dan .context.rendered_name adalah nama yang diberikan provider milik komponen itu sendiri kepada sumber daya yang dirender untuknya, yaitu nama yang digunakan untuk menargetkan sebuah sumber daya — di bawah helm, nama Deployment yang dikeluarkan oleh workload hasil sintesis, dan nama rilis yang digunakan chart untuk membentuk nama-namanya sendiri.

Pewarisan melalui extends

Sebuah Feature dapat mendeklarasikan spec.extends: <feature-name> yang menunjuk ke Feature dasar yang permukaan penulisannya diwarisinya. Referensi tersebut menyebut Feature dasar berdasarkan metadata.name-nya, bukan berdasarkan koordinat registri tempat Feature tersebut dipublikasikan, dan menerima tiga bentuk versi yang sama seperti setiap referensi katalog: polos (core/queue) untuk rilis tertinggi yang tersedia, tepat (core/queue:1.0.0), atau rentang caret (core/queue:^1.0.0). Compiler menelusuri rantai induk saat katalog dimuat, memvalidasi bahwa rantai tersebut asiklik, lalu menggabungkan spec induk ke dalam anak untuk menghasilkan satu Feature yang telah di-resolve. Field yang ditulis pada anak didahulukan saat terjadi tabrakan kunci; metadata.labels dan metadata.annotations milik induk, selector appliesTo / appliesToAnyOf, blok interoperability, usesSchema, featuresSchema, serta deklarasi JSON Schema 2020-12 pada schema digabungkan ke bawah secara otomatis. Setiap field metadata lainnya adalah milik anak apa adanya, sehingga identitas dan provenans tidak pernah diwariskan.

Apa yang diwarisi oleh metadata: sebuah Feature. labels dan annotations digabungkan per kunci di sepanjang rantai, dimulai dari Feature dasar, dengan nilai Feature yang memperluas menang pada kunci yang sama — aturan yang sama dengan yang diikuti Components. Bagian metadata: lainnya tidak ikut terbawa: name, version, description, maintainers, license, repository, home dan keywords adalah milik Feature yang memperluas itu sendiri, persis seperti yang ditulis.

# Base Feature — generic message queue intent
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/queue
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=worker"
schema:
values:
qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true }
infra:
partition_count: { type: integer, min: 1 }
---
# Child Feature — Kafka-specialized variant
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/kafka-queue
version: 1.0.0
spec:
extends: core/queue:1.0.0
schema:
values:
compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }

core/kafka-queue hasil penggabungan mewarisi appliesTo dari induk, mewarisi properti values.qos dan infra.partition_count, serta menambahkan values.compression_codec di atasnya. Anak yang secara eksplisit mendeklarasikan appliesTo menimpa selector induk secara keseluruhan (penggabungan label-selector tidak bersifat mendalam — selector anak menggantikan selector induk). schema.values.qos milik anak menimpa deklarasi induk untuk properti tersebut.

Cara setiap bagian permukaan pemasangan diwariskan. Kedua bentuk selector diwariskan secara independen satu sama lain, karena keduanya saling melengkapi alih-alih saling menggantikan: setiap bentuk yang ada harus terpenuhi — string appliesTo harus cocok, dan setidaknya satu item appliesToAnyOf harus cocok — sedangkan bentuk yang tidak ada tidak membatasi apa pun. Jadi sebuah Feature dapat mengambil AND-selector dari Feature dasarnya sambil mendeklarasikan OR-set miliknya sendiri. Blok interoperability diwariskan per field — anak yang mendeklarasikan blok tersebut tanpa daftar conflictsWith tetap membawa daftar yang dideklarasikan Feature dasarnya, sedangkan anak yang mendeklarasikan conflictsWith miliknya sendiri menggantikan daftar Feature dasar alih-alih menambahkannya. Feature yang tidak mendeklarasikan satu pun dari ketiganya terpasang tepat di tempat Feature dasarnya terpasang.

Pewarisan adalah penggabungan skema, bukan pengikatan antarmuka. Rantai extends: sebuah Feature menghasilkan satu Feature yang telah di-resolve, bukan keluarga polimorfik. URI Feature dasar dari rantai tersebut bukanlah yang dirujuk oleh field feature: pada binding Manifest — Manifests mengikat berdasarkan URI Feature daun, dan skema yang telah di-resolve mencakup properti yang diwariskan. Kontrak Feature yang di-implements: oleh sebuah FeatureRecipe juga merupakan URI daun; FeatureRecipes tidak menelusuri rantai pewarisan.

aggrega pull mengambil basis. Feature basis adalah dependensi dari setiap Release yang melampirkan Feature yang memperluasnya, baik ada maupun tidak ada hal lain yang menyebutkannya. aggrega pull mengikuti setiap extends: hingga ujung rantai, mengambil dari registry basis yang tidak dimuat oleh direktori katalog mana pun, dan mencatat setiap basis di lockfile Release, dirujuk dari spec.extends milik Feature yang menyebutkannya; build membaca basis dari sana.

Mode kesalahan. Rantai extends: yang siklis, dan induk yang tidak disediakan oleh entitas katalog mana pun, menghentikan build dengan menyebut Feature tempat resolusi dimulai, Feature yang baris extends:-nya perlu dibuka, dan referensi yang dideklarasikannya. Pesannya ada di Cyclic extends on Components or Features (extends siklis pada Component atau Feature) dan An extends: chain cannot be assembled (Rantai tidak dapat disusun).

Untuk kosakata pewarisan / antarmuka yang lebih luas di seluruh Components, Features, dan Features kredensial, lihat vocabulary/inheritance-and-interface.md.

Komposabilitas: kontrak sosial kemurnian

Konvensi pustaka standar adalah satu Feature, satu fungsi internal — sidecar observabilitas adalah Feature observabilitas; sidecar proksi jaringan adalah Feature proksi jaringan; keduanya tidak digabungkan menjadi satu komposit dengan dua kepentingan yang tidak berkaitan. Konvensi ini menjaga agar setiap Features tetap dapat dikomposisikan, diberi versi secara independen, dan dilampirkan secara independen.

Compiler Go inti tidak menegakkan konvensi ini. Definisi Feature dengan kepentingan campuran sah secara sintaksis dan dikompilasi tanpa masalah. Penegakan bersifat opsional (opt-in):

  • Perusahaan yang menyusun katalog internal dapat menulis plugin linter kustom yang memeriksa definisi Feature di CI/CD dan memberi peringatan ketika label appliesTo dari satu Feature mencakup domain kapabilitas yang tidak berkaitan.
  • Penulis Feature yang mencatat, di interoperability.conflictsWith, bahwa dua Features akan tumpang tindih memilih untuk mengaktifkan pemeriksaan saat build: compiler berhenti di mana pun keduanya mencapai satu komponen. Pemeriksaan ini hanya membandingkan nama yang dideklarasikan, tidak lebih, sehingga yang ditegakkannya adalah deklarasi yang ditulis penulis, bukan konvensi kemurnian itu sendiri.

Features pustaka standar sumber terbuka mengikuti konvensi kemurnian melalui disiplin penulisan; katalog perusahaan bebas menyimpang ketika komposit yang terkait erat memang sesuai dengan model deployment.

Apa yang layak menjadi Feature, dan di mana pengaturan milik suatu produk sendiri ditempatkan

Feature adalah sebuah lampiran: ia membawa sesuatu yang dilampirkan secara sengaja oleh pengembang atau operator — sumber daya, sebuah langkah pipeline, pengkabelan — dan konvensi pustaka standar adalah bahwa Feature harus dapat dipenuhi oleh setidaknya dua produk independen. Bagian kedua itulah uji yang perlu diterapkan sebelum menulis Feature, karena portabilitas adalah apa yang dijanjikan oleh kata lampiran. Sebuah lampiran menyatakan bahwa kapabilitas tersebut dapat berpindah: lampirkan ke satu komponen, lampirkan ke komponen lain, dan realisasi setiap produk memenuhinya dengan caranya sendiri.

Kapabilitas yang hanya dimiliki oleh satu produk di lapangan adalah pengaturan milik produk itu sendiri, bukan sebuah Feature. Kapabilitas itu ditempatkan sebagai nilai yang ditulis pada permukaan milik produk tersebut, yang ditetapkan oleh penulis yang memutuskannya dalam pilar penulis itu dan dibaca berdampingan dengan semua hal lain yang mengonfigurasi produk yang sama. Menerbitkannya sebagai Feature justru menawarkan portabilitas yang tidak dapat diberikan oleh produk lain mana pun: lampiran tersebut secara konstruksi hanya menyebut satu produk, sehingga penulis yang melampirkannya ke produk berikutnya yang ia pilih akan menghadapi build yang berhenti dengan menyebut tipenya, dan Feature tersebut telah mengajarkan kapabilitas yang tidak pernah dimilikinya.

Uji ini menghitung produk di lapangan, bukan komponen di katalog ini, masing-masing dibaca dari referensi konfigurasinya sendiri yang terkini. Dua produk independen yang mengimplementasikan suatu kapabilitas membuatnya portabel, berapa pun jumlah produk tersebut yang disertakan di sini, sehingga sebuah Feature dapat dideklarasikan sebelum ada apa pun di katalog yang merealisasikannya — melampirkannya saat itu akan menghentikan build dengan menyebut tipenya — dan setiap realisasi yang disertakan adalah sebuah FeatureRecipe untuk satu produk, yang memenuhi lampiran tersebut dengan cara apa pun produk itu mengonfigurasinya.

Pinning sertifikat upstream adalah contoh kasusnya. Sebuah pin adalah kontrol atas kunci mana yang boleh disajikan oleh suatu upstream: hanya terima sertifikat yang kunci publiknya cocok dengan kunci yang disediakan oleh Release. Itu adalah pernyataan yang berbeda dari mewajibkan sertifikat upstream berantai ke trust anchor yang disediakan oleh Release, dan berbeda pula dari menyatakan apa yang dikatakan oleh subjek sertifikat — keduanya menyatakan apa yang harus dikatakan oleh sertifikat, sedangkan pin menyatakan kunci mana yang harus menjadi sertifikat itu. Beberapa gateway di sini dapat memverifikasi terhadap sebuah anchor, itulah sebabnya dataplane.aggrega.ai/upstream-tls: trust-anchor adalah nilai yang dapat dicocokkan oleh sebuah selector. Pinning adalah kapabilitas terpisah, dan setidaknya dua produk independen mengimplementasikannya untuk koneksi yang mereka buka ke suatu upstream: Tyk menerima kunci publik upstream dalam bentuk PEM, dan Envoy menerima hash darinya. Jadi kapabilitas ini adalah sebuah Feature, core/upstream-key-pinning, yang selector-nya menyebut dataplane.aggrega.ai/upstream-pinning: public-key, dan apa yang direalisasikan oleh katalog ini dijawab produk demi produk: core/gateway/tyk membawa nilai tersebut dan sebuah FeatureRecipe untuk setiap targetnya, sedangkan gateway di sini yang menyematkan Envoy hanya mengekspos pengaturan pin-nya untuk sertifikat yang disajikan klien, atau tidak sama sekali, sehingga gateway tersebut tidak membawa nilai dan lampiran ke gateway itu berhenti di selector. Sebuah pin mempersempit apa yang boleh disajikan oleh suatu upstream; ia adalah kontrol, bukan jaminan bahwa koneksi tersebut aman dalam hal lain.

Ada dua batasan pada uji ini, dan yang kedua adalah bagian yang paling mudah terlewatkan:

  • Ini adalah disiplin penulisan, bukan pemeriksaan compiler. Sebuah Feature yang mendeklarasikan opsi yang tidak diimplementasikan oleh produk mana pun tetap lolos validasi skema, linter penerbitan, maupun render — compiler tidak menafsirkan apa yang dijanjikan oleh sebuah Feature. Penilaiannya tetap berada pada penulis katalog.
  • Ketidakmampuan satu produk untuk memenuhi suatu opsi bukanlah alasan untuk menghapus opsi tersebut. Jika dua produk atau lebih menyediakan suatu kapabilitas dengan nama-nama yang dapat dikelompokkan, kapabilitas itu portabel dan Feature mempertahankannya; produk yang tidak dapat memenuhinya menolaknya. Feature yang dipangkas hingga hanya mencakup apa yang didukung oleh setiap produk hampir tidak memiliki apa pun lagi untuk dikatakan.

Cakupan Feature dan bentuk penulisannya

spec.schema milik sebuah Feature mendefinisikan bentuk values: dan infra: milik Feature itu sendiri — maksud kognitif yang dikonfigurasi Developer per pemasangan Feature di dalam Aggregate (values), yang berbeda dari angka kapasitas yang diputuskan Operator per lingkungan (infra). Pilar-pilar Feature berada di namespace-nya sendiri dan divalidasi secara terpisah dari pilar-pilar Component induknya. Ketika Developer memasang Feature autoscaler pada Component web-server di dalam Aggregate, Aggregate tersebut membawa values: milik Component (bentuk induk) ditambah values: milik Feature (bentuk maksud penskalaan — metrik mana yang mendorong penskalaan); angka kapasitas yang ditujukan bagi operator (min_replicas / max_replicas) mengalir melalui blok infra: milik Release pada pemasangan Feature tersebut.

# Aggregate fragment — Feature attachment with its own values:
components:
web-server:
type: core/web-server
values:
log_level: "info" # the Component's own values
tls_enabled: true
features:
autoscaler:
type: core/autoscaler
values:
metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)
# Release fragment — Feature attachment's infra block (operator-side capacity):
boundaries:
prod:
components:
web-server:
features:
autoscaler:
infra:
min_replicas: 2
max_replicas: 10

schema: milik Feature memvalidasi blok values: dan infra: milik pemasangan Feature itu sendiri. schema: milik Component memvalidasi milik Component sendiri. Keduanya dievaluasi secara terpisah pada tahap analisis statis; pilar pemasangan yang tidak cocok dengan schema: milik Feature menghentikan build dengan galat yang cakupannya adalah lokasi pemasangan Feature, bukan Component induknya. Yang divalidasi adalah konfigurasi efektif pemasangan tersebut — hasil penyusunan setiap cakupan yang mengonfigurasinya — sehingga nilai yang dibuat sesuai pada satu cakupan lalu ditimpa menjadi sesuatu yang tidak sah pada cakupan yang lebih sempit akan terdeteksi.

Nilai bawaan yang dideklarasikan diwujudkan ke dalam pilar yang di-render milik pemasangan. Selain validasi, default: yang dideklarasikan pada field values atau infra milik Feature diisikan ke pilar yang di-render milik pemasangan tersebut saat build untuk setiap kunci yang tidak ditulis siapa pun — sehingga templat FeatureRecipe yang membaca {{ .infra.tier }} menerima nilai yang dideklarasikan skema, bukan nilai kosong. Nilai yang diberikan penulis selalu menang, dan nilai bawaan hanya mengisi kunci yang mereka hilangkan: pemasangan yang menulis satu kunci dari skema Feature tetap menerima nilai bawaan yang dideklarasikan untuk kunci-kunci lain skema tersebut, dan objek bertingkat yang ditulis sebagian mempertahankan apa yang ditulis serta memperoleh saudara-saudaranya yang tidak ditulis.

Tiga sifat pengisian ini perlu diketahui saat menulis:

  • Nilai bawaan tidak pernah menggantikan nilai yang diberikan cakupan mana pun. Jika sebuah Feature dipasang pada lebih dari satu cakupan — misalnya batas Release dan salah satu komponennya — nilai cakupan yang lebih sempit yang berlaku, dan nilai bawaan hanya mengisi apa yang sama sekali tidak ditulis oleh cakupan mana pun.
  • Nilai bawaan mengisi pemasangan; nilai bawaan tidak pernah membuatnya. Mendeklarasikan nilai bawaan pada Feature yang tidak dipasang di mana pun tidak menyumbang apa pun ke keluaran, sehingga skema Feature tidak dapat menambahkan konfigurasi yang tidak diminta penulis mana pun.
  • Pemasangan yang dideklarasikan pada batas Release, bukan pada satu komponen, hanya mengisi infra, karena permukaan tersebut tidak membawa blok values: untuk diisi.

Karena pewujudan menggunakan resolusi skema yang sama dengan validasi, nilai bawaan yang dideklarasikan pada Feature induk menjangkau pemasangan milik turunan extends:, dan nilai bawaan yang dijangkau melalui $ref: lintas dokumen ke dalam sebuah SchemaLibrary juga diwujudkan. Nilai bawaan yang hanya dideklarasikan di dalam referensi lokal dalam dokumen #/$defs/, atau di bawah cabang allOf / oneOf / anyOf, tidak diwujudkan.

Satu konsekuensi perlu dinyatakan secara gamblang, karena validasi saja tidak akan mengungkapkannya: field required: yang juga membawa default: dipenuhi oleh nilai bawaan tersebut, sehingga menghilangkannya sah — dan nilai yang diterima oleh pemeriksaan adalah nilai yang dibawa keluaran yang di-render.

Konteks templat compiler mengekspos status instans Feature kepada FeatureRecipe yang terikat melalui field .features.<alias> (berisi .type, .resolved_version, .labels, .values, .infra, dan .provides per pemasangan). Templat di dalam FeatureRecipe membaca values: milik Feature sendiri melalui .values.<field> pada cakupan templat milik FeatureRecipe sendiri; values: milik Component induk tidak terlihat langsung oleh templat FeatureRecipe kecuali Feature secara eksplisit mendeklarasikan soket uses: ke Component induk.

Pemisahan cakupan ini membuat Features dapat disusun: Feature autoscaler tidak bergantung pada Component mana tempat ia dipasang; schema: miliknya menjelaskan maksud penskalaan otomatis apa pun induknya. values: milik Component induk adalah urusan induk; values: milik Feature adalah urusan Feature; kedua pilar tersusun tanpa membocorkan nama field melintasi batas tersebut.

Target pengikatan anotasi

Sebuah Feature tidak mendeklarasikan pengikatan anotasi sendiri; map mappings.features.annotations milik Manifest yang memuatnya. Feature berpartisipasi dalam hubungan pengikatan secara tidak langsung sebagai target perutean: setiap pengikatan menyebut satu tipe Feature melalui field feature:, dan daftar maps.infra serta maps.values milik pengikatan tersebut mendeklarasikan path bertitik ke properti spec.schema.infra.<path> dan spec.schema.values.<path> milik Feature yang disebut.

Saat pemuatan katalog, compiler memverifikasi bahwa setiap path bertitik dalam daftar maps sebuah pengikatan sesuai dengan properti yang benar-benar dideklarasikan oleh spec.schema milik Feature target pada pilar yang disebut. Pengikatan yang merutekan ke path yang tidak dideklarasikan oleh skema Feature akan menghentikan pemuatan katalog dengan OPS_ERROR yang jelas, yang menyebutkan pengikatan, Feature target, serta pilar dan path yang dilaluinya — pengikatan ditulis di Manifest, yang merupakan dokumen milik operator. Dengan demikian, penulis skema tahu bahwa setiap properti yang mereka deklarasikan di bawah spec.schema.values.<path> atau spec.schema.infra.<path> dapat dijangkau sebagai target pengikatan; sebaliknya, setiap properti yang dilalui oleh pengikatan Manifest harus ada pada skema Feature target.

Ketika anotasi di sisi Aggregate atau sisi Release cocok dengan sebuah pengikatan, compiler menyintesis attachment Feature yang payload pilarnya merutekan nilai anotasi ke path yang disebut. Attachment hasil sintesis secara struktural tidak dapat dibedakan dari attachment Feature yang dideklarasikan secara eksplisit oleh penulis pada lokasi yang sama; rendering hilir, validasi, dan konteks template FeatureRecipe semuanya mengonsumsi kedua bentuk tersebut secara seragam. Untuk bentuk pengikatan, pembagian sisi-vs-pilar, dan disiplin attachment-eksplisit-menang, lihat entities/manifest.md §“Annotation-Driven Feature Bindings”. Untuk aturan kaskade sisi Aggregate dan contoh penulisannya, lihat providers/well-known-annotations.md §“Aggregate-side annotation cascade”.

Blok assertions:

Feature.spec.assertions: adalah map opsional berisi aturan bernama yang menyatakan invarian arsitektural dari kontrak Feature — aturan lintas bidang atas values: milik Feature dan status terselesaikan dari Component yang dilampirkan. Setiap kunci adalah pengidentifikasi aturan yang muncul dalam pesan kegagalan; setiap nilai adalah isi template Go. Compiler mengevaluasinya setelah validasi skema dan sebelum FeatureRecipe yang terikat dirender, sesuai urutan penulisannya, dan aturan pertama yang gagal menghentikan build dengan pesan galat milik aturan tersebut.

spec:
appliesTo: "component.aggrega.ai/type=server"
assertions:
active-active-needs-two-replicas: |
{{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}}
{{- fail "mode=active-active requires replicas >= 2" -}}
{{- end -}}

Seperti assertion Component, assertion Feature menyatakan invarian tingkat kontrak — properti yang harus dipenuhi oleh lampiran Feature terlepas dari FeatureRecipe mana yang mengimplementasikan perenderannya. Untuk aturan lintas bidang yang bergantung pada implementasi tertentu (persyaratan plugin Wasm, keanehan chart), gunakan bidang assertions: milik FeatureRecipe sebagai gantinya. Untuk tata bahasa penulisan lengkap, konteks template, dan pembagian tanggung jawab antara assertion Feature dan FeatureRecipe, lihat templates/assertions-block.md.