Модель облікових даних
Одна родина приєднань
Облікові дані в Aggrega — це сутність Feature. Їх приєднують на тій самій поверхні, під тим самим ключовим словом і в тій самій формі, що й будь-яку іншу сутність Feature. Тут розробник приєднує облікові дані бази даних у сутності Aggregate, записуючи їхній локатор у values:
# the Aggregate — its parameters and the components' own values left outspec: components: api: type: core/compute/server db: type: core/datastore/mariadb features: root_password: # a credential Feature type: core/secret-value:1.0.0 values: key: MARIADB_ROOT_PASSWORD origin: "{{ .parameters.db_root_pass }}"а оператор приєднує до сервера ціль збирання метрик у сутності Release, оскільки кожен вхід, який приймає core/prometheus-exporter — порт, шлях та інтервал збирання, — є операційним, тож його записують в infra:
# the Release — the api's own infra and the db's entry left outspec: components: api: features: metrics: # an operational Feature type: core/prometheus-exporter:1.0.0 infra: port: http # the named port of the api's ServiceІснує одне ключове слово приєднання (features:), одна форма контексту рендерингу (.features.<name>, і та сама форма під з’єднанням, .context.uses.<alias>.features.<slot>, для приєднання, записаного на з’єднанні), один порядок виконання та один набір вихідних координат — для приєднання на компоненті це компонент, до якого його приєднано, а потім ім’я, під яким його приєднано, незалежно від того, чи макет цілі несе ці два елементи як каталог <component>--<instance>/ поруч із каталогом самого компонента, чи як префікс імені файлу <component>--<instance>--. Між приєднаннями відрізняється те, що вони створюють, — впроваджене значення, ресурс, на який можна посилатися, sidecar, хмарна ідентичність, — а не поверхня, на якій їх оголошено.
Сутність Feature облікових даних несе на своїй сутності каталогу мітку feature.aggrega.ai/kind: secret. Ця мітка — описові метадані: вона повідомляє читачеві, сайту каталогу та селектору міток, для чого призначена сутність Feature. Жодна гілка компілятора її не читає, і жодна поведінка від неї не залежить. Поведінка походить від сутності FeatureRecipe, з якою оператор зіставляє тип сутності Feature.
Ментальна модель одним реченням: існує один вид приєднання; відрізняється те, що воно створює.
Слоти та вільні приєднання
Сутність Component або Feature може оголошувати слоти в featuresSchema:
spec: featuresSchema: root_password: required: true inject: [] # blackbox — the Recipe delivers it selector: "feature.aggrega.ai/kind=secret" user_password: inject: [env, file] # transparent — the developer may dictate deliveryПриєднання, ім’я екземпляра якого збігається з оголошеним слотом, заповнює цей слот. Приєднання під будь-яким іншим ім’ям є вільним приєднанням: сутність його не запитувала, і воно рендериться поруч із усім, що сутність запитувала. Згенерована схема для оголошеного слоту лишається відкритою, тож оголошення одного слоту ніколи не закриває блок для вільних приєднань. Одна форма зупиняє збірку замість рендерингу: приєднання, записане на самому компоненті, сутність Feature якого задовольняє selector слоту, який там ніщо не зв’язує, — це заповнення, записане під неправильним ім’ям, а не вільне приєднання.
Дві речі, які слот може обмежувати:
inject— механізми доставки, які сутність Workload може вибрати для того, що заповнює слот. Порожній список означає слот типу чорна скринька: його доставляє власна механіка сутності Recipe (наприклад, параметрexistingSecretчарту), і сутність Workload не може посилатися на нього з контейнера.selector— рядок селектора міток, якому мають відповідати мітки сутності Feature, що заповнює слот. Саме тут міткаkind=secretвиправдовує себе: автор сутності, який хоче, щоб слот заповнювали лише облікові дані, каже це селектором, а перевірка — це оцінювання набору міток, яке компілятор виконує під час статичного аналізу.
Третє, що може зробити слот, — вимагати, щоб він зрештою був зв’язаний. required: true робить ім’я слоту обов’язковим: компілятор зупиняється під час статичного аналізу, коли ніщо його не зв’язує, з діагностикою, що називає слот і тип компонента, який його оголосив. Вимогу перевіряють щодо набору приєднань, який компонент має після каскадного застосування кожної області, тож приєднання, додане вище за компонент, зв’язує слот точно так само, як заповнення, записане на компоненті.
Друга поверхня виражає іншу вимогу. Повторювана анотація сутності Component features.aggrega.ai/requiredType.<label> оголошує обов’язок присутності: щонайменше одне приєднання має нести тип сутності Feature, названий в анотації, під будь-яким ім’ям і в будь-якій області, а обов’язок, який ніщо не задовольняє, зупиняє збірку під час того самого статичного аналізу з власною діагностикою. Вони ніколи не відповідають одне за одного — слот питає, чи зв’язана одна названа точка зв’язування, обов’язок — чи несе якесь приєднання названий тип, — тож сутність, чия сутність Recipe має читати те, що приєднано, оголошує слот, а та, чий контракт просто вимагає наявності певної можливості, оголошує обов’язок.
Що компілятор гарантує, а що ні
Цей розділ — ключовий. Aggrega — це компілятор ahead-of-time, і його гарантії вужчі, ніж змушує припускати слово «secret».
Компілятор ніколи не розв’язує облікові дані. Він не автентифікується в хмарному API, не читає сховище секретів і не отримує матеріал під час aggrega build. Значення values та infra приєднання облікових даних проходять графом і потрапляють у контекст рендерингу як непрозорі скаляри, а сутність FeatureRecipe рендерить їх в артефакт, якого очікує цільова платформа. Розв’язання відбувається пізніше, у кластері або в менеджері стану IaC, щодо того, на що вказує відрендерений артефакт.
Компілятор не може відрізнити вказівник від значення матеріалу. Він агностичний щодо того, що означає скаляр (див. 05-invariants.md). Приєднання облікових даних, локатор якого несе координату сховища (path, key, ARN), рендерить посилання на цю координату; приєднання облікових даних, локатор якого несе сам матеріал, рендерить матеріал дослівно у вихідний файл. Обидва варіанти допустимі, і компілятор обробляє їх однаково, бо не має способу їх розрізнити.
Отже, чесне формулювання гарантії таке:
Aggrega гарантує, що компілятор не виконує жодного розв’язання. Вона не гарантує, що відрендерений вихід не містить матеріалу, — це повністю залежить від того, яку сутність Feature облікових даних приєднано і що поклав у неї її автор: розробник у
valuesабо оператор вinfra.
Два наслідки, які варто засвоїти:
- Відрендерене дерево артефактів настільки ж чутливе, як його приєднання, що несе найбільше матеріалу. Поводьтеся з
dist/відповідно: якщо будь-яке приєднання несе матеріал inline, дерево містить матеріал. - Власні родини каталогу
core/secret-valueіcore/referenced-secretмістять форми, що приймають значення безпосередньо. Вони існують, бо реальним розгортанням потрібен шлях для локальної розробки, і вони цього не приховують: постачені приклади використовують очевидні заповнювачі (dev-root-pw-change-me) саме для того, щоб матеріал у відрендереному прикладі помітно не був справжніми обліковими даними. Для розгортання, яке не повинно нести матеріал, приєднайте сутність Feature облікових даних на основі сховища, сутність FeatureRecipe якої видає ресурс отримання (ExternalSecret, користувацький ресурс отримання зі сховища секретів, нативне для провайдера посилання на секрет), а не такий, що видає дані.
Домовленість стандартної бібліотеки полягає в тому, що облікові дані запитують як приєднання, а не записують у блок values, щоб заміна заповнення для локальної розробки на заповнення на основі сховища була зміною в сутності Manifest, а не редагуванням наміру розробника. Це домовленість, якої дотримується каталог, а не правило, яке примусово застосовує компілятор.
Оголошена чутливість
Компілятор не може відрізнити вказівник від значення матеріалу, як сказано в розділі вище, — але автор може і може це заявити. Чутливість в Aggrega — це анотація на оголошенні: автор сутності каталогу зазначає, що несе секретний матеріал, а компілятор виводить решту з цього твердження та зв’язків, які він уже побудував. Нічого не виводиться зі значення, і нічого не вгадується з імені поля.
Її записують рівно у двох місцях, і вони несуть справді різні твердження.
На листку схеми — ці дані є секретним матеріалом. Листок values, infra або provides оголошує sensitive: true:
spec: schema: values: origin: type: string required: true sensitive: true # the material key: type: string default: value # a data key — a locator, not materialНа слоті приєднання — усе, що зв’язує цю точку, обробляє секретний матеріал. Слот featuresSchema оголошує sensitive: true:
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]Ці два рівні не є зручним дублікатом один одного, і форма облікових даних, на які можна посилатися, — це розібраний випадок, який показує чому. Такі облікові дані публікують provides.name і provides.key — локатор ресурсу та ключ даних у ньому — і жоден із них не є чутливим: ім’я Kubernetes Secret публічне, як і ключ усередині нього. Обидва рендеряться відкритим текстом у власний маніфест споживача як secretKeyRef. Проте слот, який заповнюють ці облікові дані, безперечно обробляє секретний матеріал. Один рівень не може виразити обидва факти: позначення опублікованих локаторів, щоб слот читався як чутливий, стверджувало б про них щось хибне і переносило б цю помилку всюди, де читають оголошення.
З цих двох оголошень компілятор виводить для кожного приєднання, чи обробляє воно матеріал, оголошений чутливим, — істина, коли приєднана сутність Feature оголошує чутливий листок або коли слот, який вона зв’язує, оголошує такий, причому достатньо будь-якого з них окремо. Він виводить це з приєднання в тому вигляді, який воно має після згортання кожної авторської області, тож оголошення ширшої області, яке витіснило вужче заповнення, не зберігається, а вимога слоту застосовується до того заповнення, яке фактично перемогло. Сутність Feature облікових даних, яка взагалі не оголошує чутливого листка — бо матеріалом володіє цільовий рушій, а автор нічого не пише, — все одно дає чутливе приєднання, коли зв’язує чутливий слот.
Межа, сказана прямо
Слово «чутливий» змушує читача очікувати механізму конфіденційності. Це не він, і гарантія вужча, ніж підказує назва, у п’яти конкретних аспектах:
- Вона не шифрує. Нічого не обгортається, не запечатується і не перетворюється.
- Вона не змінює вердикт збірки, за одним винятком. Жодна збірка не зупиняється через відсутність оголошення, а каталог, сутності облікових даних якого не несуть жодного оголошення, збирається успішно. Жодне значення не приймається і не відхиляється через те, що існує оголошення, крім випадку, коли
valuesMappingсутності Recipe або FeatureRecipe для CloudFormation читає значення, оголошене чутливим, щоб заповнити параметри отриманого шаблону: там кожен літерал, який зв’язує зіставлення, відхиляється, тож додавання оголошення може перетворити успішну збірку на таку, що зупиняється, — див. A secret bound to a CloudFormation parameter would be written into the template (Секрет, зв’язаний із параметром CloudFormation, було б записано в шаблон). Усюди інде додавання оголошень до наявного каталогу залишає кожну успішну збірку успішною. - Вона не гарантує, що відрендерений вихід вільний від матеріалу. Наведена вище гарантія не змінюється: чи несе артефакт матеріал, залежить від того, яке заповнення приєднано і що поклав у нього його автор. Значення, оголошене чутливим і передане inline, рендериться точно так само, як неоголошене, усюди, де збірка взагалі його рендерить, — описане вище відхилення CloudFormation зупиняє літерал замість його рендерингу, а внутрішню функцію записують так, як її подано, разом із її текстом, — і
dist/лишається настільки ж чутливим, як його приєднання, що несе найбільше матеріалу. - Вона не нав’язує механізм доставки. Оголошення не може перетворити значення inline на посилання на сховище і не звужує того, що дозволяє список дозволених
injectслоту. Нав’язати доставку означало б видати ресурс, якого автор ніколи не оголошував, а саме це забороняє інваріант відсутності примарної інфраструктури — див. 05-invariants.md. - На більшості цілей вона не змінює жодного відрендереного байта і на них ніколи не змінить. Два постачені шляхи рендерингу реагують на оголошення у своєму виході (провайдери Helm, Helm-Chart і Compose теж його читають, лише щоб не допустити позначене значення в текст помилки): провайдер Terraform позначає вхід вбудованого модуля, що несе матеріал, оголошений чутливим, власним атрибутом чутливості Terraform — див. language-reference/providers/terraform.md «Входи модуля, оголошені чутливими»; коли
valuesMappingсутності Recipe або сутності FeatureRecipe сутності Feature, приєднаної до компонента, вигадує імена входів, жоден вхід не може нести атрибут, і збірка виводить про це попередження, див. A declared-sensitive value reaches the target through a values mapping (Значення, оголошене чутливим, досягає цілі через зіставлення значень), — а провайдер CloudFormation відхиляє описані вище зв’язування літералів, що зупиняє збірку замість зміни її байтів. Усюди інде додавання оголошень у наявному каталозі залишає кожен відрендерений артефакт ідентичним. Межа поза цим є структурною, а не питанням того, що вже побудовано: оголошення може досягти відрендереного артефакту лише на цільовій платформі, власна мова якої має поняття чутливості, — оголошення, яке ця платформа розуміє і яке визначає, як вона показує значення, а не як зберігає його. На цілі без такого поняття оголошенню нема на що перетворитися, тож ідентичний вхід рендериться ідентично з ним чи без нього, назавжди.
Одне, що оголошення змінює, — це те, що CLI виводить для читання людиною. Значення, оголошене чутливим, замінюється фіксованим заповнювачем у трасуванні кожного проходу та в макетах inspect: ключ зберігається, приховується лише значення. Це рішення щодо відображення на поверхнях, які ніхто не розгортає, а відрендерені артефакти видаються дослівно, бо саме їх розгортають.
Там, де компілятор може ідентифікувати значення за ключем — оголошений листок або ключ доставки, що несе матеріал з оголошеного ключа provides, — підстановка точна. Значення, яке шаблон уже записав в інший документ, не має ключа для підстановки, бо відрендерений документ не фіксує, з якого оголошення походить кожен символ, а відновлення цього означало б інспектування вмісту. Тому трасування показує такий документ, вдруге оцінюючи той самий шаблон щодо контексту, у якому дані, оголошені чутливими, уже читаються як заповнювач, і позначає результат як повторний рендеринг, а не як те, що було відрендерено: шаблон, що розгалужується за вмістом значення, рендериться інакше із заповнювачем, а дані, яких не називає жодне оголошення, проходять без змін. Поверхні, це позначення та його межі описано в language-reference/vocabulary/compact-form-authoring.md «Оголошення листка чутливим».
Отже, чесне формулювання того, що дає ця вісь:
Оголошення чутливості — це твердження про намір автора, яке подорожує разом із сутністю, щоб інструменти та політики могли міркувати про те, що обробляє розгортання. Це не механізм, який його захищає.
Захист матеріалу лишається завданням сховища секретів, кластера та конвеєра, що обробляє відрендерене дерево, — як говорить решта цього розділу.
Як облікові дані потрапляють у контейнер
Дві форми доставки, які вибирає сутність FeatureRecipe приєднання, а не розробник:
Впроваджене значення. Сутність FeatureRecipe оголошує injectMapping і жодних ресурсів. Її вихід глибоко зливається з каналом доставки компонента-споживача до рендерингу базової сутності Recipe, тож сутність Recipe, що читає .context.inject.env.<KEY>, отримує значення. Нічого самостійного не видається.
Двоє облікових даних, доставлених під одним ключем, зупиняють збірку із зазначенням обох приєднань: зіставлення, що записує ключ, який інша приєднана сутність Feature уже доставила — через власне зіставлення цієї сутності Feature або її власний блок inject:, — відхиляється, а не зливається, тож одні облікові дані ніколи не подаються замість інших. Правило однакове для кожного приєднання, де б його не було приєднано і чи заповнює воно слот на компоненті, чи на з’єднанні. Зіставлення, що замінює ключ, доставлений власним блоком inject: компонента або одним із його з’єднань, — це перехоплення, на яке спираються сутності Features маршрутизації, і воно лишається допустимим.
Ресурс, на який можна посилатися. Сутність FeatureRecipe оголошує source, workload, artifacts та/або valuesMapping, тож видає ресурс — зазвичай нативний для платформи Secret. Вона публікує ідентичність цього ресурсу через свої provides, а споживач зчитує її назад як .features.<name>.provides.name / .provides.key. Власне ім’я ресурсу виводиться з тих самих опублікованих provides, тож ім’я, яке читає споживач, і ім’я, яке несе ресурс, — це один оцінений рядок, а не два виведення, що можуть розійтися.
Сутність Workload сутності Recipe споживає заповнення, на яке можна посилатися, через мапу attachments: контейнера:
workload: | containers: main: attachments: DB_PASSWORD: from: root_password # a slot the Component declares as: envСинтезатор розв’язує посилання з опублікованих provides слоту — Kubernetes secretKeyRef для as: env, том на основі секрету для as: file. Автор сутності Recipe пише лише ім’я слоту та механізм.
Сутність FeatureRecipe може робити і те, і те: переписувати канал доставки і видавати ресурс. Вона також може оголосити pipeline кроків Wasm, які виконуються однаково для кожної родини приєднань, — приєднання облікових даних може на запрошення перетворювати відрендерені документи компонента-хоста точно так само, як операційне приєднання.
Хто дає назву обліковим даним
Локатор облікових даних — ім’я секрету, запис сховища, який слід отримати, значення, яке слід доставити, — записує той, хто його знає, і це не завжди розробник. З’єднання, яке зв’язує сутність Release, не має запису в сутності Aggregate, а сутність Release ніде не пише values, тож облікові дані, які брали б свій локатор лише з values, ніколи не вдалося б назвати на такому з’єднанні, як і на будь-якому приєднанні, створеному сутністю Release.
Тому кожна сутність Feature облікових даних стандартної бібліотеки, що несе локатор викликача, — core/referenced-secret, core/referenced-secret-set, core/secret-value і core/secret-provided — приймає його від будь-якого з авторів: від розробника у values приєднання, у сутності Aggregate, або від оператора в його infra, у сутності Release. Листок має одне ім’я, одну форму та одне оголошення sensitive: true в обох стовпах, і кожна реалізація читає той стовп, який його несе. Заборона values: у сутності Release лишається незмінною: локатор оператора — це infra. Сутностей Features, які не приймають локатора, — core/random-password, core/generated-secret — це не стосується.
Рівно один, і це забезпечує сутність Feature. Приєднання несе локатор в одному стовпі, ніколи в обох і ніколи в жодному. Схема жодного стовпа не може цього виразити, бо кожен стовп валідується окремо; це робить власний блок assertions кожної сутності Feature, а приєднання, яке його порушує, зупиняє збірку із зазначенням сутності Feature, приєднання та компонента. Це контракт сутності каталогу, який дотримується так само, як кожне твердження сутності Feature: компілятор оцінює шаблон, написаний автором сутності Feature, і не має власного правила щодо облікових даних, стовпів чи локаторів.
Що лишається на своєму місці. Кожне інше поле зберігає свій стовп — ключ даних облікових даних, на які можна посилатися, і далі записують у values, тож приєднання, створене лише сутністю Release, читає його значення за замовчуванням, — а core/secret-provided і далі доставляє лише через власний блок inject: приєднання, який пише тільки сутність Aggregate і якого приєднання з’єднання ніколи не несе.
Спільне використання одних облікових даних кількома споживачами
Облікові дані може тримати споживач. Слот належить тій сутності, якій потрібні облікові дані, і часто це той, хто викликає, а не те, що викликають: компонент, який пред’являє ключ, коли звертається назовні, оголошує слот для цього ключа у власній сутності каталогу, на сокеті, через який звертається, тож ключ тримається на з’єднанні, на якому його пред’являють, — і ніщо в ребрі uses не зобов’язує ціль надавати ключ. core/ai-agent/crewai — це постачена форма: його сокет model оголошує необов’язковий слот credential із селектором feature.aggrega.ai/kind=secret, inject: [env] та sensitive: true, а сутність Aggregate заповнює його під з’єднанням, у uses.model.<alias>.features.credential. Те, що компоненти моделей зі стандартної бібліотеки публікують для читання споживачем, — це адреса обслуговування та назва моделі, а не облікові дані, тож ключ, який агент пред’являє під час виклику цієї кінцевої точки, оголошує агент, і він тримається на його з’єднанні. Слот необов’язковий, але з’єднання, що веде до моделі, яку її каталог позначає міткою component.aggrega.ai/hosting: managed, і не несе жодних облікових даних, зупиняє збірку, якщо тільки його власні values не вказують, що модель їх не потребує, unauthenticated: true — це твердження, яке несе сутність каталогу агента і яке компілятор обчислює так само, як будь-яке твердження, читаючи мітку як рядок. Компонент моделі, до якого він під’єднується, може тримати власний ключ для своїх викликачів — core/ai-model/vllm оголошує слот api_key саме для цього, — і це дві окремі точки зв’язування: приєднання зв’язує слот за назвою там, де його оголошено, на компоненті або на з’єднанні, тож заповнення одного нічого не каже про інший.
Саме таке розміщення робить дві наведені нижче форми справжнім вибором розгортання: коли слот на споживачі, одна збірка може дати кожному споживачеві власний ключ, а інша — усім той самий, і жодна сутність каталогу між ними не змінюється.
Та сама сутність каталогу обслуговує обидві форми, і вибирає між ними автор:
- Для кожного споживача окремо. Кожен споживач заповнює власний слот власним приєднанням облікових даних — на компоненті або на своєму з’єднанні, якщо слот належить сокету. Кожен отримує власний відрендерений ресурс.
- Спільно. Для слота, який оголошує компонент, одні облікові дані приєднуються один раз у спільній області — у підсистемі в сутності Aggregate, у межі в сутності Release — і каскадно поширюються на кожен компонент цієї області. Слот, який оголошує сокет, заповнюється для кожного з’єднання, і ніщо не поширюється каскадно всередину з’єднання, тож там спільна форма записується на кожному з’єднанні: облікові дані кожного з’єднання читають один параметр. Якщо споживачі мають посилатися на один фізичний ресурс, цей параметр його називає —
core/referenced-secret, зв’язаний із реалізацією existing-Secret, спрямовує кожне з’єднання на один Secret за назвою, а згенеровані облікові дані — це один запит і багато посилань, як описано нижче.
Варто точно сказати, як рендериться спільна форма, бо легко припустити інше: спільне приєднання рендерить один ресурс на кожного споживача, і кожен несе той самий матеріал з однієї декларації. Рендеринг виконується для кожного компонента, тому назва ресурсу, виведена з {{ .context.instance_id }}-{{ .attachment_name }}, відрізняється для кожного споживача. Спільною є одна декларація; випущені ресурси не дедуплікуються в один. Один параметр, прочитаний на кожному з’єднанні, рендериться так само за реалізації, що рендерить ресурс, — по одному на з’єднання, а назва приєднання — це псевдонім з’єднання, крапка і слот.
Якщо розгортанню потрібен рівно один фізичний Secret, який читають кілька споживачів, виразіть це сутністю Feature облікових даних, чия сутність FeatureRecipe виконується в області межі (executionScope: boundary) і рендерить один раз для межі, а не один раз для кожного компонента.
Ключ, який тримають обидва кінці з’єднання
Сервер, що перевіряє ключ, і компонент, що його викликає, тримають цей ключ кожен на своєму боці. Сервер тримає ключ, який він перевіряє, у слоті власної сутності Component — core/ai-model/vllm, core/ai-model/tei і core/ai-model/tgi кожен оголошують api_key, як і модель та шлюз LiteLLM для ключа, який LiteLLM називає своїм майстер-ключем, — а його сутність Recipe доставляє те, що заповнює слот, як змінну, яку читає сервер. Той, хто викликає, тримає ключ, який пред’являє, на своєму боці: на з’єднанні, на якому його пред’являє, у слоті, який оголошує його сокет, — так, як сокет model компонента core/ai-agent/crewai оголошує credential, — або, якщо його сутність Component оголошує ключ на собі, у цьому слоті, для кожного з’єднання, яке він встановлює. Жоден кінець не бачить приєднань іншого: приєднання на з’єднанні потрапляє лише до того, хто викликає, а відрендерений вивід сервера однаковий, хоч би що несли з’єднання, які до нього доходять. Сервер ніколи не дізнається, який ключ тримає той, хто викликає, а той, хто викликає, читає лише те, що публікує сервер, — адресу та назву моделі. Обидва кінці узгоджені, бо сутність Aggregate живить їх з одного параметра:
spec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key router: type: local/gateway/model-router # its `models` socket declares a `credential` slot uses: models: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-keyЧи це один секрет, чи два, залежить від того, де обидва кінці розв’язують секрети. Провайдер розв’язує секрет за посиланням у межах області секретів: простору імен Kubernetes у helm, проєкту Compose у compose, кореневої конфігурації межі в terraform, а в cloudformation — стека, в обліковому записі та регіоні AWS, у які він розгортається. Якщо обидва кінці в одній області, вони посилаються на один ресурс секрету. Якщо в різних, кожен кінець тримає власний ресурс секрету, реалізований з того самого запису сховища. Сутність Manifest вибирає реалізацію кожного кінця — за типом Feature або, для окремого приєднання, за його назвою, яка для приєднання з’єднання має вигляд <alias>.<slot> (local.credential вище). Оскільки обидва живить один параметр, обидві реалізації читають origin як той самий вид локатора: обидві — як назву Secret, обидві — як ключ запису сховища або обидві — як саме значення.
У helm, коли обидва кінці в одному просторі імен, зв’язування core/referenced-secret з helm/k8s-existing-secret і задоволення параметра назвою Secret, що є в цьому просторі імен, model-keys, змушує обидва кінці посилатися на нього за назвою, і жоден Secret не рендериться. Контейнер сервера несе:
- name: VLLM_API_KEY valueFrom: secretKeyRef: name: model-keys key: api-keyа сутність Recipe маршрутизатора читає ту саму назву та ключ зі свого з’єднання, у .context.uses.local.features.credential.provides. Коли обидва кінці в різних просторах імен, зв’язування з helm/k8s-external-secret і задоволення параметра ключем запису сховища дає кожному кінцю власний ExternalSecret у власному просторі імен, і обидва отримують цей один запис. У compose обидва кінці несуть те саме посилання ${VAR}, яке Docker Compose підставляє з середовища, з яким запускається цей один проєкт. Таке розміщення — домовленість, якої дотримується каталог стандартної бібліотеки; компілятор нічого не порівнює між двома кінцями.
Один ключ обслуговує кожного, хто викликає. vLLM, TEI і TGI кожен перевіряють один ключ, тож кожен, хто викликає, пред’являє той самий ключ, і сервер не може відрізнити одного викликача від іншого, хоч скільки з’єднань до нього доходить. Це власне обмеження сервера. TGI порівнює свій ключ без урахування регістру, тож два ключі, що відрізняються лише регістром, для нього один ключ. Модель і шлюз LiteLLM також приймають ключі, які видають самі, поки приєднано їхню облікову базу даних.
Облікові дані, які генерує ціль
Якщо сутність Release не надає облікових даних, сутність каталогу часто вдається до значення за замовчуванням для розробки — вбудованого значення в сутності Recipe, значення за замовчуванням параметра модуля. Це значення однакове для кожного читача каталогу, що прийнятно для ознайомлення і ні для чого іншого. core/random-password усуває цю потребу: ніхто не пише облікові дані, бо їх генерує ціль.
Збірка не може бути місцем, де створюється пароль. Її вивід — чиста функція її входу і ніколи не несе значення секрету, тож пароль, згенерований під час збірки, змінювався б з кожною збіркою і лежав би у відрендерених файлах. Натомість сутність FeatureRecipe рендерить запит — ресурс-генератор, що називає ресурс секрету, який він заповнює, — а ціль генерує значення під час розгортання:
- у
helm— контролер у кластері: генератор паролів External Secrets Operator, що узгоджується черезExternalSecret, або контролер kubernetes-secret-generator, що узгоджуєStringSecret; - у
terraform—random_passwordпровайдера random, що генерується під час застосування конфігурації; - у
cloudformation— секрет Secrets Manager, який генерує власний рядок, коли стек його створює.
У кожному випадку відрендерений вивід називає генератор і ресурс секрету та не несе жодного значення. Це властивість того, що є у збірки, а не захист, який вона додає: значення не існує, доки його не створить ціль. Де ціль зберігає його потім — справа цілі: Terraform зберігає його в плані та стані, кластер — у Secret.
Що має працювати на цілі. Запит виконується лише там, де щось його виконує. У helm це контролер, а компілятор не може оглянути кластер, щоб дізнатися, чи він працює, тож сутності FeatureRecipes для helm зупиняють збірку, якщо тільки сутність Release не підтвердить передумову через infra.control_plane_present: true на приєднанні. У terraform і cloudformation значення генерує сам apply або стек, і заздалегідь нічого не має працювати.
Де його не можна використати. Compose не запускає жодного контролера і не має ресурсу, що генерує значення, тож жодна сутність FeatureRecipe не реалізує там core/random-password, і збірка, що зв’язує його на compose, зупиняється через відсутність такої. Сутність Release, націлена на compose, надає облікові дані через core/secret-value, зазвичай як посилання на змінну, яке Docker Compose підставляє під час запуску стека.
Як його читає споживач. core/random-password публікує ті самі provides.name і provides.key, що й core/referenced-secret, і несе ту саму мітку feature.aggrega.ai/kind: secret, тож слот, що вибирає сімейство облікових даних, його допускає, а споживач читає згенеровані облікові дані точно так само, як і ті, що вже існують.
Як кілька споживачів спільно використовують одні. Генератор створює нове значення для кожного запиту, тож правило спільного використання з попереднього розділу діє ще суворіше: згенеровані облікові дані, приєднані в спільній області — або на кожному споживачі, — рендерять один запит на споживача, і кожен запит генерує інший пароль, яким база даних і її клієнти не можуть користуватися. Одні згенеровані облікові дані, спільні для кількох споживачів, виражаються як один запит і багато посилань: core/random-password на одному компоненті, зі значенням name, що фіксує Secret, який він заповнює, і core/referenced-secret на інших, зв’язаний із реалізацією existing-Secret і спрямований на ту саму назву. Записані з одного параметра, вони не можуть розійтися, і рендер несе рівно один запит, на який посилається кожен споживач.
core/random-password — це не core/generated-secret. Та сутність Feature передає облікові дані рушію, який уже володіє всім їхнім життєвим циклом, — керованій базі даних, контролеру бази даних — і нічого не рендерить. core/random-password рендерить сам запит для робочого навантаження, чия сутність Recipe очікує отримати облікові дані.
Пріоритет приєднань
Приєднання може бути оголошене одночасно в кількох областях. Право власності на спірне поле визначається трьома правилами, що застосовуються в такому порядку:
- Походження. Явно записане поле переважає поле, внесене розгортанням на основі анотацій, незалежно від того, з якої області походить кожне з них.
- Повноваження композиції. Декларація в сутності Aggregate, яку ви розгортаєте, переважає декларацію всередині сутності Aggregate, яку вона компонує, навіть коли скомпонований документ оголосив її у вужчій області.
- Специфічність. У межах одного рівня авторства вужча область уточнює ширшу поле за полем: заповнення на рівні компонента перевизначає приєднання з тією самою назвою екземпляра на рівні всієї підсистеми чи всієї межі лише для тих полів, які воно згадує, а поля, які воно пропускає, зберігають значення ширшої області.
Сторона розробника надає values, а сторона оператора — infra, тож вони ніколи не змагаються за те саме поле. Сутність Feature облікових даних, яка бере свій локатор з будь-якої зі сторін, оголошує його як два поля, по одному на стовп, а її власне твердження відхиляє приєднання, що несе обидва, тож і там пріоритету не доводиться розв’язувати нічию. Пріоритет керує лише значеннями полів; він не змінює порядок обчислення, який слідує каскадній послідовності в 10-compilation-pipeline.md.
Застарілі чарти, що вимагають відформатованого рядка
Чарт іноді хоче один рядок підключення з вбудованим матеріалом — oracle://admin:PASSWORD@HOST:1521/DB. Компілятор ahead-of-time не може побудувати цей рядок з координати сховища, бо ніколи не тримає матеріал. Два підтримувані шляхи:
Шаблонізація на боці кластера. Сутність FeatureRecipe облікових даних випускає ресурс, який форматує рядок у кластері, використовуючи власну шаблонізацію оператора сховища секретів. Застосунок потім посилається за назвою на отриманий Secret платформи, а компілятор пов’язав цей зв’язок, жодного разу не тримаючи матеріал:
{ "apiVersion": "external-secrets.io/v1beta1", "kind": "ExternalSecret", "metadata": { "name": "oracle-dsn-secret" }, "spec": { "target": { "name": "oracle-formatted-dsn", "template": { "engineVersion": "v2", "data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" } } }, "data": [ { "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } } ] }}Підняття параметрів. Сутність Aggregate оголошує типізований параметр, а навколишній CI-конвеєр надає значення під час збірки через parameters: сутності Release — наприклад, файл, який записує конвеєр і який сутність Release імпортує за допомогою parameters: { $import: ./ci-parameters.yaml }. Це явний запасний вихід, і він робить компроміс видимим: матеріал тепер проходить через збірку, тож відрендерений вивід його несе, і з ним треба поводитися відповідно.
Локальна розробка
Зразковий шлях локальної розробки залишає намір розробника незмінним і замінює зв’язування. Сутність Aggregate і далі приєднує той самий тип Feature облікових даних; локальна сутність Manifest зіставляє цей тип з локальною сутністю FeatureRecipe замість тієї, що спирається на сховище. Компілятор і далі нічого не отримує — локальна сутність FeatureRecipe просто доставляє рідний для провайдера синтаксис, який розв’язує локальне середовище виконання: для Compose це посилання на змінну, наприклад ${SECRET_NAME}, записане в середовище сервісу, яке Docker Compose підставляє з середовища оболонки або з файлу .env під час запуску стека. Зміна середовища — це редагування сутності Manifest.
Керування даними навколо облікових даних
Aggrega не моделює схеми даних — рядки, стовпці, файли є справою застосунку. Вона моделює ідентичність керування даних за допомогою міток, і домовленість стандартної бібліотеки така:
- Дані живуть у компонентах, чия онтологічна мітка позначає їх як компоненти зі станом або ресурсоподібні (
component.aggrega.ai/type: stateful-server,resource). Брокер повідомлень, що зберігає корисні навантаження в черзі, теж належить до них: він несеstateful-server, коли володіє власним диском, іresource, коли сутність Release під’єднує розміщений брокер, а полицяmessaging, під якою його переглядають, — це окрема вісьcomponent.aggrega.ai/category. compliance.aggrega.ai/data-class(public,internal,restricted) надає цим даним семантичну ідентичність. Домовленість фіксує ключ і його значення, а не те, які компоненти його несуть: жодна сутність Component стандартної бібліотеки його не несе, бо клас даних, які тримає компонент, — це твердження про те, як організація використовує компонент, а не властивість продукту, тож організація вказує його на власних сутностях Components. Це звичайна мітка: селектори міток її обчислюють, а плагін керування, який приєднує оператор, може її прочитати й відхилити збірку. Сам компілятор її не інтерпретує і не ставить жоден клас вище за інший — які класи існують і як вони впорядковуються, визначають власні налаштування приєднаної політики, як у ../language-reference/examples/policy-data-class-route/.
data-class і sensitive — це дві осі, і їх злиття втрачає інформацію. Вони стоять поруч, і їх легко сплутати з однією поверхнею, тож тримайте в голові цю відмінність:
compliance.aggrega.ai/data-class | sensitive | |
|---|---|---|
| Форма | градуйована — public / internal / restricted | булева |
| Гранулярність | цілий вузол | один лист схеми або один слот приєднання |
| Що виражає | яку ідентичність керування мають дані, які тримає компонент | що цей елемент даних є секретним матеріалом або що ця точка зв’язування з ним працює |
| Як записується | мітка в metadata.labels | ключове слово в декларації |
Жодна не замінює іншу: втиснення чутливості в градуйовану мітку нав’язало б упорядкування факту, який його не має, а втиснення класу даних на лист нав’язало б гранулярність, якої класифікація не має. Сутність може нести обидві, і компонент, що тримає дані restricted і чий слот облікових даних оголошено як sensitive, стверджує дві окремі правдиві речі. Ключові слова для листа і слота пояснено в ../language-reference/vocabulary/compact-form-authoring.md «Оголошення листа чутливим» та ../language-reference/entities/component.md «Оголошення слота чутливим».
Шифрування даних у стані спокою свідомо лишається поза наміром розробника і поза компілятором. Воно належить до сутності Recipe від Ops для компонента зі станом і до плагіна рендерингу, який читає мітки вузла і випускає конфігурацію зашифрованого сховища. Таке розміщення — це настанова щодо дизайну про те, куди належить це питання, — компілятор не перевіряє, чи дотримується її будь-яка сутність Recipe.
Що тут є відмінним, а що ні
Публічне позиціонування варто формулювати просто й вузько, щоб читач міг правильно його оцінити.
Відмінне: контракт сокета публікується, а не оголошується inline. Контракт, якому мають відповідати облікові дані, — слот, його список дозволених способів доставки, його селектор міток — створює на сутності каталогу той, хто її опублікував, і він зберігається в каталозі, який супроводжує третя сторона. Споживач не описує контракт inline у власній конфігурації; він заповнює контракт, опублікований кимось іншим, а компілятор перевіряє це заповнення щодо опублікованого оголошення. Споживач і автор контракту — різні люди, які працюють у різних репозиторіях і з різною частотою випусків.
Відмінне: заповнення обмежене селектором міток. Слот може вказати, який різновид речі може його заповнити (selector: "feature.aggrega.ai/kind=secret"), замість того щоб називати конкретну реалізацію. Перевірка є обчисленням набору міток, тож сутність може приймати родину заповнень, про які вона ніколи не чула, а нове заповнення стає допустимим, коли має правильні мітки.
Не відмінне: відображення ін’єкції. Відображення «ця назва локальної змінної середовища отримує те створене значення» — добре відомий шаблон; кілька інструментів конфігурації та розгортання виражають ту саму ідею власним синтаксисом. Версія Aggrega — це відображення, обчислене заздалегідь і злите в канал доставки, але ідея належить екосистемі, а не нам.
Не відмінне: статична генерація наперед. Статична генерація артефактів розгортання з опису вищого рівня, без доступу до живого кластера під час генерації, не є винаходом Aggrega. Інші інструменти роблять це і робили це ще до появи Aggrega. Те, що додає Aggrega, — це шар опублікованих контрактів над нею, а не сама статична генерація.
Це не межа безпеки. Ніщо в цьому розділі не є механізмом конфіденційності. Модель облікових даних — це модель з’єднань: вона визначає, звідки береться вказівник або значення, хто може його обмежувати і як він потрапляє до контейнера. Захист матеріалу — завдання сховища секретів, кластера та конвеєра, що обробляє відрендерене дерево.
Перехресні посилання
- 05-invariants.md — інваріанти компіляції наперед і рядкового каналу, на яких ґрунтується цей розділ.
- 10-compilation-pipeline.md — де в конвеєрі розташовані розв’язання вкладень і етап Resource Generation.
- ../language-reference/entities/component.md — створення слотів
featuresSchema, зокрема оголошенняsensitiveна рівні слота, ключове словоrequiredі порівняння слота з вимогою присутності пункт за пунктом. - ../language-reference/vocabulary/compact-form-authoring.md — ключове слово
sensitiveна рівні листка, місце, де зчитується оголошення, і асиметріяparameters:. - ../language-reference/entities/workload.md — мапа
attachments:контейнера та її правила валідації. - ../language-reference/examples/04-secrets.md — контрольний список для створення та розібрані приклади transparent / blackbox.
- ../language-reference/examples/05-credential-features.md — родини Feature для облікових даних і наскрізний покроковий приклад.
- ../language-reference/examples/model-api-key-sharing/ — слот облікових даних, який оголошує сокет агента і який на кожному з’єднанні заповнюється трьома способами з однієї сутності каталогу: ключ на з’єднання, один Secret, на який посилається кожне з’єднання, і спільне значення за замовчуванням, яке перевизначає одне з’єднання, разом із відрендереним результатом кожної форми.