Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Manifest

Концептуальна роль сутності Manifest (домен 4 — таблиця зіставлень, що прив’язує абстрактні інтерфейси до конкретних сутностей Recipes) описана в architecture/04-entity-taxonomy.md. Ця сторінка охоплює авторський інтерфейс сутності Manifest: як вона співіснує із сутністю Release, форму плаского зіставлення URI, композицію через extends, правила скорочених URI, прив’язки сутностей Feature на основі анотацій і зарезервований платформою префікс aggrega.ai/.

Manifest і Release: розділення відповідальності

Сутності Manifest і Release мають відповідальності, що не перетинаються:

  • Сутність Manifest визначає, який Recipe реалізує кожен тип каталогу, а через spec.capability цього Recipe — провайдера (наприклад, Helm, Helm-chart, Compose), який його рендерить. Це таблиця зіставлень — закомічений у Git запис для кожного проєкту про те, який конкретний Recipe реалізує кожен абстрактний інтерфейс; версії та дайджести, яких збірка вимагає від цих Recipes, закріплюються окремо, у lockfile кожної сутності Release.
  • Сутність Release визначає місце призначення (наприклад, фізичну вихідну теку для генерації артефактів GitOps). Це маршрутизатор розгортання — опис для кожного середовища того, куди потрапляють скомпільовані артефакти.

Схема сутності Release не містить поля provider на жодному рівні вкладеності; диспетчеризація провайдерів належить виключно сутності Manifest.

Шлях компіляції. Коли користувач запускає aggrega build --release release.yaml, компілятор визначає фізичні артефакти, поєднуючи обидва джерела:

  1. Читання місця призначення. Компілятор сканує межі сутності Release — наприклад, межа ovh-cluster-3 містить компонент user-db (тип: core/postgres:1.0.0).
  2. Сканування Manifest. Компілятор відкриває Manifest, на який сутність Release вказує через своє поле manifest:.
  3. Дворівневий пошук. Спочатку перевіряється рівень name на наявність "user-db". Якщо збігу не знайдено, перевіряється рівень type на наявність "core/postgres:1.0.0" (з версією), а потім "core/postgres" (без версії).
  4. Визначення Recipe. Значенням відповідного запису є URI сутності Recipe; названий ним Recipe оголошує в spec.capability, який провайдер його рендерить.
  5. Генерація виводу. Тепер компілятор знає цільову теку (dist/boundaries/ovh-cluster-3/), провайдера (рендеринг Helm через Wasm) і артефакт (вихідний код сутності Recipe). Межі GitOps, визначені заздалегідь, дотримуються від початку до кінця.

Пласке зіставлення URI

Блок mappings: у Manifest — це пласка мапа від URI типу компонента до URI Recipe (і від URI типу функції до URI FeatureRecipe). На рівні Manifest зіставлення не залежить від можливостей: можливість визначається полем spec.capability кожного розв’язаного Recipe під час рендерингу, а не структурою Manifest. Блок упорядковує зіставлення під двома ключами верхнього рівня:

  • components.type зіставляє URI типу компонента з URI Recipe. Кожен екземпляр компонента оголошеного типу розв’язується до вказаного Recipe. Зіставлення є взаємно однозначним для кожного типу компонента. Ключ, що не називає точного типу екземпляра, однаково досягає його через базу типу, якщо жоден ключ не називає цей точний тип і для тієї самої бази не написано іншого ключа, — тож ключ, написаний без версії (core/postgres), або ключ, що називає іншу версію (core/postgres:1.0.0), може досягти екземпляра core/postgres:2.0.0, — але Recipe, який він називає, має реалізовувати власну версію кожного такого екземпляра: екземпляр core/postgres:2.0.0, досягнутий у такий спосіб і зіставлений із Recipe, що оголошує implements: core/postgres:1.0.0, зупиняє збірку. Зіставте такий екземпляр ключем, що називає його версію (core/postgres:2.0.0), з Recipe, який її реалізує.
  • features.type зіставляє URI типу функції з URI FeatureRecipe. Кожне приєднання Feature оголошеного типу розв’язується до вказаного FeatureRecipe. Облікові Features (з міткою feature.aggrega.ai/kind: secret) містяться в тій самій мапі features.type, що й операційні Features, — це єдина модель сутності Feature.

