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

Переменные шаблонов путей

Поля directory: и subDirectory: границы сущности Release — это шаблоны Go, вычисляемые во время сборки. Они определяют, куда на диске попадают отрисованные артефакты, и, как следствие, какие артефакты собираются вместе: две границы, которые вычисляются в один и тот же кортеж (path, provider), используют общий сборщик и дают один объединённый результат (один Chart.yaml, один docker-compose.yaml). Эта страница — справочник для авторов по переменным, на которые могут ссылаться эти шаблоны, по семантике строгого вычисления и по правилам каскада, позволяющим границам наследовать значения от родительских.

Концептуальное описание пространственного разделения и диспетчеризации по (path, provider) см. в architecture/16-recipe-input-composition.md. Описание авторской поверхности сущности Release см. в entities/release.md. Последствия на стороне провайдеров описаны в providers/architecture.md и на страницах отдельных провайдеров.

Строгое вычисление: missingkey=error

Шаблоны путей вычисляются в режиме Go missingkey=error. Ссылка на необъявленное поле, незаданный ключ parameters.X или опечатка вроде {{ .parmaeters.region }} приводит к явной ошибке, а не к тихой подстановке пустой строки в путь.

Эта строгость асимметрична по отношению к остальному компилятору: valuesMapping, injectMapping и другие поверхности рендеринга значений используют missingkey=zero в соответствии с соглашением Helm/Sprig. Формирование путей структурно отличается: шаблон рендеринга значения, который выдаёт пустую строку, попадает в поле манифеста, где последствия ограничены; шаблон пути, который выдаёт пустую строку, попадает в структуру каталогов, где последствия не ограничены (коллизии, нарушенная сборка, пути-призраки). Строгий режим шаблонов путей существует для того, чтобы выявлять такие сбои во время сборки, а не во время развёртывания.

Проверка по списку допустимых переменных на этапе разбора

Помимо строгости во время выполнения, шаблоны путей проверяются на этапе разбора по закрытому списку допустимых имён переменных. Ссылка на имя переменной, которого нет в этом списке, останавливает сборку до начала какой-либо работы по рендерингу; диагностическое сообщение указывает ошибочное поле и границу, на которой оно встречается.

Список допустимых переменных закрыт намеренно: такие поверхности, как .context.inject, .values и .locals, сознательно не доступны шаблонам путей. Формирование путей — вопрос структуры, а не рендеринга значений; привязка путей сборки к значениям отдельных компонентов сделала бы граф путей зависимым от данных и подорвала бы инвариант детерминированного вывода.

Матрица переменных

Переменнаяdirectory:subDirectory:Описание
{{ .capability }}дадаВозможность рендеринга (helm, helm-chart, compose, terraform, cloudformation), которую объявляет сущность Recipe вносящего вклад компонента, для артефактов, выводимых по этому пути.
{{ .boundary_name }}дадаЗаданное автором имя границы в сущности Release (например, production, eu-prod).
{{ .parameters.X }}дадаЛюбой типизированный параметр, объявленный в сущности Aggregate и заполненный в сущности Release. Строгий доступ — обращение к .parameters.unknown останавливает сборку.
{{ .manifest.recipe_name }}дадаИмя сущности Recipe, разрешённое через Manifest для вносящего вклад компонента. Полезно для направления артефактов каждой сущности Recipe в отдельные подпапки для каждой сущности Recipe.
{{ .parent_boundary.* }}дадаКаскадный доступ к вычисленным значениям объемлющей границы. См. Каскад родительской границы ниже.
{{ .component_id }}—даID экземпляра компонента, вносящего вклад. Для сущности Feature, подключённой на границе, чья сущность FeatureRecipe выполняется один раз для границы (executionScope: boundary), это составной идентификатор, который ресурсы этого подключения несут в своей метке aggrega.ai/component-id, — bfr--app--shared для подключения shared на границе app, сокращённый там, где провайдер подключения ограничивает длину имён, — поэтому вывод подключения попадает в директорию, названную по этой метке. Доступна только в subDirectory:, поскольку directory: является свойством уровня границы — строка директории вычисляется один раз для каждой границы, до любой маршрутизации на уровне компонентов.

По умолчанию поле directory: имеет значение boundaries/, за которым следует путь границы (стабильный идентификатор времени сборки, выводимый из дерева границ); сущность Release, которая перечисляет свои компоненты без объявления границ, записывает их вообще без сегмента каталога. Поле subDirectory: по умолчанию имеет значение {{ .capability }}, чтобы артефакты каждой возможности попадали в собственную подпапку в каталоге границы, — независимо от того, опущено ли оно или записано как subDirectory: "", что читается в точности как опущенное поле. Указание subDirectory: "." или шаблона, который вычисляется в пустую строку, отменяет эту группировку.

Что эти шаблоны не определяют: размещение artifacts:

Один сегмент выходного пути не задаётся шаблоном пути. Файл, названный в блоке artifacts: сущности Recipe, записывается в каталог, названный по компоненту, который его объявил, внутри того, во что вычисляется subDirectory:. Этот сегмент фиксирован и присутствует всегда — для цели, которая записывает файлы своих участников рядом друг с другом, а не вкладывает каждого участника в собственный чарт или модуль.

Причина в том, что даёт файлу имя. Манифест, который цель рендерит или синтезирует, получает имя от цели по компоненту, к которому он относится, поэтому он уже идентифицирует свой компонент. Артефакт же называется ключом, который написал его автор, — app-config.yaml, netpol.yaml, — и этот ключ ничего не говорит о компоненте, потому что сущность Recipe, объявляющая его, не знает, какие компоненты будут к ней привязаны. Два компонента в одной границе, привязанные к одной сущности Recipe, записали бы один путь, и ни у автора сущности Recipe, ни у автора сущности Release нет средства, чтобы их разделить.

Добавляется только каталог; имя файла остаётся заданным автором ключом, поэтому файл, который автор видит в выходных данных, носит написанное им имя.

Что по-прежнему даёт subDirectory: и как они сочетаются. subDirectory: перемещает каждый файл, выводимый участником, — отрендеренные манифесты, синтезированные манифесты и артефакты вместе, — поэтому это инструмент, чтобы выделить одному компоненту собственный каталог для последующих инструментов, работающих со всем набором манифестов одного компонента, или чтобы направить несколько компонентов в одну общую папку. Сегмент artifacts: применяется ниже того, во что оно вычисляется. Поэтому запись subDirectory: "{{ .capability }}/{{ .component_id }}" для компонента, чья сущность Recipe объявляет artifacts:, даёт имя компонента дважды: артефакт попадает в <capability>/<component>/<component>/<key>, а отрендеренные манифесты этого компонента — в <capability>/<component>/<key>. Используйте переопределение, когда нужно собрать весь вывод компонента, и не задавайте его, когда достаточно разделить артефакты, — это уже делается по умолчанию.

.capability разрешается для каждого компонента, а directory: границы вычисляется для двух разных целей. Вычисление уровня границы, которое публикует .parent_boundary.directory для дочерних границ, выполняется до привязки какого-либо компонента, поэтому .capability там пуст. Вычисление уровня компонента, которое определяет, куда фактически попадают артефакты участника, несёт возможность этого компонента. Поэтому родитель, задающий directory: "d-{{ .capability }}", публикует вниз по каскаду d-, тогда как его собственные артефакты попадают в d-compose.

Каскад родительской границы

Вложенные границы получают представление .parent_boundary, которое предоставляет вычисленный путь непосредственной родительской границы и её собственные данные, разрешённые каскадом. Каскад одноуровневый: .parent_boundary границы — это её прямой родитель, а не прародитель. Чтобы обратиться выше, родительская граница сама использует .parent_boundary в своих шаблонах, явно передавая значения вниз по дереву.

Доступные поля в .parent_boundary:

ПолеОписание
.parent_boundary.directoryВычисленное значение directory: родительской границы (после применения шаблона).
.parent_boundary.boundary_nameЗаданное автором имя родительской границы.
.parent_boundary.parametersТа же карта .parameters.*, которую видела родительская граница (значения параметров глобальны для сущности Release, но псевдоним предоставлен для симметрии).
.parent_boundary.annotationsАннотации родительской границы, разрешённые каскадом.

Канонический шаблон: родительская граница, в которой directory: задаётся один раз, и дочерние границы, которые направляют свои артефакты под родителя, объявляя directory: "{{ .parent_boundary.directory }}". Так дочерние границы сводятся к пути сборки родителя, и получается один объединённый результат, содержащий участников из всех дочерних границ. Именно на этом основана сущность Feature core/compose-bridge: родительская граница с функцией bridge, две дочерние границы (например, services-net и data-net), разделяющие directory: родителя, и один объединённый docker-compose.yaml, содержащий все компоненты и сервис bridge.

Обратный вариант: не указывайте .parent_boundary.directory в дочерних границах (или вычисляйте отдельный путь), и каждая дочерняя граница получит собственную сборку. Обе формы полноценны.

Разобранные примеры структур

Структура 1 — разделение по границам по умолчанию

spec:
boundaries:
api-prod:
directory: "deploy/api-prod"
components:
api: {}
cache: {}
data-prod:
directory: "deploy/data-prod"
components:
db: {}

Каждая граница вычисляется в отдельный directory:, поэтому у каждой своя сборка:

deploy/api-prod/<capability>/...
deploy/data-prod/<capability>/...

Значение по умолчанию subDirectory: "{{ .capability }}" разделяет артефакты по возможностям внутри каталога каждой границы. Две границы, два результата сборки на каждую возможность, без слияния.

Структура 2 — объединённая сборка через общий родительский каталог

