Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Композиция вывода

Одна сборка Aggrega создаёт выходные файлы в каталогах отдельных границ внутри dist/ с помощью шести различных механизмов: рендеринга из источника, синтеза рабочих нагрузок, генерации ресурсов FeatureRecipe, патчей конвейера плагинов FeatureRecipe, композиции на уровне Release и прямого вывода артефактов. Механизмы выполняются в определённом порядке; выходные данные детерминированно конфликтуют, когда два механизма создают файл с одинаковым именем в одном и том же каталоге границы; при обнаружении конфликта сборка останавливается до вывода и называет всех участников, с категорией, которую указывает правило для этого конфликта.

На этой странице шесть механизмов описаны в одном месте и указан порядок рендеринга между ними. Справочники по отдельным главам и сущностям охватывают собственные области; правила обнаружения конфликтов для всех шести механизмов находятся здесь.

Шесть механизмов, порождающих вывод

Каждый механизм относится к определённой поверхности написания Recipe / FeatureRecipe и создаёт файлы по определённым соглашениям об именовании. Механизмы накапливаются для каждого узла: один экземпляр компонента может одновременно задействовать несколько механизмов (базовый Recipe с источником + сопутствующий файл, синтезированный из Workload + CRD ExternalSecret, порождённый FeatureRecipe + патч конвейера плагинов, применённый к синтезированному Deployment).

1 — Рендеринг Recipe из источника (source: + valuesMapping:)

Поверхность написания. Recipe объявляет source: <path> вместе с valuesMapping: (поле принимает встроенный шаблон Go, файловый $import: или библиотечный $import: к записи MappingLibrary — см. entities/recipe.md, раздел «Поле valuesMapping — три режима написания»). Источник указывает на Helm-чарт на диске, YAML-файл docker-compose или другой нативный для провайдера артефакт.

Место в конвейере. Базовый рендеринг, после разрешения locals и provides сущности Recipe.

Форма вывода. Зависит от сущности Provider (Provider-specific):

  • Провайдер helm — плоские YAML-файлы Kubernetes, названные по идентичности компонента, а затем по самому ресурсу: <component-id>-<kind>[-<namespace>]-<name>.yaml; документ без kind или без имени вместо этого называется по пути своего шаблона. Имя берётся из ресурса, а не из шаблона, поэтому два шаблона в разных подкаталогах с одинаковым именем файла остаются двумя файлами. Helm SDK рендерит чарт с объединёнными значениями; Aggrega добавляет метки и аннотации происхождения после рендеринга.
  • Провайдер helm-chart — файлы подчартов, скопированные в charts/<instance_id>/ дословно, за исключением собственного name чарта, которое зонтичный чарт устанавливает в закодированную идентичность экземпляра, чтобы два компонента, включающие чарты с одинаковым именем, оставались различимыми (см. providers/helm-chart.md); рядом создаются зонтичные Chart.yaml + values.yaml для каждой границы.
  • Провайдер compose — промежуточные файлы <nodeID>.compose-fragment.yaml, которые поступают в композицию на уровне Release (механизм 5).

2 — Синтез Workload в Recipe (workload:)

Поверхность написания. Recipe объявляет workload: с документом Workload. Поле принимает встроенное содержимое (блочный скаляр) или $import: (путь к файлу).

Место в конвейере. Базовый рендеринг, после разрешения valuesMapping сущности Recipe (тело Workload само является строкой с шаблоном Go, вычисляемой с полным контекстом шаблона).

