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

Berbagi kredensial — per konsumen, bersama, dan keduanya sekaligus

Dua agen CrewAI di belakang satu gateway yang kompatibel dengan OpenAI. Soket model setiap agen mendeklarasikan slot credential, sehingga kunci yang diberikan agen kepada model yang dijangkaunya dilampirkan pada koneksi tersebut. Workspace ini mengisi slot itu dengan tiga cara tanpa mengubah satu pun entitas katalog: satu kunci per koneksi, satu Secret yang dirujuk oleh setiap koneksi, dan default bersama yang ditimpa oleh satu koneksi.

Dua konsumen adalah intinya. Ketiga bentuk tersebut tidak dapat dibedakan dengan satu konsumen — perbedaannya adalah Secret mana yang akhirnya dirujuk oleh setiap konsumen, dan pertanyaan itu tidak bermakna sampai ada lebih dari satu konsumen.

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

Terminal window
aggrega scaffold --example model-api-key-sharing

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd model-api-key-sharing

Build

Tiga release, satu per bentuk. Bangun satu per eksekusi:

Terminal window
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/
aggrega build --release release-shared.yaml --auto-pull # → dist/shared/
aggrega build --release release-composed.yaml --auto-pull # → dist/composed/

Setiap release menulis ke direktorinya sendiri, sehingga ketiga pohon hasil render dapat berdampingan dan dapat dibandingkan (diff) satu sama lain.

Sebuah release memerlukan lockfile-nya sebelum dibangun. Pada checkout baru, resolve satu terlebih dahulu — baik sebagai langkah tersendiri maupun dengan membiarkan build mengisinya:

Terminal window
aggrega pull --release release-shared.yaml # resolve, then build normally
aggrega build --release release-shared.yaml --auto-pull # or resolve during the build

Release-release tersebut me-resolve entitas katalognya dari katalog yang dikonfigurasi, sehingga flag --catalog tidak diperlukan.

Ketiganya dibangun pada target helm, dengan sengaja. Hal teramati yang membedakan ketiga bentuk tersebut adalah nama Secret yang dirujuk oleh kontainer setiap agen, dan helm adalah tempat kredensial berupa Kubernetes Secret bernama yang dirujuk kontainer berdasarkan namanya. Dua Manifests mengikat kredensial: manifest.yaml ke k8s-secret-from-parameter, yang me-render sebuah Secret dari nilai yang dibawa lampiran, untuk release per konsumen; dan manifest-existing-secret.yaml ke k8s-existing-secret, yang tidak me-render apa pun dan mengarahkan setiap konsumen ke Secret yang sudah ada di namespace, untuk release bersama dan release gabungan.

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `model-api-key-sharing`, panggil alat `scaffold` sekali dengan `example` diatur ke `model-api-key-sharing` dan tanpa `dir`: alat ini menulis contoh ke folder `model-api-key-sharing` yang baru. Kemudian panggil alat `build` sekali untuk setiap Release, dengan urutan ini — `release-per-consumer.yaml`, `release-shared.yaml`, dan `release-composed.yaml` — setiap kali dengan `workspace_root` diatur ke `model-api-key-sharing`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis oleh setiap build; file tersebut berada di bawah `model-api-key-sharing/dist/`.

Per konsumen — setiap koneksi memegang kuncinya sendiri

aggregate-per-consumer.yaml mengisi slot pada koneksi setiap agen, dengan origin yang berbeda per agen:

researcher:
type: core/ai-agent/crewai
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-key-change-me

Lampiran pada sebuah koneksi menjadi salah satu lampiran milik agen itu sendiri, yang dinamai menurut koneksi dan slotnya — di sini gateway.credential — sehingga dua Secret dihasilkan, satu per agen, masing-masing membawa materi milik agen itu sendiri:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: researcher-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: writer-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "writer-key-change-me"

dan setiap Deployment merujuk miliknya sendiri:

dist/per-consumer/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-gateway.credential
key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: writer-gateway.credential
key: OPENAI_API_KEY

Mencabut kunci satu agen membiarkan agen lainnya tetap berjalan.

Bersama — satu Secret, dirujuk dari setiap koneksi

Kredensial pada sebuah koneksi ditulis pada koneksi tersebut: tidak ada yang dilampirkan di tempat lain yang mengisinya. Jadi beberapa konsumen berbagi satu kredensial melalui penulisan: kredensial setiap koneksi membaca nilai yang sama, dan nilai itu menamai satu Secret.

