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

Учётные данные как Features

Эта страница объясняет одну идею, Features для учётных данных из стандартной библиотеки и то, как сущность Manifest выбирает, что реализует каждую из них, и не является запускаемым рабочим пространством. Одно намерение разработчика, две формы доставки учётных данных собирает одну сущность Aggregate для двух реализаций одних и тех же учётных данных; запишите его в собственную папку так:

Terminal window
aggrega scaffold --example credential-shape-per-target

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

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

Учётные данные заполняют слот, который сущность Component объявляет в своём featuresSchema (см. entities/component.md); слот, заполняющая его Feature и FeatureRecipe, которую привязывает Manifest, образуют весь путь от присоединения автора до запущенной рабочей нагрузки.

Семейство Feature для учётных данных

Feature для учётных данных несёт метку feature.aggrega.ai/kind: secret. Метка — это метаданные каталога, описывающие, что создаёт присоединение; ни одна ветвь компилятора её не читает, и Feature для учётных данных присоединяется в features: как любая другая Feature — разработчиком в Aggregate или оператором в Release.

Стандартная библиотека разделяет Features для учётных данных по тому, что реализация делает с секретом:

  • core/secret-value доставляет значение в канал внедрения компонента, где его читает Recipe этого компонента, — значение чарта, переменная окружения.
  • core/secret-provided тоже даёт значение, но вместо этого публикует его как ключ provides, так что куда оно направляется, указывает собственный блок inject: присоединения на прозрачном слоте.
  • core/referenced-secret именует секретный ресурс — Kubernetes Secret, секрет AWS Secrets Manager, запись Vault, — который создаёт его реализация или который уже существует, и публикует name и key этого ресурса, которые потребитель читает как .features.<slot>.provides.name и .features.<slot>.provides.key.
  • core/referenced-secret-set материализует один такой ресурс, содержащий заданный автором набор ключей данных, и публикует только его локатор — для потребителя, чья цель уже фиксирует имена читаемых ключей. В Docker Compose такого ресурса нет, поэтому там его реализация вместо этого доставляет ключи как значения, как описано ниже. Его использует MariaDB (чарт Bitnami) — один многоключевой Secret с учётными данными.
  • core/generated-secret не создаёт ничего: целевой движок сам генерирует учётные данные и управляет ими, как это делает управляемая база данных со своим паролем администратора. Оператор присоединяет его в Release, потому что то, владеет ли движок учётными данными, следует из Recipe, который выбирает Manifest; Terraform RDS (встроенный артефакт HCL) так привязывает обязательный слот.
  • core/random-password отрисовывает запрос к цели сгенерировать пароль в секретный ресурс и публикует локатор этого ресурса так же, как core/referenced-secret. Никто не записывает учётные данные, и отрисованный вывод их не содержит.

Они равноправны — та же метка, та же поверхность присоединения, тот же слот, — поэтому слот всегда заполнен, а между сущностями Releases меняется то, чем он заполнен. Feature для учётных данных, объявляющая контракт provides, обязывает каждую реализующую её FeatureRecipe публиковать эти ключи, и сборка останавливается, если какая-то этого не делает; именно это делает чтение потребителем безопасным.

core/random-password нуждается в чём-то на цели, что сгенерирует значение, поскольку сборка этого никогда не делает: в Kubernetes — в контроллере (External Secrets Operator или kubernetes-secret-generator), наличие которого Release подтверждает через infra.control_plane_present: true; в Terraform — в ресурсе random_password; в CloudFormation — в секрете Secrets Manager, который генерирует собственную строку. Для Docker Compose реализация не поставляется, поэтому сборка, привязывающая её там, останавливается. Каждый запрос получает собственное значение, поэтому два компонента совместно используют один сгенерированный пароль, если подключить её один раз с закреплённым name, а в другом месте читать пароль через core/referenced-secret, привязанную к helm/k8s-existing-secret.

Кто указывает учётные данные: values или infra, ровно одно из двух

core/secret-value, core/secret-provided, core/referenced-secret и core/referenced-secret-set принимают локатор учётных данных от любого из авторов: разработчик записывает его в values привязки в сущности Aggregate, оператор — в infra привязки в сущности Release. Лист одинаков в обоих — origin или entries для набора, — и каждая реализация читает тот столп, в котором он находится.