Кожен блок також приймає рівень name поряд із type, який зіставляє конкретне ім’я екземпляра з URI Recipe (або FeatureRecipe). Рівень імен має пріоритет над рівнем типів: екземпляр, названий у components.name, розв’язується до цього Recipe, тоді як кожен інший екземпляр того самого типу розв’язується через components.type. Так виражається перевизначення для окремого екземпляра — два екземпляри одного типу компонента можуть розгортатися через два різні Recipes (наприклад, більшість екземплярів бази даних використовують масово зіставлений Recipe, а один екземпляр закріплено за іншою фізичною реалізацією), без розгалуження типу компонента чи дублювання Manifest. Перевизначення застосовується однаково: названий екземпляр і рендериться через Recipe перевизначення, і закріплює з нього своє джерело. features.name — симетричний рівень для приєднань Feature, ключем якого є власне ім’я приєднання — ключ, під яким його записано у features: компонента, — і ніколи не ім’я компонента, до якого його приєднано. Приклад перевизначення Recipe для окремого екземпляра наскрізно розбирає мінімальний випадок із двома екземплярами.

Ключем приєднання, яке несе з’єднання, є ім’я, яке воно отримує в компоненті-споживачі: <alias>.<slot> — псевдонім, під яким записано з’єднання, крапка і слот, який заповнює приєднання (див. запис з’єднання в сутності Aggregate). Тож облікові дані одного з’єднання можна реалізувати інакше, ніж будь-яке інше приєднання того самого типу:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

Запис закріплюється й перевіряється, як і будь-який інший запис рівня імен, як описано в наступному абзаці. Feature, яку називає приєднання, також закріплюється й перевіряється — так само, як Feature приєднання, записаного безпосередньо в компоненті, — під записом з’єднання, який написав його автор; див. Файл блокування.

Ключ name має називати те, що є у збірці. Рівень зіставляється за точним ім’ям, тож ключ components.name, який не є екземпляром компонента у збірці, або ключ features.name, який не є приєднанням у ній, — найчастіше ім’я компонента, на якому розташоване приєднання, записане там, де має бути власне ім’я приєднання, — ні до чого б не застосовувався, а екземпляри, для яких його призначено, мовчки розв’язувалися б через рівень type. Натомість збірка зупиняється на такому ключі ще до будь-якого рендерингу, називаючи Manifest, ключ, імена цього виду, які у збірці є, та ім’я, яке ви, імовірно, мали на увазі, — див. A Manifest name mapping names nothing in the build (зіставлення Manifest не називає нічого у збірці).

Реалізація, прив’язана за ім’ям, закріплюється й перевіряється так само, як прив’язана за типом. aggrega pull отримує кожен Recipe і FeatureRecipe, які прив’язує будь-який із рівнів, — з каталогу, кешу чи реєстру — і записує кожен у файл блокування сутності Release з його розв’язаною версією та дайджестом вмісту під записом зіставлення, що його прив’язує: manifest.spec.mappings.components.name.<instance> для запису рівня імен, поряд із manifest.spec.mappings.components.type.<type> для запису рівня типів. aggrega build перевіряє кожну з них на відповідність закріпленню. Файл блокування, у якому немає рядка для реалізації, яку прив’язує Manifest, зупиняє збирання як застарілий, називаючи реалізацію і запис, що її прив’язує; реалізація, вміст якої змінився після отримання, зупиняє його так само, називаючи обидва дайджести. В обох випадках aggrega pull --release <release> записує реалізацію в її поточному стані. Як і запис type, запис name закріплюється незалежно від того, чи оголошує Release екземпляр із таким ім’ям, тож запис name, що називає Recipe, якого немає в жодному каталозі чи реєстрі, зупиняє отримання; запис name, що не називає жодного екземпляра у збірці, теж закріплюється і зупиняє збірку, як описано в попередньому абзаці.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Визначення можливості під час рендерингу. Запис Manifest прив’язує тип компонента до URI Recipe. URI Recipe містить щонайбільше два сегменти — необов’язкову початкову можливість, потім ім’я рецепта — плюс необов’язковий :version; розв’язувач розділяє лише за першим /, тож посилання з третім сегментом не називає жодного рецепта і зупиняє розв’язання. Під час рендерингу розв’язувач завантажує Recipe прямим пошуком URI у файлі блокування та каталозі, а поле spec.capability кожного Recipe визначає групування диспетчеризації за парою (шлях, можливість). Структура Manifest лишається пласкою незалежно від того, скільки постачальників підтримує ширший каталог.

