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

Модель учётных данных

Одно семейство присоединений

Учётные данные в Aggrega — это сущность Feature. Их присоединяют на той же поверхности, под тем же ключевым словом и в той же форме, что и любую другую сущность Feature. Здесь разработчик присоединяет учётные данные базы данных в сущности Aggregate, записывая их локатор в values:

# the Aggregate — its parameters and the components' own values left out
spec:
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 out
spec:
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 ожидает получить учётные данные.

Приоритет вложений

Вложение может быть объявлено сразу в нескольких областях. Принадлежность спорного поля определяется тремя правилами, применяемыми в следующем порядке:

  1. Происхождение. Явно записанное поле побеждает поле, внесённое раскрытием на основе аннотаций, независимо от того, из какой области пришло каждое из них.
  2. Полномочия композиции. Объявление в сущности Aggregate, которую вы развёртываете, побеждает объявление внутри сущности Aggregate, которую она компонует, даже если компонуемый документ объявил его в более узкой области.
  3. Специфичность. В пределах одного уровня авторства более узкая область уточняет более широкую поле за полем: заполнение на уровне компонента переопределяет вложение с тем же именем экземпляра на уровне всей подсистемы или всей границы только для упомянутых в нём полей, а опущенные поля сохраняют значения более широкой области.

Сторона разработчика предоставляет 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-classsensitive
Формаградуированная — 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, на который ссылается каждое соединение, и общее значение по умолчанию, которое переопределяет одно соединение, вместе с отрендеренным результатом каждой формы.