Форма вывода. Зависит от сущности Provider (Provider-specific):

  • Провайдер helm — один объект контроллера, выбираемый по form сущности Workload (Deployment для stateless, StatefulSet для stateful, DaemonSet для daemon, Job для task, CronJob для scheduled) + Service для каждого сервиса + один PVC на каждый том persistent. Две формы имён, и они не совпадают: объект контроллера называется по имени релиза узла и своему kind — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml, — тогда как файл отдельного ресурса называется по ресурсу, который он содержит, с kind в конце: <release name>-<svcName>-service.yaml и <release name>-<volName>-pvc.yaml, потому что каждый из них называется по собственному metadata.name этого ресурса. Имя релиза — это идентичность узла, записанная в алфавите, допустимом для имени Kubernetes, поэтому оно совпадает с ID узла везде, где тот не содержит подчёркиваний и заглавных букв: узел my_api записывает my-zuapi-deployment.yaml (см. entities/workload.md, раздел «Synthesized-name convention»). Workload, единственная точка доступа которого — внешнее имя, вместо этого создаёт <release name>-service.yaml, так как ключа сервиса для имени нет.
  • Провайдер compose — промежуточные файлы <nodeID>.compose-fragment.yaml, которые поступают в композицию на уровне Release.
  • Провайдер helm-chart — не поддерживается; роль helm-chart — только композиция чартов в режиме с источником. Recipe, нацеленный на helm-chart и содержащий workload:, отклоняется во время рендеринга (провайдер helm-chart не сообщает о возможности синтеза).

3 — Генерация ресурсов FeatureRecipe (режим с источником для FeatureRecipes)

Поверхность написания. FeatureRecipe объявляет source: вместе с valuesMapping: (или эквивалентом) — тот же шаблон, что и при рендеринге Recipe из источника, но для присоединений Feature, а не для основных Components.

Место в конвейере. Базовый рендеринг, параллельно с базовым рендерингом Recipe для родительского Component. Каждое присоединение Feature выполняет собственный проход рендеринга FeatureRecipe.

Форма вывода. Определяется провайдером родительского Component, потому что вывод присоединения входит в группу сборки этого Component, а не в собственную, — и следует из того, как этот провайдер объединяет группу, поскольку именно это определяет, есть ли вообще место для присоединения. Три формы, по одной на каждый способ объединения:

  • Провайдер, который даёт каждому участнику собственную позицию — один чарт, содержащий по чарту на участника, одна корневая конфигурация, содержащая по модулю на участника, — тоже даёт присоединению собственную позицию, рядом с компонентом, к которому оно присоединено, а не внутри него. Две координаты составляют единственный сегмент каталога этой позиции, <component-id>--<feature-instance-id>, так что компонент api с присоединением aux располагается в api--aux рядом с api, в том каталоге, который этот провайдер назначает для своих участников. Рядом, а не внутри, потому что цель такого провайдера обнаруживает участников в выданных им позициях: каталог на уровень ниже одной из этих позиций — это содержимое, принадлежащее участнику, а не отдельный участник, поэтому на него ничто не ссылается и ничто его не читает. У присоединения, объявленного на границе, нет компонента-хоста для имени, поэтому его сегмент — только имя экземпляра. Каждая координата кодируется до объединения, поэтому координата, сама содержащая последовательность соединения, не может быть принята за соединение.
  • У провайдера, который записывает каждый документ непосредственно в каталог границы, такого места нет, потому что именно это он и объявляет о своей цели: читаются только файлы, лежащие непосредственно в каталоге. Поэтому те же две координаты переходят из сегментов каталога в имя файла, и файлы присоединения оказываются рядом с файлами компонента в виде <component-id>--<feature-instance-id>--<file>. Обе координаты кодируются, потому что у имени файла нет разделителя, на который можно опереться, и присоединяются к собственному имени файла через двухсимвольную границу, которую не может содержать ни одна закодированная координата, — именно это сохраняет два присоединения, создающие одно имя файла, в виде двух разных файлов.
  • Провайдер, который сворачивает участников своей группы в один документ, сворачивает в этот документ и вывод присоединения, причём каждый ресурс несёт собственную идентичность присоединения, чтобы оставалось понятно, что откуда пришло. Если такой провайдер несёт присоединение, отрендеренное для другой цели, это содержимое нельзя свернуть в документ, которому оно не принадлежит, поэтому оно записывается рядом с собранным — в форме с префиксом имени файла, описанной выше, по той же причине.

