Features kredensial
Halaman ini menjelaskan satu gagasan, yaitu Features kredensial pustaka standar dan cara Manifest memilih apa yang merealisasikan masing-masing, dan bukan merupakan ruang kerja yang dapat dijalankan. Satu intensi pengembang, dua bentuk pengiriman kredensial membangun satu Aggregate terhadap dua realisasi dari kredensial yang sama; tuliskan ke folder Anda sendiri dengan:
aggrega scaffold --example credential-shape-per-targetKemudian ia mencetak perintah yang dijalankan berikutnya:
cd credential-shape-per-targetaggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pullSebuah kredensial mengisi slot yang dideklarasikan oleh Component dalam featuresSchema-nya (lihat entities/component.md); slot, Feature yang mengisinya, dan FeatureRecipe yang diikat oleh Manifest membentuk seluruh jalur dari lampiran seorang penulis hingga beban kerja yang berjalan.
Keluarga Feature kredensial
Sebuah Feature kredensial membawa label feature.aggrega.ai/kind: secret. Label tersebut adalah metadata katalog yang menjelaskan apa yang dihasilkan oleh lampiran; tidak ada cabang compiler yang membacanya, dan Feature kredensial dilampirkan di bawah features: seperti Feature lainnya, oleh pengembang di Aggregate atau oleh operator di Release.
Pustaka standar membagi Features kredensial berdasarkan apa yang dilakukan realisasi terhadap secret tersebut:
core/secret-valuemengirimkan sebuah nilai ke dalam pipa inject komponen, tempat Recipe-nya membacanya — nilai chart, variabel lingkungan.core/secret-providedjuga menghasilkan sebuah nilai, tetapi memublikasikannya sebagai kunciprovides, sehingga blokinject:milik lampiran itu sendiri pada slot transparan yang menentukan ke mana nilai itu pergi.core/referenced-secretmenamai sebuah resource secret — Secret Kubernetes, secret AWS Secrets Manager, entri Vault — yang dibuat oleh realisasinya atau yang sudah ada, dan memublikasikannamedankeyresource tersebut, yang dibaca konsumen sebagai.features.<slot>.provides.namedan.features.<slot>.provides.key.core/referenced-secret-setmewujudkan satu resource semacam itu yang memuat himpunan kunci data yang diberikan penulis, dan hanya memublikasikan locator-nya, untuk konsumen yang targetnya sudah menetapkan nama kunci yang dibacanya. Docker Compose tidak memiliki resource semacam itu, sehingga di sana realisasinya mengirimkan kunci-kunci tersebut sebagai nilai, seperti dijelaskan di bawah. MariaDB (chart Bitnami) — satu Secret kredensial multi-kunci menggunakannya.core/generated-secrettidak menghasilkan apa pun: mesin target sendiri yang membuat dan mengelola kredensial, seperti yang dilakukan basis data terkelola dengan kata sandi administratornya. Operator melampirkannya di Release, karena apakah mesin memiliki kredensial tersebut ditentukan oleh Recipe yang dipilih Manifest; Terraform RDS (artefak HCL inline) mengikat slot wajib dengan cara ini.core/random-passwordmerender sebuah permintaan agar target membuat kata sandi ke dalam resource secret, dan memublikasikan locator resource tersebut seperti yang dilakukancore/referenced-secret. Tidak ada yang menulis kredensial dan output yang dirender tidak membawanya.
Semuanya setara — label yang sama, permukaan lampiran yang sama, slot yang sama — sehingga sebuah slot selalu terisi, dan yang berubah di antara Releases adalah apa yang mengisinya. Feature kredensial yang mendeklarasikan kontrak provides mewajibkan setiap FeatureRecipe yang mengimplementasikannya untuk memublikasikan kunci-kunci tersebut, dan build berhenti jika ada yang tidak melakukannya; itulah yang membuat pembacaan oleh konsumen aman.
core/random-password memerlukan sesuatu di target untuk mengambil nilainya, karena build tidak pernah melakukannya: di Kubernetes, sebuah controller (External Secrets Operator, atau kubernetes-secret-generator) yang keberadaannya ditegaskan oleh Release dengan infra.control_plane_present: true; di Terraform, resource random_password; di CloudFormation, secret Secrets Manager yang membuat string-nya sendiri. Tidak ada realisasi yang disediakan untuk Docker Compose, sehingga build yang mengikatnya di sana berhenti. Setiap permintaan mengambil nilainya sendiri, sehingga dua komponen berbagi satu kata sandi yang dihasilkan dengan melampirkannya sekali, dengan name ditetapkan, dan membacanya di tempat lain melalui core/referenced-secret yang diikat ke helm/k8s-existing-secret.
Siapa yang menamai kredensial: values atau infra, tepat satu
core/secret-value, core/secret-provided, core/referenced-secret, dan core/referenced-secret-set menerima locator kredensial dari salah satu penulis: pengembang menuliskannya di values milik lampiran dalam Aggregate, operator di infra milik lampiran dalam Release. Leaf-nya sama di keduanya — origin, atau entries untuk set — dan setiap realisasi membaca pilar mana pun yang membawanya.
Bentuk milik operator itulah yang membuat kredensial dapat digunakan di tempat pengembang tidak dapat menuliskannya: pada koneksi yang disambungkan oleh Release, dan pada lampiran yang dibuat oleh Release saja, karena Release tidak menulis values di mana pun.
# Release: the operator wires the connection and names the secret.spec: components: router: uses: models: gpt: target: gpt features: credential: type: core/referenced-secret infra: origin: openai-team-aTepat satu dari keduanya. Setiap pilar divalidasi secara terpisah, sehingga tidak ada skema yang dapat mewajibkan locator; sebagai gantinya, assertions milik setiap Feature yang memuat aturan tersebut, dan lampiran yang membawa locator di kedua pilar, atau tidak di keduanya, menghentikan build (E0033) dengan menyebutkan Feature, lampiran, dan komponennya. Itulah kontrak entitas katalog: compiler mengevaluasi assertion-nya sebagaimana ia mengevaluasi assertion Feature mana pun.
Segala hal lainnya tetap di pilarnya. key tetap menjadi leaf values, sehingga lampiran yang hanya dibuat oleh Release membaca kunci data default, value. Mendeklarasikan origin di kedua pilar adalah persis hal yang dicari oleh peringatan tumpang-tindih pilar, sehingga memuat Features ini melaporkannya — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Di sini tumpang-tindih tersebut adalah kontraknya; peringatan ini tidak mengubah putusan apa pun dan tidak mengubah satu byte pun hasil render.
Manifest memilih realisasi
Beberapa FeatureRecipes dapat mengimplementasikan satu Feature untuk target yang sama, dan Manifest yang memilih. core/referenced-secret memiliki tiga di Kubernetes, dan tempat kredensial berada yang menentukan pilihan di antaranya:
helm/k8s-secret-from-parametermenulis nilai yang diberikan penulis ke dalam Secret yang dihasilkannya, sehingga materi tersebut berada di output yang dirender: untuk evaluasi dan pekerjaan lokal.helm/k8s-external-secretmerenderExternalSecretyang menamai entri dalam secret store, yang direkonsiliasi menjadi Secret oleh External Secrets Operator di kluster.helm/k8s-existing-secrettidak menghasilkan apa pun: FeatureRecipe ini membacaoriginsebagai nama Secret yang sudah ada dan memublikasikannya persis seperti yang ditulis.
Dua yang pertama menurunkan nama Secret dengan cara yang sama, dari nama host yang dirender dan nama slot, sehingga konsumen membaca locator yang sama dari keduanya dan referensi yang direndernya tidak berubah; itulah yang ditunjukkan contoh. Yang ketiga memublikasikan nama Secret yang sudah ada itu sendiri, sehingga mem-binding-nya sengaja mengubah referensi konsumen.
core/secret-value direalisasikan di Docker Compose oleh compose/dotenv-secret, yang menulis nilai ke environment layanan persis seperti yang ditulis: origin yang ditulis sebagai ${DB_PASSWORD} masuk sebagai referensi tersebut, yang diisi oleh Docker Compose dari shell Anda atau file .env saat stack dimulai. Di Kubernetes, helm/env-secret mengirimkan nilai ke dalam pipa inject, dan helm/k8s-secret-from-value juga menuliskannya ke dalam Secret dan memublikasikan locator-nya, untuk konsumen yang membaca kredensial melalui referensi. Tidak satu pun realisasi Kubernetes menerima referensi variabel Compose, yang tidak akan diisi oleh apa pun di sana.
core/referenced-secret direalisasikan di Docker Compose oleh compose/dotenv-referenced-secret. Compose tidak memiliki resource secret untuk dirujuk, sehingga origin adalah kredensial itu sendiri, bukan nama sebuah Secret: nilai ini dikirimkan ke pipa inject di bawah key milik lampiran, dan Recipe Compose yang membaca slot tersebut menuliskannya ke file yang dihasilkan persis seperti yang ditulis, sehingga origin yang ditulis sebagai ${DB_PASSWORD} masuk sebagai referensi tersebut. Realisasi ini tidak membuat resource apa pun, sehingga nama yang dipublikasikannya kosong dan kunci yang dipublikasikannya adalah values.key.
core/referenced-secret-set direalisasikan di Docker Compose oleh compose/dotenv-secret-set, yang mengirimkan setiap entri ke pipa inject sebagai variabel yang dinamai sesuai kuncinya, ditulis ke environment layanan persis seperti yang ditulis, sehingga entri yang nilainya ${GITHUB_TOKEN} masuk sebagai referensi tersebut. Realisasi ini tidak membuat resource apa pun, sehingga locator yang dipublikasikannya kosong: konsumen di Compose membaca entri dari pipa inject-nya sendiri alih-alih merujuk sebuah Secret berdasarkan nama, seperti yang dilakukan compose/mcp dan compose/mcp-stdio-bridge sejak 1.1.0 untuk server_env milik server Model Context Protocol.
Nama FeatureRecipe yang disediakan untuk lebih dari satu target, seperti provided-secret, ditulis dengan targetnya di Manifest, compose/provided-secret:1.0.0, karena nama polosnya cocok dengan keduanya.
Satu nama, dipublikasikan sekali
Recipe milik konsumen tidak pernah menurunkan nama Secret yang dihasilkan kredensial: ia membaca locator yang dipublikasikan kredensial, existingSecret: "{{ .features.root_password.provides.name }}". Nama tersebut ditulis sekali, pada provides milik FeatureRecipe, sehingga mengubah cara penyusunannya hanyalah suntingan di tempat itu saja. Pengiriman kredensial — secretKeyRef end-to-end membangun jalur yang dapat direferensikan di Kubernetes dan jalur yang diinjeksikan di Docker Compose, dan Berbagi kredensial — per konsumen, dibagi, dan keduanya sekaligus menunjukkan beberapa konsumen yang memegang kuncinya sendiri atau berbagi satu kunci.