spec:
boundaries:
cluster:
directory: "deploy/cluster"
annotations:
aggrega.ai/chart-name: "cluster-umbrella"
features:
bridge:
type: core/compose-bridge:1.0.0
boundaries:
services-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: services }
components:
api: {}
data-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: data }
components:
db: {}

Обе дочерние границы вычисляют directory: в deploy/cluster (каталог родителя), поэтому все участники сливаются по одному пути сборки. При значении по умолчанию subDirectory: "{{ .capability }}" участники compose из обеих дочерних границ попадают в deploy/cluster/compose/ и образуют один объединённый docker-compose.yaml. Сущность Feature compose-bridge, подключённая к родителю, выполняется один раз (диспетчеризация в области границы) и добавляет сервис моста в тот же объединённый файл.

Аннотация родителя aggrega.ai/chart-name: "cluster-umbrella" каскадно передаётся обеим дочерним границам; если бы границы содержали также участников helm-chart, подчарты helm-chart обеих дочерних границ объединились бы под одним зонтичным чартом с именем cluster-umbrella. Несовпадающие значения chart-name у участников по одному пути останавливают сборку.

Структура 3 — маршрутизация по компонентам через subDirectory: и параметры

spec:
parameters:
region: "eu-west-1"
boundaries:
eu-prod:
directory: "deploy/{{ .parameters.region }}"
components:
api:
subDirectory: "{{ .capability }}/{{ .component_id }}"
db:
subDirectory: "{{ .capability }}/{{ .component_id }}"
ingress:
subDirectory: "shared"

directory: границы вычисляется в deploy/eu-west-1 (подстановка параметров). Переопределения subDirectory: для отдельных компонентов направляют каждого участника в собственный подкаталог компонента, а компонент ingress переопределяет его на плоский подкаталог shared для сквозных артефактов:

deploy/eu-west-1/<capability>/api/...
deploy/eu-west-1/<capability>/db/...
deploy/eu-west-1/shared/...

Этот шаблон подходит организациям, которым нужны отдельные каталоги артефактов для каждого компонента ради последующих инструментов, работающих с манифестами одного компонента. Если Recipe компонента также объявляет artifacts:, прочитайте раздел Что эти шаблоны не определяют выше, прежде чем выбирать эту структуру: такие файлы уже содержат сегмент компонента, поэтому это переопределение добавляет второй.

Диагностика

Подсистема шаблонов путей останавливает сборку в каждой из следующих ситуаций, и на странице errors/fatal-halts.md они описаны под этими названиями. На той странице приводится сообщение, которое выдаёт каждая остановка; сверяйте вывод сборки с этим текстом.

  • Path-template references a variable outside the allowlist (Шаблон пути ссылается на переменную вне списка разрешённых) — на этапе разбора: шаблон пути ссылается на переменную, которой нет в списке разрешённых.
  • Path collision (Коллизия путей) — на этапе сборки: два участника из разных границ вычисляются в один и тот же путь, но расходятся в свойстве, которое должно быть одинаковым у всех участников по этому пути.
  • Instance-ID collision (Коллизия идентификаторов экземпляров) — на этапе сборки: две границы, вычисляемые в один и тот же кортеж (path, provider), вносят компоненты с одинаковыми идентификаторами экземпляров.
  • Chart-name mismatch (Несовпадение имени чарта) — на этапе сборки: объединённая сборка helm-chart получает участников с конфликтующими аннотациями aggrega.ai/chart-name, разрешёнными через каскад.
  • Missing template key (Отсутствующий ключ шаблона) — шаблон пути ссылается на поле открытой переменной, которое не разрешается ни в какое значение (например, {{ .parameters.region }}, когда в сущности Release отсутствует region, или ключ .parent_boundary в границе верхнего уровня, у которой нет родителя); missingkey=error выдаёт явное сообщение с указанием границы, поля шаблона (directory: или subDirectory:) и отсутствующего ключа. .parameters и .parent_boundary открыты — их ключи являются авторскими данными, — тогда как .manifest объявляет свои ключи, поэтому ключ с опечаткой в .manifest вместо этого отклоняется на этапе разбора как неизвестная ссылка, а диагностика перечисляет ключи, которые определяет .manifest.

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

  • entities/release.md — создание сущностей Release, включая пространственное разделение и поля directory: / subDirectory:.
  • providers/architecture.md — диспетчеризация провайдеров и модель сборки по каждой паре (path, provider).
  • providers/compose.md — вывод на стороне compose по каждой паре (path, provider), включая сценарий с объединённым путём.
  • providers/helm-chart.md — зонтичная композиция helm-chart и правило каскада имени чарта для объединённых путей.
  • entities/featurerecipe.md — сущности FeatureRecipes уровня границы (сущность Feature core/compose-bridge опирается на описанную здесь модель сборки с объединёнными путями).
  • errors/fatal-halts.md — полный каталог диагностик, включая перечисленные выше остановки при диспетчеризации путей.