Типичные формы:

  • CRD ExternalSecret / VaultSecret, сгенерированный Fetcher учётного FeatureRecipe.
  • CRD ServiceMonitor / PrometheusRule, сгенерированный Feature наблюдаемости.
  • CRD HTTPRoute / Gateway, сгенерированный Feature маршрутизации.

4 — конвейер плагинов FeatureRecipe (патчи RFC 6902 + выпуск ресурсов)

Поверхность описания. FeatureRecipe объявляет pipeline: — массив шагов Wasm-плагинов (принцип Two-Part Plugin Principle: Fetcher + Injector для сущностей Features учётных данных; произвольные конвейеры плагинов для сущностей Features, не связанных с учётными данными).

Место в конвейере. Конвейер плагинов, после завершения базового рендеринга и рендеринга FeatureRecipe в режиме с источником.

Форма вывода. Зависит от Plugin-specific логики конкретного плагина. Шаг возвращает два класса вывода:

  • Патчи RFC 6902, которые механизм применения накладывает на адресуемые документы в отрендеренном наборе (например, добавление sidecar-контейнера, монтирование тома с секретом, перезапись переменной окружения в синтезированном Deployment).
  • Побочные эффекты — полноценные новые ресурсы, выпускаемые вместе с патчем через side_effects шага (обычно CRD vault-fetch от Fetcher, на который затем ссылается Injector).

Текущий статус: доступно согласно Статус языка → Фазы конвейера компиляции. Каждый объявленный шаг выполняется во время aggrega build: хост вызывает плагин Wasm шага для отрендеренного набора, применяет возвращённые патчи и выпускает побочные эффекты шага. Описание поверхности контракта плагинов см. в plugins/plugin-contract.md.

5 — композиция на уровне Release (сборка границы для каждого провайдера)

Поверхность описания. Определяется формой Release — без описания на уровне отдельного Recipe. Возможность, собирающая границу, делает это один раз, после того как отрендерен каждый узел этой границы: возможность compose собирает все фрагменты узлов в один docker-compose.yaml на границу, а возможность helm-chart собирает копии вложенных чартов узлов в один зонтичный чарт на границу.

Место в конвейере. После базового рендеринга, когда для границы накоплен вывод каждого узла по его Recipe.

Форма вывода. Зависит от провайдера:

  • Провайдер compose — один docker-compose.yaml в корне границы, объединяющий сервисы, тома и сети всех участвующих узлов. Промежуточные файлы <nodeID>.compose-fragment.yaml (механизмы 1 + 2) сливаются в единый вывод; фрагменты не появляются в итоговом каталоге границы.
  • Провайдер helm-chart — один зонтичный Chart.yaml + values.yaml в корне границы, а также каталоги вложенных чартов узлов в charts/<instance_id>/.

6 — прямой выпуск артефактов Recipe (artifacts:)

Поверхность описания. Recipe объявляет artifacts: как отображение именованных записей; каждая запись — либо встроенное содержимое (шаблонная строка с телом файла), либо ссылка $import: на путь к файлу шаблона — прямой выпуск файла без участия провайдера.

Место в конвейере. Вычисление артефактов в рамках базового рендеринга.

Форма вывода. Один файл на запись артефакта, названный по ключу записи в отображении artifacts:. Автор Recipe напрямую задаёт имя файла и содержимое.

Текущий статус: доступно согласно Статус языка → Виды входных данных Recipe. Каждая запись вычисляется с полным контекстом шаблона после синтеза рабочей нагрузки и разрешения источника, и полученный файл выпускается под ключом записи. Что цель делает с выпущенным артефактом, зависит от возможности: провайдер, принимающий самостоятельный артефакт, выпускает его отдельным файлом, а провайдер, принимающий артефакты только вместе с другим видом входных данных, включает запись в то, что собирает, — поэтому тело, не имеющее ожидаемой сборщиком формы, приводит к остановке в категории TRANSLATION_ERROR, а не выпускается дословно. Прежде чем описывать артефакт для возможности, сверьтесь с таблицей по возможностям в architecture/16-recipe-input-composition.md.