Прямий пошук URI

Значенням зіставлення в Manifest є URI Recipe. Компілятор розв’язує URI безпосередньо у файлі блокування та каталозі, повертаючи відповідний Recipe. Він не перебирає оголошення spec.implements, щоб знайти Recipe, який «реалізує» тип компонента. Кожен запис Manifest прив’язує створений розробником тип компонента до конкретного URI Recipe; вибір явний і однозначний у вмісті Manifest.

spec.implements — це перевірка узгодженості таблиці зіставлень. Значення spec.implements розв’язаного Recipe МУСИТЬ збігатися з ключем типу компонента в Manifest для цього запису зіставлення — або з базовим типом, який цей ключ розширює через extends на будь-якій глибині ланцюжка, оскільки Recipe, написаний для базового типу, реалізує все, що його розширює. Значення, яке не збігається з жодним із них, спричиняє OPS_ERROR зі зрозумілою діагностикою, що називає запис Manifest, розв’язаний Recipe і конфліктне значення spec.implements. Перевірка спрацьовує один раз для кожного запису зіставлення Manifest, над скомпонованим Manifest і до розв’язання будь-якого Recipe — статично, детерміновано й без обходу будь-чого, крім власного ланцюжка extends зіставленого типу. Ключ components.type, який досягає екземпляра компонента у версії, яку він не називає, оцінюється для цього екземпляра ще раз у той самий спосіб: на місці ключа тоді стоїть власний тип екземпляра у версії, у якій збірка його компілює, як описано в розділі Пласке зіставлення URI. Що Recipe базового типу робить і чого не робить для спеціалізації, див. у ../vocabulary/inheritance-and-interface.md.

Її виконує кожна команда, що читає залежності сутності Release, і кожна сама вирішує, що означає виявлена проблема: aggrega build і aggrega pull зупиняються, оскільки обидві створюють те, чим ви користуватиметеся далі, тоді як aggrega validate і aggrega lint повідомляють про неї разом з іншими знахідками й завершуються з ненульовим кодом, а редактор публікує її як одну з діагностик. Для оцінювання екземпляра винятком є aggrega lint: він оцінює записи зіставлення, а не екземпляри, яких вони досягають, тож не повідомляє про це, тоді як aggrega build, aggrega pull і aggrega validate --release повідомляють. Діагностику та спосіб виправлення див. у ../errors/fatal-halts.md.

Перевірка узгодженості — єдине місце зіставлення, яке читає ланцюжок extends. Вибір Recipe лишається точним за ключем зіставлення: тип компонента, що розширює зіставлений базовий тип, однаково потребує тут власного запису й не отримує запису через успадкування.

spec.implements також пропонує кандидатів. Екземпляр, тип якого не має зіставлення в Manifest, зупиняє збирання з OPS_ERROR, що перелічує як кандидатів для закріплення рецепти, чий spec.implements здатен реалізувати цей тип; автодоповнення в редакторі для значення зіставлення ставить ці самі рецепти першими. Обидва місця порівнюють spec.implements із самим запитаним типом, тож рецепт, що реалізує один із базових типів цього типу, не пропонується як кандидат, хоча зіставлення визнали б узгодженим. Отже, spec.implements оголошує, що рецепт може реалізувати, і допомагає людині зробити вибір — у перевірці узгодженості, діагностиці відсутнього зіставлення та автодоповненні, — але ніколи не розв’язує збирання. Зіставлення в Manifest — це явний вибір розгортання користувачем, закріплений у файлі блокування для відтворюваності; каталог ніколи не обирає розгортання замість користувача.

Три форми сегмента версії в URI

URI сутності Recipe у сутності Manifest може містити версію в будь-якій із трьох форм:

  • Точна — helm/postgres:1.2.0. Lockfile має закріплювати саме цю версію; під час першого розв’язання lockfile резолвер закріплює цю версію; якщо каталог або реєстр не містить цієї версії на момент розв’язання, завантаження робочого простору зупиняється з помилкою.
  • Діапазон — helm/postgres:^1.2.0. Діапазон semver зі стандартним правилом MVS; під час першого розв’язання lockfile резолвер закріплює найвищу доступну версію, що задовольняє діапазон.
  • Без версії — helm/postgres. Без суфікса :version; під час першого розв’язання lockfile резолвер закріплює найновішу доступну версію.

