Архітектура Provider
Провайдер рендерить вхідні види сутності Recipe у нативні для провайдера файли маніфестів. Коли Recipe оголошує capability: helm, capability: compose або будь-яку іншу назву провайдера, компілятор передає рендеринг провайдеру, який обслуговує цю назву. У цьому розділі описано, як провайдер реалізується як сутність Plugin для рендерингу провайдера, як працює диспетчеризація, а також контракт plugin-socket, що пов’язує компілятор із кожним провайдером.
Що цей розділ не охоплює: модель композиції з трьох вхідних видів (source: + valuesMapping:, workload:, artifacts: — кожен приймає вбудований вміст або $import:), яку Recipe використовує для створення свого результату. Ця модель наскрізна для всіх провайдерів і описана в ../../architecture/16-recipe-input-composition.md, зокрема матриця можливостей провайдерів (Provider Capability Matrix), яка показує, який вхідний вид підтримує кожен провайдер.
Сутність Plugin для рендерингу провайдерів
Рендеринг Provider обслуговує Plugin з pluginType: provider. Plugin для рендерингу провайдера:
- обслуговує одне або кілька імен провайдерів — оголошених у
spec.provider.capabilities. Ім’я провайдера, яке називає сутність Recipe (spec.capability: helm), прив’язується до сутності Plugin для рендерингу провайдерів, чий списокspec.provider.capabilitiesмістить це ім’я. Коли ту саму ціль обслуговує більше ніж одна сутність Plugin, робочий простір обирає між ними через прив’язку провайдера в.aggrega-config.yaml, яка розв’язується під часaggrega pullі записується в lock-файл; якщо прив’язки немає і кандидат рівно один, використовується цей кандидат, а якщо прив’язки немає і кандидатів більше одного, збірка явно зупиняється з переліком плагінів-кандидатів. - містить метадані сокета провайдера в тому самому блоці —
spec.providerзберігає наведений вище список можливостей разом з рештою оголошень провайдера.spec.provider.workloadSchema— це оголошення JSON Schema 2020-12, що документує, як тип Workload, яким володіє платформа, перетворюється на нативний вихід цього провайдера; каталог стандартної бібліотеки оголошує його для провайдерів, які виконують синтез, як задокументований контракт перетворення.spec.provider.wellKnownAnnotationsперелічує граничні анотаціїaggrega.ai/, які читає провайдер. Підтримка синтезованого входу (workload:) є властивістю провайдера і перевіряється під час рендерингу — її не визначає наявністьworkloadSchema.
Повний опис полів для створення сутності Plugin, зокрема блоку spec.provider, див. у ../entities/plugin.md.
Диспетчеризація за провайдером
Кожен Recipe оголошує рівно один capability: на початку свого spec. Компілятор читає це поле й передає рендеринг провайдеру, що обслуговує цю назву. Recipe не може водночас націлюватися на кілька провайдерів. Композиція з кількома провайдерами відбувається на рівні сутності Release: межа може містити компоненти різних провайдерів, і внески кожного провайдера за обчисленим шляхом складання межі складаються незалежно — одне складання на кожен кортеж (path, provider).
Шлях диспетчеризації для одного вузла:
- Компілятор визначає URI сутності Recipe для цього вузла через трирівневий пошук у Manifest у розділі зіставлень цільового провайдера. Саме групування Manifest за віссю провайдерів робить «той самий Component, різні Recipes для різних провайдерів» природним шаблоном.
spec.capabilityзнайденого Recipe визначає назву провайдера, якому передається рендеринг.- Компілятор прив’язує провайдера для цієї назви: він знаходить Plugin для рендерингу провайдера, чий список
spec.provider.capabilitiesмістить цю назву, і виконує рендеринг через гостьовий модуль цього Plugin. Рендеринг відбувається лише через Wasm — немає вбудованого в хост рендерера, до якого можна було б повернутися, тож назва провайдера, для якої не знайдено жодного Plugin, явно зупиняє збірку на етапі маршрутизації. - Провайдер викликається з контекстом рендерингу вузла (значення стовпів, проєкції
.context.*, вхідні типи Recipe). - Провайдер повертає відрендерений результат. Компілятор спрямовує відрендерені файли до складальника для кожного
(path, provider), ключем якого є обчисленийdirectory:межі, об’єднаний ізsubDirectory:кожного компонента. Дві межі, що обчислюються в той самий шлях для того самого провайдера, спільно використовують складальник — канонічний шаблон: батьківська межа плюс дві дочірні межі зdirectory: "{{ .parent_boundary.directory }}", що зливаються в одне об’єднане складання.
Див. ../entities/manifest.md щодо форми диспетчеризації Manifest за віссю провайдерів і ../entities/recipe.md щодо оголошення одного провайдера на боці Recipe. Модель складання для кожного (path, provider) і список дозволених змінних шаблонів шляхів, що керує обчисленими шляхами, описано в ../path-template-variables.md.
Контракт Wasm-плагіна
Рендеринг Provider виконується всередині пісочниці WebAssembly. Компілятор Go є хостом; Plugin provider-rendering є гостем. Для кожного вузла компілятор передає плагіну контекст рендерингу вузла, а плагін повертає файли, які він відрендерив. Цей контракт однаковий для кожного провайдера:
- Канонічне бінарне кодування в обох напрямках. Компілятор кодує контекст рендерингу — значення та вкладення вузла, розібраний
.workload, обчислені записи артефактів, перелік лише імен розв’язаного.sourceі метадані межі — як канонічний CBOR (RFC 8949 §4.2.1) і передає його плагіну. Плагін відповідає в тому самому кодуванні списком відрендерених файлів — для кожного шлях відносно кореня виводу вузла та точні байти для запису туди, за потреби з форматом файлу — разом із будь-якою діагностикою. Кожен експорт сокета, від рендерингу одного вузла до складання межі та з’єднання зв’язку між межами, передає це кодування в обох напрямках, а набір для розробки плагінів кожної мови декодує та кодує його для плагіна. Відповідь, яка не відповідає формі виводу експорту в цьому кодуванні, зупиняє збірку. Контракт плагінів документує корисне навантаження кожного експорту. - Без доступу до файлової системи. Plugins не можуть читати довільні файли з файлової системи хоста. Джерело, яке називає Recipe, — чарт у реєстрі, модуль у репозиторії — компілятор розв’язує до запуску плагіна; плагін отримує перелік його вмісту лише з іменами й запитує в компілятора вибрані файли через функцію хоста, яка відповідає лише щодо файлів у джерелі цього вузла.
- Без доступу до мережі. Plugins детерміновані й герметичні та не відкривають власних з’єднань. Зовнішні вхідні дані, потрібні плагіну під час рендерингу, — віддалена схема, на яку посилаються значення чарту, — запитуються через функцію хоста компілятора для зовнішніх вхідних даних, яка відповідає вмістом, закріпленим робочим простором для цього посилання.
- Детермінований вивід. За ідентичного входу й тієї самої версії плагіна плагін має створювати побайтово ідентичний вивід. Саме цей контракт забезпечує дію гарантії побайтово ідентичного виводу компілятора наскрізно через рівень плагінів. Збірка, запущена з
--verify-determinism, рендерить кожен вузол двічі й зупиняється, якщо два рендери вузла відрізняються.
Архітектуру сокетів плагінів на ширшому рівні розширюваності, включно з іншими сокетами Wasm у конвеєрі компіляції (ролі перетворення та вердикту сокета керування), описано в ../../architecture/14-extensibility.md.
Провайдери стандартної бібліотеки Aggrega
Провайдери helm, helm-chart, compose, terraform і cloudformation разом утворюють набір провайдерів стандартної бібліотеки. Вони охоплюють поширені цілі розгортання, і корпоративним командам не потрібно створювати власних провайдерів.
helm підтримує всі три види вхідних даних: sourced (upstream-чарт Helm, отриманий через Helm SDK, де вихід valuesMapping сутності Recipe слугує перевизначеннями чарту), synthesized (плаский Kubernetes YAML — об’єкт-контролер, вибраний за form сутності Workload (Deployment, StatefulSet, DaemonSet, Job або CronJob), разом із Services і PVC — згенерований із розібраної сутності Workload) і artifacts (окремі YAML-файли поруч із виходом чарту). Які з трьох видів він приймає, див. у матриці можливостей Provider Capability Matrix у ../../architecture/16-recipe-input-composition.md.
helm-chart підтримує режим sourced (композиція umbrella-чарту: один чарт на межу, один підчарт на компонент) і artifacts: поряд із ним, в обох формах написання. Запис artifacts:, завантажений через $import:, спершу обробляється Go-шаблонізатором Aggrega, а потім до рендерингу вставляється в каталог templates/ чарту; запис artifacts: із вбудованим вмістом обчислюється так само й розміщується в корені підчарту без додавання відомостей про походження, де власні шаблони чарту зчитують його через .Files.Get / .Files.Glob Helm. Окремий Recipe лише з artifacts не належить до видів, які він оголошує, як і вид synthesized: umbrella-чарт оркеструє підчарти, тоді як вид Workload — це листове поняття, що належить усередині кожного підчарту (галузь провайдера helm).
compose підтримує sourced (завантажує compose-файл і глибоко зливає з ним накладку valuesMapping), synthesized (генерує compose services: + volumes: + networks: із розібраного Workload для форм stateless і stateful, з обмеженою обробкою томів для persistentTemplate — PVC для кожної репліки згортаються в один спільний іменований том із попередженням; форми daemon, scheduled і task не мають відповідника в compose і явно зупиняють збірку) і artifacts (фрагменти compose, чиї ключі верхнього рівня services: / networks: / volumes: / configs: зливаються в об’єднаний для кожної межі docker-compose.yaml). Artifacts можуть іти поряд із будь-яким із двох інших видів, а окремий Recipe лише з artifacts — artifacts: без source: і без workload: — теж є видом, який оголошує цей провайдер: його фрагменти зливаються за тими самими правилами, тож вузол додає саме те, що оголошує, і не потребує Workload замість обчислень, яких у нього немає.
terraform підтримує sourced (дослівно включає модуль Terraform і передає вихід valuesMapping як аргументи блоку module цього компонента в кореневій конфігурації межі) і artifacts (генерує написане автором тіло HCL або .tf.json у тому вигляді, у якому його обчислює шаблон, не переписуючи його). Вид вхідних даних synthesized він не пропонує — немає точного відображення виду Workload платформи на довільні ресурси Terraform. Провайдер генерує конфігурацію і ніколи не запускає Terraform; значення, що залежать від середовища виконання, лишаються рядками інтерполяції ${ ... }, які середовище Terraform розв’язує під час apply.
cloudformation рендерить межу в один шаблон стека AWS CloudFormation: збирає фрагменти ресурсів, написані її компонентами, в єдиний шаблон на чистому JSON, виводить provides кожного компонента як Outputs стека і зв’язує ребра uses як Fn::GetAtt у межах стека та як Fn::ImportValue / Fn::GetStackOutput між стеками. Він підтримує вхідні дані sourced і artifacts та генерує конфігурацію, ніколи не запускаючи CloudFormation; значення, відомі лише під час виконання, лишаються вбудованими функціями CloudFormation.
Покажчик довідки провайдерів веде до власної довідкової сторінки кожного провайдера; які види вхідних даних приймає кожен із них, показує матриця можливостей у ../../architecture/16-recipe-input-composition.md.
Власні провайдери
Корпоративні команди, які створюють власні провайдери, дотримуються того самого підходу, що й стандартна бібліотека: створюють сутність Plugin для рендерингу провайдера (pluginType: provider), яка оголошує в spec.provider.capabilities назву (або назви) провайдера, який вона обслуговує, разом з рештою своїх метаданих spec.provider, а потім постачають артефакт Wasm, що реалізує описаний вище контракт рендерингу. Компілятор обробляє власні провайдери так само, як провайдери стандартної бібліотеки; диспетчеризація за провайдером працює за назвою провайдера, оголошеною в сутності Recipe.
Створення провайдера задокументовано, а не відкладено на потім. Посібник Створення провайдера від початку до кінця будує робочий гостьовий модуль провайдера — самоопис describe(), збірку, сутність Plugin, під’єднання та рендеринг, результат якого можна прочитати. Посібник розробника плагінів Wasm є довідником щодо сутності та життєвого циклу публікації, а контракт плагінів описує структури вхідних даних і результатів кожного сокета. Гостьові модулі пишуть мовами Go, Rust або TypeScript з використанням набору засобів розробки плагінів.