aggregate-shared.yaml mendeklarasikan satu parameter dan membacanya pada kedua koneksi:

parameters:
team_model_key:
type: string
default: team-model-key
components:
researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}"
writer: { ... } # the same credential, reading the same parameter

Release tersebut mengikat kredensial ke k8s-existing-secret, yang membaca origin sebagai nama Secret yang sudah ada di namespace. Realisasi ini tidak me-render Secret sama sekali — hanya Service milik gateway dan dua Deployment yang ditulis — dan kedua Deployment merujuk satu Secret yang dinamai oleh parameter:

dist/shared/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

Itu tepat satu Secret fisik, yang dibuat di luar Release oleh siapa pun yang mendeploy-nya, dan dibaca oleh setiap konsumen. Materi kunci tidak pernah melewati berkas yang ditulis maupun artefak hasil render.

Apa yang dibawa parameter mengikuti realisasi yang diikat oleh Manifest. Di bawah k8s-existing-secret, parameter itu berupa nama Secret. Jika diikat ke k8s-secret-from-parameter, dua koneksi yang sama yang membaca satu parameter akan membawa kunci itu sendiri, dan build akan me-render satu Secret per konsumen, masing-masing memegang materi yang sama: rendering berjalan per komponen, dan realisasi itu menamai Secret yang di-render-nya menurut komponen konsumen dan koneksinya. Satu parameter itulah yang menjaga para konsumen agar tidak saling menyimpang; realisasi mana yang membacanya menentukan apakah mereka berbagi satu sumber daya. Kredensial yang dibuat di dalam klaster dibagikan dengan cara yang sama — satu permintaan dan banyak rujukan; lihat Model kredensial.

Gabungan — default bersama, satu koneksi menimpa

aggregate-composed.yaml mempertahankan parameter bersama sebagai default dan mengizinkan satu koneksi menamai Secret miliknya sendiri:

researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-model-key # this connection's own Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

Penimpaan adalah apa yang ditulis oleh satu koneksi itu; tidak ada yang menurun ke koneksi itu, dan writer tetap menggunakan Secret bersama tanpa perubahan:

dist/composed/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-model-key
key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

Kredensial sebuah koneksi adalah satu lampiran utuh tersendiri, sehingga penimpaan menyatakan ulang setiap field yang diperlukannya — di sini tipe Feature, key dan origin — dan tidak mewarisi apa pun dari default.

Apa yang diberikan slot

core/ai-agent/crewai mendeklarasikan slot satu kali, pada soket model-nya, dan ketiga bentuk tersebut semuanya merupakan pilihan yang dibuat di Aggregate:

usesSchema:
model:
selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api"
required: true
inject: [env, file]
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Slot ini opsional, sehingga bentuk keempat adalah tidak melampirkan apa pun: hapus blok features: dari kedua koneksi dan pohon hasil render kehilangan setiap entri env OPENAI_API_KEY, menyisakan dua Deployment dan Service gateway. Tidak ada yang diciptakan untuk mengisi kekosongan itu. Entitas katalog identik dalam setiap kasus; penulislah yang memutuskan.

Hal itu dapat dibangun karena gateway di sini, core/ai-model/openai-compatible, tidak membawa label component.aggrega.ai/hosting. Koneksi yang menjangkau target yang diberi label managed oleh katalog — misalnya core/ai-model/openai — tanpa kredensial menghentikan build karena asersi agen itu sendiri, kecuali koneksi tersebut menyatakan dalam values-nya bahwa target tidak memerlukannya, unauthenticated: true.

Slot ini juga agnostik terhadap keluarga (feature.aggrega.ai/kind=secret menerima kedua keluarga kredensial), yang memungkinkan agen yang sama menerima Secret yang dapat dirujuk di helm dan kredensial inject-value di compose. Pengiriman kredensial — secretKeyRef end-to-end membahas pembagian provider tersebut, dan release negatifnya menunjukkan apa yang terjadi ketika kredensial yang tidak dapat dirujuk diminta memenuhi sebuah rujukan.

Determinisme

Ketiga release dibangun dengan --verify-determinism, yang me-render setiap node dua kali dan membandingkan byte yang dihasilkan:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

Membangun ulang salah satu dari ketiganya dari pohon bersih mereproduksi keluaran hasil render-nya byte demi byte.