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

Архітектура 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).

Шлях диспетчеризації для одного вузла:

  1. Компілятор визначає URI сутності Recipe для цього вузла через трирівневий пошук у Manifest у розділі зіставлень цільового провайдера. Саме групування Manifest за віссю провайдерів робить «той самий Component, різні Recipes для різних провайдерів» природним шаблоном.
  2. spec.capability знайденого Recipe визначає назву провайдера, якому передається рендеринг.
  3. Компілятор прив’язує провайдера для цієї назви: він знаходить Plugin для рендерингу провайдера, чий список spec.provider.capabilities містить цю назву, і виконує рендеринг через гостьовий модуль цього Plugin. Рендеринг відбувається лише через Wasm — немає вбудованого в хост рендерера, до якого можна було б повернутися, тож назва провайдера, для якої не знайдено жодного Plugin, явно зупиняє збірку на етапі маршрутизації.
  4. Провайдер викликається з контекстом рендерингу вузла (значення стовпів, проєкції .context.*, вхідні типи Recipe).
  5. Провайдер повертає відрендерений результат. Компілятор спрямовує відрендерені файли до складальника для кожного (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 з використанням набору засобів розробки плагінів.