Наступні збірки використовують версію, закріплену в lockfile, незалежно від форми, яку ввів користувач. Повторне розв’язання до новішої версії потребує явної дії користувача — aggrega pull --upgrade --release <release> <uri> повторно розв’язує одну залежність, утримуючи всі інші закріплення, а aggrega pull --upgrade --release <release> повторно розв’язує всі — lockfile є джерелом істини для збірок; форма, яку ввів користувач, — це спосіб, у який користувач виражає обмеження версії під час написання.

Посилання з кваліфікатором можливості

Ідентичність Recipe у каталозі обмежена можливістю: два рецепти можуть мати однакові metadata.name і версію, водночас оголошуючи різні значення spec.capability. Ідентичність у реєстрі — recipe/{capability}/{name}:{version}, що виводиться з виду рецепта, його spec.capability без будь-якого закріплення версії, яке воно може містити, та його імені; дерево каталогу стандартної бібліотеки за домовленістю віддзеркалює цю координату в recipe/{capability}/{name}/. Значення зіставлення в Manifest називає рецепт з однією з двох точностей:

  • Просте — mariadb:1.0.0. Розв’язується, коли рівно один рецепт у каталозі має це ім’я; на практиці це переважна форма.
  • З кваліфікатором можливості — compose/mariadb:1.0.0. Сегмент перед першим / називає spec.capability рецепта без закріплення версії — закріплення, записане в посилання, відхиляється (E0095). Обов’язкове, коли більше ніж один рецепт постачається з тим самим ім’ям: просте посилання, що збігається з двома рецептами, є неоднозначним і гучно зупиняє розв’язання, а не мовчки вибирає один із них.

URI сутності Recipe не має інших позицій. Резолвер розділяє лише за першим /, тож compose/mariadb називає можливість compose і рецепт mariadb, а посилання з трьох сегментів не збігається з жодним рецептом за жодної точності.

Наведені вище форми сегмента версії застосовуються до обох форм посилання.

Сутності, опубліковані в реєстрі, у зіставленнях

На сутність, що споживається з реєстру, а не з локального каталогу, посилаються за точно тією самою ідентичністю, що й на локальну: посилання не містить ні хоста реєстру, ні сегмента виду сутності. Резолвер підставляє обидва — хост із налаштованого реєстру за замовчуванням робочого простору, сегмент виду — з місця посилання в схемі — згідно з правилами контекстних скорочених URI нижче. Коли копії немає ні в локальному каталозі, ні в кеші, aggrega pull — або збірка, запущена з --auto-pull, — завантажує сутність із виведеного розташування, кешує її та закріплює розв’язану версію й дайджест вмісту в lockfile; наступні збірки використовують кеш без доступу до мережі.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Оскільки хост і сегмент виду сутності виводяться, а не пишуться автором, додавання будь-якого з них до посилання не адресує опубліковану сутність — воно створює ідентичність, якої не має жоден запис каталогу. Посилання на сутність Component або Feature — це її metadata.name дослівно плюс необов’язковий :version, незалежно від того, чи розв’язується сутність із локального каталогу, з кешу чи з реєстру. Робочий простір, що споживає приватний реєстр, називає цей хост у власній конфігурації, а не в кожному посиланні.

Перевірка повноти

Після розв’язання всіх зіставлень компілятор перевіряє, що кожен екземпляр компонента та вкладення (облікова сутність Feature є вкладенням, як і будь-яке інше) у сутності Aggregate розробника має розв’язану сутність Recipe або FeatureRecipe. Незіставлені сутності спричиняють фатальну зупинку з явною діагностикою, що перелічує кожну відсутню сутність і пропонує, який ключ components.type або features.type додати, щоб усунути прогалину.

Якорі YAML для маніфестів без повторів