Форма оператора позволяет использовать учётные данные там, где разработчик не может их записать: на соединении, которое связывает Release, и на привязке, которую создаёт только Release, поскольку Release нигде не записывает values.

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

Ровно одно из двух. Каждый столп проверяется отдельно, поэтому ни одна из схем не может требовать локатор; вместо этого правило содержат собственные assertions каждой сущности Feature, и привязка, несущая локатор в обоих столпах или ни в одном, останавливает сборку (E0033) с указанием Feature, привязки и компонента. Это контракт сущностей каталога: компилятор вычисляет их утверждение так же, как утверждение любой Feature.

Всё остальное остаётся в своём столпе. key остаётся листом values, поэтому привязка, которую создаёт только Release, читает ключ данных по умолчанию — value. Объявление origin в обоих столпах — именно то, что ищет предупреждение о пересечении столпов, поэтому загрузка этих Features выдаёт его — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Здесь пересечение — это контракт; предупреждение не меняет ни одного вердикта и ни одного байта вывода.

Сущность Manifest выбирает реализацию

Несколько FeatureRecipes могут реализовывать одну Feature для одной и той же цели, и выбирает Manifest. У core/referenced-secret их три в Kubernetes, и выбор между ними определяется тем, где хранятся учётные данные:

  • helm/k8s-secret-from-parameter записывает заданное автором значение в выпускаемый им Secret, поэтому секретные данные оказываются в отрендеренном выводе: для ознакомления и локальной работы.
  • helm/k8s-external-secret рендерит ExternalSecret, указывающий на запись в хранилище секретов, которую External Secrets Operator в кластере согласует в Secret.
  • helm/k8s-existing-secret ничего не выпускает: он читает origin как имя уже существующего Secret и публикует его в том виде, в каком оно записано.

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

core/secret-value реализуется в Docker Compose через compose/dotenv-secret, который записывает значение в окружение сервиса ровно в том виде, в каком оно задано: origin, записанный как ${DB_PASSWORD}, попадает туда как эта ссылка, которую Docker Compose заполняет из вашей оболочки или файла .env при запуске стека. В Kubernetes helm/env-secret доставляет значение в канал внедрения, а helm/k8s-secret-from-value также записывает его в Secret и публикует его локатор — для потребителя, который читает учётные данные по ссылке. Ни одна из реализаций для Kubernetes не принимает ссылку на переменную Compose, которую там ничто не заполнило бы.

core/referenced-secret реализуется в Docker Compose через compose/dotenv-referenced-secret. В Compose нет ресурса секрета, на который можно сослаться, поэтому origin — это сами учётные данные, а не имя Secret: они доставляются в канал внедрения под ключом key прикрепления, а сущность Recipe для Compose, читающая слот, записывает их в выпускаемый файл ровно в том виде, в каком они заданы, так что origin, записанный как ${DB_PASSWORD}, попадает как эта ссылка. Он не создаёт никакого ресурса, поэтому публикуемое им имя пусто, а публикуемый ключ — values.key.

core/referenced-secret-set реализуется в Docker Compose через compose/dotenv-secret-set, который доставляет каждую запись в канал внедрения как переменную, названную по её ключу, и записывает её в окружение сервиса ровно в том виде, в каком она задана, так что запись со значением ${GITHUB_TOKEN} попадает как эта ссылка. Он не создаёт никакого ресурса, поэтому публикуемый им локатор пуст: потребитель в Compose читает записи из своего канала внедрения, а не ссылается на Secret по имени, как это делают compose/mcp и compose/mcp-stdio-bridge начиная с 1.1.0 для server_env сервера Model Context Protocol.

Имя FeatureRecipe, поставляемой для нескольких целей, например provided-secret, указывается в сущности Manifest вместе с целью, compose/provided-secret:1.0.0, поскольку имя без префикса совпадает с обоими.

Одно имя, опубликованное один раз

Recipe потребителя никогда не выводит имя Secret, который создают учётные данные: он читает локатор, который публикуют учётные данные, existingSecret: "{{ .features.root_password.provides.name }}". Имя задаётся один раз, в provides сущности FeatureRecipe, поэтому изменение способа его составления — это правка только в этом месте. Доставка учётных данных — secretKeyRef от начала до конца строит путь по ссылке в Kubernetes и путь с внедрением в Docker Compose, а Совместное использование учётных данных — для каждого потребителя, общие и оба варианта сразу показывает нескольких потребителей, у каждого из которых свой ключ или которые используют один общий.