Совместное использование учётных данных — для каждого потребителя, общие и оба способа сразу
Два агента CrewAI за одним OpenAI-совместимым шлюзом. Сокет model каждого агента
объявляет слот credential, поэтому ключ, который агент предъявляет модели,
к которой обращается, прикрепляется к этому соединению. Это рабочее пространство заполняет слот тремя
способами, не меняя ни одной сущности каталога: отдельный ключ для каждого соединения, один Secret,
на который указывают все соединения, и общий вариант по умолчанию, который переопределяет одно соединение.
Суть в двух потребителях. При одном потребителе три формы неотличимы друг от друга — разница в том, на какой Secret в итоге указывает каждый потребитель, и этот вопрос лишён смысла, пока потребителей не больше одного.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example model-api-key-sharingЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd model-api-key-sharingСборка
Три релиза, по одному на каждую форму. Собирайте по одному за запуск:
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-файл. В свежем клоне репозитория сначала получите его — либо отдельным шагом, либо позволив сборке заполнить его:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega 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,
по одному на агента, и каждый содержит собственные данные своего агента:
[… 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 ссылается на свой:
- 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-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 parameterРелиз привязывает учётные данные к k8s-existing-secret, который читает origin
как имя Secret, уже существующего в пространстве имён. Он вообще не рендерит
Secret — записываются только Service шлюза и два Deployment, —
и оба Deployment ссылаются на единственный Secret, который называет параметр:
- 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 Secretwriter: 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 без изменений:
- 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, который рендерит каждый узел
дважды и сравнивает выведенные байты:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismПовторная сборка любого из трёх из чистого дерева воспроизводит его отрендеренный результат байт в байт.