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

Контракт контекста шаблонов

На этой странице описано представление времени выполнения, которое компилятор внедряет в Go-шаблоны сущностей Recipe и FeatureRecipe: структура контекста шаблона, доступность каждого поля на разных этапах конвейера компиляции и канонический контракт, который нужен опытным авторам при написании шаблонов, использующих состояние других компонентов. Доступность по местам вычисления шаблонов (какие поля присутствуют в каком месте вычисления) описана в expansion-matrix.md; на этой странице описаны структуры полей и их семантика.

Обзор

Компилятор собирает контекст шаблона для каждого узла во время рендеринга и внедряет его в каждый шаблон Go, который рендерер вычисляет для этого узла. Контекст существует только в памяти — он никогда не сохраняется на диск и никогда не передаётся через Wasm ABI единым блоком данных. Каждое место шаблона получает представление одного и того же объекта контекста; некоторые поля заполняются поздно (.workload появляется при синтезе рабочей нагрузки; .source — при разрешении источника; .steps заполняется при выполнении pipeline: по мере завершения каждого шага, см. Состояние языка → Фазы конвейера компиляции).

Схема для этой структуры времени выполнения — template-context-v1beta1.schema.json (поставляется в составе дистрибутива схем Aggrega).

Поля верхнего уровня

Поля верхнего уровня находятся в корне контекста шаблона — внутри шаблона к ним обращаются как .field.

  • .values (map). Когнитивная полезная нагрузка, написанная разработчиком, из сущности Aggregate. Значения каждого компонента передаются в отрисованный Recipe через это поле. Проверяется при разрешении по schema: каталога (объявлению JSON Schema 2020-12 сущности Component или Feature). Если записанное автором нулевое / пустое / ложное значение поля семантически отличается от отсутствия поля, используйте optional (см. sprig-functions.md), а не default.
  • .infra (map). Физические размеры, заданные эксплуатацией, из сущности Release. Проверяется при разрешении по schema: каталога (объявлению JSON Schema 2020-12 сущности Component или Feature). Действует та же рекомендация по выбору между optional и default, что и для .values: предпочитайте optional, когда записанный ноль или false выражает законное намерение (масштабирование до нуля, отсутствие повторных попыток, выключенный флаг функции).
  • .locals (map со строковыми значениями). Приватное состояние Recipe — имена, объявленные в блоке locals: сущности Recipe, разрешённые в преамбуле locals и опубликованные в этот столп при разрешении источника. Записи разрешаются в порядке, заданном автором, и запись может читать соседнюю запись, определённую выше, поэтому порядок важен везде, где одна запись читает другую. Доступно только в собственных шаблонах Recipe; вызывающим сторонам никогда не предоставляется.
  • .provides (map со строковыми значениями). Публичные выходные строки Recipe — контракт, относительно которого блоки inject: вызывающих сторон разрешают ссылки from:. Заполняется при вычислении provides.
  • .features (map вложений). Перебирает Features, подключённые к этому Component (на уровне Aggregate + на уровне подсистемы + на уровне Release + через аннотации Manifest, согласно пятиуровневой луковичной модели), с ключами по имени экземпляра, которое автор дал вложению. Каждая запись содержит одни и те же поля — см. структуру вложения ниже. Вложение, записанное на одном из соединений сущности Component, в их число не входит: оно читается в рамках этого соединения, в .context.uses.<alias>.features.<slot>, поэтому шаблон, перебирающий .features, встречает только собственные вложения сущности Component.
  • .metadata (struct). Идентификация сущности Release для детерминированного именования: release_name, release_version, environment, aggregate_name. Заполняется при каждой отрисовке; значения берутся из блока metadata: сущности Release.
  • .source. source: сущности Recipe, разрешённый вычислением шаблона разрешения источника. nil для Recipes без источника; nil до выполнения разрешения источника. В шаблонах сущности FeatureRecipe это собственный source: этой сущности FeatureRecipe, никогда не хост-компонента, — см. Точка вывода FeatureRecipe вложения.
  • .workload. Разобранный объект Workload, заполняемый после того, как отрисованный документ workload: декодирован и прошёл ограничивающую его проверку: схему Workload, featuresSchema сущности Component для каждого вложения, объявленного её контейнерами, и разрешимость того, на что ссылается каждое вложение. nil для несинтезированных Recipes; nil до выполнения синтеза рабочей нагрузки.
  • .steps (map выходных данных шагов). Заполняется при выполнении pipeline: по мере работы Wasm-плагинов и предоставляет возвращённые выходные данные завершённого шага последующим шагам через .steps.<id>.outputs. Шаг читает выходные данные предшествующего шага из собственного шаблона with; outputs шага становятся видны только шагам, объявленным после него. Пусто, если узел не объявляет конвейер, а также до завершения первого шага узла.

Поле верхнего уровня, которое для этого узла ничего не содержит, — .workload у сущности Recipe, которая ничего не синтезирует, .source у сущности Recipe без источника, .features у сущности Component без вложений, — в шаблоне значений читается как пустое, точно так же, как неустановленный ключ в .values: {{ .workload }} ничего не выводит, default над ним подставляет своё резервное значение, а if или with над ним переходит в ветку false. range по нему ничего не перебирает. Чтение под ним — {{ .workload.containers }} — по-прежнему останавливает сборку, потому что спускаться некуда. А шаблон, который и выводит такое поле там, где он всегда выполняется, — вне любых if, with и range, — и перебирает его, останавливает сборку с указанием этого поля, как и для любого пути, который ничего не содержит и читается обоими способами, потому что ни одно значение не выводится как ничто и одновременно не перебирается как ничто: см. A template reads and iterates a path that holds nothing (Шаблон читает и перебирает путь, который ничего не содержит).

Структура подключения

