Архитектура сущностей Provider
Провайдер преобразует входные виды сущности Recipe в нативные для провайдера файлы манифестов. Когда Recipe объявляет capability: helm, capability: compose или любое другое имя провайдера, компилятор передаёт рендеринг провайдеру, который обслуживает это имя. В этой главе описано, как провайдер реализуется в виде сущности Plugin для рендеринга провайдеров, как работает диспетчеризация и каков контракт plugin-socket, связывающий компилятор с каждым провайдером.
Что в этой главе не рассматривается: модель композиции из трёх входных видов (source: + valuesMapping:, workload:, artifacts: — каждый принимает встроенное содержимое или $import:), которую Recipe использует для получения своего результата. Эта модель является сквозной для всех провайдеров и описана в ../../architecture/16-recipe-input-composition.md, включая матрицу возможностей Provider (Provider Capability Matrix), которая показывает, какой входной вид поддерживает каждый провайдер.
Сущность Plugin для рендеринга провайдеров
Provider-рендеринг обслуживается сущностью Plugin с pluginType: provider. Plugin для provider-рендеринга:
- обслуживает одно или несколько имён провайдеров, объявленных в
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 }}", сводящиеся в одну объединённую сборку.
Форма диспетчеризации Manifest по оси провайдеров описана в ../entities/manifest.md, а объявление единственного провайдера на стороне Recipe — в ../entities/recipe.md. Модель сборки для (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 (вышестоящий 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 (композиция зонтичного чарта: один чарт на границу, один подчарт на компонент) и artifacts:, идущие вместе с ним, в обеих формах написания. Запись artifacts:, загружаемая через $import:, сначала обрабатывается шаблонизатором Go в Aggrega, а затем внедряется в каталог templates/ чарта до рендеринга; запись artifacts: со встроенным содержимым вычисляется так же и помещается в корень подчарта без добавления сведений о происхождении, где собственные шаблоны чарта читают её через .Files.Get / .Files.Glob Helm. Отдельная сущность Recipe только с artifacts не входит в объявленные им виды, как и вид synthesized: зонтичный чарт оркеструет подчарты, а вид 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 с использованием набора средств разработки плагинов.