Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Совместное использование учётных данных — для каждого потребителя, общие и оба способа сразу

Два агента CrewAI за одним OpenAI-совместимым шлюзом. Сокет model каждого агента объявляет слот credential, поэтому ключ, который агент предъявляет модели, к которой обращается, прикрепляется к этому соединению. Это рабочее пространство заполняет слот тремя способами, не меняя ни одной сущности каталога: отдельный ключ для каждого соединения, один Secret, на который указывают все соединения, и общий вариант по умолчанию, который переопределяет одно соединение.

Суть в двух потребителях. При одном потребителе три формы неотличимы друг от друга — разница в том, на какой Secret в итоге указывает каждый потребитель, и этот вопрос лишён смысла, пока потребителей не больше одного.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd model-api-key-sharing

Сборка

Три релиза, по одному на каждую форму. Собирайте по одному за запуск:

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/

Каждый релиз записывает результат в собственный каталог, поэтому все три отрендеренных дерева сосуществуют и их можно сравнивать друг с другом.

Перед сборкой релизу нужен lock-файл. В свежем клоне репозитория сначала получите его — либо отдельным шагом, либо позволив сборке заполнить его:

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

Релизы получают свои сущности каталога из настроенного каталога, поэтому флаг --catalog не нужен.

Все три собираются под цель helm, намеренно. Наблюдаемый признак, различающий три формы, — это имя Secret, на который ссылается контейнер каждого агента, а в helm учётные данные представлены именованным Secret Kubernetes, на который контейнер ссылается по имени. Учётные данные привязывают две сущности Manifests: manifest.yaml к k8s-secret-from-parameter, который рендерит Secret из значения, переносимого вложением, — для релиза с ключом на каждого потребителя; и manifest-existing-secret.yaml к k8s-existing-secret, который ничего не рендерит и направляет каждого потребителя на Secret, уже существующий в пространстве имён, — для релизов с общим и составным вариантами.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `model-api-key-sharing`, вызовите инструмент `scaffold` один раз, задав для `example` значение `model-api-key-sharing`, без `dir`: он запишет пример в новую папку `model-api-key-sharing`. Затем вызовите инструмент `build` один раз для каждого файла Release в таком порядке — `release-per-consumer.yaml`, `release-shared.yaml` и `release-composed.yaml` — каждый раз задавая для `workspace_root` значение `model-api-key-sharing`, для `release` — этот файл, для `auto_pull` — true и для `write` — true. Сообщите, какие файлы записала каждая сборка; они находятся в `model-api-key-sharing/dist/`.

Для каждого потребителя — каждое соединение хранит собственный ключ

aggregate-per-consumer.yaml заполняет слот на соединении каждого агента, с разным origin для каждого агента:

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

Вложение на соединении становится одним из собственных вложений агента, названным по соединению и слоту — здесь gateway.credential, — поэтому создаются два Secret, по одному на агента, и каждый содержит собственные данные своего агента:

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"

и каждый Deployment ссылается на свой:

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

Отзыв ключа одного агента не останавливает другой.

Общий — один Secret, на который ссылается каждое соединение

Учётные данные на соединении записываются на этом соединении: ничто, прикреплённое в другом месте, их не заполняет. Поэтому несколько потребителей разделяют одни учётные данные за счёт написания конфигурации: учётные данные каждого соединения читают одно и то же значение, и это значение называет один Secret.

aggregate-shared.yaml объявляет один параметр и читает его на обоих соединениях:

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

Релиз привязывает учётные данные к k8s-existing-secret, который читает origin как имя Secret, уже существующего в пространстве имён. Он вообще не рендерит Secret — записываются только Service шлюза и два Deployment, — и оба Deployment ссылаются на единственный Secret, который называет параметр:

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

Это ровно один физический Secret, созданный вне сущности Release тем, кто его развёртывает, и читаемый каждым потребителем. Данные ключа никогда не проходят через написанный автором файл или отрендеренный артефакт.

Что переносит параметр, зависит от реализации, которую привязывает Manifest. При k8s-existing-secret это имя Secret. Если же привязать к k8s-secret-from-parameter, те же два соединения, читающие один параметр, переносили бы сам ключ, и сборка отрендерила бы по одному Secret на потребителя, и каждый содержал бы одни и те же данные: рендеринг выполняется для каждого компонента, а эта реализация называет рендеримый Secret по потребляющему компоненту и соединению. Именно единственный параметр не даёт потребителям разойтись; а то, какая реализация его читает, определяет, разделяют ли они ресурс. Учётные данные, сгенерированные в кластере, разделяются так же — один запрос и много ссылок; см. Модель учётных данных.

Составной — общий вариант по умолчанию и одно переопределяющее соединение

aggregate-composed.yaml сохраняет общий параметр как значение по умолчанию и позволяет одному соединению назвать собственный Secret:

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

Переопределение — это то, что записывает автор для этого одного соединения; на него ничего не каскадируется, а writer сохраняет общий Secret без изменений:

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

Учётные данные соединения — это целое собственное вложение, поэтому переопределение заново указывает каждое нужное ему поле — здесь тип Feature, key и origin — и не наследует ни одного из значения по умолчанию.

Что даёт слот

core/ai-agent/crewai объявляет слот один раз, на своём сокете model, и все три формы — это выбор, сделанный в сущности 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]

Слот необязателен, поэтому четвёртый вариант — вообще ничего не прикреплять: удалите блок features: из обоих соединений, и отрендеренное дерево потеряет все записи env OPENAI_API_KEY, оставив два Deployment и Service шлюза. Ничего не придумывается для заполнения пробела. Сущность каталога одинакова во всех случаях; решает автор.

Это собирается, потому что шлюз здесь, core/ai-model/openai-compatible, не несёт метки component.aggrega.ai/hosting. Соединение без учётных данных, ведущее к цели, которую каталог помечает как managed, — например, core/ai-model/openai, — останавливает сборку на собственной проверке агента, если только соединение не указывает в своих values, что цель их не принимает, unauthenticated: true.

Слот также не зависит от семейства (feature.aggrega.ai/kind=secret допускает любое семейство учётных данных), что и позволяет одному и тому же агенту принимать Secret, на который можно ссылаться, в helm и учётные данные с внедрением значения в compose. Доставка учётных данных — secretKeyRef от начала до конца разбирает это разделение по провайдерам, а его негативный релиз показывает, что происходит, когда от учётных данных, на которые нельзя ссылаться, требуют удовлетворить ссылку.

Детерминированность

Все три релиза собираются с --verify-determinism, который рендерит каждый узел дважды и сравнивает выведенные байты:

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

Повторная сборка любого из трёх из чистого дерева воспроизводит его отрендеренный результат байт в байт.