Перейти до вмісту
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, утворюють увесь шлях від прикріплення автора до запущеного робочого навантаження.

Сімейство облікових Features

Облікова 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: їх доставляють у канал inject під ключем key прикріплення, а сутність Recipe для Compose, що читає слот, записує їх в емітований файл точно так, як їх задано, тож origin, записаний як ${DB_PASSWORD}, потрапляє як це посилання. Він не створює жодного ресурсу, тому ім’я, яке він публікує, порожнє, а ключ, який він публікує, — values.key.

core/referenced-secret-set реалізується в Docker Compose через compose/dotenv-secret-set, який доставляє кожен запис у канал inject як змінну, названу за його ключем, і записує її в середовище сервісу точно так, як її задано, тож запис зі значенням ${GITHUB_TOKEN} потрапляє як це посилання. Він не створює жодного ресурсу, тому локатор, який він публікує, порожній: споживач у Compose читає записи зі свого каналу inject, а не посилається на 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, а Спільне використання облікових даних — для кожного споживача, спільно та обидва варіанти одночасно показує кількох споживачів, що мають власний ключ або спільно використовують один.