Порядок рендеринга

Шесть механизмов выполняются в определённом порядке, чтобы последующие механизмы могли читать результаты предыдущих. Порядок:

  1. Вычисление provides — для каждого узла сначала разрешается блок locals: сущности Recipe в порядке, заданном автором, причём каждая запись читает записи над ней; затем вычисляются шаблоны provides: узла в произвольном порядке относительно друг друга (самодостаточно: .context.instance_id, .context.rendered_name, если провайдер узла его сообщает, .values, .infra, разрешённые .locals, статический текст). Именно порядок «locals перед provides» позволяет записи provides: прочитать локальное значение и получить уже разрешённое значение.
  2. Публикация locals и разрешение источника — эти локальные значения публикуются в .locals, и шаблон URI source: сущности Recipe вычисляется относительно них (разрешая указатель на источник, если он задан шаблоном). Поверхность источника использует общий контекст locals, поэтому она читает .locals, а не .provides.
  3. Inject mapping — вычисляются блоки injectMapping: сущности FeatureRecipe (конвейер inject перехватывается до рендеринга Recipe).
  4. Values mapping — вычисляется valuesMapping: сущности Recipe (режим с источником и режим без источника формируют словари значений).
  5. Синтез Workload — синтез Workload для Recipe (механизм 2 выдаёт манифесты для синтезированного режима).
  6. Вычисление артефактов — вычисление artifacts: сущности Recipe (механизм 6).
  7. Provider render — отрисовка провайдером (механизм 1 — режим sourced создаёт плоские манифесты; режим sourceless создаёт генеративные манифесты).
  8. Рендеринг Feature — рендеринг FeatureRecipe для каждого подключения Feature на узле (механизмы 3 + 4 — здесь выполняется генерация ресурсов; конвейер плагинов выполняется позже, на шаге 9).
  9. Конвейер плагинов — изменение после рендеринга: шаги плагинов pipeline: сущности FeatureRecipe применяют патчи RFC 6902 и выдают дополнительные ресурсы (механизм 4).
  10. Композиция на уровне Release — сборка границы, выполняемая возможностью, объединяет фрагменты отдельных узлов в результаты для каждой границы (механизм 5).

Порядок важен, потому что последующие механизмы могут читать результаты предыдущих: например, шаг конвейера плагинов может применить патч к Deployment, отрендеренному провайдером, а компоновщик уровня Release может объединить фрагменты, выданные рендерингом провайдера, рендерингом фич и конвейером плагинов.

Набор правил обнаружения коллизий

Когда два механизма создают файл с одинаковым именем в одном каталоге границы, сборка останавливается с указанием всех участников, с категорией, которую называет каждое из правил ниже. Набор правил:

Правило формы Recipe: коллизия ключей записей artifacts:

Recipe объявляет в artifacts: две записи с одинаковым ключом (ключ определяет имя создаваемого файла независимо от того, задано ли тело записи встроенно или загружено через $import:). Обнаруживается при загрузке Recipe согласно errors/fatal-halts.md «artifacts: entry keys must be unique (ключи записей должны быть уникальными)».

Правило формы Recipe: коллизия между видами входных данных во время вывода

Каждый из трёх видов входных данных сущности Recipe — sourced, synthesized и artifacts — выводит файлы в один и тот же каталог границы. Если вывод, отрисованный из источника, синтезированный из рабочей нагрузки или выведенный как артефакт, создаёт файл, имя которого уже создал другой вид входных данных, сборка останавливается на этапе вывода. Обнаруживается во время вывода согласно errors/fatal-halts.md «Emission-time filename collision across input kinds (Коллизия имён файлов между видами входных данных во время вывода)».

Коллизия имён сервисов compose (уровень Release)

