Model kredensial
Satu keluarga lampiran
Kredensial di Aggrega adalah sebuah Feature. Kredensial dilampirkan pada permukaan yang sama, di bawah kata kunci yang sama, dalam bentuk yang sama seperti Feature lainnya. Di sini pengembang melampirkan kredensial basis data di Aggregate, dengan menulis lokatornya di values:
# the Aggregate — its parameters and the components' own values left outspec: components: api: type: core/compute/server db: type: core/datastore/mariadb features: root_password: # a credential Feature type: core/secret-value:1.0.0 values: key: MARIADB_ROOT_PASSWORD origin: "{{ .parameters.db_root_pass }}"dan operator melampirkan target scrape metrik ke server di Release, karena setiap input yang diterima core/prometheus-exporter — port, path, dan interval scrape — bersifat operasional, sehingga ditulis di infra:
# the Release — the api's own infra and the db's entry left outspec: components: api: features: metrics: # an operational Feature type: core/prometheus-exporter:1.0.0 infra: port: http # the named port of the api's ServiceAda satu kata kunci lampiran (features:), satu bentuk konteks render (.features.<name>, dan bentuk yang sama di bawah koneksi, .context.uses.<alias>.features.<slot>, untuk lampiran yang ditulis pada koneksi), satu urutan eksekusi, dan satu set koordinat output — untuk lampiran pada komponen, komponen tempat lampiran itu dipasang lalu nama yang digunakan untuk memasangnya, baik tata letak target membawa keduanya sebagai direktori <component>--<instance>/ di samping direktori komponen itu sendiri maupun sebagai prefiks nama file <component>--<instance>--. Yang berbeda antarlampiran adalah apa yang dihasilkannya — nilai yang diinjeksi, sumber daya yang dapat direferensikan, sidecar, identitas cloud — bukan permukaan tempat lampiran itu dideklarasikan.
Feature kredensial membawa label feature.aggrega.ai/kind: secret pada entitas katalognya. Label tersebut adalah metadata deskriptif: label itu memberi tahu pembaca, situs katalog, dan pemilih label untuk apa Feature tersebut. Tidak ada cabang kompiler yang membacanya, dan tidak ada perilaku yang bergantung padanya. Perilaku berasal dari FeatureRecipe yang dipetakan operator untuk tipe Feature tersebut.
Model mental dalam satu kalimat: hanya ada satu jenis lampiran; yang berbeda adalah apa yang dihasilkannya.
Slot dan lampiran bebas
Sebuah Component atau Feature dapat mendeklarasikan slot di featuresSchema:
spec: featuresSchema: root_password: required: true inject: [] # blackbox — the Recipe delivers it selector: "feature.aggrega.ai/kind=secret" user_password: inject: [env, file] # transparent — the developer may dictate deliveryLampiran yang nama instansnya cocok dengan slot yang dideklarasikan mengisi slot tersebut. Lampiran dengan nama lain adalah lampiran bebas: entitas tidak memintanya, dan lampiran itu dirender bersama apa pun yang diminta entitas. Skema yang dihasilkan untuk slot yang dideklarasikan tetap terbuka, sehingga mendeklarasikan satu slot tidak pernah menutup blok bagi lampiran bebas. Satu bentuk menghentikan build alih-alih dirender: lampiran yang ditulis pada komponen itu sendiri yang Feature-nya memenuhi selector dari slot yang tidak diikat oleh apa pun di sana, yaitu pengisian yang ditulis dengan nama yang salah, bukan lampiran bebas.
Dua hal yang dapat dibatasi oleh slot:
inject— mekanisme pengiriman yang dapat dipilih Workload untuk apa yang mengisi slot. Daftar kosong berarti slot kotak hitam: mekanisme Recipe sendiri yang mengirimkannya (misalnya opsiexistingSecretpada chart), dan Workload tidak boleh mereferensikannya dari kontainer.selector— string pemilih label yang harus dipenuhi oleh label Feature pengisi. Di sinilah labelkind=secretmenunjukkan gunanya: penulis entitas yang ingin slot hanya diisi oleh kredensial menyatakannya dengan pemilih, dan pemeriksaannya adalah evaluasi himpunan label yang dilakukan kompiler selama analisis statis.
Hal ketiga yang dapat dilakukan slot adalah menuntut agar pada akhirnya terikat. required: true membuat nama slot wajib: kompiler berhenti selama analisis statis ketika tidak ada yang mengikatnya, dengan diagnostik yang menyebutkan slot dan tipe komponen yang mendeklarasikannya. Tuntutan itu dievaluasi terhadap himpunan lampiran yang dimiliki komponen setelah setiap cakupan diterapkan secara berjenjang, sehingga lampiran yang disumbangkan di atas komponen mengikat slot persis seperti pengisian yang ditulis pada komponen.
Permukaan kedua menyatakan tuntutan yang berbeda. Anotasi Component yang dapat diulang features.aggrega.ai/requiredType.<label> mendeklarasikan mandat kehadiran: setidaknya satu lampiran harus membawa tipe Feature yang disebutkan anotasi, dengan nama apa pun dan pada cakupan apa pun, dan mandat yang tidak dipenuhi oleh apa pun menghentikan build selama analisis statis yang sama dengan diagnostiknya sendiri. Keduanya tidak pernah saling menggantikan — slot menanyakan apakah satu titik pengikatan bernama sudah terikat, mandat menanyakan apakah ada lampiran yang membawa tipe bernama — sehingga entitas yang memerlukan Recipe-nya untuk membaca apa yang dilampirkan mendeklarasikan slot, sedangkan entitas yang kontraknya hanya menuntut keberadaan suatu kapabilitas mendeklarasikan mandat.
Apa yang dijamin dan tidak dijamin oleh kompiler
Bagian ini adalah bagian yang menopang. Aggrega adalah kompiler ahead-of-time, dan jaminannya lebih sempit daripada yang diasumsikan pembaca dari kata “secret”.
Kompiler tidak pernah me-resolve kredensial. Kompiler tidak melakukan autentikasi ke API cloud, tidak membaca vault, dan tidak mengambil material selama aggrega build. values dan infra dari lampiran kredensial berjalan melalui graf dan masuk ke konteks render sebagai skalar opak, dan FeatureRecipe merendernya ke dalam artefak apa pun yang diharapkan platform target. Resolusi terjadi kemudian, di kluster atau pengelola state IaC, terhadap apa pun yang ditunjuk oleh artefak yang dirender.
Kompiler tidak dapat membedakan pointer dari nilai material. Kompiler agnostik terhadap makna suatu skalar (lihat 05-invariants.md). Lampiran kredensial yang lokatornya membawa koordinat penyimpanan (path, key, sebuah ARN) merender referensi ke koordinat tersebut; lampiran kredensial yang lokatornya membawa material itu sendiri merender material, apa adanya, ke dalam file output. Keduanya sah, dan kompiler memperlakukan keduanya secara identik karena tidak memiliki cara untuk membedakannya.
Jadi pernyataan jujur tentang jaminannya adalah:
Aggrega menjamin bahwa kompiler tidak melakukan resolusi apa pun. Aggrega tidak menjamin bahwa output yang dirender tidak berisi material — itu sepenuhnya bergantung pada Feature kredensial mana yang dilampirkan dan apa yang dimasukkan penulisnya, pengembang di
valuesatau operator diinfra.
Dua konsekuensi yang perlu dipahami:
- Pohon artefak yang dirender sama sensitifnya dengan lampirannya yang paling banyak membawa material. Perlakukan
dist/sesuai hal itu: jika ada lampiran yang membawa material secara inline, pohon tersebut berisi material. - Keluarga
core/secret-valuedancore/referenced-secretmilik katalog itu sendiri mencakup bentuk yang menerima nilai secara langsung. Bentuk ini ada karena deployment nyata memerlukan jalur pengembangan lokal, dan bentuk ini jujur tentang hal itu: contoh yang disertakan menggunakan placeholder yang jelas (dev-root-pw-change-me) justru agar material dalam contoh yang dirender terlihat jelas bukan kredensial sungguhan. Untuk deployment yang tidak boleh membawa material, lampirkan Feature kredensial berbasis penyimpanan yang FeatureRecipe-nya memancarkan sumber daya pengambilan (sebuahExternalSecret, sumber daya kustom pengambilan dari vault, referensi secret native provider) alih-alih yang memancarkan data.
Konvensi pustaka standar adalah bahwa kredensial diminta sebagai lampiran alih-alih ditulis ke dalam blok values, sehingga menukar pengisian pengembangan lokal dengan pengisian berbasis penyimpanan adalah perubahan Manifest, bukan pengeditan niat pengembang. Itu adalah konvensi yang diikuti katalog, bukan aturan yang ditegakkan kompiler.
Sensitivitas yang dideklarasikan
Kompiler tidak dapat membedakan pointer dari nilai material, sesuai bagian di atas — tetapi penulis dapat, dan dapat menyatakannya. Sensitivitas di Aggrega adalah anotasi pada deklarasi: penulis entitas katalog menyatakan apa yang membawa material rahasia, dan kompiler menurunkan sisanya dari pernyataan itu ditambah pengkabelan yang sudah dibangunnya. Tidak ada yang disimpulkan dari nilai, dan tidak ada yang ditebak dari nama field.
Sensitivitas ditulis tepat di dua tempat, dan keduanya membawa klaim yang benar-benar berbeda.
Pada daun skema — datum ini adalah material rahasia. Daun values, infra, atau provides mendeklarasikan sensitive: true:
spec: schema: values: origin: type: string required: true sensitive: true # the material key: type: string default: value # a data key — a locator, not materialPada slot lampiran — apa pun yang mengikat titik ini menangani material rahasia. Slot featuresSchema mendeklarasikan sensitive: true:
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]Kedua tingkat ini bukan duplikat praktis satu sama lain, dan bentuk kredensial yang dapat direferensikan adalah kasus konkret yang menunjukkan alasannya. Kredensial yang dapat direferensikan menerbitkan provides.name dan provides.key — lokator sumber daya dan kunci data di dalamnya — dan keduanya tidak sensitif: nama Secret Kubernetes bersifat publik, begitu pula kunci di dalamnya. Keduanya dirender sebagai teks biasa ke dalam manifes milik konsumen sebagai secretKeyRef. Namun slot yang diisi kredensial itu jelas menangani material rahasia. Satu tingkat saja tidak dapat menyatakan kedua fakta: menandai lokator yang diterbitkan agar slot terbaca sensitif akan menyatakan sesuatu yang salah tentangnya dan membawa kesalahan itu ke mana pun deklarasi dibaca.
Dari kedua deklarasi itu kompiler menurunkan, per lampiran, apakah lampiran menangani material yang dideklarasikan sensitif — benar ketika Feature yang dilampirkan mendeklarasikan daun sensitif, atau ketika slot yang diikatnya mendeklarasikannya, dan salah satunya saja sudah cukup. Kompiler menurunkannya dari lampiran sebagaimana adanya setelah setiap cakupan penulisan digabungkan, sehingga deklarasi cakupan yang lebih luas yang telah digantikan oleh pengisian yang lebih sempit tidak tertinggal, dan tuntutan slot berlaku pada pengisian mana pun yang benar-benar menang. Feature kredensial yang sama sekali tidak mendeklarasikan daun sensitif — karena engine target memiliki materialnya dan penulis tidak menulis apa pun — tetap menghasilkan lampiran sensitif ketika mengikat slot sensitif.
Batas atasnya, dinyatakan dengan jelas
Kata “sensitif” mengundang pembaca untuk mengharapkan mekanisme kerahasiaan. Ini bukan mekanisme semacam itu, dan jaminannya lebih sempit daripada yang disiratkan namanya dalam lima hal spesifik:
- Ini tidak mengenkripsi. Tidak ada yang dibungkus, disegel, atau diubah.
- Ini tidak mengubah putusan build, dengan satu pengecualian. Tidak ada build yang berhenti karena deklarasi tidak ada, dan katalog yang entitas kredensialnya tidak membawa deklarasi apa pun berhasil di-build. Tidak ada nilai yang diterima atau ditolak karena adanya deklarasi, kecuali ketika
valuesMappingdari Recipe atau FeatureRecipe CloudFormation membaca nilai yang dideklarasikan sensitif untuk mengisi parameter templat yang diambil: di sana setiap literal yang diikat oleh pemetaan ditolak, sehingga menambahkan deklarasi dapat mengubah build yang berhasil menjadi build yang berhenti — lihat A secret bound to a CloudFormation parameter would be written into the template (Secret yang diikat ke parameter CloudFormation akan ditulis ke dalam templat). Di tempat lain, menambahkan deklarasi ke katalog yang ada membuat setiap build yang berhasil tetap berhasil. - Ini tidak menjamin bahwa output yang dirender bebas dari material. Jaminan yang dinyatakan di atas tidak berubah: apakah suatu artefak membawa material bergantung pada pengisian mana yang dilampirkan dan apa yang dimasukkan penulisnya. Nilai yang dideklarasikan sensitif yang diberikan secara inline dirender persis seperti nilai yang tidak dideklarasikan di mana pun build merendernya — penolakan CloudFormation di atas menghentikan literal alih-alih merendernya, dan fungsi intrinsik ditulis sebagaimana diberikan, termasuk teksnya — dan
dist/tetap sama sensitifnya dengan lampirannya yang paling banyak membawa material. - Ini tidak memaksakan mekanisme pengiriman. Deklarasi tidak dapat mengubah nilai inline menjadi referensi penyimpanan, dan tidak mempersempit apa yang diizinkan allowlist
injectsuatu slot. Memaksakan pengiriman berarti memancarkan sumber daya yang tidak pernah dideklarasikan penulis, yang justru dilarang oleh invarian tanpa infrastruktur hantu — lihat 05-invariants.md. - Ini tidak mengubah satu byte pun yang dirender pada sebagian besar target, dan pada target tersebut tidak akan pernah. Dua jalur render yang disertakan bertindak berdasarkan deklarasi dalam apa yang dihasilkannya (provider Helm, Helm-Chart, dan Compose juga membacanya, hanya untuk menjaga nilai yang ditandai tetap di luar teks kegagalan): provider Terraform menandai input modul yang di-vendor yang membawa material yang dideklarasikan sensitif dengan atribut sensitivitas milik Terraform sendiri — lihat language-reference/providers/terraform.md “Input modul yang dideklarasikan sensitif”; ketika
valuesMappingdari Recipe, atau dari FeatureRecipe milik Feature yang dilampirkan ke komponen, menciptakan nama input, tidak ada input yang dapat membawa atribut tersebut dan build mencetak peringatan yang menyatakannya, lihat A declared-sensitive value reaches the target through a values mapping (Nilai yang dideklarasikan sensitif mencapai target melalui pemetaan nilai) — dan provider CloudFormation menolak pengikatan literal yang dijelaskan di atas, yang menghentikan build alih-alih mengubah byte-nya. Di tempat lain, menambahkan deklarasi di seluruh katalog yang ada membuat setiap artefak yang dirender tetap identik. Batas atas di luar itu bersifat struktural, bukan soal apa yang telah dibangun: deklarasi hanya dapat mencapai artefak yang dirender pada platform target yang bahasanya sendiri memiliki konsep sensitivitas — deklarasi yang dipahami platform tersebut, yang mengatur cara platform menampilkan nilai, bukan cara menyimpannya. Pada target tanpa konsep semacam itu, tidak ada apa pun yang dapat menjadi wujud deklarasi, sehingga input yang identik dirender secara identik dengan atau tanpa deklarasi, secara permanen.
Satu hal yang diubah oleh deklarasi adalah apa yang dicetak CLI untuk dibaca manusia. Nilai yang dideklarasikan sensitif diganti dengan placeholder tetap di trace per tahap dan di tata letak inspect, dengan mempertahankan kunci dan hanya menyembunyikan nilainya. Itu adalah keputusan tampilan pada permukaan yang tidak di-deploy siapa pun, dan artefak yang dirender dipancarkan apa adanya karena artefak itulah yang di-deploy.
Ketika kompiler dapat mengidentifikasi nilai berdasarkan kunci — daun yang dideklarasikan, atau kunci pengiriman yang membawa material dari kunci provides yang dideklarasikan — substitusinya tepat. Nilai yang sudah ditulis templat ke dalam dokumen lain tidak membawa kunci tempat substitusi dilakukan, karena dokumen yang dirender tidak mencatat apa pun tentang deklarasi asal setiap karakter, dan memulihkannya berarti memeriksa konten. Jadi trace menampilkan dokumen semacam itu dengan mengevaluasi templat yang sama untuk kedua kalinya terhadap konteks yang data sensitifnya sudah terbaca sebagai placeholder, dan memberi label pada hasilnya sebagai render ulang, bukan sebagai apa yang telah dirender: templat yang bercabang berdasarkan konten suatu nilai dirender secara berbeda terhadap placeholder, dan datum yang tidak disebut oleh deklarasi apa pun diteruskan tanpa perubahan. Permukaan, pelabelan tersebut, dan batasannya ada di language-reference/vocabulary/compact-form-authoring.md “Mendeklarasikan daun sebagai sensitif”.
Jadi pernyataan jujur tentang apa yang diberikan sumbu ini:
Deklarasi sensitivitas adalah pernyataan niat penulis yang menyertai entitas, sehingga perkakas dan kebijakan dapat bernalar tentang apa yang ditangani suatu deployment. Ini bukan mekanisme yang melindunginya.
Melindungi material tetap menjadi tugas penyimpanan secret, kluster, dan pipeline yang menangani pohon yang dirender — sebagaimana dinyatakan di bagian lain bab ini.
Bagaimana kredensial mencapai kontainer
Dua bentuk pengiriman, dipilih oleh FeatureRecipe lampiran, bukan oleh pengembang:
Nilai yang diinjeksi. FeatureRecipe mendeklarasikan injectMapping dan tidak ada sumber daya. Output-nya digabungkan secara mendalam ke dalam pipa pengiriman komponen yang mengonsumsi sebelum Recipe dasar dirender, sehingga Recipe yang membaca .context.inject.env.<KEY> menerima nilainya. Tidak ada yang dipancarkan secara mandiri.
Dua kredensial yang dikirim di bawah satu kunci menghentikan build, dengan menyebutkan kedua lampiran: pemetaan yang menulis kunci yang sudah dikirim oleh Feature lain yang dilampirkan — melalui pemetaan Feature itu sendiri atau blok inject: miliknya — ditolak alih-alih digabungkan, sehingga satu kredensial tidak pernah disajikan sebagai pengganti kredensial lain. Aturannya sama untuk setiap lampiran, di mana pun lampiran itu dipasang dan baik lampiran itu mengisi slot pada komponen maupun pada koneksi. Pemetaan yang mengganti kunci yang dikirim oleh blok inject: milik komponen itu sendiri atau oleh salah satu koneksinya adalah intersepsi yang diandalkan oleh Features perutean, dan tetap sah.
Sumber daya yang dapat direferensikan. FeatureRecipe mendeklarasikan source, workload, artifacts, dan/atau valuesMapping, sehingga memancarkan sumber daya — biasanya Secret native platform. FeatureRecipe menerbitkan identitas sumber daya itu melalui provides miliknya, dan konsumen membacanya kembali sebagai .features.<name>.provides.name / .provides.key. Nama sumber daya itu sendiri diturunkan dari provides yang sama yang diterbitkan, sehingga nama yang dibaca konsumen dan nama yang dibawa sumber daya adalah satu string yang dievaluasi, bukan dua penurunan yang bisa menyimpang.
Workload milik Recipe mengonsumsi pengisian yang dapat direferensikan melalui map attachments: milik kontainer:
workload: | containers: main: attachments: DB_PASSWORD: from: root_password # a slot the Component declares as: envSynthesizer me-resolve referensi dari provides slot yang diterbitkan — secretKeyRef Kubernetes untuk as: env, volume berbasis secret untuk as: file. Penulis Recipe hanya menulis nama slot dan mekanismenya.
FeatureRecipe dapat melakukan keduanya: menulis ulang pipa pengiriman dan memancarkan sumber daya. FeatureRecipe juga dapat mendeklarasikan pipeline berisi langkah Wasm, yang berjalan sama untuk setiap keluarga lampiran — lampiran kredensial dapat mentransformasi dokumen yang dirender milik komponen host atas undangan, persis seperti yang dapat dilakukan lampiran operasional.
Siapa yang menamai kredensial
Lokator kredensial — nama secret, entri penyimpanan yang akan diambil, nilai yang akan dikirim — ditulis oleh siapa pun yang mengetahuinya, dan itu tidak selalu pengembang. Koneksi yang dikabel oleh Release tidak memiliki entri di Aggregate, dan Release tidak menulis values di mana pun, sehingga kredensial yang mengambil lokatornya hanya dari values tidak akan pernah dapat dinamai pada koneksi semacam itu, maupun pada lampiran apa pun yang dibuat Release.
Karena itu, setiap Feature kredensial pustaka standar yang membawa lokator pemanggil — core/referenced-secret, core/referenced-secret-set, core/secret-value, dan core/secret-provided — menerimanya dari salah satu penulis: pengembang di values lampiran, di Aggregate, atau operator di infra miliknya, di Release. Daun itu memiliki satu nama, satu bentuk, dan satu deklarasi sensitive: true di kedua pilar, dan setiap realisasi membaca pilar mana pun yang membawanya. Larangan values: pada Release tidak berubah: lokator operator adalah infra. Features yang tidak menerima lokator — core/random-password, core/generated-secret — tidak terpengaruh.
Tepat satu, dijaga oleh Feature. Lampiran membawa lokator dalam satu pilar, tidak pernah di keduanya dan tidak pernah tidak di keduanya. Skema pilar mana pun tidak dapat menyatakan hal itu, karena setiap pilar divalidasi tersendiri; blok assertions milik setiap Feature yang melakukannya, dan lampiran yang melanggarnya menghentikan build dengan menyebutkan Feature, lampiran, dan komponennya. Itulah kontrak entitas katalog, yang ditegakkan sebagaimana setiap asersi Feature: kompiler mengevaluasi templat yang ditulis penulis Feature dan tidak memiliki aturan sendiri tentang kredensial, pilar, atau lokator.
Apa yang tetap di tempatnya. Setiap field lain mempertahankan pilarnya — kunci data dari kredensial yang dapat direferensikan tetap ditulis di values, sehingga lampiran yang dibuat Release saja membaca nilai bawaannya — dan core/secret-provided tetap mengirim hanya melalui blok inject: milik lampiran itu sendiri, yang hanya ditulis oleh Aggregate dan tidak pernah dibawa oleh lampiran koneksi.
Berbagi satu kredensial di antara beberapa konsumen
Konsumen dapat memegang kredensial. Sebuah slot milik entitas mana pun yang membutuhkan kredensial, dan sering kali itu adalah pemanggil, bukan pihak yang dipanggil: komponen yang menyajikan kunci saat menghubungi pihak lain mendeklarasikan slot untuk kunci itu pada entitas katalognya sendiri, pada soket yang dipakainya untuk menghubungi, sehingga kunci itu dipegang pada koneksi tempat kunci itu disajikan — dan tidak ada apa pun pada sebuah edge uses yang mewajibkan target menyediakannya. core/ai-agent/crewai adalah bentuk yang disertakan — soket model miliknya mendeklarasikan slot credential opsional yang membawa selector feature.aggrega.ai/kind=secret, inject: [env], dan sensitive: true, dan sebuah Aggregate mengisinya di bawah koneksi, di uses.model.<alias>.features.credential. Yang dipublikasikan komponen model pustaka standar untuk dibaca konsumen adalah lokasi penyajian dan nama model, bukan kredensial, sehingga kunci yang disajikan agen saat memanggil endpoint tersebut dideklarasikan oleh agen dan dipegang pada koneksinya. Slot itu opsional, tetapi koneksi yang menjangkau model yang dilabeli katalognya component.aggrega.ai/hosting: managed dan tidak membawa kredensial akan menghentikan build, kecuali values miliknya sendiri menyatakan bahwa model tersebut tidak memerlukannya, unauthenticated: true — sebuah asersi yang dibawa entitas katalog agen, yang dievaluasi kompiler sebagaimana ia mengevaluasi asersi apa pun, dengan membaca label sebagai string. Komponen model yang dihubunginya dapat memegang kuncinya sendiri untuk pemanggil miliknya sendiri — core/ai-model/vllm mendeklarasikan slot api_key tepat untuk itu — dan keduanya adalah titik pengikatan yang terpisah: lampiran mengikat slot berdasarkan nama di tempat slot itu dideklarasikan, pada komponen atau pada koneksi, sehingga mengisi yang satu tidak mengatakan apa pun tentang yang lain.
Penempatan itulah yang membuat dua bentuk di bawah ini benar-benar menjadi pilihan deployment: dengan slot berada pada konsumen, satu build dapat memberi setiap konsumen kuncinya sendiri dan build lain dapat memberi mereka semua kunci yang sama, tanpa ada entitas katalog yang berubah di antara keduanya.
Entitas katalog yang sama melayani kedua bentuk, dan penulis yang memilih bentuk mana:
- Per konsumen. Setiap konsumen mengisi slotnya sendiri dengan lampiran kredensialnya sendiri — pada komponen, atau pada koneksinya jika slot itu milik soket. Masing-masing mendapatkan sumber daya hasil render miliknya sendiri.
- Bersama. Untuk slot yang dideklarasikan komponen, satu kredensial dilampirkan sekali pada cakupan bersama — subsistem di Aggregate, batas di Release — dan menurun secara bertingkat ke setiap komponen dalam cakupan itu. Slot yang dideklarasikan soket diisi per koneksi, dan tidak ada yang menurun secara bertingkat ke dalam koneksi, sehingga di sana bentuk bersama ditulis pada setiap koneksi: kredensial setiap koneksi membaca satu parameter. Jika para konsumen harus merujuk satu sumber daya fisik, parameter itulah yang menamainya —
core/referenced-secretyang diikat ke realisasi existing-Secret mengarahkan setiap koneksi ke satu Secret berdasarkan nama, dan kredensial yang dihasilkan adalah satu permintaan dan banyak rujukan, seperti di bawah.
Rendering bentuk bersama perlu dinyatakan dengan tepat, karena mudah untuk berasumsi sebaliknya: lampiran bersama merender satu sumber daya per konsumen, masing-masing membawa materi yang sama dari satu deklarasi itu. Rendering berjalan per komponen, sehingga nama sumber daya yang diturunkan dari {{ .context.instance_id }}-{{ .attachment_name }} berbeda untuk setiap konsumen. Yang dibagikan adalah deklarasi tunggalnya; sumber daya yang dihasilkan tidak dideduplikasi menjadi satu. Satu parameter yang dibaca pada setiap koneksi dirender dengan cara yang sama di bawah realisasi yang merender sumber daya — satu per koneksi, dengan nama lampiran berupa alias koneksi, sebuah titik, dan slot.
Jika sebuah deployment memerlukan tepat satu Secret fisik yang dibaca beberapa konsumen, nyatakan hal itu dengan Feature kredensial yang FeatureRecipe-nya berjalan pada cakupan batas (executionScope: boundary), yang merender sekali untuk batas, bukan sekali per komponen.
Kunci yang dipegang kedua ujung koneksi
Server yang memeriksa kunci dan komponen yang memanggilnya masing-masing memegang kunci itu, masing-masing di sisinya sendiri. Server memegang kunci yang diverifikasinya dalam slot pada Component miliknya sendiri — core/ai-model/vllm, core/ai-model/tei, dan core/ai-model/tgi masing-masing mendeklarasikan api_key, demikian pula model dan gateway LiteLLM untuk kunci yang disebut LiteLLM sebagai master key miliknya — dan Recipe-nya mengirimkan apa pun yang mengisi slot itu sebagai variabel yang dibaca server. Pemanggil memegang kunci yang disajikannya di sisinya sendiri: pada koneksi tempat ia menyajikannya, dalam slot yang dideklarasikan soketnya — seperti soket model milik core/ai-agent/crewai mendeklarasikan credential — atau, jika Component-nya mendeklarasikan kunci itu pada dirinya sendiri, dalam slot tersebut, untuk setiap koneksi yang dibuatnya. Tidak ada ujung yang melihat lampiran ujung lainnya: lampiran pada koneksi hanya jatuh ke pemanggil, dan keluaran hasil render sebuah server tetap sama apa pun yang dibawa koneksi yang menjangkaunya. Server tidak pernah tahu kunci mana yang dipegang pemanggil, dan pemanggil hanya membaca apa yang dipublikasikan server — sebuah alamat dan nama model. Kedua ujung sepakat karena Aggregate mengisi keduanya dari satu parameter:
spec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key router: type: local/gateway/model-router # its `models` socket declares a `credential` slot uses: models: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-keyApakah itu satu secret atau dua bergantung pada tempat kedua ujung me-resolve secret. Sebuah provider me-resolve secret berdasarkan rujukan di dalam cakupan secret: namespace Kubernetes pada helm, proyek Compose pada compose, konfigurasi root sebuah batas pada terraform, dan pada cloudformation sebuah stack, di akun dan region AWS tempat stack itu di-deploy. Jika kedua ujung berada dalam satu cakupan, keduanya merujuk satu sumber daya secret. Jika berada di cakupan berbeda, setiap ujung memegang sumber daya secret miliknya sendiri, yang direalisasikan dari entri penyimpanan yang sama. Manifest memilih realisasi setiap ujung — berdasarkan tipe Feature, atau untuk satu lampiran berdasarkan namanya, yang untuk lampiran koneksi adalah <alias>.<slot> (local.credential di atas). Karena satu parameter mengisi keduanya, kedua realisasi membaca origin sebagai jenis lokator yang sama: keduanya nama sebuah Secret, keduanya kunci entri penyimpanan, atau keduanya nilai itu sendiri.
Pada helm dengan kedua ujung dalam satu namespace, mengikat core/referenced-secret ke helm/k8s-existing-secret dan memenuhi parameter dengan nama Secret yang ada di namespace itu, model-keys, membuat kedua ujung merujuknya berdasarkan nama dan tidak merender Secret apa pun. Kontainer server membawa:
- name: VLLM_API_KEY valueFrom: secretKeyRef: name: model-keys key: api-keydan Recipe milik router membaca nama dan kunci yang sama dari koneksinya, di .context.uses.local.features.credential.provides. Dengan kedua ujung di namespace berbeda, mengikatnya ke helm/k8s-external-secret dan memenuhi parameter dengan kunci entri penyimpanan memberi setiap ujung ExternalSecret miliknya sendiri, di namespace-nya sendiri, keduanya mengambil satu entri itu. Pada compose, kedua ujung membawa rujukan ${VAR} yang sama, yang disubstitusi Docker Compose dari lingkungan tempat proyek tunggal itu dijalankan. Penempatan ini adalah konvensi yang diikuti katalog pustaka standar; kompiler tidak membandingkan apa pun di antara kedua ujung.
Satu kunci melayani setiap pemanggil. vLLM, TEI, dan TGI masing-masing memeriksa satu kunci, sehingga setiap pemanggil menyajikan kunci yang sama dan server tidak dapat membedakan satu pemanggil dari yang lain, berapa pun banyaknya koneksi yang menjangkaunya. Itu adalah batasan server itu sendiri. TGI mencocokkan kuncinya tanpa memperhatikan huruf besar-kecil, sehingga dua kunci yang hanya berbeda pada huruf besar-kecil merupakan satu kunci baginya. Model dan gateway LiteLLM juga menerima kunci yang mereka terbitkan sendiri, selama basis data pembukuan mereka terlampir.
Kredensial yang dihasilkan target
Jika Release tidak menyediakan kredensial, entitas katalog sering kali kembali ke nilai default pengembangan — nilai inline dalam Recipe, default pada parameter modul. Nilai itu sama bagi setiap pembaca katalog, yang dapat diterima untuk evaluasi dan tidak untuk hal lain. core/random-password menghilangkan kebutuhan akan nilai itu: tidak ada yang menulis kredensial, karena target yang menghasilkannya.
Build tidak bisa menjadi tempat kata sandi dibuat. Keluarannya adalah fungsi murni dari masukannya dan tidak pernah membawa nilai secret, sehingga kata sandi yang diambil pada waktu build akan berubah di setiap build dan berada di berkas hasil render. Sebagai gantinya, FeatureRecipe merender sebuah permintaan — sumber daya generator yang menamai sumber daya secret yang diisinya — dan target mengambil nilainya pada waktu deploy:
- pada
helm, sebuah controller di kluster: generator kata sandi External Secrets Operator, yang direkonsiliasi melaluiExternalSecret, atau controller kubernetes-secret-generator, yang merekonsiliasiStringSecret; - pada
terraform,random_passworddari provider random, yang diambil saat konfigurasi diterapkan; - pada
cloudformation, secret Secrets Manager yang menghasilkan string miliknya sendiri saat stack membuatnya.
Dalam setiap kasus, keluaran hasil render menamai generator dan sumber daya secret dan tidak membawa nilai apa pun. Itu adalah sifat dari apa yang dimiliki build, bukan perlindungan yang ditambahkannya: nilai itu tidak pernah ada sampai target membuatnya. Tempat target menyimpannya setelah itu adalah urusan target — Terraform menyimpannya di plan dan state, kluster di sebuah Secret.
Apa yang perlu berjalan di target. Sebuah permintaan hanya dipenuhi di tempat ada sesuatu yang memenuhinya. Pada helm itu adalah controller, dan kompiler tidak dapat memeriksa kluster untuk mengetahui apakah ada yang berjalan, sehingga FeatureRecipes helm menghentikan build kecuali Release menegaskan prasyarat tersebut dengan infra.control_plane_present: true pada lampiran. Pada terraform dan cloudformation, apply atau stack menghasilkan nilainya sendiri dan tidak ada yang perlu berjalan sebelumnya.
Di mana ini tidak dapat digunakan. Compose tidak menjalankan controller dan tidak memiliki sumber daya yang menghasilkan nilai, sehingga tidak ada FeatureRecipe yang merealisasikan core/random-password di sana, dan build yang mengikatnya pada compose berhenti karena tidak ada FeatureRecipe tersebut. Release yang menargetkan compose menyediakan kredensialnya melalui core/secret-value, biasanya sebagai rujukan variabel yang disubstitusi Docker Compose saat stack dimulai.
Cara konsumen membacanya. core/random-password memublikasikan provides.name dan provides.key yang sama dengan core/referenced-secret, dan membawa label feature.aggrega.ai/kind: secret yang sama, sehingga slot yang memilih keluarga kredensial menerimanya dan konsumen membaca kredensial yang dihasilkan persis seperti membaca kredensial yang sudah ada.
Cara beberapa konsumen berbagi satu kredensial. Generator mengambil nilai baru untuk setiap permintaan, sehingga aturan berbagi dari bagian sebelumnya berlaku dengan lebih tajam: kredensial yang dihasilkan yang dilampirkan pada cakupan bersama — atau pada setiap konsumen — merender satu permintaan per konsumen, dan setiap permintaan mengambil kata sandi yang berbeda, yang tidak dapat digunakan oleh basis data dan kliennya. Satu kredensial yang dihasilkan dan dibagikan oleh beberapa konsumen dinyatakan sebagai satu permintaan dan banyak rujukan: core/random-password pada satu komponen, dengan nilai name miliknya menetapkan Secret yang diisinya, dan core/referenced-secret pada komponen lainnya, diikat ke realisasi existing-Secret dan diarahkan ke nama yang sama. Jika ditulis dari satu parameter, keduanya tidak mungkin berbeda, dan hasil render membawa tepat satu permintaan yang dirujuk setiap konsumen.
core/random-password bukan core/generated-secret. Feature tersebut menyerahkan kredensial kepada mesin yang sudah memiliki seluruh siklus hidupnya — basis data terkelola, controller basis data — dan tidak merender apa pun. core/random-password merender permintaan itu sendiri, untuk workload yang Recipe-nya mengharapkan untuk diberi kredensial.
Prioritas lampiran
Sebuah lampiran dapat dideklarasikan pada beberapa cakupan sekaligus. Kepemilikan atas field yang diperebutkan diselesaikan dengan tiga aturan, yang diterapkan dalam urutan ini:
- Asal. Field yang ditulis secara eksplisit mengalahkan field yang disumbangkan oleh ekspansi berbasis anotasi, dari cakupan mana pun masing-masing berasal.
- Otoritas komposisi. Deklarasi dalam Aggregate yang sedang Anda deploy mengalahkan deklarasi di dalam Aggregate yang dikomposisinya, bahkan ketika dokumen yang dikomposisi mendeklarasikannya pada cakupan yang lebih sempit.
- Spesifisitas. Dalam satu tingkat penulisan, cakupan yang lebih sempit menyempurnakan cakupan yang lebih luas field demi field: pengisian tingkat komponen menimpa lampiran tingkat subsistem atau tingkat batas dengan nama instans yang sama hanya untuk field yang disebutkannya, dan field yang dihilangkannya mempertahankan nilai dari cakupan yang lebih luas.
Sisi pengembang menyediakan values dan sisi operator menyediakan infra, sehingga keduanya tidak pernah memperebutkan field yang sama. Feature kredensial yang mengambil lokatornya dari salah satu sisi mendeklarasikannya sebagai dua field, satu per pilar, dan asersinya sendiri menolak lampiran yang membawa keduanya, sehingga di sana pun prioritas tidak memiliki seri yang harus diputuskan. Prioritas hanya mengatur nilai field; prioritas tidak mengubah urutan evaluasi, yang mengikuti urutan kaskade di 10-compilation-pipeline.md.
Chart lama yang menuntut string berformat
Sebuah chart terkadang menginginkan satu string koneksi dengan materi tertanam di dalamnya — oracle://admin:PASSWORD@HOST:1521/DB. Kompiler ahead-of-time tidak dapat membangun string itu dari koordinat penyimpanan, karena kompiler tidak pernah memegang materi tersebut. Dua jalur yang didukung:
Templating di sisi kluster. FeatureRecipe kredensial menghasilkan sumber daya yang memformat string di dalam kluster, menggunakan templating milik operator vault itu sendiri. Aplikasi kemudian merujuk Secret platform yang dihasilkan berdasarkan nama, dan kompiler telah menghubungkan relasi itu tanpa pernah memegang materinya:
{ "apiVersion": "external-secrets.io/v1beta1", "kind": "ExternalSecret", "metadata": { "name": "oracle-dsn-secret" }, "spec": { "target": { "name": "oracle-formatted-dsn", "template": { "engineVersion": "v2", "data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" } } }, "data": [ { "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } } ] }}Pengangkatan parameter. Aggregate mendeklarasikan parameter bertipe dan pipeline CI di sekitarnya menyediakan nilai pada waktu build melalui parameters: milik Release — misalnya file yang ditulis pipeline dan diimpor Release dengan parameters: { $import: ./ci-parameters.yaml }. Ini adalah jalan keluar yang eksplisit, dan jalan keluar ini membuat kompromi itu terlihat: materi kini mengalir melalui build, sehingga keluaran hasil render membawanya dan harus ditangani sebagaimana mestinya.
Pengembangan lokal
Jalur utama pengembangan lokal mempertahankan maksud pengembang tanpa perubahan dan menukar pengikatannya. Aggregate tetap melampirkan tipe Feature kredensial yang sama; Manifest lokal memetakan tipe itu ke FeatureRecipe lokal, bukan ke yang didukung penyimpanan. Kompiler tetap tidak mengambil apa pun — FeatureRecipe lokal hanya mengirimkan sintaksis asli provider yang di-resolve oleh runtime lokal: untuk Compose, rujukan variabel seperti ${SECRET_NAME} yang ditulis ke lingkungan layanan, yang disubstitusi Docker Compose dari lingkungan shell atau berkas .env saat stack dimulai. Berganti lingkungan adalah suntingan Manifest.
Tata kelola data seputar kredensial
Aggrega tidak memodelkan skema data — baris, kolom, dan berkas adalah urusan aplikasi. Aggrega memodelkan identitas tata kelola data dengan label, dan konvensi pustaka standar adalah:
- Data berada di komponen yang label ontologinya menandainya sebagai stateful atau menyerupai sumber daya (
component.aggrega.ai/type: stateful-server,resource). Message broker yang menyimpan payload dalam antrean juga termasuk salah satunya: ia membawastateful-serverketika memiliki disknya sendiri danresourceketika Release menghubungkan broker yang di-host, dan rakmessagingtempat ia dijelajahi adalah sumbu terpisahcomponent.aggrega.ai/category. compliance.aggrega.ai/data-class(public,internal,restricted) memberi data itu identitas semantik. Konvensi ini menetapkan kunci dan nilainya, bukan komponen mana yang membawanya: tidak ada Component pustaka standar yang membawanya, karena kelas data yang disimpan sebuah komponen adalah pernyataan tentang cara sebuah organisasi menggunakan komponen itu, bukan sifat produk, sehingga organisasi menyatakannya pada Components miliknya sendiri. Ini adalah label biasa: label selector mengevaluasinya, dan plugin tata kelola yang dilampirkan operator dapat membacanya dan menolak sebuah build. Kompiler sendiri tidak menafsirkannya dan tidak menempatkan kelas mana pun di atas kelas lain — kelas apa saja yang ada dan bagaimana peringkatnya adalah pengaturan milik kebijakan yang dilampirkan, seperti dalam ../language-reference/examples/policy-data-class-route/.
data-class dan sensitive adalah dua sumbu, dan menggabungkannya menghilangkan informasi. Keduanya berdampingan dan mudah dikira satu permukaan, jadi pegang perbedaannya:
compliance.aggrega.ai/data-class | sensitive | |
|---|---|---|
| Bentuk | bertingkat — public / internal / restricted | boolean |
| Granularitas | seluruh node | satu leaf skema, atau satu slot lampiran |
| Menyatakan | identitas tata kelola apa yang dimiliki data yang disimpan sebuah komponen | bahwa datum ini adalah materi rahasia, atau bahwa titik pengikatan ini menanganinya |
| Ditulis sebagai | label di metadata.labels | kata kunci pada sebuah deklarasi |
Tidak ada yang menggantikan yang lain: memaksakan sensitivitas ke dalam label bertingkat akan memaksakan urutan pada fakta yang tidak memilikinya, dan memaksakan kelas data pada sebuah leaf akan memaksakan granularitas yang tidak dimiliki klasifikasi tersebut. Sebuah entitas dapat membawa keduanya, dan komponen yang menyimpan data restricted yang slot kredensialnya dideklarasikan sensitive menyatakan dua hal benar yang terpisah. Kata kunci leaf dan slot diajarkan di ../language-reference/vocabulary/compact-form-authoring.md “Mendeklarasikan leaf sebagai sensitif” dan ../language-reference/entities/component.md “Mendeklarasikan slot sebagai sensitif”.
Enkripsi saat diam sengaja berada di luar maksud pengembang dan di luar kompiler. Enkripsi itu menjadi bagian dari Recipe Ops untuk komponen stateful, dan dari plugin rendering yang membaca label node dan menghasilkan konfigurasi penyimpanan terenkripsi. Penempatan itu adalah panduan desain tentang tempat perhatian tersebut berada — kompiler tidak memeriksa apakah ada Recipe yang mematuhinya.
Apa yang khas di sini, dan apa yang tidak
Posisi publik layak dinyatakan secara lugas dan sempit, agar pembaca dapat menakarnya dengan tepat.
Khas: kontrak socket dipublikasikan, bukan dideklarasikan secara inline. Kontrak yang harus dipenuhi sebuah kredensial — slot, daftar izin pengirimannya, selektor labelnya — ditulis pada entitas katalog oleh siapa pun yang memublikasikannya, dan berada di katalog yang dikelola pihak ketiga. Konsumen tidak menjelaskan kontrak secara inline dalam konfigurasinya sendiri; ia mengisi kontrak yang dipublikasikan orang lain, dan kompiler memeriksa pengisian itu terhadap deklarasi yang dipublikasikan tersebut. Konsumen dan penulis kontrak adalah orang yang berbeda, bekerja di repositori yang berbeda, dengan irama rilis yang berbeda.
Khas: pengisian dibatasi oleh selektor label. Sebuah slot dapat menyatakan jenis hal apa yang boleh mengisinya (selector: "feature.aggrega.ai/kind=secret") alih-alih menyebut implementasi tertentu. Pemeriksaannya adalah evaluasi himpunan label, sehingga sebuah entitas dapat menerima keluarga pengisian yang belum pernah dikenalnya, dan pengisian baru menjadi memenuhi syarat dengan membawa label yang tepat.
Tidak khas: pemetaan injeksi. Memetakan “nama variabel lingkungan lokal ini menerima nilai yang dihasilkan itu” adalah pola yang sudah dikenal luas; beberapa alat konfigurasi dan deployment mengungkapkan gagasan yang sama dalam sintaksisnya sendiri. Versi Aggrega adalah pemetaan yang dievaluasi lebih awal dan digabungkan ke dalam pipa pengiriman, tetapi gagasannya milik ekosistem, bukan milik kami.
Tidak khas: pembuatan statis lebih awal (ahead-of-time). Membuat artefak deployment secara statis dari deskripsi tingkat yang lebih tinggi, tanpa akses ke cluster yang aktif pada saat pembuatan, bukanlah penemuan Aggrega. Alat lain melakukannya, dan sudah melakukannya sebelum Aggrega ada. Yang ditambahkan Aggrega adalah lapisan kontrak terpublikasi di atasnya, bukan pembuatan statis itu sendiri.
Bukan batas keamanan. Tidak ada satu pun dalam bab ini yang merupakan mekanisme kerahasiaan. Model kredensial adalah model pengkabelan: model ini menentukan dari mana sebuah pointer atau nilai berasal, siapa yang boleh membatasinya, dan bagaimana ia mencapai container. Melindungi materi adalah tugas penyimpanan secret, cluster, dan pipeline yang menangani pohon hasil render.
Rujukan silang
- 05-invariants.md — invarian kompilasi lebih awal dan pipa string yang menjadi landasan bab ini.
- 10-compilation-pipeline.md — tempat resolusi lampiran dan Resource Generation berada dalam pipeline.
- ../language-reference/entities/component.md — penulisan slot
featuresSchema, termasuk deklarasisensitivetingkat slot, kata kuncirequired, dan perbandingan poin demi poin antara slot dan mandat kehadiran. - ../language-reference/vocabulary/compact-form-authoring.md — kata kunci
sensitivetingkat daun, tempat deklarasi dibaca, dan asimetriparameters:. - ../language-reference/entities/workload.md — map
attachments:container dan aturan validasinya. - ../language-reference/examples/04-secrets.md — daftar periksa penulisan dan contoh lengkap transparent / blackbox.
- ../language-reference/examples/05-credential-features.md — keluarga Feature kredensial dan panduan langkah demi langkah dari awal hingga akhir.
- ../language-reference/examples/model-api-key-sharing/ — slot kredensial yang dideklarasikan socket sebuah agen, diisi pada setiap koneksi dengan tiga cara dari satu entitas katalog: satu kunci per koneksi, satu Secret yang dirujuk setiap koneksi, dan nilai bawaan bersama yang ditimpa oleh satu koneksi, beserta keluaran hasil render setiap bentuk.