.features.<name> и .features.<slot> имеют одинаковую структуру — одно подключение, читаемое одним способом:

  • .type (строка). URI каталога подключённой сущности Feature.
  • .resolved_version (строка). Версия подключённой сущности Feature после разрешения Manifest — версия, фактически привязанная для этой сборки, а не закреплённая версия, повторно указанная на стороне потребителя. Аналогично .context.uses.<alias>.resolved_version. Пусто, если type подключения не разрешается ни в одну сущность каталога.
  • .labels (словарь строковых значений). Метки каталога подключённой сущности Feature, передаваемые дословно в том порядке, в котором их объявляет Feature: ничего не фильтруется, не переименовывается и не лишается префикса, поэтому шаблон читает ровно то, что написал автор Feature. Аналогично .context.uses.<alias>.labels. Отсутствует, если Feature не объявляет меток, а также если type подключения не разрешается ни в одну сущность каталога.
  • .values (словарь). Собственный слой намерений разработчика для подключения, задаваемый в объявлении подключения в Aggregate. Отличается от .values верхнего уровня основного компонента.
  • .infra (словарь). Собственный слой эксплуатационных размеров для подключения, задаваемый в объявлении подключения в Release. Отличается от .infra верхнего уровня основного компонента.
  • .provides (словарь строковых значений). Разрешённый публичный контракт сущности FeatureRecipe, привязанной к этому подключению: имя создаваемого ресурса, его ключ данных, облачная идентичность и любые дополнительные ключи, которые публикует FeatureRecipe. Читается как .features.<name>.provides.<key>, аналогично .context.uses.<alias>.provides: потребитель читает то, что опубликовал производитель, а не выводит это заново. Подключение, у которого привязанная FeatureRecipe ничего не публикует, вообще не содержит ключа provides, а не пустой словарь, поэтому выполняйте проверку перед обращением к отдельному ключу.

.provides делает подключение потребляемым, а не просто присутствующим. Если Feature объявляет контракт schema.provides, этот контракт проверяется для реализующей его FeatureRecipe — FeatureRecipe должна опубликовать каждый объявленный ключ, — а потребитель читает результат здесь. Так, сущность Feature для идентичности, которая создаёт ServiceAccount и публикует его имя, позволяет потребляющей сущности Recipe привязаться к нему:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Имя создаваемого ресурса указывается один раз, производителем, и затем потребляется — оно никогда не повторяется на стороне потребителя, где два значения могли бы разойтись. Пример workload-identity-binding отображает это от начала до конца.

.labels позволяет шаблону подстраиваться под то, чем является подключение, без сопоставления по его имени и разбора его URI. Компилятор не читает ни одну из меток — он передаёт строки, а их смысл определяет автор шаблона.

Сущность Feature, не объявляющая меток, вообще не содержит .labels, а не пустой словарь, поэтому выполняйте проверку перед обращением к отдельной метке: обращение к отсутствующему ключу останавливает сборку. Метку, которую Feature может не объявлять, читайте через optional, потому что index останавливает сборку с указанием ключа, если словарь его не содержит:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Поскольку метки поступают дословно, собственное пространство имён автора каталога доходит до шаблона без изменений, и Recipe читает тот же ключ, который объявляет Feature.

Блок .context

.context — собранный компилятором контекст выполнения для одного узла: данные об идентичности, топологии и конвейере доставки, которые рендерер передаёт в каждое место шаблона. Его поля:

  • .context.instance_id (строка). Идентичность узла в виде имени — значение, которым сама сборка именует и помечает метками то, что она выпускает, поэтому шаблон, составляющий из него имя ресурса или внутрикластерный адрес, предсказывает имя, которое сборка действительно создаёт. Для узла, который объявляет ваш собственный Aggregate, это имя, которое вы написали. Для узла, который вносит импортированный Aggregate, это развёрнутая идентичность с выписанным разделителем модулей (data-layer.main-db становится data-layer-zdmain-db), поскольку точка не может входить в имя ресурса, а в адресе внутри кластера она отделяет сервис от его пространства имён. Форма с точками — та, которой ваши документы и диагностика сборки адресуют этот узел; см. Соглашения об именовании.
  • .context.rendered_name (строка). Имя, которое провайдер узла даёт ресурсам, отрисовываемым им для узла, — как из предоставленного вами исходника, например имени релиза, которое читает чарт, так и из синтезируемой им рабочей нагрузки, где он называет её ресурсы собственным именем, как helm делает с тем же именем релиза. Присутствует только там, где провайдер его выводит. В шаблонах подключения Feature это имя хост-компонента, так же как .context.instance_id там — идентичность хоста; см. Именование отрисованного ресурса.
  • .context.labels (map со строковыми значениями). Метки, заданные в каталоге, плюс любые дополнения label-transform, сделанные при построении топологии.
  • .context.annotations (три корзины, см. ниже). Каскадные аннотации, сгруппированные по происхождению.
  • .context.inject (карта механизмов, см. ниже). Предварительно заполненный, перехваченный конвейер доставки — стандартная поверхность, из которой шаблоны Recipe читают значения других компонентов.
  • .context.uses (карта соединений, см. ниже). JOIN-проекция по исходящим рёбрам топологии.
  • .context.self_inject (карта механизмов, см. ниже). Для каждого имени, которое разработчик записал в собственном блоке inject: компонента, — собственный ключ provides, который доставляет эта запись, или единственное собственное значение, которое читает её шаблон.
  • .context.used_by (список, см. ниже). Компоненты, чьи записи uses указывают на данный. Читается FeatureRecipe, подключённым к компоненту, в шаблонах, создающих собственные ресурсы подключения; везде в остальных местах пуст.
  • .context.render_facts (map списков, см. ниже). То, что провайдер компонента сообщил об отрисованном им выводе, с ключами по имени факта. Читается FeatureRecipe, подключённым к компоненту, в каждом из его шаблонов, выполняемых после отрисовки компонента; в остальных местах отсутствует.

