Облікові дані на з’єднаннях — окремий ключ для кожного з’єднання й один ключ на обох кінцях
Сховище семантичної пам’яті, яке звертається до двох моделей і пред’являє кожній інший ключ, скомпільоване в маніфести Kubernetes. Воно читає завантажений матеріал за допомогою хостованої моделі й кодує його за допомогою сервера ембедингів, що працює поруч із ним у кластері. Ключ, який воно пред’являє хостованій моделі, отримується зі сховища секретів кластера. Сервер ембедингів перевіряє власний ключ, і сховище пред’являє саме цей ключ — обидва кінці читають його з одного параметра, тож їх неможливо записати по-різному.
Цей робочий простір не створює жодної власної сутності каталогу. Кожна Component, Feature і Recipe, які він називає, постачається в каталозі стандартної бібліотеки; файли тут — три Aggregates, один Manifest і три Releases — це все, що будь-кому потрібно написати.
Що він збирає
┌── extraction_model ──► llm a hosted model API │ key on the connection, fetched from a secret store memory ───┤ │ └── embedding_model ──► embeddings an embedding server that checks a key key on the connection ═══ the server's own api_key (both read one parameter)| екземпляр | Component із каталогу | що це тут |
|---|---|---|
memory | core/datastore/cognee | викликач: сховище семантичної пам’яті, у якого кожен із двох сокетів моделей оголошує слот credential для ключа, що його воно пред’являє на цьому з’єднанні |
llm | core/ai-model/openai | хостингова модель із міткою component.aggrega.ai/hosting: managed; до неї звертаються як до посилання, тож для неї в кластері нічого не запускається |
embeddings | core/ai-model/tei | Text Embeddings Inference у кластері з міткою self-hosted; він вимагає ключ від кожного викликача і зберігає його у власному слоті api_key |
Три релізи спільно використовують один Manifest, manifest.yaml, і кожен має власний Aggregate:
| реліз | Aggregate | що він показує |
|---|---|---|
release-matched.yaml | aggregate-matched.yaml | обидва з’єднання записує розробник, обидва кінці з’єднання для ембедингів читають один параметр |
release-mismatched.yaml | aggregate-mismatched.yaml | те саме, але обидва кінці читають два параметри: збирання успішне, а перевірка домовленостей видає пораду |
release-operator-wired.yaml | aggregate-operator-wired.yaml | з’єднання для видобування залишено оператору: Release підключає його і називає його ключ в infra |
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example connection-credentialsПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd connection-credentialsЗбирання
За один запуск збирайте один реліз:
aggrega build --release release-matched.yaml --auto-pull # → dist/matched/aggrega build --release release-mismatched.yaml --auto-pull # → dist/mismatched/aggrega build --release release-operator-wired.yaml --auto-pull # → dist/operator-wired/Кожен реліз записує у власний каталог, тож три згенеровані дерева співіснують і їх можна порівнювати між собою.
Перед збиранням релізу потрібен його lock-файл, а lock-файли генеруються, а не постачаються. Спершу розв’яжіть його або дозвольте збиранню заповнити його:
aggrega pull --release release-matched.yaml # resolve, then build normallyaggrega build --release release-matched.yaml --auto-pull # or resolve during the buildРобочий простір розв’язує свої сутності з реєстру за замовчуванням, який називає .aggrega-config.yaml, тож прапорець --catalog не потрібен.
Отримання виводить:
[… omitted: a warning that the declared-sensitive origin of llm.credential reaches the target with no per-key sensitivity marking, because its realization maps it through a valuesMapping]Pull complete: release-matched.lock (entities=15, source_artifacts=0, external_inputs=0)а збирання, де <workspace> позначає теку цього прикладу:
[… omitted: the same warning about llm.credential the pull printed] notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 8 files written to <workspace>/distДва інші релізи виводять ті самі рядки: кожне отримання називає власний
lock-файл, а кожне збирання записує вісім файлів. Рядок notice:
стосується Feature облікових даних, яку тут використовує кожне приєднання:
core/referenced-secret приймає назву свого секрету, origin, або з
values розробника, або з infra оператора, і рекомендація повідомляє,
що один лист оголошено в обох стовпах. Вона не змінює жодного вердикту й жодного
згенерованого байта; Credential Features
пояснює, чому лист є в обох.
Там, де ця сторінка показує, що створило збирання, блок скопійовано зі справжнього запуску — див. Читання виводу на цих сторінках, де описано домовленість і позначку, якою вона позначає пропущені рядки.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної папки самостійно. Якщо в папці робочої області ще немає папки `connection-credentials`, один раз викличте інструмент `scaffold` зі значенням `example`, встановленим у `connection-credentials`, і без `dir`: він записує приклад у нову папку `connection-credentials`. Потім викличте інструмент `build` один раз для кожної сутності Release у такому порядку — `release-matched.yaml`, `release-mismatched.yaml`, `release-operator-wired.yaml` — щоразу з `workspace_root`, встановленим у `connection-credentials`, `release`, встановленим у цей файл, `auto_pull`, встановленим у true, і `write`, встановленим у true. Скажіть мені, які файли записала кожна збірка; вони розташовані в `connection-credentials/dist/`.Згенероване дерево
dist/matched/helm/├── embeddings-default-service.yaml├── embeddings-headless-service.yaml├── embeddings-statefulset.yaml├── llm-service.yaml├── memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml├── memory-default-service.yaml├── memory-headless-service.yaml└── memory-statefulset.yamlОдин файл додало приєднання, а не власний Recipe компонента:
ExternalSecret, який отримує ключ, що сховище пред’являє розміщеній
моделі. Його ім’я файлу містить компонент, до якого його приєднано, memory, та
ім’я приєднання, llm.credential, записане як llm-zdcredential, бо
крапка ділить один рядок із власним ім’ям файлу; див.
Іменування згенерованого ресурсу.
Жоден файл не містить ключа ембедингів: він зберігається в Secret, який простір імен уже
має, як показують розділи нижче.
Який документ що записав
- Каталог оголошує точки прив’язки. Component сховища оголошує
слот
credentialна кожному з двох своїх сокетів моделей; Component сервера ембедингів оголошуєapi_keyна собі; кожен Recipe визначає змінну, у вигляді якої передається ключ. - Aggregate — розробник — записує, до яких моделей звертається сховище, облікові дані на кожному з’єднанні, ключ, який перевіряє сервер, і єдиний параметр, який читають обидва кінці з’єднання ембедингів.
- Manifest — маршрутизація оператора для цієї цілі — визначає, чим
стають облікові дані на Kubernetes: посиланням на Secret, який простір імен
уже містить, для кожного вкладення
core/referenced-secret, окрім того, що на з’єднанні з розміщеною моделлю, яке отримується з кластерного сховища секретів. - Release — документ оператора для одного середовища — задає значення параметрів, розміщує межу в просторі імен і, у релізі, де з’єднання підключає оператор, підключає з’єднання вилучення та називає ключ, що на ньому пред’являється.
Ключ на кожне з’єднання
Сховище звертається до двох моделей через два сокети, які оголошує його сутність каталогу,
extraction_model і embedding_model, і кожен сокет оголошує слот
credential. Тож ключ, який пред’являє сховище, розміщено на з’єднанні, на якому його
пред’являють, і кожне з’єднання несе власний. З
aggregate-matched.yaml:
memory: type: core/datastore/cognee values: # The width of the vectors the embedding model above returns. embedding_dimensions: 384 uses: extraction_model: llm: target: llm features: credential: # the key presented to the hosted model type: core/referenced-secret values: key: api-key origin: "{{ .parameters.provider_key_entry }}" embedding_model: embeddings: target: embeddings features: credential: # the key presented to the embedding server type: core/referenced-secret values: key: api-key origin: "{{ .parameters.embedding_key_secret }}"Вкладення, записане на з’єднанні, стає одним із власних вкладень сховища,
названим за псевдонімом з’єднання, крапкою та слотом:
llm.credential і embeddings.credential. Ось перші два й
останні чотири записи env контейнера сховища з
dist/matched/helm/memory-statefulset.yaml:
- name: LLM_API_KEY valueFrom: secretKeyRef: name: memory-llm.credential key: api-key- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-key[… omitted: the store's own settings, HTTP_PORT to EMBEDDING_DIMENSIONS]- name: EMBEDDING_ENDPOINT value: http://embeddings-default:8080/v1- name: EMBEDDING_MODEL value: BAAI/bge-small-en-v1.5- name: LLM_ENDPOINT value: https://api.openai.com/v1- name: LLM_MODEL value: gpt-4o-miniПерші два — це ключі, кожен з облікових даних на власному з’єднанні,
під змінною, яку Recipe сховища призначає цій стороні: LLM_API_KEY для
вилучення, EMBEDDING_API_KEY для ембедингів. Обидва є посиланнями, а не
значеннями, і провайдер helm записує записи, які читає із Secret, перед
звичайними. Останні чотири надійшли з двох з’єднань: кожна модель
публікує свою адресу та назву моделі, а Recipe сховища читає їх
для кожного сокета.
Сутність Component сховища також оголошує слот ключа на собі, model_api_key. Її
Recipe читає цей слот лише для непід’єднаного сокета, коли сховище звертається
до провайдера за власною адресою провайдера і немає з’єднання, яке несло б
ключ. Тут обидва сокети під’єднано, тож його не читають.
Один ключ на обох кінцях
Сервер ембедингів перевіряє ключ. Він зберігає цей ключ у слоті власної
сутності Component, api_key, а його Recipe передає все, що заповнює слот, як
API_KEY — змінну, яку Text Embeddings Inference читає під час запуску. З
aggregate-matched.yaml:
embeddings: type: core/ai-model/tei values: model: BAAI/bge-small-en-v1.5 features: api_key: # the key the server verifies type: core/referenced-secret values: key: api-key origin: "{{ .parameters.embedding_key_secret }}"Це одне вкладення на сервері. Ключ, який пред’являє сховище, — інше вкладення,
на з’єднанні сховища, показаному вище. Заповнення слота на одному кінці нічого не заповнює
на іншому, тож оголошення ключа на обох кінцях — це мінімум, а не
дублювання. Те, що ці два ключі залишаються одним, забезпечує те, що обидва читають один параметр,
embedding_key_secret, який оголошує Aggregate і виконує Release:
parameters: provider_key_entry: ai/openai-api-key embedding_key_secret: embedding-server-keyManifest прив’язує core/referenced-secret до k8s-existing-secret, який
читає origin як ім’я сутності Secret, що вже є у просторі імен, і нічого
не рендерить. Тож обидва кінці посилаються на цей один Secret. У контейнерному
env сервера, з dist/matched/helm/embeddings-statefulset.yaml:
- name: API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keyі в контейнерному env сховища, з dist/matched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-server-key key: api-keySecret створюється поза сутністю Release тим, хто її розгортає, тож матеріал ключа ніколи не проходить через авторський файл чи відрендерений артефакт.
Чому сервер ніколи не бачить ключів тих, хто його викликає
Вкладення на з’єднанні потрапляє лише до того, хто викликає. Дві облікові дані сховища є вкладеннями сховища: те, що вони рендерять, розміщується поруч зі сховищем, і контейнер сховища посилається на це. Ніщо з них не досягає компонента, на який вказує з’єднання, тож ціль рендериться однаково, хоч би що несли з’єднання, які до неї ведуть.
Хостована модель показує це наочно. Вона рендерить один файл — Service, що відображає
внутрішньокластерне ім’я на хост провайдера, — увесь spec файлу
dist/matched/helm/llm-service.yaml:
spec: type: ExternalName externalName: api.openai.com ports: - port: 443Ключ, який сховище їй пред’являє, отримується поруч зі сховищем, як показує наступний
розділ. Сервер ембедингів показує це через порівняння: невідповідний
релiз нижче змінює ключ на з’єднанні сховища з сервером ембедингів і не чіпає
ключ сервера, а три файли сервера в dist/mismatched/ відрізняються
від файлів у dist/matched/ лише міткою aggrega.ai/aggregate-name,
яка називає сутність Aggregate, з якої кожен із них зібрано.
Отже, ніщо в конфігурації сервера не називає ключ, який має той, хто викликає. Під час виконання запит несе ключ того, хто викликає, і сервер порівнює його з ключем, який має сам; той, хто викликає, зі свого боку, читає лише те, що публікує сервер: адресу та назву моделі.
Один ключ на сервер
Text Embeddings Inference перевіряє один ключ. Кожен клієнт пред’являє той самий ключ,
клієнту, що пред’являє будь-який інший, відмовляють, а сервер не може відрізнити одного
клієнта від іншого, тож щоб відкликати доступ одного клієнта, доводиться змінити ключ,
який пред’являє кожен клієнт. Скільки б з’єднань до нього не вело, його слот api_key
містить один ключ. Це обмеження самого сервера, і core/ai-model/vllm та core/ai-model/tgi
з каталогу мають його теж. Це не обмеження
з’єднання: клієнт, що звертається до кількох серверів, має по одному ключу на з’єднання, як
сховище тут має два.
Ключ одного з’єднання зі сховища секретів
Manifest прив’язує кожне вкладення core/referenced-secret за його типом, а
одне з них — за його назвою. З manifest.yaml:
features: # One realization for every core/referenced-secret attachment: the Secret # already exists in the namespace, and origin is its name. type: core/referenced-secret:1.0.0: helm/k8s-existing-secret:1.0.0 # One attachment bound differently, by its name. An attachment written on # a connection is named for the connection's alias, a dot and the slot, # so the memory store's credential on its llm connection is # llm.credential. That key is fetched from the store, and origin is the # store entry to fetch. name: llm.credential: helm/k8s-external-secret:1.0.0k8s-external-secret читає origin як запис сховища, який слід отримати.
origin цього з’єднання — параметр provider_key_entry, заповнений як
ai/openai-api-key, тож вкладення рендерить ExternalSecret, який
оператор сховища секретів у кластері узгоджує в Secret. Увесь spec
з
dist/matched/helm/memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml:
spec: refreshInterval: "1h" secretStoreRef: name: platform-secret-store kind: ClusterSecretStore target: name: memory-llm.credential creationPolicy: Owner data: - secretKey: api-key remoteRef: key: "ai/openai-api-key"Secret, який він заповнює, memory-llm.credential, названо за сховищем і
з’єднанням, і саме на цю назву посилається LLM_API_KEY сховища вище.
Реалізація читає з ClusterSecretStore під назвою platform-secret-store.
Те, що несе параметр, випливає з реалізації, яка його читає: запис сховища для ключа розміщеної моделі, назва Secret для ключа ембедингів. Ключ одного з’єднання отримує власну реалізацію, тоді як кожне інше вкладення того самого типу зберігає реалізацію свого типу.
Де обидва кінці розв’язують секрет
Цільова платформа розв’язує секрет за посиланням усередині області видимості секретів: межі, у якій один ресурс може посилатися на інший за іменем. Якщо обидва кінці з’єднання розташовані в одній області, обидва посилаються на один ресурс секрету. Якщо вони розташовані в різних областях, кожен кінець має власний ресурс секрету, реалізований з того самого запису сховища. Manifest обирає реалізацію для кожного кінця — за типом Feature для кожного вкладення цього типу або для одного вкладення за його іменем.
Кожна цільова платформа визначає область у власних термінах. У Kubernetes, для якого збирається цей робочий простір, це простір імен: робоче навантаження посилається на Secret лише у власному просторі імен. Кожен реліз тут розміщує свою єдину межу в одному просторі імен, aggrega.ai/namespace: memory, і кожен згенерований документ містить його — початок обох StatefulSet:
metadata: name: memory namespace: memory
# dist/matched/helm/embeddings-statefulset.yamlmetadata: name: embeddings namespace: memoryТож обидва кінці посилаються на той самий Secret, наведений вище. Якщо сервер вбудовувань розташований у власному просторі імен, Manifest прив’язує облікові дані обох кінців за іменем — api_key і embeddings.credential — до k8s-external-secret, Release заповнює параметр записом сховища, і кожен кінець має ExternalSecret у власному просторі імен, причому обидва отримують той самий запис. Тоді сховище звертається до сервера між просторами імен, що описано в cross-boundary-networking. На інших цільових платформах областю є проєкт Compose, коренева конфігурація Terraform і стек CloudFormation; кожну з них описано в моделі облікових даних.
Оператор підключає з’єднання
aggregate-operator-wired.yaml записує з’єднання з сервером вбудовувань і залишає
сокет сховища extraction_model непідключеним: його оголошує сутність каталогу сховища,
а розробник залишає його оператору. Release підключає його до
розміщеної моделі, яку оголошує Aggregate. З release-operator-wired.yaml:
memory: uses: # A connection the Aggregate does not write, into a socket the # store's catalog entity declares, to a component the Aggregate # declares. A Release writes no values, so the credential on it # names its secret in infra. extraction_model: llm: target: llm features: credential: type: core/referenced-secret infra: origin: ai/openai-api-keyRelease може підключити з’єднання до сокета, який оголошує сутність каталогу, а
Aggregate залишає непідключеним, до компонента, який оголошує Aggregate. Він не додає
жодного компонента і ніколи не перенаправляє з’єднання, яке записав Aggregate. Він не записує
values, тому облікові дані на цьому з’єднанні називають свій секрет в infra:
core/referenced-secret бере origin з values розробника або з
infra оператора, рівно з одного з двох, і збирання зупиняється на
приєднанні, що містить обидва або жодного.
Приєднання має назву llm.credential точно так само, як в узгодженому релізі, тому
рівень імен Manifest прив’язує його так само. Окрім мітки, що називає
Aggregate, між dist/operator-wired/ і
dist/matched/ відрізняються два рядки. data ресурсу ExternalSecret:
data: - secretKey: value remoteRef: key: "ai/openai-api-key"і посилання сховища на Secret, який він заповнює, у
dist/operator-wired/helm/memory-statefulset.yaml:
- name: LLM_API_KEY valueFrom: secretKeyRef: name: memory-llm.credential key: valueКлюч даних — value, а не api-key, тому що key — це лист values,
який записує лише Aggregate, тож приєднання, яке створює лише Release,
читає типове значення Feature. Реалізація публікує цей ключ, а сховище
читає його з опублікованого, тож обидва кінці все одно узгоджуються.
Розміщена модель має мітку managed, тому з’єднання, що до неї веде, містить
облікові дані або вказує у власних values, що модель їх не потребує,
unauthenticated: true. Це діє незалежно від того, який документ записав з’єднання.
Вилучіть блок features: зі з’єднання в Release, і збирання
зупиниться. Зупинка — E0033, невдала перевірка твердження Component сховища, і
її повідомлення закінчується власним реченням правила: the extraction_model connection
llm of “memory” reaches “llm”, whose component.aggrega.ai/hosting label is
managed, with no credential: attach one under credential on that connection, or
set unauthenticated: true in its values (з’єднання extraction_model
llm сутності «memory» веде до «llm», мітка component.aggrega.ai/hosting якого —
managed, без облікових даних: приєднайте їх у credential на цьому з’єднанні або
встановіть unauthenticated: true в його values).
Коли два кінці не збігаються
aggregate-mismatched.yaml надає ключу сервера і ключу сховища два різні
параметри:
parameters: provider_key_entry: type: string description: > The store entry holding the key the memory store presents to the hosted model provider. embedding_key_secret: type: string description: The Secret holding the key the embedding server verifies. # The fault: a second parameter for what is meant to be the same key. memory_embedding_key_secret: type: string description: The Secret holding the key the memory store presents to the embedding server.api_key сервера читає embedding_key_secret, а з’єднання сховища
читає memory_embedding_key_secret, які Release заповнює двома
різними Secret. Збірка вдається і записує вісім файлів: компілятор
обчислює кожне надане йому приєднання і нічого не порівнює між двома
кінцями. Сервер і далі посилається на embedding-server-key, а сховище тепер
пред’являє інший, з dist/mismatched/helm/memory-statefulset.yaml:
- name: EMBEDDING_API_KEY valueFrom: secretKeyRef: name: embedding-client-key key: api-keyПісля розгортання сервер прийматиме запити сховища, лише якщо ці два Secret випадково містять той самий ключ.
Це виявляє перевірка домовленостей публікації для сутності Release:
aggrega lint --release release-mismatched.yamlrelease-mismatched.yaml:warn: E0329 connection-credential-matches-target-key: connection "embeddings" on socket "embedding_model" of component "memory" carries a credential in its credential slot and its target "embeddings" holds a key in its api_key slot, but the two ends write their secret's locator differently, so they may name different secrets and the target would refuse the key this caller presents. The locators are compared as written, and neither is shown here. Reading one parameter at both ends keeps them one key; that agreement is the standard-catalog convention, and the build does not check it.conventions checked: 10 entities, 1 advisory finding(s)Та сама перевірка для узгодженого релізу нічого не повідомляє:
aggrega lint --release release-matched.yamlconventions checked: 10 entities, 0 advisory finding(s)і для релізу, з’єднання якого підключає оператор, теж нічого.
Правило знаходить два кінці за іменами, які їм дає стандартний каталог, —
api_key цілі та credential з’єднання — і порівнює
origin, який записує кожен кінець, у записаному вигляді: два кінці, що читають один параметр, вважаються
рівними, і нічого не розв’язується. Воно ніколи не цитує жодного з них, бо записане
там може бути самим секретом. Воно не оцінює ціль із міткою managed,
чий api_key, якщо вона його оголошує, є ключем, який пред’являється її постачальнику,
а не тим, який пред’являють її клієнти; тому з’єднання з llm не викликає зауважень
у жодному з трьох релізів. Знахідка є порадою: aggrega lint завершується з кодом 0,
а робочий простір, два кінці якого навмисно відрізняються, відмовляється від неї через
allow_connection_credential_mismatches. Редактор, що ставить демону те саме
запитання, aggrega/lint із зазначенням сутності Release, отримує ту саму знахідку з
кодом connection-credential-matches-target-key і коротким кодом E0329.
Правило та те, що воно читає, описано в розділі
Правила дисципліни.
Детермінованість
Усі три релізи збираються з --verify-determinism, який рендерить кожен
вузол двічі й порівнює згенеровані байти:
aggrega build --release release-matched.yaml --verify-determinismПовторна збірка будь-якого з трьох із чистого дерева відтворює його результат рендерингу байт у байт.
Адаптація прикладу
- Додайте другого клієнта сервера вбудовувань. Облікові дані його з’єднання
теж читають
embedding_key_secret. Сервер тримає один ключ для всіх клієнтів, тож другий клієнт пред’являє той самий ключ. - Отримуйте ключ вбудовувань теж зі сховища. Прив’яжіть
api_keyіembeddings.credentialза іменем доk8s-external-secretі заповнітьembedding_key_secretзаписом сховища замість імені Secret. Обидва кінці змінюються разом, бо обидва читають цей параметр. - Зверніться до моделі, яка не перевіряє ключ. Не додавайте облікові дані до
з’єднання. Якщо ціль позначено як
managed, вкажіть це на з’єднанні за допомогоюunauthenticated: trueу йогоvalues.
Про спільне використання одного ключа з’єднаннями кількох клієнтів див. model-api-key-sharing. Про маршрутизатор, який тримає ключі провайдерів від імені своїх клієнтів, див. ai-agent-and-model-router. Модель, що лежить в основі всього цього, — модель облікових даних.