Щоб уникнути роздування YAML у великих наборах зіставлень, сутність Manifest підтримує необов’язковий блок defs: для стандартних якорів YAML (& і *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Узгодження можливостей Feature

Узгодження можливостей використовує те саме пласке зіставлення URI:

  1. Розробник вкладає core/data-masking у компонент у сутності Aggregate під власним ім’ям у мапі features: цього компонента.
  2. Компілятор шукає core/data-masking у мапі features.type сутності Manifest.
  3. Якщо пошук розв’язується в URI сутності FeatureRecipe (наприклад, helm/data-masking-litellm:1.0.0), можливість існує, і конвеєр сутності FeatureRecipe виконується у визначеному порядку.
  4. Якщо features.type не містить відповідного запису, компілятор зупиняє збірку й перелічує незіставлену сутність Feature.

Сутність Manifest також приймає блок features.annotations — паралельну поверхню написання, яка дає змогу сутності Release або підсистемі Aggregate вкладати Features за ключем анотації, а не через оголошення для кожного компонента. Форма прив’язки, розподіл «бічне проти стовпа», що визначає, яка поверхня написання використовує які шляхи маршрутизації, принцип переваги явного вкладення та правило значень схеми за замовчуванням описано в окремому розділі Прив’язки Feature на основі анотацій нижче.

Композиція через extends

Manifest може оголосити одне посилання extends:, що називає базовий Manifest, чиї mappings він успадковує. Посилання не є URI і ніколи не розв’язується через каталог: Manifest належить до боку розгортання й створюється поруч із Release, а не публікується, тому значення — це або відносний шлях до файлу Manifest — ./base-manifest.yaml, — або голий metadata.name сутності Manifest, що лежить у власному каталозі Release. Відносний шлях має вести до Manifest усередині робочого простору — або, якщо Release названо поза робочим простором (у командному рядку чи в конфігурації робочого простору), усередині каталогу, що містить цей Release, а для Manifest, який ви окремо називаєте в командному рядку поза робочим простором, — усередині каталогу, що містить цей Manifest: шлях, який виходить назовні або який виводить назовні символьне посилання, відхиляється ще до читання файлу, на який він вказує (див. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside” (Посилання на інший файл виводить за межі каталогу, в якому має залишатися)). Дочірні зіставлення перезаписують базові в разі збігу ключів, що підтримує шаблони накладання середовищ (паритет staging/prod із точковими відмінностями для кожного середовища) і шаблони локальної розробки без повного копіювання.

Семантика злиття. Коли локальний Manifest розширює базовий Manifest, компілятор виконує поверхневу заміну ключів для кожного рівня — словники type і name зливаються незалежно, без глибокого злиття, — що гарантує пошук у словнику за O(1) і робить поведінку успадкування передбачуваною. У межах кожного рівня дочірні ключі перезаписують батьківські.

Шаблон мосту для локальної розробки. Типове застосування extends — заміна FeatureRecipe для облікових даних під час локального прототипування без змін в Aggregate. У продакшені базовий Manifest зіставляє Feature облікових даних core/aws-secrets-manager із продакшн-сутністю FeatureRecipe на рівні features.type. Для локального прототипування команда платформи надає local-manifest, який розширює базовий і точково перевизначає зіставлення Feature облікових даних на host-env-injector — локальну FeatureRecipe, що передає облікові дані у файл Compose як посилання на змінну, наприклад ${SECRET_NAME}, яке Docker Compose підставляє з оточення оболонки або з файлу .env під час запуску стека. Розробник отримує стандартний локальний робочий процес, а Aggregate лишається агностичним щодо можливостей для продакшену.

Контекстно-залежні скорочені URI

Під час розв’язання OCI URI у сутностях Manifests компілятор Aggrega застосовує контекстно-залежне виведення. Якщо інженер пропускає повне доменне ім’я (FQDN) і тип архітектурної сутності, компілятор автоматично використовує реєстр за замовчуванням (налаштований у .aggrega-config.yaml) і виводить тип сутності з того, де рядок розташований у схемі.

Правила виведення:

  1. Домен за замовчуванням: до будь-якого URI без домену (наприклад, python-worker-helm:1.0) додається префікс налаштованого default_registry (за замовчуванням: hub.aggrega.ai/).
  2. Контекстне розгортання сутності: компілятор додає правильний шлях сутності на основі суворого словника схеми:
    • Рядки в Aggregate.spec.components[].type розгортаються до /component/.
    • Рядки в Aggregate.spec.aggregates[].type розгортаються до /aggregate/.
    • Рядки в Manifest.spec.mappings.components.type або Manifest.spec.mappings.components.name розгортаються до /recipe/.
    • Рядки в Manifest.spec.mappings.features.type або Manifest.spec.mappings.features.name розгортаються до /featurerecipe/. Це стосується й облікових сутностей Features (з міткою feature.aggrega.ai/kind: secret) — вони використовують той самий шлях FeatureRecipe.
    • Рядки, призначені pipeline[].plugin, розгортаються до /plugin/.
  3. Трирівневий пріоритет: перед застосуванням OCI-виведення компілятор шукає в каталогах каталогу робочого простору та в кеші артефактів (рівень робочого простору й кешу), як визначено в трирівневій моделі розв’язання сутностей. OCI-виведення застосовується лише тоді, коли сутність доходить до рівня реєстру. Ключ або значення зіставлення ніколи не читається як шлях до файлу: локально створений Recipe або FeatureRecipe лежить у каталозі каталогу — catalog/ у корені робочого простору або в одному з тих, що перелічує workspace.catalog_dirs, — і називається своїм посиланням.

Скорочення на практиці:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Без префікса ops/. Імена сутностей Recipe не мають префікса ops/ — каталог типу сутності recipe/ у таксономії OCI вже визначає домен, і сутності Recipes публікуються за шляхом recipe/{capability}/{name} без додаткових префіксів. Сутності Manifests посилаються на Recipes за {capability}/{name} або за простим ім’ям для контекстно-залежного виведення. Повну таксономію OCI див. у architecture/13-catalog-and-registry.md §6.

Прив’язки Feature на основі анотацій

Блок features.annotations сутності Manifest оголошує прив’язки між ключами анотацій і типами Feature, а також шляхи маршрутизації, якими кожна прив’язка передає значення анотації. Прив’язка — це засіб авторингу, що дає змогу стиснути повторювані приєднання Feature до окремих компонентів (шаблон, за якого десятки компонентів у межах однієї межі мають однаковий блок features:) до поодиноких оголошень анотацій на межах Release або в підсистемах Aggregate.

Форма схеми:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Прив’язка містить поле feature, що називає цільовий тип Feature, і блок maps, який групує маршрути підключів із шляхами через крапку за цільовою опорою. Поле feature посилається на тип Feature, який також має бути в сусідньому розділі features.type (саме там розміщено прив’язку версії FeatureRecipe). Блок maps оголошує два списки з ключами-опорами — maps.infra і maps.values, — кожен із яких містить рядки шляхів через крапку, що вказують на властивості spec.schema.<pillar>.<path> цільової Feature. Прив’язка має оголосити принаймні один шлях у двох списках разом (JSON Schema вимагає minProperties: 1 для maps).

Поліморфізм Provider для одного й того самого ключа анотації — наприклад, feature.aggrega.ai/rewrite-host прив’язується до core/k8s-dns-resolver у розгортанні Kubernetes, але до core/compose-bridge у локальному розгортанні Compose — виражається вибором різних типів Feature у різних Manifests; кожен Manifest прив’язує анотацію до одного Feature, а FeatureRecipe вибраного Feature містить реалізацію, специфічну для провайдера.

Розподіл «сторона–опора». Інваріант Aggregate-as-Authoring-Surface обмежує кожну сторону авторингу шляхами маршрутизації однієї опори. Анотації на боці Aggregate маршрутизуються лише через шляхи maps.values; анотації на боці Release — лише через шляхи maps.infra. Прив’язка, що оголошує шляхи в обох опорах, підтримує композицію між сторонами: анотація на боці Aggregate активує підмножину опори values; анотація на боці Release для того самого ключа активує підмножину опори infra; обидва внески складаються в одне приєднання Feature на пару (Component, Feature) із заповненими обома опорами. Невідповідність сторони й опори — наприклад, анотація на боці Aggregate для прив’язки, що оголошує лише maps.infra, — зупиняє збирання зі зрозумілою діагностикою, яка називає ключ анотації, опору маршрутизації, сторону авторингу та місце в джерелі й належить до домену документа, у якому було написано значення анотації.

Перевірка цілей шляхів. Під час завантаження каталогу компілятор перевіряє, що кожен шлях через крапку, оголошений у maps.infra і maps.values, відповідає властивості, яку справді оголошує spec.schema.<pillar> цільової Feature. Прив’язка, що маршрутизує до шляху, якого немає в схемі Feature, зупиняє завантаження каталогу зі зрозумілою помилкою OPS_ERROR, яка називає прив’язку, цільову Feature, а також опору й шлях маршрутизації. Форми схеми, що виходять за межі простого обходу властивостей ($ref, patternProperties, композиція oneOf / anyOf / allOf), завершують статичну перевірку на цій гілці й залишають виявлення невідповідностей подальшій валідації схеми.

Форми значень анотацій. Прив’язка приймає значення анотацій у трьох формах. Скалярне — одне значення YAML (рядок, число, булеве значення). Скаляр у парі з прив’язкою, що оголошує рівно один шлях у двох опорах разом, маршрутизує значення до цього єдиного шляху; скаляр у парі з прив’язкою, що оголошує більше одного шляху, є неоднозначною маршрутизацією й зупиняє збирання зі зрозумілою діагностикою, що належить до домену документа, у якому було написано значення анотації. Структуроване — мапа YAML, кожен підключ верхнього рівня якої відповідає запису шляху через крапку в maps.infra або maps.values; кожен підключ маршрутизується до своєї оголошеної опори незалежно, і розподіл «сторона–опора» застосовується до кожного підключа окремо. Явне YAML null — відмовляється від успадкованої прив’язки в області каскаду (а null для окремого підключа всередині структурованого значення відмовляється від цього підключа, тоді як сусідні залишаються). Канонічні настанови щодо авторингу структурованих значень — каскадне злиття за підключами, композиція між сторонами, перевірка типів за підключами, послаблена дисципліна типових значень для полів схеми без оголошеного type — див. у providers/well-known-annotations.md §«Structured annotation values».

Явне приєднання перемагає за збігу ключів. Коли компонент Release або компонент Aggregate має і явний запис features:, і анотацію, що розгортається в той самий ключ Feature, явний запис зберігається, а розгортання анотації для цього ключа на цьому компоненті нічого не робить. Синтетичне приєднання ніколи не перезаписує екземпляр Feature, оголошений автором. Тож автори можуть застосовувати розгортання анотацій для більшості компонентів і точково перевизначати окремі компоненти, написавши явний запис features: з тим самим ключем: явний запис містить налаштування конкретного компонента, а анотація каскадно поширюється на всі інші компоненти без змін.

Перевага явного запису на рівні листків під час композиції між сторонами. Коли явне приєднання та внесок анотації заповнюють той самий екземпляр Feature, але записують у різні листки, обидва внески зберігаються, і отримана Feature містить обидва листки з походженням, записаним для кожного листка окремо. Коли явне приєднання та внесок анотації націлені на той самий листок у тій самій опорі, перемагає явний внесок, а IR записує походження пригніченої анотації як маркер перевизначення на цьому листку. Завантаження каталогу повідомляє про це перевизначення під час збирання дорадчим попередженням лінтера, яке називає ключ і джерело пригніченої анотації.

Типові значення схеми під час розгортання. Синтетичне приєднання Feature, створене розгортанням анотації, містить лише листки, які значення анотації заповнює через оголошені шляхи прив’язки. Типові значення схеми, оголошені в spec.schema цільової Feature, не зливаються із синтетичним приєднанням під час розгортання. Матеріалізація типових значень — відповідальність шару рендерингу FeatureRecipe, що однаково застосовується до явних і синтетичних приєднань, тож обидва шляхи дають однаковий результат для однакової ефективної конфігурації.

Розділення просторів імен анотацій:

ПрефіксВласникПризначення
aggrega.ai/Лише платформа AggregaВласні анотації платформи, які провайдер читає безпосередньо (наприклад, aggrega.ai/namespace).
feature.aggrega.ai/Офіційна стандартна бібліотекаСкорочення анотацій Feature, прив’язані в Manifest.
{any-other-domain}/Підприємство / спільнотаВласні скорочення анотацій Feature.

Резервування префікса aggrega.ai/

Прив’язки features.annotations у сутності Manifest не можуть використовувати голий префікс aggrega.ai/ — його зарезервовано для платформних анотацій, які генерує компілятор (мітки OTel/походження тощо). Обмежені підпрефікси (component.aggrega.ai/*, compliance.aggrega.ai/*, корпоративний acme.aggrega.ai/*) залишаються доступними для авторів. Набір зарезервованих платформою анотацій див. у providers/well-known-annotations.