Когда два разных узла (в любом сочетании границ) добавляют в объединённый вывод compose сервисы с одинаковым именем, провайдер compose останавливается при компоновке границы с категорией TRANSLATION_ERROR, указывая каждый участвующий кортеж (boundary, node, serviceName). Обнаруживается при компоновке на уровне Release согласно разделу о выводе уровня Release в providers/compose.md.

Сервис отклоняется только по имени, без сравнения того, что объявили два узла. Сервис compose — это один запущенный контейнер, поэтому два узла, каждый из которых хотел свой, получат один на двоих, и намерение одного из участников теряется, насколько бы идентичными ни были два определения.

Конфликт имён томов и конфигураций compose (уровень Release)

Когда два разных узла добавляют в объединённый вывод compose запись верхнего уровня volumes: или configs: с одинаковым именем и эти объявления различаются, провайдер compose останавливается с категорией TRANSLATION_ERROR, указывая запись и каждый участвующий кортеж (boundary, node). Обнаруживается при компоновке на уровне Release согласно разделу о выводе уровня Release в providers/compose.md.

В отличие от правила для сервисов выше, это правило сравнивает объявления, и общее имя допустимо, если участники согласны. Именованный том или конфигурация — это один объект, поэтому два узла, объявившие его одинаково, оба запросили ровно ту запись, которая окажется в объединённом документе, и ничего не теряется. Два узла, объявившие его по-разному, расходятся во мнении об этом одном объекте, и сохранение любого из объявлений отбросило бы другое из сборки, которая иначе завершилась бы успешно. Два объявления считаются согласованными, если они описывают одну и ту же запись в собранном файле, поэтому тело, записанное как пустое отображение, и полностью опущенное тело согласуются.

Псевдоним и каталог подчарта helm-chart

Подчарт helm-chart располагается в charts/<instance_id>/, а его значения ограничены его псевдонимом — идентификатором экземпляра, закодированным для позиции псевдонима. Два экземпляра не могут получить один псевдоним, если их идентификаторы экземпляров не являются одной и той же строкой, поскольку кодирование записывает недопустимые для псевдонима символы, а не заменяет их, — поэтому псевдоним идентифицирует ровно один подчарт, и записанные под ним значения попадают только в этот подчарт. Идентификаторы экземпляров, в свою очередь, уникальны в пределах границы согласно правилам уплощения сущностей Aggregate, поэтому каталог тоже не может конфликтовать. Обе половины структурны: ни одна не опирается на проверку.

Коллизия имён отрисованных ресурсов Helm

В пределах границы два узла, отрисовывающие ресурсы с одинаковым именем Kubernetes, создают два YAML-файла с пересекающимися полями metadata.name. Имена файлов различаются, поскольку каждое имеет префикс собственной основы именования, тогда как metadata.name внутри них всё же может совпасть, — поэтому сборка проверяет имена, которые несут отрисованные ресурсы, и если два участника выводят одно имя для одного kind в одном пространстве имён, сборка останавливается с категорией TRANSLATION_ERROR до записи чего-либо, называя это имя и каждый компонент и каждое присоединение, которые его вывели (см. errors/fatal-halts.md).

Самый крупный случай закрыт конструктивно, а не проверкой. Чарт из источника, называющий свои ресурсы по имени релиза, больше не может вызвать это между двумя компонентами, поскольку две хоть сколько-нибудь различающиеся основы именования дают два имени релиза — см. providers/helm.md «How the release name is derived». Остаются два случая, и именно о них сообщает описанная выше проверка. Первый — чарт, записывающий имя ресурса в свои шаблоны буквально, и никакое выведение не может отличить такое имя от любого другого литерала. Второй — два присоединения Feature к одному компоненту, каждое из которых поставляет чарт, написанный его автором: оба отрисовываются с именем релиза этого компонента, по замыслу, поэтому два чарта, называющие ресурс по .Release.Name, там совпадают — дайте ресурсам двух чартов разные имена или присоедините их к разным компонентам.

