Chia sẻ một thông tin xác thực — theo từng bên tiêu thụ, dùng chung, và cả hai cùng lúc
Hai agent CrewAI đứng sau một gateway tương thích OpenAI. Socket model của mỗi agent
khai báo một slot credential, nên khóa mà agent xuất trình cho mô hình
nó kết nối tới được gắn trên chính kết nối đó. Workspace này lấp slot theo ba
cách mà không thay đổi một thực thể catalog nào: một khóa cho mỗi kết nối, một Secret
mà mọi kết nối cùng trỏ tới, và một mặc định dùng chung bị một kết nối ghi đè.
Hai bên tiêu thụ chính là điểm mấu chốt. Với một bên tiêu thụ duy nhất, ba dạng không thể phân biệt — khác biệt nằm ở việc mỗi bên tiêu thụ rốt cuộc trỏ tới Secret nào, và câu hỏi đó không có nội dung cho đến khi có nhiều hơn một bên tiêu thụ.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example model-api-key-sharingSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd model-api-key-sharingBuild
Ba release, mỗi dạng một release. Mỗi lần chạy, build một release:
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/Mỗi release ghi vào thư mục riêng, nên cả ba cây đã render cùng tồn tại và có thể so sánh diff với nhau.
Một release cần lockfile trước khi build. Trên một bản checkout mới, hãy resolve lockfile trước — hoặc như một bước riêng, hoặc để quá trình build tự điền:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildCác release resolve thực thể catalog từ catalog đã cấu hình, nên không cần cờ --catalog.
Cả ba đều build trên target helm, một cách có chủ ý. Điểm quan sát được để phân biệt
ba dạng là tên của Secret mà container của mỗi agent tham chiếu,
và helm là nơi thông tin xác thực là một Kubernetes Secret có tên mà container
tham chiếu theo tên. Hai Manifests ràng buộc thông tin xác thực: manifest.yaml với
k8s-secret-from-parameter, cái render một Secret từ giá trị mà
attachment mang theo, cho release theo từng bên tiêu thụ; và
manifest-existing-secret.yaml với k8s-existing-secret, cái không render gì
và trỏ mỗi bên tiêu thụ tới một Secret đã có trong namespace, cho các release dùng chung
và kết hợp.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `model-api-key-sharing`, hãy gọi công cụ `scaffold` một lần với `example` được đặt thành `model-api-key-sharing` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `model-api-key-sharing` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-per-consumer.yaml`, `release-shared.yaml` và `release-composed.yaml` — mỗi lần với `workspace_root` được đặt thành `model-api-key-sharing`, `release` được đặt thành tệp đó, `auto_pull` được đặt thành true và `write` được đặt thành true. Hãy cho tôi biết mỗi bản build đã ghi những tệp nào; chúng nằm trong `model-api-key-sharing/dist/`.Theo từng bên tiêu thụ — mỗi kết nối giữ khóa riêng
aggregate-per-consumer.yaml lấp slot trên kết nối của mỗi agent, với
origin khác nhau cho mỗi agent:
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-meMột attachment trên một kết nối trở thành một attachment riêng của agent, được đặt tên
theo kết nối và slot — ở đây là gateway.credential — nên hai Secret được
tạo ra, mỗi agent một cái, mỗi cái mang dữ liệu riêng của agent đó:
[… 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"và mỗi Deployment tham chiếu Secret riêng của nó:
- 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_KEYThu hồi khóa của một agent không ảnh hưởng agent còn lại đang chạy.
Dùng chung — một Secret, được tham chiếu từ mỗi kết nối
Thông tin xác thực trên một kết nối được viết trên chính kết nối đó: không gì gắn ở nơi khác lấp được nó. Vì vậy nhiều bên tiêu thụ dùng chung một thông tin xác thực bằng cách soạn thảo: thông tin xác thực của mỗi kết nối đọc cùng một giá trị, và giá trị đó đặt tên cho một Secret.
aggregate-shared.yaml khai báo một tham số và đọc nó trên cả hai
kết nối:
parameters: team_model_key: type: string default: team-model-keycomponents: 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 parameterRelease ràng buộc thông tin xác thực với k8s-existing-secret, cái đọc origin
như tên của một Secret đã tồn tại trong namespace. Nó không render
Secret nào cả — chỉ Service của gateway và hai Deployment được ghi ra —
và cả hai Deployment đều tham chiếu một Secret duy nhất mà tham số đặt tên:
- 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Đó đúng là một Secret vật lý duy nhất, được tạo bên ngoài Release bởi người triển khai nó, và được mọi bên tiêu thụ đọc. Dữ liệu của khóa không bao giờ đi qua một tệp được soạn thảo hay một artifact được render.
Thứ mà tham số mang theo tùy thuộc vào realization mà Manifest ràng buộc. Với
k8s-existing-secret, đó là tên của một Secret. Nếu thay vào đó ràng buộc với
k8s-secret-from-parameter, cùng hai kết nối đọc một tham số
sẽ mang chính khóa, và quá trình build sẽ render một Secret cho mỗi bên tiêu thụ,
mỗi cái chứa cùng dữ liệu: việc render chạy theo từng component, và realization đó
đặt tên Secret nó render theo component tiêu thụ và
kết nối. Một tham số duy nhất là thứ giữ cho các bên tiêu thụ không lệch nhau;
realization nào đọc nó quyết định việc chúng có dùng chung một tài nguyên hay không. Một thông tin xác thực
được sinh trong cluster cũng được dùng chung theo cách tương tự — một yêu cầu và nhiều
tham chiếu; xem Mô hình thông tin xác thực.
Kết hợp — mặc định dùng chung, một kết nối ghi đè
aggregate-composed.yaml giữ tham số dùng chung làm mặc định và cho phép một
kết nối đặt tên một Secret của riêng nó:
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 Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared defaultPhần ghi đè là thứ mà kết nối đó tự soạn thảo; không gì lan truyền xuống nó, và
writer giữ nguyên Secret dùng chung:
- 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_KEYThông tin xác thực của một kết nối là một attachment hoàn chỉnh của riêng nó, nên phần ghi đè
phải nêu lại mọi trường nó cần — ở đây là kiểu Feature, key và origin — và
không kế thừa trường nào từ mặc định.
Slot mang lại điều gì
core/ai-agent/crewai khai báo slot một lần, trên socket model của nó, và
cả ba dạng đều là những lựa chọn được đưa ra trong 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 là tùy chọn, nên dạng thứ tư là không gắn gì cả: bỏ khối
features: khỏi cả hai kết nối và cây đã render mất mọi mục env
OPENAI_API_KEY, chỉ còn lại hai Deployment và Service của gateway.
Không có gì được bịa ra để lấp chỗ trống. Thực thể catalog giống hệt nhau trong mọi
trường hợp; người soạn thảo quyết định.
Việc đó build được vì gateway ở đây, core/ai-model/openai-compatible, không mang
nhãn component.aggrega.ai/hosting. Một kết nối tới target mà
catalog gắn nhãn managed — chẳng hạn core/ai-model/openai — mà không có thông tin xác thực sẽ dừng
quá trình build theo assertion của chính agent, trừ khi kết nối nêu trong
values của nó rằng target không cần thông tin xác thực, unauthenticated: true.
Slot cũng không phụ thuộc vào họ thông tin xác thực (feature.aggrega.ai/kind=secret chấp nhận
cả hai họ), đó là điều cho phép cùng một agent nhận một Secret có thể tham chiếu
trên helm và một thông tin xác thực kiểu inject-value trên compose.
Phân phối thông tin xác thực — secretKeyRef từ đầu đến cuối
minh họa sự phân chia provider đó, và release phủ định của nó cho thấy điều gì xảy ra khi một
thông tin xác thực không thể tham chiếu được yêu cầu đáp ứng một tham chiếu.
Tính tất định
Cả ba release đều build với --verify-determinism, cờ này render mỗi node
hai lần và so sánh các byte được tạo ra:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismBuild lại bất kỳ release nào trong ba release từ một cây sạch sẽ tái tạo đầu ra đã render giống hệt từng byte.