.context.annotations — три корзины

Аннотации каскадом распределяются по трём корзинам с ключами по происхождению:

  • .context.annotations.release — аннотации границы Release (домен 4). Служат для управления физическими реалиями; рендереры при необходимости направляют их в поля infra:. Общеизвестные аннотации aggrega.ai/* находятся в этой корзине.
  • .context.annotations.catalog — аннотации метаданных Component из домена 2. Неизменяемые внутренние характеристики, заданные архитектором; в основном используются политиками-плагинами Wasm.
  • .context.annotations.aggregate — аннотации подсистемы Aggregate из домена 1. Когнитивные метаданные; рендереры при необходимости направляют их в полезную нагрузку values:.

Каждая корзина — плоская map из строки в строку. Согласно правилам разделения архитектуры, корзины предназначены для разных целей; движок это разделение не обеспечивает, поэтому соответствие корзин их назначению поддерживается дисциплиной авторов. Устройство каскадных аннотаций описано в главе 6 §2, поток 5.

.context.inject — канал доставки

Канал — это заранее разрешённая карта доставки компилятора. К моменту выполнения шаблона Recipe на базовой отрисовке каждый источник inject (литералы self-inject, заданные разработчиком, ссылки self-inject from:, разрешённые по собственным provides, межкомпонентные ссылки uses[].inject, разрешённые по provides цели, перехваты injectMapping из FeatureRecipe) уже разрешён в итоговое строковое значение и слит в эту карту.

Поля:

  • .context.inject.env — map со строковыми значениями: имя переменной окружения → разрешённое значение.
  • .context.inject.file — map со строковыми значениями: путь к файлу → разрешённое значение.
  • .context.inject.arg — map со строковыми значениями: флаг аргумента → разрешённое значение.
  • .context.inject.all — map со строковыми значениями, объединяющая механизмы env/file/arg/пользовательские в один плоский словарь; удобна для сериализации всего конвейера ({{ toJson .context.inject.all }}).

Механизм присутствует в канале только тогда, когда через него что-то доставляется. Шаблон, читающий механизм, через который ничего не доставляется, — .context.inject.file при отсутствии доставки файлов, — читает его как пустой, как шаблон значений читает любой отсутствующий ключ, а range по нему ничего не отрисовывает; это чтение подставляет пустое значение для всего шаблона, поэтому {{ toJson .context.inject }} в том же шаблоне показывает "file": "". Доставляется ли через механизм что-либо, показывает hasKey .context.inject "file".

  • Пользовательские механизмы (например, ssm_param) — доступны для чтения под собственным именем поля, .context.inject.<mechanism>.<key>, точно так же, как три основных. Значения пользовательского механизма попадают в конвейер из self-inject на уровне компонента, из ребра uses[].inject, из сопоставления inject: подключения Feature и из вывода injectMapping FeatureRecipe. Для self-inject на уровне компонента список разрешённых spec.inject сущности Component должен называть механизм; механизм, которого нет в этом списке, останавливает сборку. Записи пользовательского механизма также появляются в .context.inject.all наряду с тремя основными. Пользовательский механизм может носить любое имя, кроме all: это имя и есть само объединённое представление, поэтому механизм с таким именем никогда нельзя было бы прочитать отдельно. Блок inject, называющий механизм all, и список разрешённых сущности Component или сущности Feature (spec.inject, inject сокета), где он указан, останавливают сборку при загрузке документа, а отказ поясняет, что это имя принадлежит этому объединённому представлению. Имена чувствительны к регистру, поэтому ALL — обычный пользовательский механизм.

Канал — это состояние после перехвата: к моменту, когда шаблоны Recipe читают его, блоки injectMapping из FeatureRecipe уже глубоко слили свои переопределения поверх него на этапе сопоставления inject. Сопоставление может заменить ключ, доставленный собственным блоком inject: компонента, блоком inject: одного из его соединений или блоком inject: его собственного подключения; ключ, который доставляют обе из двух подключённых Features — через свои блоки inject: или свои сопоставления, — останавливает сборку вместо того, чтобы попасть в канал с одним из двух значений. Feature, подключённый к границе Release, достигает компонента тем же путём — через injectMapping своего FeatureRecipe, которое выполняется в собственном контексте компонента при любом executionScope сущности FeatureRecipe; переписывание мостом compose переменной хоста потребителя — одно из таких сопоставлений, подчиняющееся тому же правилу.

.context.self_inject — какое собственное значение доставляет каждое из имён разработчика

Если сущность Component объявляет spec.inject, разработчик может записать блок inject: на самом компоненте и выбрать имена, под которыми доставляются собственные значения и provides компонента. .context.inject содержит то, во что разрешились эти записи, а .inject_raw — их в записанном виде; .context.self_inject указывает для каждой из них собственный ключ provides компонента, который она доставляет, или единственное собственное значение, которое читает её шаблон. Он имеет ту же форму, что и .context.uses.<alias>.inject соединения, — механизм, затем имя разработчика, затем ключ, — где ключ называет одно из собственных provides или значений компонента:

  • provides.<key> — запись, написанная с from: <key>, которая доставляет одно из собственных provides компонента.
  • values.<key> — запись, шаблон value: которой читает ровно одно из собственных значений компонента и ничего больше, причём <key> — ключ верхнего уровня этого значения. Текст или функции вокруг чтения не имеют значения, как и то, насколько глубоко шаблон читает значение: '{{ .values.role }}', 'role={{ .values.role | upper }}' и '{{ with .values.role }}{{ . }}{{ end }}' все сопоставляются с values.role, а '{{ .values.config.port }}', '{{ index .values.config "port" }}' и '{{ (default dict .values.config).port }}' все сопоставляются с values.config.
  • пустая строка — любая другая запись: литерал, шаблон, читающий два значения, шаблон, читающий что-либо помимо значений (.infra, .metadata, .context), и шаблон, чтение значений в котором текст не относит к одному ключу верхнего уровня, — значения, переданные функции через их корень (index .values "role"), значения, прочитанные целиком (toJson .values или поле, прочитанное внутри {{ with .values }} либо через переменную, привязанную к .values), или весь контекст, переданный дальше (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

В сущности Aggregate каждый шаблон value: начинается с {{"{{"}}, а не с {{, поскольку весь текст сущности Aggregate один раз читается как шаблон для интерполяции параметров, прежде чем вычисляются собственные шаблоны блока; шаблоны, приведённые в списке выше, показаны так, как они читаются после этого экранирования. См. Текст, содержащий собственные двойные фигурные скобки.

Именно это позволяет сущности Recipe, запускающей собственный образ разработчика, считать свои имена переменных для собственных значений компонента значениями по умолчанию — это соглашение каталога стандартной библиотеки, и корпоративный каталог может выбрать иначе. Прежде чем доставить собственное значение под своим именем, такая сущность Recipe проверяет, не доставляет ли его уже блок разработчика, и пропускает своё значение по умолчанию, если доставляет, — поэтому разработчик, переименовавший одно значение, сохраняет все остальные значения по умолчанию:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject присутствует при каждом рендеринге и пуст там, где разработчик не записал блок. Механизм появляется, только когда блок его называет, поэтому защищайте чтение механизма, который блок может не называть, как это делает with выше. Шаблон получает имена отсортированными, как бы он их ни читал, как и любую карту. Карта читается из текста, записанного разработчиком; ничто в ней не является разрешённым значением, и компилятор не придаёт никакого смысла ни именам, ни ключам.

.context.uses — JOIN-проекция

.context.uses — это обогащённое представление компилятора для каждого исходящего топологического ребра текущего узла. Каждая запись карты имеет ключом локальный псевдоним сокета (например, databases.primary становится .context.uses.primary, если в Aggregate написано uses: { databases: { primary: { target: ... } } }) и содержит JOIN-проекцию разрешённого состояния цели вместе с контрактом доставки на стороне вызывающего:

  • .target (string) — идентификатор экземпляра целевого узла.
  • .socket (string) — имя сокета на стороне вызывающего (ключ usesSchema).
  • .provides (карта строковых значений) — разрешённые ключи provides: цели (публичные выходные строки, которые целевой Recipe экспортировал при вычислении provides).
  • .inject (карта механизм → карта ключ → значение) — директивы inject на стороне вызывающего для этого ребра (блок inject: в объявлении uses[].inject). Ключи механизмов — env/file/arg/пользовательские; записи карты каждого механизма — ссылки локальный ключ → ключ provides цели.
  • .labels (карта строковых значений) — метки цели, а не потребляющего компонента: набор, который несёт собственный .context.labels цели, — её метки, заданные в каталоге, плюс любые добавления label-transform, сделанные при построении топологии.
  • .annotations (три группы) — группы аннотаций release/catalog/aggregate цели.
  • .component (string) — URI типа сущности Component цели.
  • .resolved_version (string) — версия сущности Component цели после разрешения Manifest.
  • .boundary_path (string) — путь границы Release цели; задаётся независимо от того, находится ли цель в границе вызывающего или в другой.
  • .origin_feature (string) — задаётся, когда ребро синтезировано подключением Feature (например, sidecar-Feature, добавляющая ребро uses к Feature учётных данных).
  • .values (map) — разрешённая конфигурация разработчика для этого соединения на уровне ребра, заданная в записи uses сущности Aggregate. Присутствует, только если ребро несёт значения на уровне ребра.
  • .infra (map) — разрешённая конфигурация оператора для этого соединения на уровне ребра, заданная в записи uses сущности Release. Присутствует, только если ребро несёт infra на уровне ребра.
  • .origin_release (boolean) — true, если это соединение проложил Release, а не объявил Aggregate; отсутствует для соединения, которое объявляет Aggregate.
  • .features (карта подключений) — подключения, записанные на этом соединении, с ключами по имени слота, который объявляет сокет; см. ниже. Присутствует, только если соединение несёт хотя бы одно.
  • .render_facts (карта списков) — то, что рендеры цели сообщили о сгенерированном ими выводе, с ключами по имени факта, в той же форме, что и .render_facts вызывающего в .context.used_by: каждый факт — список, сначала вызовы собственного провайдера цели, затем каждая из её Features в порядке рендеринга; списки, полученные одним именем от каждого, объединяются в один. Присутствует только для FeatureRecipe, задающего readsTargetRenderFacts: true, — его подключения рендерятся после того, как отрендерены все компоненты, так что рендер каждой цели завершён, — и тогда на каждом соединении; пуст для цели, провайдеры которой ничего не сообщают. Читается только в valuesMapping:, workload: и artifacts: этого FeatureRecipe; отсутствует в собственных шаблонах Recipe компонента, в injectMapping:, в with: и when: шага pipeline: и во всех FeatureRecipe, не задающих этот ключ, — шаблон такого FeatureRecipe, читающий его, останавливает сборку до начала рендеринга.

Обе карты конфигурации на уровне ребра относятся к потребителю: они попадают только в контекст рендеринга потребляющего узла, но никогда — цели.

Предоставленное значение читается по пути .provides.<name> — предоставленные имена вложены в .provides, а не расположены непосредственно на ребре, поэтому .context.uses.<alias>.<name> не адресует никакого поля и ничего не возвращает.

На соединении, два конца которого отрисовываются в разные выходные данные, .provides содержит заместители, а не значения. Если провайдер связывает такое соединение собственной ссылкой после того, как оба набора выходных данных собраны, — например, стек CloudFormation читает значение другого стека, — каждое значение, которое несёт .context.uses.<alias>.provides, является заполнителем, который провайдер позже заменяет межстековой ссылкой или самим значением, как описано на его собственной странице. Такое значение нужно копировать, а не сравнивать — это то же правило, которому следует значение, доставляемое таким соединением по каналу inject, тоже заполнитель того же рода. Записывайте его целиком, внутри более длинной строки или через функцию, оставляющую его как есть, например quote. Шаблон, который сравнивает значение, прочитанное из .provides, ветвится по нему, измеряет его или изменяет, принимал бы решение по заполнителю, поэтому вместо этого сборка останавливается, называя шаблон и каждое прочитанное им значение; ветвитесь по собственному значению потребляющего компонента. Остановка распространяется на каждый шаблон, читающий .provides соединения, включая injectMapping: присоединённого FeatureRecipe, и на FeatureRecipe с областью границы, читающий те же соединения под .boundary. Соединение, оба конца которого отрисовываются в одни выходные данные, несёт свои значения как есть.

Один псевдоним обозначает одно соединение, поэтому карта содержит запись для каждого соединения компонента. Ключом карты служит только псевдоним, независимо от сокета, к которому подключено соединение, и никакие два соединения одного компонента не имеют общего псевдонима — ни на одном сокете, ни на двух, каким бы документом или подключением ни было задано каждое. Сборка отвергает такую пару, называя оба соединения и место, где записано каждое, до начала рендеринга. Список, дважды называющий одну цель, — такая пара, поскольку псевдоним записи списка — это её цель; такой же парой является соединение local на сокете models рядом с соединением local на сокете databases.

Шаблоны Recipe используют эту проекцию, чтобы получать состояние цели без обхода графа IR. Шаблоны injectMapping сущности FeatureRecipe используют её, чтобы обращаться к аннотациям цели для решений о маршрутизации между границами (шаблон DNS-резолвера K8s, описанный в entities/featurerecipe.md, — канонический разобранный пример).

Шаблон, перебирающий .context.uses, видит соединения в порядке ключей — отсортированными по псевдониму, — а не в том порядке, в котором их записал Aggregate. Так обходится каждая карта, которую перебирает шаблон, включая .features и .features соединения, поэтому шаблон никогда не восстанавливает авторский порядок перебором карты; там, где порядок имеет значение, поверхность написания моделирует его как список. В любом случае отрендеренный вывод побайтно идентичен между сборками одних и тех же входных данных.

Подключения соединения — .context.uses.<alias>.features

Подключение, записанное на соединении, — в features: записи uses компонента в Aggregate или в записи Release для этого соединения — заполняет слот, который объявляет сокет. Для всего, что сборка с ним делает, это подключение потребляющего компонента: Manifest связывает его реализацию, его FeatureRecipe рендерится на стороне потребителя, его контракт provides соблюдается. Шаблон читает его в соединении, на котором оно записано:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Ключ — слот. .context.uses.<alias>.features.<slot> обозначает слот, который объявляет сокет соединения, — выше это credential, — так что потребитель, обращающийся к нескольким целям, читает собственные учётные данные каждой цели под псевдонимом этой цели. У соединения без подключений нет .features, поэтому чтение защищено проверкой.
  • Форма подключения. Каждая запись содержит ровно то же, что .features.<name> содержит для одного из собственных подключений компонента, — .type, .resolved_version, .labels, .values, .infra и разрешённые .provides связанного с ним FeatureRecipe; см. форму подключения. Читаемые здесь provides — те же, с которыми рендерится собственный FeatureRecipe подключения, поэтому имя, на которое ссылается потребитель, и имя ресурса, генерируемого этим FeatureRecipe, — одно вычисленное значение.
  • Никогда не в .features. Собственный .features компонента содержит только подключения, записанные в его собственном блоке. Поэтому Recipe, который перебирает .features и выбирает подключения по типу — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}…, — никогда не встречает учётные данные соединения, даже той же Feature: шаблон обращается к подключению соединения через это соединение, а не через .features. То же верно для каждой поверхности, показывающей подключения компонента, включая контекст assertions.

Компоненты, использующие данный, — .context.used_by

.context.uses смотрит наружу — на соединения, которые создаёт компонент. .context.used_by смотрит внутрь — на компоненты, чьи записи uses указывают на данный. Его читает FeatureRecipe, присоединённый к компоненту, и именно там место ресурсу, описывающему или ограничивающему эти соединения, — например, сетевой политике, пропускающей только компоненты, объявленные как вызывающие данный:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Каждая запись содержит:

  • .component_id (строка) — идентификатор экземпляра подключающегося компонента в развёрнутой форме (frontend, data-layer.etl); это то же значение, которое шаблон пути subDirectory: читает как .component_id.
  • .socket (строка) — сокет, который соединение заполняет на подключающемся компоненте (его ключ usesSchema).
  • .provides (карта строковых значений) — то, что публикует подключающийся компонент, суженное до ключей, объявленных его сущностью Component: те же значения, которые потребитель этого компонента читает в .context.uses.<alias>.provides. Ключ, который Recipe компонента публикует без объявления в его Component, сюда не входит.
  • .source_namespace (строка) — пространство имён, в которое помещён подключающийся компонент: применимая к нему аннотация aggrega.ai/namespace, каскадно наследуемая вниз по его границам, причём его собственная запись в Release имеет приоритет. Компонент, запись которого в Release задаёт пространство имён или сбрасывает его значением null, несёт собственную настройку, а не настройку своей границы, поэтому значение указывает пространство имён, в которое рендерятся собственные ресурсы компонента. Отсутствует, если к компоненту не применяется никакое пространство имён; читайте его через with или if, как в примере, а не выводите напрямую.
  • .source_boundary_path (строка) — путь границы Release, содержащей подключающийся компонент; вложенные границы соединяются через / (edge, edge/inner).
  • .render_facts (карта списков) — то, что рендеры подключающегося компонента сообщили о выданном ими результате, с ключами по имени факта, в той же форме, что и .context.render_facts. Каждый факт — список, поэтому шаблон всегда перебирает его, даже если в нём одна запись. Записи могут поступать от собственного рендера подключающегося компонента и от рендеров присоединённых к нему Features: списки, полученные одним именем от каждого, объединяются в один — сначала вызовы собственного провайдера компонента, затем каждая из его Features в порядке рендеринга. Присутствует только для FeatureRecipe, задающего readsCallerRenderFacts: true, — его присоединения рендерятся после того, как отрендерены все компоненты, поэтому рендер каждого вызывающего завершён, — и тогда во всех записях, пустой для вызывающего, чьи провайдеры ничего не сообщают. FeatureRecipe, не задающий этот ключ, не видит .render_facts ни в одной записи, а его шаблон, читающий их, останавливает сборку до начала рендеринга.

Два значения размещения — те же, что FeatureRecipe с областью границы читает как source_namespace и source_boundary_path в записи того же соединения в своих списках рёбер .boundary: оба представления одинаково определяют, где размещён компонент, поэтому никогда в этом не расходятся. Ребро в этих списках также несёт путь сборки каждой конечной точки — source_assembly_path и target_assembly_path, каталог внутри выходного каталога сборки, в который её собирает провайдер конечной точки, — чего запись .context.used_by не несёт.

FeatureRecipe, задающий readsCallerRenderFacts: true, читает факты каждого вызывающего так же, как факты хоста. Для провайдера, документирующего факт ports, каждая запись которого содержит port:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Для вызывающего, чей провайдер не сообщает ports, рендерится пустой ports:, а не ошибка, потому что имя, о котором никто не сообщил, читается как пустое.

Как ведёт себя список:

  • В порядке записи. Записи следуют порядку, в котором записаны подключающиеся компоненты, а затем порядку собственных записей uses каждого. Компонент, подключающийся дважды, появляется дважды — по разу на соединение. Поскольку это список, а не карта, range встречает вызывающих в этом порядке — ничего не сортируется.
  • Только там, где присоединение рендерит собственные ресурсы. Его читают valuesMapping:, workload: и artifacts: у FeatureRecipe. Он пуст в собственных шаблонах Recipe компонента, в injectMapping: и в with: и when: шага pipeline:, потому что результат каждого из них может попасть в собственный отрендеренный вывод компонента: injectMapping: записывает канал доставки компонента, а шаг конвейера может переписать документы компонента. Именно это сохраняет собственный вывод компонента одинаковым, кто бы его ни использовал: подключение ещё одного вызывающего к компоненту меняет вывод присоединённой к нему Feature, читающей его вызывающих, и ничего из того, что рендерит сам компонент.
  • Ничего о самом соединении. Запись не содержит ни values или infra отдельного соединения, ни присоединений соединения; они остаются у потребляющего компонента, в его .context.uses.<alias>.
  • Пуст, если компонент никто не использует. range по нему тогда ничего не рендерит.
  • Передаётся, а не интерпретируется. Идентификатор, сокет, опубликованные значения и размещение — строки, которые компилятор пропускает насквозь, а факты рендеринга — то, что сообщили провайдеры каждого вызывающего, с ключами по имени. Компилятор ничего не выводит из имени, ничего не загружает и ничего не решает о том, каких вызывающих должен пропускать ресурс; решает шаблон.

Что провайдер сообщил о рендере — .context.render_facts

Провайдер компонента может сообщать факты о выведенном им результате — свойства записанных им документов, которые видны только благодаря его собственному знанию своего формата. Какие факты сообщает провайдер, под какими именами и что содержится в каждой записи, — это собственный документированный контракт провайдера; сторону провайдера см. в разделе Reporting facts about what a guest emitted. Провайдер helm, например, сообщает метки выданных им шаблонов подов, селекторы своих контроллеров и Services и порты своих контейнеров — см. его факты рендеринга. FeatureRecipe, присоединённый к компоненту, читает сообщённое провайдером компонента в .context.render_facts, с ключами по имени факта. Для провайдера, документирующего факт ports, каждая запись которого содержит name и port:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Каждый факт — список. Провайдер сообщает каждый факт как список, даже если в нём одна запись, поэтому шаблон всегда перебирает его — отдельного единичного значения для чтения нет.
  • Один список на имя, объединённый по рендеру компонента. Рендеринг компонента может потребовать более одного вызова его провайдера — например, рендер чарта и размещение артефактов, — и каждый вызов сообщает за себя. Списки, полученные одним именем от этих вызовов, объединяются в один в порядке выполнения вызовов. То, что отрендерили присоединённые к компоненту Features, сюда не входит: Feature читает в .context.render_facts только собственный рендер компонента, что бы ни выдали другие Features компонента.
  • Во всех шаблонах присоединённого FeatureRecipe. Его читают valuesMapping:, workload: и artifacts:, а также with: и when: шагов pipeline: — факты берутся из собственного рендера компонента, поэтому их чтение не ставит ничего в зависимость от того, кто подключается к компоненту. Он отсутствует в собственных шаблонах Recipe компонента и в injectMapping:, которые выполняются до рендеринга компонента.
  • Пустой, а не отсутствующий. Если провайдер компонента ничего не сообщает, .context.render_facts — пустая карта, а имя, о котором никто не сообщил, читается как пустое, поэтому range по нему ничего не рендерит, а не завершается ошибкой.
  • Порядок. Список хранит записи в том порядке, в котором их сообщил провайдер. Запись-объект — карта с ключами, как и любая другая в контексте, поэтому шаблон, перебирающий её, встречает ключи в порядке ключей.
  • Передаётся, а не интерпретируется. Компилятор проверяет только, что значение каждого факта — список. Он никак не учитывает, что означает имя или запись; что с ними делать, решает шаблон.

.uses в утверждении — по сокету, затем по псевдониму

Шаблон assertions: читает те же соединения через собственное, более узкое представление: .uses находится в корне, а не под .context, и не содержит ничего из того, что опубликовала цель соединения, поскольку обе фазы утверждений вычисляются до рендеринга. Оно повторяет авторскую форму uses: <socket>: <alias>: { target: … }: ключами служат сокеты, а под каждым сокетом — псевдонимы всех его соединений; соединение, записанное как элемент списка, использует свою цель в качестве псевдонима. Запись каждого соединения содержит target, alias и, для соединения, созданного подключением Feature, origin_feature, а также три из сведений, которые содержит .context.uses, под теми же именами и с теми же значениями: .labels — метки цели; .values — значения, записанные на соединении; и .features — подключения, записанные на нём, с ключами по слотам. Каждое из трёх присутствует в каждой записи и пусто, если у соединения их нет. Подключение под .features содержит только type, resolved_version и values — в таком виде утверждение читает любое подключение, включая собственные подключения компонента, поскольку к моменту выполнения утверждения FeatureRecipe подключения ещё не разрешила свои provides.

Сокет с одним соединением и сокет с несколькими имеют одинаковую форму, поэтому утверждение читает их одинаково. Для компонента, запись которого в сущности Aggregate содержит uses: { models: { local: { target: llama }, fast: { target: turbo } } }:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" проверяет, подключён ли сокет, len считает его соединения, range по нему обходит каждое в алфавитном порядке их псевдонимов, а .uses.models.local.target читает одно соединение. .uses.models.target не адресует ни одного соединения и приводит к остановке из-за missingkey=error в точке вывода утверждений. У каждого соединения есть собственная запись по той же причине, что и в карте контекста рендеринга: два соединения одного компонента никогда не имеют общего псевдонима, так как сборка отклоняет это до выполнения любого утверждения. Полный контекст утверждений описан в assertions-block.md.

Контекст шаблона содержит эти поля в форме inject, каждое со своей семантикой. Авторам Recipe и FeatureRecipe следует знать, какую точку вывода читать.

Точка выводаТипКогда заполняетсяНазначение
.context.injectкарта механизмов (присутствует всегда)При каждом рендерингеСтандартный заранее гидратированный канал доставки — читайте его в шаблонах valuesMapping:/workload:/artifacts: и в любом месте шаблона FeatureRecipe.
.inject (верхнего уровня)карта механизмов (допускает null)При рендеринге FeatureRecipe присоединения, если присоединение задаёт блок inject:Собственные записи inject: подключения, под каждым механизмом, который называет его блок, — env, file, arg или пользовательским, например vault_ref, — где каждое локальное имя сопоставлено с ключом, который называет его from:. Этот ключ — либо ключ, который сущность FeatureRecipe публикует в своих provides: и который компилятор также доставляет в .context.inject компонента, либо ключ, который сама потребляет сущность FeatureRecipe, читающая .inject: запись, называющая ключ, который сущность FeatureRecipe не публикует, останавливает сборку, если только шаблон, вычисляемый сущностью FeatureRecipe относительно этого контекста, — её valuesMapping:, workload:, artifacts:, omits: или with: либо when: шага конвейера, — не читает .inject по пути, который называет шаблон: .inject, .inject.env, {{ with .inject }} и тому подобное, а не через передачу всего контекста, как toJson .. Её injectMapping: не учитывается, поскольку он вычисляется относительно контекста компонента, где .inject отсутствует. Блок подключения не содержит литералов: запись value: в нём останавливает сборку, а литерал, нужный компоненту, записывается в собственном блоке inject: компонента. Пользовательский механизм читается в .inject.<mechanism> точно так же, как .inject.env, а его записи появляются в .inject.all наряду с тремя основными. Чтение через точку механизма, который подключение не задаёт, останавливается как неизвестный ключ, даже внутри if или with, где .context.inject.<mechanism> читается как пустое; механизм, который подключение может не задавать, следует читать через {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, что собирается независимо от того, задаёт ли подключение этот механизм или какой-либо блок inject:. Отсутствует в шаблонах базовой сущности Recipe и в подключении, не задающем ни одного блока inject:.
.inject_raw (верхнего уровня)карта механизмов (допускает null)Задаётся, когда разработчик написал блок inject: в родительском компонентеНеизменённое намерение разработчика до какого-либо перехвата inject-mapping. Каждый механизм, который называет блок, — env, file, arg или пользовательский, например ssm_param, — находится под собственным именем и содержит записи ровно в том виде, в каком они написаны (in вместе с from или value), в порядке написания: .inject_raw.ssm_param читает пользовательский механизм так же, как .inject_raw.env читает основной. Используйте для логических проверок вида «запрашивал ли разработчик изначально этот ключ доставки?»; не подвержено переписыванию через injectMapping в FeatureRecipe. nil, если разработчик не указал блок inject:.
.context.self_injectкарта механизмов (присутствует всегда)Каждый рендеринг; пусто там, где разработчик не записал блок inject: на компонентеКаждое имя из собственного блока inject: компонента, сопоставленное с собственным ключом, который доставляет его запись, — provides.<key>, values.<key> или пусто. Используйте, чтобы пропустить имя по умолчанию для собственного значения, которое разработчик уже доставляет; см. выше.

Авторам, которым нужна итоговая доставка после перехвата, следует читать .context.inject. Авторам, которым нужно неизменяемое исходное намерение (например, чтобы обнаружить перехват или задать резервное поведение, когда разработчик не указал блок inject), следует читать .inject_raw. Авторам, которым нужно знать, какие из собственных значений компонента разработчик уже назвал, следует читать .context.self_inject.

Точка вывода FeatureRecipe вложения

Когда рендерер вычисляет шаблоны FeatureRecipe вложения, задаётся дополнительное поле верхнего уровня:

  • .attachment_name (строка) — имя экземпляра вложения: слот, который оно занимает в featuresSchema сущности-владельца, или произвольное имя, которое дал ему автор. Секции locals:, provides:, injectMapping:, valuesMapping: и artifacts: сущности FeatureRecipe читают его, чтобы вывести детерминированный идентификатор ресурса — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, если провайдер хоста сообщает имя рендеринга, как это делает helm, и {{ .context.instance_id }}-{{ .attachment_name }}, если не сообщает, — а также чтобы назвать обрабатываемое вложение.

Собственные шаблоны базового Recipe не разрешают вложение, поэтому поле не входит в их контекст: шаблон provides:, locals: или source: сущности Recipe, который ссылается на него, останавливает сборку с указанием этой ссылки, а не выводит пустое значение. FeatureRecipe с executionScope: boundary отрисовывается один раз для границы, а не один раз для каждого компонента, поэтому поле недоступно и шаблонам, выполняемым для границы; его injectMapping: выполняется для каждого компонента, которого достигает вложение, и читает поле там.

В шаблонах, создающих собственные ресурсы вложения, — его valuesMapping:, workload: и artifacts: — контекст вложения также перечисляет компоненты, использующие его хост, в .context.used_by, а если его FeatureRecipe задаёт readsTargetRenderFacts: true, содержит результаты рендеринга каждого компонента, с которым связан его хост, в .context.uses.<alias>.render_facts. Эти шаблоны и его шаги pipeline: также читают сведения, которые провайдер хоста сообщил о рендеринге хоста, в .context.render_facts. FeatureRecipe с областью границы отрисовывает свои ресурсы без хост-компонента и без .context; вместо этого он читает все связи внутри своей границы из .boundary.internal_uses_edges и .boundary.incoming_cross_boundary_uses_edges. Его injectMapping: — единственный шаблон, который выполняется в контексте компонента — каждого компонента, которого достигает вложение, включая .context.*, — и ссылка на .boundary там останавливает сборку.

Это поле — единственный способ получить имя экземпляра вложения. .context.instance_id — это хост-компонент, для которого разрешается вложение: он обозначает хост во всех точках шаблонов, которые вычисляет компилятор, включая собственные locals: сущности FeatureRecipe, — поэтому эти два имени не взаимозаменяемы и ни одно не может заменить другое.

.source принадлежит самому присоединению. Шаблон source: сущности FeatureRecipe вычисляется перед её valuesMapping:, так же как шаблон сущности Recipe — перед её собственным, и то, что он создал, и содержит .source в шаблонах, создающих ресурсы присоединения, — её valuesMapping:, omits:, workload: и artifacts:, — а также в её шагах pipeline:. Это никогда не источник хост-компонента: сущность FeatureRecipe, которая не объявляет source: или чей шаблон ничего не создаёт, ничего там не читает, даже на хосте, чья сущность Recipe объявляет источник. Сущность FeatureRecipe с областью действия границы читает собственный источник в тех же шаблонах. Единственное исключение — injectMapping:, который выполняется до вычисления источника присоединения и читает .source так же, как собственная сущность Recipe хост-компонента.

.context.rendered_name тоже относится к хост-компоненту: во всех шаблонах вложения уровня компонента оно содержит имя, которое собственный провайдер хоста сообщает для хоста, — значение, которое читает собственный Recipe хоста, — поэтому вложение называет ресурс по своему хосту с помощью {{ .context.rendered_name }}-{{ .attachment_name }} и получает имя, допустимое для платформы, даже если идентификатор хоста содержит подчёркивание или заглавную букву. Оно присутствует, если провайдер хоста сообщает имя, и отсутствует, если не сообщает; чтение его на таком хосте останавливает сборку из любого шаблона, который FeatureRecipe задаёт встроенно, кроме его injectMapping:; см. Именование ресурса рендеринга.

Доступность по местам вызова

Доступность полей зависит от места вызова шаблона. Шаблоны provides: сущности Recipe выполняются на этапе вычисления provides с самодостаточным контекстом (без .context.inject/.context.uses); valuesMapping: сущности Recipe выполняется на этапе базового рендеринга с полным контекстом шаблона; injectMapping: сущности FeatureRecipe выполняется на этапе сопоставления inject с полным контекстом шаблона, включая перехватываемый канал inject. Полная таблица доступности по каждому месту вызова приведена в expansion-matrix.md; на этой странице описана структура полей, на которые указывает столбец матрицы «доступные ссылки».

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

  • 05-templates.md — обзор шаблонизации.
  • expansion-matrix.md — матрица вычисления по местам шаблонов.
  • sprig-functions.md — вспомогательные функции Sprig, подключённые к движку шаблонов.
  • ../entities/recipe.md — поверхность написания сущности Recipe.
  • ../entities/featurerecipe.md — поверхность написания сущности FeatureRecipe (включая разобранный пример DNS-резолвера K8s для обхода .context.uses).
  • ../vocabulary/topology-triad.md — спецификация контракта внедрения (описывает контекст с двумя состояниями, правила коллизий ключей и разобранные примеры).
  • ../10-status.md#compilation-pipeline-phases — текущая готовность поверхностей маппинга внедрения, базового рендеринга и конвейера плагинов.