Каждое синтезированное имя начинается с собственной идентичности узла — имя объекта-контроллера и каждое имя отдельного ресурса через соглашение об именовании синтезированных сервисов <release name>-<svcName> (согласно entities/workload.md «Synthesized-name convention»), — что делает коллизии между узлами структурно невозможными по построению. Авторам, чья сборка останавливается на имени Deployment / Service, следует сначала проверить, не выводят ли две разные сущности Recipes одноимённые ресурсы разными путями отрисовки (например, templates/deployment.yaml чарта из источника, конфликтующий с metadata.name синтезированного из рабочей нагрузки Deployment).

Шаблоны взаимодействия механизмов

Синтез Workload + патч конвейера плагинов

Канонический шаблон: механизм 2 (синтез рабочей нагрузки) выпускает базовый Deployment; механизм 4 (плагин Injector) применяет патч RFC 6902, который монтирует в Deployment том с секретом. Два механизма компонуются: Deployment остаётся тем же ресурсом K8s, а патч накладывает ссылки на ConfigMap / Secret поверх синтезированной основы.

Это основной шаблон внедрения учётных данных в синтезированные рабочие нагрузки. Fetcher (механизм 3, генерация ресурсов) выпускает CRD ExternalSecret, который кластер получает во время выполнения; Injector (механизм 4, патч конвейера плагинов) изменяет Deployment, чтобы смонтировать полученный K8s Secret.

Источниковый рендеринг + синтез Workload на разных границах

В одной сущности Aggregate один компонент может быть привязан к источниковому helm Recipe (механизм 1) на границе A, а соседний компонент — к helm Recipe, синтезирующему Workload (механизм 2), на границе B. Каталог каждой границы содержит соответствующую форму вывода; имена файлов на разных границах не конфликтуют, поскольку каталоги dist/ отдельных границ изолированы друг от друга.

Слияние compose на уровне Release для каждого выходного каталога

Сборка возможности compose собирает фрагменты отдельных узлов всех границ, каталог которых вычисляется в один и тот же путь, в один docker-compose.yaml по этому пути; две границы одного Release, нацеленные на compose, записывают два файла, если их каталоги различаются, и один объединённый файл, если каталог у них общий.

Поэтому конфликты имён сервисов обнаруживаются для каждого файла при его слиянии на уровне Release согласно приведённому выше правилу. Две границы, нацеленные на compose, в разных каталогах, в каждой из которых объявлен сервис с именем api, не конфликтуют: файл каждой границы содержит свой сервис. Две границы с общим каталогом записывают один файл, и сборка останавливается с указанием обоих участников.

Перекрёстные ссылки

  • entities/recipe.md — средства описания сущности Recipe (механизмы 1 + 2 + 6 формируют вывод из содержимого Recipe).
  • entities/featurerecipe.md — средства описания сущности FeatureRecipe (механизмы 3 + 4 формируют вывод из содержимого FeatureRecipe).
  • providers/helm.md — формы вывода провайдера helm для каждого механизма и соглашения об именовании.
  • providers/helm-chart.md — композиция зонтичного чарта и подчартов в провайдере helm-chart (механизм 5).
  • providers/compose.md — разбиение на фрагменты по узлам и композиция на уровне Release в провайдере compose (механизм 5).
  • errors/fatal-halts.md — правила формы Recipe об уникальности ключей записей artifacts: и о конфликтах имён файлов между разными видами входных данных.
  • templates/expansion-matrix.md — момент вычисления каждого места шаблона в порядке рендеринга.
  • plugins/plugin-contract.md — контракт конвейера плагинов (механизм 4).
  • 10-status.md — текущая степень готовности механизма 6 (artifacts:) и среды выполнения конвейера плагинов механизма 4.
  • architecture/10-compilation-pipeline.md — полный конвейер компиляции, включая порядок стадий рендеринга.
  • architecture/16-recipe-input-composition.md — три вида входных данных Recipe (исходная концепция для механизмов 1 + 2 + 6).