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

FeatureRecipe

Концептуальная роль сущности FeatureRecipe (домен 3 — реализация интерфейса Feature на основе Wasm-плагинов) описана в architecture/04-entity-taxonomy.md. На этой странице рассматриваются средства описания FeatureRecipe в каталоге.

Расположение в каталоге

Сущности FeatureRecipes упорядочены так, что провайдер стоит в первом сегменте пути (по той же схеме, что и Recipes):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

URI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (например, hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).

Контракт описания

Сущности FeatureRecipes привязываются к интерфейсу Feature через implements и объявляют конкретного провайдера. Их поверхность авторинга — это полный набор видов входных данных базовой сущности Recipe плюс два блока, специфичных для FeatureRecipe:

  1. Три вида входных данных — source + valuesMapping (с источником), workload (синтезируемые) и artifacts: по форме идентичны базовой сущности Recipe (см. Композиция входных данных Recipe и entities/recipe.md). Сущность FeatureRecipe, содержащая любой из них, является генерирующей ресурсы — она отрисовывает ресурсы рядом с базовым компонентом. Место, куда попадают эти ресурсы, содержит компонент, к которому прикреплена сущность Feature, а затем имя, под которым она прикреплена, в той из двух форм, которую допускает собственная структура цели: как каталог {component}--{instance}/ рядом с каталогом хоста, внутри того каталога, который эта цель отводит для своих участников, — на цели, чей провайдер даёт каждому участнику собственную позицию; как префикс имени файла {component}--{instance}-- рядом с собственными файлами компонента — на цели, которая читает только файлы, лежащие непосредственно в каталоге. На провайдере, который собирает своих участников в единый документ, ресурсы вместо этого встраиваются в этот документ — к какому бы семейству ни принадлежала сущность Feature: CRD ServiceMonitor или ExternalSecret как встроенные или $import artifacts:; внешний chart или модуль через source: + valuesMapping:; или собственные вычислительные ресурсы (например, Deployment агента-sidecar) через workload:. valuesMapping: разделяет три режима написания базовой сущности Recipe (встроенный блочный скаляр, файловый $import:, библиотечный $import: к записи MappingLibrary) — см. entities/recipe.md, раздел «Поле valuesMapping — три режима написания». По соглашению сущность FeatureRecipe изменяет базовый компонент или добавляет ресурсы рядом с ним, но схема не ограничивает, какие виды входных данных она может использовать: компилятор отрисовывает всё, что объявляет FeatureRecipe, с ограничением лишь возможностями привязанного провайдера, и остаётся без собственного мнения о том, «подходит ли для модификатора» тот или иной вид (см. основополагающие инварианты). Синтез (workload:) требует провайдера, который его поддерживает; в противном случае сборка останавливается на этапе отрисовки с диагностикой возможностей провайдера.
  2. injectMapping (перехват до рендеринга): нативный блок шаблона Go, выполняемый до рендеринга базового Recipe. Он выдаёт словарь JSON или YAML, который компилятор нативно глубоко сливает поверх канала памяти .context.inject вызывающей стороны, позволяя изменять переменные окружения и строки подключения на стороне вызывающего без Wasm.
  3. pipeline: последовательный массив шагов плагинов WebAssembly (Wasm) для изменения Workload после отрисовки (например, внедрение sidecar Envoy через JSONPatch или монтирование тома с секретом). Поле plugin каждого шага называет сущность Plugin по её URI, всегда с областью по собственному типу сокета плагина (<pluginType>/<name>, с необязательной версией, как в parser/yaml или parser/yaml:1.0.0); сборка разрешает сущность в её адресуемый по содержимому артефакт .wasm, найденный по идентичности плагина и настроенному реестру, а голый .wasm или ссылка на артефакт здесь не принимаются. О написании плагина и ссылках на него см. руководство разработчика плагинов Wasm, а о принципе Two-Part Plugin (Fetcher / Injector) — architecture/04-entity-taxonomy.md, §«Domain 3: Infrastructure Base». Компилятор выполняет шаги в объявленном порядке: он вызывает гостевой экспорт названного плагина на отрисованном выводе и применяет возвращённые JSON Patch и порождённые побочные эффекты; о состоянии выполнения каждой поверхности конвейера см. Состояние языка. Блок pipeline: самостоятелен: сущность FeatureRecipe может объявить его без какого-либо вида входных данных, и тогда она не порождает собственных ресурсов, а весь её эффект — то, что её шаги вносят в документы, уже отрисованные сборкой, или порождают рядом с ними.

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

Рядом с FeatureRecipe закрепляется то же, что и рядом с Recipe: дайджест каждого файла, импортируемого записью artifacts, и каждого удалённого source:, координаты которого записаны полностью, — в файле entity.lock в собственном каталоге FeatureRecipe, который записывает aggrega pin и который вы фиксируете рядом с ним. Pull для FeatureRecipe, чей lock-файл не содержит этих закреплений, останавливается и называет этот шаг, если pull не попросили его выполнить. Сборка останавливается, когда импортированный файл больше не соответствует своему дайджесту, и когда дайджест источника расходится с записанным в lock-файле Release (источник, указанный по git ref:, записывается по коммиту, в который он разрешился, и не сравнивается); в сам файл FeatureRecipe запись никогда не производится. aggrega pull описывает этот файл и то, как реагировать на каждую остановку.

Шаблонизация поля source

Поле source: сущности FeatureRecipe является поверхностью шаблонизации на тех же условиях, что и у сущности Recipe: шаблон вычисляется при разрешении источника, и то, что он выдал, затем разрешает сборка. Обе формы принимают шаблоны Go — универсальная строковая форма и структурированная объектная форма, строковые подполя которой вычисляются как шаблоны, а нестроковые подполя передаются без изменений. Перечень форм, обработка схем и порядок привязки путей описаны в entities/recipe.md, разделы «Source field templating», «Source field scheme inventory» и «How a source: path is anchored»; в этом разделе указано только то, что отличается для присоединения.

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

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

Что может читать шаблон. Набор ссылок совпадает с тем, по которому проверяются собственные записи locals: сущности FeatureRecipe, и отличается от набора сущности Recipe в двух отношениях, следующих из того, что разрешается присоединение, а не компонент:

  • .attachment_name доступно и называет экземпляр, под которым присоединена сущность Feature. Шаблон источника сущности Recipe отвергает его, поскольку источник сущности Recipe разрешается для узла и никакого присоединения нет.
  • .context.instance_id называет компонент-хост, для которого разрешается присоединение, а не само присоединение, а .context.rendered_name содержит имя, которое собственный провайдер хоста сообщает для хоста, — оно присутствует, только если этот провайдер его сообщает, а иначе сборка останавливается. См. Именование отрендеренного ресурса.

.locals содержит набор, который читают другие шаблоны этой сущности FeatureRecipe: её собственный разрешённый блок, под которым лежит блок сущности Recipe хоста, так что ключ, объявленный присоединением, имеет приоритет над одноимённым ключом хоста. Ссылка на ключ, которого в этом наборе нет, останавливает сборку с указанием этого ключа, а не убирает ключ при рендеринге. .provides, .context.inject и .context.uses отвергаются по тем же соображениям самодостаточности, по которым их отвергает поверхность источника сущности Recipe.

FeatureRecipe с областью границы читает вместо этого границу. Сущность Feature, чья FeatureRecipe объявляет executionScope: boundary, рендерится один раз для границы, а не один раз на компонент, поэтому у её шаблона источника нет компонента-хоста, который можно было бы прочитать. Он читает .boundary.* — те же опоры, которые читают её locals: и provides:, — а опоры уровня компонента (.context, .workload, .attachment_name, .inject) ей недоступны.

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

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

Исключительность injectMapping

Поле injectMapping доступно исключительно в FeatureRecipes — оно намеренно отсутствует в базовой схеме Recipe. Эта исключительность изолирует перехват переменных от valuesMapping: valuesMapping базового Recipe, сам того не зная, потребляет переписанные строки .context.inject, порождённые блоками injectMapping сущностей FeatureRecipe, так что они остаются развязанными. Как работает этот механизм, описано в разделе о перехвате inject-mapping ниже, а полную семантику перехвата до рендеринга см. в разделе об inject mapping в architecture/10-compilation-pipeline.md.

Перехват через inject-mapping: как работает injectMapping

Когда вызывающему узлу нужна строка подключения к цели в ином виде, чем неизменённый .provides.host цели, — с добавленным пространством имён для межграничного DNS Kubernetes, с префиксом кода региона для многорегионального шлюза или с суффиксом режима SSL в DSN, — injectMapping выполняет это изменение на стороне вызывающего узла, ещё до того, как valuesMapping базового Recipe увидит конвейер inject.

Поле injectMapping — это шаблон Go text/template, который рендерер вычисляет на этапе inject mapping, до рендеринга базового Recipe. Шаблон выводит словарь JSON или YAML с необязательными ключами механизмов (env, file, arg или пользовательский механизм, который Recipe компонента читает по пути .context.inject.<name>) — или плоское отображение, которое по умолчанию относится к env, — и рендерер выполняет глубокое слияние этого наложения поверх конвейера .context.inject вызывающего узла. Маршрутизация на стороне вызывающего узла через injectMapping выполняется на этапе inject mapping без запуска песочницы Wasm для простых операций со строками; плагины Wasm по-прежнему предназначены для структурных изменений AST через массив pipeline.

Записывайте каждое значение через toJson. Рендерер читает вывод шаблона как YAML, поэтому значение, подставленное между кавычками как есть, либо ломает этот вывод, либо читается обратно изменённым, как только содержит двойную кавычку или обратную косую черту, — обычно это пароль. toJson записывает значение как строку JSON, которую YAML читает обратно в точности, поэтому значение доставляется со всеми символами, которые в нём есть:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

Значение, собираемое из нескольких частей, сначала собирается, а затем один раз записывается через toJson, как в примерах ниже.

Вывод, который невозможно прочитать, останавливает сборку. Если вывод шаблона не читается ни в одной из двух форм — обычная причина в скаляре в кавычках, испорченном значением внутри него, — ни один из его ключей не может быть доставлен, поэтому сборка останавливается с указанием присоединения и FeatureRecipe, а не рендерит компонент так, будто ничего не было доставлено; см. fatal-halts.md «An attached Feature’s injectMapping output cannot be read (Невозможно прочитать вывод injectMapping присоединённой сущности Feature)». Приводимая причина скрывается, если она зависит от значения, объявленного чувствительным. Пустой вывод или вывод, который разбирается как словарь, ничего не доставляющий, ничего не доставляет и не является ошибкой.

Ключ верхнего уровня — это механизм, и all им не является. Каждый ключ верхнего уровня вывода в виде словаря называет механизм, через который доставляются его записи: env, file и arg или любое другое имя, которое доставляется как отдельный механизм под этим именем. .context.inject.all строится из этих механизмов после слияния и никогда не сливается из вывода, поэтому записи, написанные под all:, никуда бы не попали; вместо этого сборка останавливается с указанием присоединения, ключа и FeatureRecipe и сообщает, какие ключи может содержать вывод, — см. fatal-halts.md «An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Вывод injectMapping присоединённой сущности Feature записывает доставки под ключом, который ничто не доставляет)». Записывайте такие записи под механизмом, из которого их читает компонент.

Изменение строго локально для вызывающего узла. FeatureRecipe изменяет только конвейер inject узла, к которому она подключена, и никогда — вывод .provides цели. .provides.host цели могут потреблять многие вызывающие узлы по всему кластеру; injectMapping на стороне вызывающего узла сливается только в конвейер конкретного вызывающего узла, поэтому изменения маршрутизации ограничены ребром, которое их запросило.

Что может переписать отображение. К моменту рендеринга отображений каждый блок inject: уже выполнил доставку, поэтому вывод отображения всегда сливается поверх ключей, уже записанных чем-то другим, — и то, кто записал ключ, определяет, что происходит. Ключ, доставленный собственным блоком inject: вызывающего узла или блоком inject: одного из его подключений, отображение вправе переписать: это перехват, и значение отображения заменяет эту одну запись. Ключ, который собственное подключение отображения доставило через свой блок inject:, отображение также вправе переписать. Ключ, уже доставленный другой подключённой сущностью Feature — через её собственный блок inject: или через injectMapping её собственной FeatureRecipe, — переписать нельзя: сборка останавливается с указанием обоих подключений, вместо того чтобы позволить отображению, выполненному последним, решать, какое значение прочитает вызывающий узел. Таким образом, две маршрутизирующие сущности Features могут каждая уточнять собственный ключ, но две сущности Features не могут обе доставлять один ключ — включая случай, когда две маршрутизирующие сущности Features переписывают ключ одного и того же подключения, поскольку первая выполняет перехват, а вторая сталкивается с доставкой первой; см. fatal-halts.md «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Две подключённые сущности Features доставляют один ключ, последняя — через injectMapping своей FeatureRecipe)».

Вывод цели без связывания

Поскольку компилятор встраивает каскадные аннотации каждой цели в конвейер .context.uses вызывающего узла, шаблон injectMapping может извлечь координаты маршрутизации без того, чтобы Ops жёстко прописывали идентичность цели в infra сущности Feature:

  1. Шаблон ищет в .context.uses то топологическое ребро, которое внедрило запрошенную разработчиком переменную.
  2. Он извлекает каскадные release_annotations цели (например, aggrega.ai/namespace).
  3. Он форматирует полное доменное имя (FQDN) или строку подключения.
  4. Он выдаёт словарь переопределений.

Компилятор остаётся агностичным по отношению к сетевой семантике — пространствам имён Kubernetes, облачным регионам, топологиям мостовых прокси — и просто выполняет глубокое слияние с тем, что выдал шаблон. Когда затем выполняется valuesMapping базового Recipe, он потребляет перехваченные, переписанные строки из .context.inject.env так, как если бы это были исходные значения разработчика.

Разобранный пример: DNS-резолвер K8s

Стандартный каталог поставляет это как core/k8s-dns-resolver с FeatureRecipe для helm. Поскольку имена переменных окружения должны быть уникальны в пределах контейнера, target_var (например, API_HOST) служит глобально уникальным идентификатором конкретного контракта внедрения в пределах вызывающего узла. Перебирая явные рёбра в .context.uses и проверяя, какое ребро заявило target_var, шаблон находит нужный целевой узел и считывает его пространство имён. Единственный параметр — переписываемая переменная; цель и её пространство имён обнаруживаются, а не прописываются жёстко.

Схема маршрутизирующей сущности Feature (core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

Реализация FeatureRecipe:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

Сценарии за пределами маршрутизации

injectMapping чаще всего применяется для разрешения адресов через границы (как в примере с резолвером K8s DNS выше), но такое изменение на стороне вызывающего узла подходит для любого сценария, в котором нужно перехватить и отформатировать намерение разработчика до рендеринга инфраструктуры. Диапазон возможностей иллюстрируют ещё два шаблона.

Динамическое форматирование параметров безопасности (добавление SSL). Если в организации требуется, чтобы все внешние подключения к базам данных использовали строгую проверку TLS, сущность Feature может перехватить запрошенную разработчиком переменную DB_URL и добавить нужный режим SSL, чтобы приложение запускалось с правильными параметрами безопасности.

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

Добавление префиксов для многорегионального шлюза. Если универсальный компонент API развёрнут глобально, региональная маршрутизирующая сущность Feature может самостоятельно прочитать аннотации границы своего окружения и добавить префикс к внедряемым строкам подключения для своих вызывающих узлов.

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

Границы injectMapping. Этот механизм ограничен изменением канала памяти .context.inject (контракта доставки). Он не может добавлять новые контейнеры, монтировать тома или изменять вывод valuesMapping базовой сущности Recipe. Любое изменение, требующее структурных правок отрендеренного AST (например, массивов JSON или YAML), относится к массиву pipeline сущности FeatureRecipe и выполняется плагинами WebAssembly.

Граница целей патча для pipeline. Шаг pipeline патчит только тот вывод, который provider отрисовывает в структурированное дерево. Вывод в форме YAML и JSON структурирован — включая модули Terraform .tf.json, написанные на JSON, — поэтому JSONPatch шага редактирует адресуемые значения на месте, не затрагивая ни одного другого байта (комментарии, порядок, форматирование). Вывод, который provider выдаёт как непрозрачное тело, например конфигурация Terraform на нативном HCL, не является целью патча: патч против непрозрачного тела останавливает сборку с диагностикой, а не изменяет текст, который невозможно адресовать структурно. Поэтому написание шага pipeline против непрозрачного вывода — это ошибка проектирования, проявляющаяся как явная остановка, а не как молчаливое отсутствие действия.

Входные параметры вендорного модуля Terraform не являются целью патча, и об этом стоит сказать отдельно. Это аргументы блока module данного компонента, которые провайдер terraform записывает в корневую конфигурацию границы: нативный HCL, а значит, непрозрачный по правилу выше, и артефакт всей границы, а не узла, вывод которого патчит шаг. Поэтому нет позиции, из которой шаг pipeline мог бы их адресовать, и он никак не может изменить то, что получает подключённый модуль Terraform. Эти значения формируются там, где они написаны, — в valuesMapping: базовой сущности Recipe.

Условные шаги — when:

Шаг pipeline может содержать необязательное поле when:: встроенный шаблон Go, который компилятор вычисляет во время обхода конвейера, с тем же контекстом шаблона и тем же вычислителем, что и тело with: этого шага. Результат рендеринга определяет, выполняется ли шаг.

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

when: и optional: независимы. when: решает, выполняется ли шаг вообще; optional: смягчает сбой выполняющегося шага. Шаг может объявлять оба — when: управляет входом, а если шаг всё же выполняется, optional: определяет, как обрабатывается сбой внутри него. Шаблон when:, который не удаётся отрендерить, является дефектом авторинга и останавливает сборку независимо от optional:.

Отрендеренный текст when: оценивается по общему правилу булевых шаблонов: строки true, True и TRUE, любое ненулевое число и любая другая непустая строка считаются истинными; строки false, False и FALSE, пустая строка и нулевое число считаются ложными.

Шаблон FeatureRecipe для учётных данных

Когда FeatureRecipe реализует сущность Feature для учётных данных (помеченную feature.aggrega.ai/kind: secret), он может следовать принципу Two-Part Plugin Principle: pipeline, выстраивающий в цепочку плагин Fetcher (генерирующий CRD, специфичный для хранилища секретов) и плагин Injector (монтирующий секрет в целевой контейнер), — форма, которую описывает examples/04-secrets. Сущности FeatureRecipes для учётных данных из стандартной библиотеки не объявляют pipeline: и сами рендерят ресурс секрета; см. examples/05-credential-features.

FeatureRecipe для учётных данных рендерится в том же проходе Resource Generation, что и FeatureRecipe любого другого подключения, и её pipeline: выполняется на тех же условиях: компилятор обходит все подключения, у которых есть работа в этом проходе, как единую упорядоченную последовательность и выполняет объявленный конвейер каждого из них с той же семантикой наборов документов /own и /host. Подключение входит в эту последовательность по одной из двух причин: его FeatureRecipe объявляет входной вид, и тогда оно генерирует собственные ресурсы, или объявляет pipeline:, и тогда оно переписывает уже выпущенные документы. Поэтому подключение учётных данных может обращаться к отрендеренным документам компонента-хоста — монтировать том с секретом, добавлять ссылку на переменную окружения — точно так же, как операционное подключение, и единственное различие между ними состоит в том, куда попадают его собственные сгенерированные файлы.

В компоненте объявление чувствительности в сущности Feature следует за valuesMapping: сущности FeatureRecipe точно так же, как объявление сущности Component следует за её Recipe. Если FeatureRecipe рендерится из source: без valuesMapping:, значения, получаемые её целью, имеют ключами пути листьев, объявленные в Feature, поэтому лист, объявленный как sensitive: true, помечает свой отрендеренный ключ. Если FeatureRecipe объявляет valuesMapping:, ключи являются собственным изобретением этого шаблона, ни одно объявление их не называет, и сборка выводит по одному предупреждению на каждый такой лист с указанием подключения, листа и FeatureRecipe. Feature, подключённая к границе, предупреждений не вызывает: её .values всегда пусто, поэтому ни у одного объявленного листа нет значения для пометки — см. A declared-sensitive value reaches the target through a values mapping (Значение, объявленное чувствительным, попадает в цель через сопоставление значений).

Блок provides: — публикация для потребителя

Блок provides: сущности FeatureRecipe — это её публикуемый вывод: отображение строковых значений на шаблоны Go, которые вычисляются в собственной области видимости подключения (.values, .infra, полностью разрешённые .locals сущности FeatureRecipe, а также .context.instance_id и .context.rendered_name узла-хоста). Локальные значения разрешаются первыми, поэтому запись provides: читает их и получает уже разрешённые значения; обращение к ключу, который блок locals: не объявляет, останавливает сборку. С помощью этого блока подключение сообщает потребителю, что оно произвело — имя сгенерированного ресурса, сгенерированный ключ данных, облачную идентичность, — без того чтобы потребитель заново выводил эту идентичность из тех же входных данных.

Потребитель читает его по пути .features.<instance-name>.provides.<key> (или .features.<slot>.provides.<key> для подключения учётных данных), аналогично .context.uses.<alias>.provides для ребра uses. Если подключение записано на одном из соединений потребителя, потребитель читает то же отображение в рамках этого соединения, по пути .context.uses.<alias>.features.<slot>.provides.<key>, и подключение не входит в его .features (см. Подключения соединения). Собственный блок inject: подключения разрешает свои ссылки from: по тому же отображению, поэтому автор может выбрать любой из каналов: provides для чтения в шаблоне, inject для доставки в переменную окружения, файл или аргумент.

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

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

Разрешение выполняется один раз для каждого подключения, до отрисовки потребителя, и одно и то же разрешённое отображение используется и для чтения потребителем, и для проверки контракта, и для собственной генерации ресурсов подключения (Resource Generation) — поэтому то, что читает потребитель, и то, что выпускает подключение, не могут расходиться.

Provider и implements

spec.capability обязательно и называет провайдера, чей Wasm-плагин рендеринга рендерит вывод сущности FeatureRecipe (helm, helm-chart, compose и т. д.), на тех же условиях, что и spec.capability сущности Recipe (см. entities/recipe.md): закрепление версии выбирает, какая версия этого плагина выполняет рендеринг, и не является частью имени FeatureRecipe — Manifest сопоставляет FeatureRecipe, объявляющую capability: "compose:1.2.3", как compose/<name>:<version>, а значение сопоставления, в котором закрепление записано в имя, отклоняется как некорректная ссылка на recipe (E0095) ещё до какого-либо поиска. Поле implements привязывает FeatureRecipe к интерфейсу Feature и поддерживает точное сопоставление, сопоставление по диапазону, совместимому по мажорной версии, или сопоставление без версии — семантику сопоставления версий implements см. в vocabulary/inheritance-and-interface.

Область выполнения — spec.executionScope

Необязательное перечисление spec.executionScope выбирает модель диспетчеризации для генерации ресурсов. Допускаются два значения; если поле опущено, по умолчанию используется component.

  • component (по умолчанию). Генерация ресурсов сущности FeatureRecipe выполняется один раз для каждого подключённого экземпляра компонента. Каждый вызов получает отдельный для компонента контекст шаблона с корнем в .context.*: .context.instance_id, .context.inject, .context.uses, .context.annotations и т. д. Её valuesMapping:, workload: и artifacts: также читают .context.used_by — компоненты, чьи записи uses указывают на хост, каждый со своей идентичностью, своим сокетом, тем, что он публикует, а также пространством имён и границей, в которых он размещён; этого не видит ни один шаблон, который рендерит сам хост.
  • boundary. Генерация ресурсов выполняется один раз для каждой подключённой границы, независимо от того, сколько компонентов в поддереве границы потребляют фичу. Каждый вызов получает контекст шаблона области границы с корнем в .boundary.* вместо .context.*.

Описанный выше перехват injectMapping всегда выполняется для каждого потребителя независимо от executionScope. Каждый компонент, использующий фичу, по-прежнему получает собственную перезапись .context.inject на стороне вызывающего. Дедупликация на уровне границы применяется только к шагу генерации ресурсов (source/valuesMapping и массив pipeline).

Поэтому шаблоны FeatureRecipe с областью границы выполняются в двух областях. Её injectMapping выполняется один раз для каждого компонента, которого достигает присоединение, в контексте этого компонента — том же, который читает injectMapping FeatureRecipe с областью компонента: .context.*, .attachment_name, .features и собственные .values, .infra и .locals присоединения. Её .infra — это блок infra: присоединения к границе, а её .locals — блок, вычисленный один раз для границы. Все остальные её шаблоны — в том числе locals:, provides:, source:, valuesMapping: и artifacts:, а также with: и when: шагов её конвейера — выполняются один раз для границы, в контексте области границы, описанном ниже. Каждый шаблон проверяется относительно области, в которой он выполняется: valuesMapping:, читающий .context.instance_id, останавливает сборку, а injectMapping, читающий его, рендерит идентичность этого компонента. .boundary не задаётся ни в каком контексте компонента, поэтому injectMapping, читающий его, останавливает сборку с указанием ссылки, каким бы ни был executionScope сущности FeatureRecipe.

Контекст шаблона области границы

При executionScope: boundary шаблоны сущности FeatureRecipe, кроме её injectMapping, вычисляются относительно представления .boundary.* той границы, к которой подключена фича. Представление предоставляет:

  • .boundary.path — путь границы Release, к которой подключена фича: имена границ от самой внешней внутрь, соединённые через / (bridge, bridge/frontend). Он называет границу, а не каталог, в который записывается её вывод, — его задаёт directory: (заменяет .context.instance_id).
  • .boundary.assembly_path — каталог относительно выходного каталога сборки, в который собирается собственный вывод присоединения: вычисленные directory: и subDirectory: границы, то есть каталог, в который сборка направляет этот вывод (bridge/compose). Он равен source_assembly_path или target_assembly_path конечной точки соединения ровно тогда, когда эта конечная точка рендерится в тот же собранный файл, поэтому FeatureRecipe сравнивает их, чтобы отличить соединение внутри своего файла от соединения в другом файле.
  • .boundary.boundary_name — имя границы, заданное автором в сущности Release.
  • .boundary.components — словарь с ключами по ID экземпляра, содержащий все компоненты поддерева границы (instance_id, component, resolved_version, boundary_path).
  • .boundary.internal_uses_edges — рёбра uses:, у которых обе конечные точки находятся внутри поддерева этой границы (шаблон compose-bridge перебирает их, оставляя рёбра, обе конечные точки которых собраны в его собственный файл compose и размещены в разных сетях этого файла, чтобы получить конфигурацию прокси для каждого ребра). Каждое ребро несёт разрешённые provides своих конечных точек, внедрённые переменные окружения и размещение каждой конечной точки: source_namespace и target_namespace — аннотацию aggrega.ai/namespace, применимую к этой конечной точке (значение её собственной записи в Release, если оно есть, иначе значение её границы); source_boundary_path и target_boundary_path — путь границы Release, в которой она находится; и source_assembly_path и target_assembly_path — каталог в выходном каталоге сборки, в который её собирает провайдер, составленный из вычисленных directory: и subDirectory: её границы (bridge/compose). Две конечные точки с одним путём сборки рендерятся в один собранный файл, а провайдер compose считает путь сборки сетью конечной точки, если никакое пространство имён не применяется.
  • .boundary.outgoing_cross_boundary_uses_edges — рёбра, у которых источник внутри поддерева, а цель снаружи.
  • .boundary.incoming_cross_boundary_uses_edges — рёбра, у которых цель внутри поддерева, а источник снаружи (используются агрегаторами в стиле ingress).
  • .boundary.cross_boundary_uses_edges — объединение входящих и исходящих межграничных рёбер, когда сущности FeatureRecipe нужно полное межграничное представление.
  • .boundary.labels — объединение меток поддерева с сохранением авторского порядка.
  • .boundary.annotations — собственные аннотации границы плюс каскад.
  • .boundary.feature_attachments — все фичи, подключённые к этой границе (чтобы FR области границы при необходимости могла исследовать соседние).

Опора .infra в FR области границы разрешается в блок infra: фичи, подключённой к границе (заданные на стороне Release физические размеры для этого подключения к границе). .values всегда пуст для FR области границы: правило разделения опор схемы Release запрещает values: в подключениях сущностей Feature на уровне Release, поэтому фича, подключённая к границе, не несёт значений для проецирования. FR области границы, которым нужны данные в форме параметров, должны получать их через .infra (поверхность, через которую оператор задаёт конфигурацию фичи границы) или через .boundary.annotations (разрешаемые каскадом строковые значения, заданные на границе или любом предке); .parameters не входит в представление, и шаблон, читающий его, останавливается с указанием корней, которые определяет представление. .locals по-прежнему является собственным блоком locals FR. .steps и .metadata остаются без изменений.

Список допустимых полей шаблона в области границы

FR области границы во всех шаблонах, кроме injectMapping, могут ссылаться только на поля, доступные в представлении области границы. Если при executionScope: boundary такой шаблон ссылается на поле, доступное только для отдельного компонента (например, .context.instance_id, .context.inject, .context.uses), сущность FeatureRecipe не проходит проверку во время разбора с ошибкой, в которой названы FR, недопустимое поле и поля, которые определяет представление области границы. Зеркальное правило действует в обратном направлении: FR области компонента, ссылающаяся на поля .boundary.*, не проходит тот же валидатор. injectMapping в обеих областях проверяется относительно контекста компонента, в котором он выполняется, поэтому он может читать .context.*, а ссылка на .boundary в нём приводит к остановке с указанием ссылки и корней, которые определяет этот контекст.

Валидатор выполняет тот же обход AST шаблона, что и список допустимых переменных шаблонов путей, но с отдельным набором ссылок для каждой области.

Дедупликация и вывод генерации ресурсов

Для executionScope: boundary компилятор дедуплицирует генерацию ресурсов по кортежу (boundary_path, FR-instance). Два компонента в одном поддереве границы, потребляющие одну и ту же фичу, подключённую к границе, вызывают одно выполнение FR, а не два. Межграничные подключения одной и той же фичи выполняются независимо для каждой границы.

FR области границы выдаёт один набор непромежуточных файлов на каждый кортеж (boundary_path, FR-instance), а их расположение определяется тем, как провайдер объединяет вывод своей границы. Координатой здесь служит только имя экземпляра, тогда как подключение области компонента несёт и свой компонент: фича области границы подключена к границе, а не к какому-либо компоненту, поэтому объемлющий каталог границы уже говорит всё, что сказал бы сегмент компонента, и называть нечего.

Провайдер, который записывает каждый документ непосредственно в каталог границы, объявляет, что его цель читает только файлы, лежащие непосредственно в каталоге. Поэтому объемлющего каталога для подключения нет, и имя экземпляра вместо этого становится префиксом имени файла: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, рядом с собственными файлами границы. Имя экземпляра кодируется, поскольку у имени файла нет разделителя, на который можно опереться, и оно стыкуется с собственным именем файла на двухсимвольной границе, которую не может содержать ни одна закодированная координата, — так что два подключения, выдающие одно имя файла, всё равно дают два файла.

Провайдер, который собирает вывод своей границы в объемлющую структуру — один чарт, содержащий по чарту на каждого участника, одна корневая конфигурация, содержащая по модулю на каждого участника, — помещает каждого участника в отдельный подкаталог, и подключение к границе является таким же участником, как любой другой. Тогда его вывод располагается в <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, где <contributors-directory> — то, как эта цель называет место, где живут её дочерние единицы. Подкаталог носит имя экземпляра подключения, то есть имя, под которым вы записали его в блоке features: границы, поэтому каталог, создаваемый сборкой, можно найти в том, что вы написали.

Промежуточный вывод поступает в сборщик границы для пары (путь, провайдер) по вычисленному пути FR под собственной spec.capability FR — это механизм, которым Feature core/compose-bridge объединяет сервис моста с компонентными участниками compose по одному и тому же пути сборки. Такой вывод записывается только как часть файла, собираемого там из компонентов границы, поэтому если ни один из них не попадает по этому пути — например, каждый компонент отправлен в другое место своим subDirectory:, — сборка останавливается с указанием границы, Feature, пути, по которому был направлен её вывод, и провайдера, а не записывает вывод в никуда (см. «A boundary-level Feature’s output reaches no assembled file (вывод Feature уровня границы не попадает ни в один собранный файл)» в fatal-halts.md).

Разрешение provides: с учётом каскада

FR с областью границы создают один набор provides: на каждый кортеж (boundary_path, FR-instance) и вычисляют его один раз. Шаблон provides: сущности FR вычисляется с контекстом шаблона области границы (поэтому он может ссылаться на .boundary.components, .boundary.path, .infra, но не на поля отдельного потребителя и не на .values). Значения provides — константы относительно потребителей: каждый потребитель в поддереве границы видит одни и те же предоставленные значения.

Разрешение provides FR с областью границы на стороне потребителя везде читает это единственное вычисление. Каждый компонент, которого достигает присоединение, читает его в .features.<instance-name>.provides.<key> — в шаблонах своего Recipe и в собственном injectMapping сущности FeatureRecipe, который выполняется в контексте этого компонента. Потребитель Component, читающий через ребро uses, которое несёт присоединение, в .context.uses.<feature-alias>.provides.<provided-name>, получает те же значения: компилятор разрешает это в provides: сущности FeatureRecipe с областью границы для той границы, в которой находится потребитель, проходя от ребра uses потребителя, которое несёт идентичность экземпляра функции для каждого присоединения, к provides: FR с областью границы. Предварительный проход вычисляет эти provides до сборки потребителя, поэтому значения уже есть, когда строится конвейер потребителя.

Эффект для каждого потребителя — это таблица в provides:, которую читает injectMapping. FeatureRecipe с областью границы, которой нужно что-то изменить для каждого потребителя, один раз вычисляет в своём provides: таблицу с ключами по потребителям на основе соединений границы, а её injectMapping читает строки текущего компонента — (index .features .attachment_name).provides с ключом .context.instance_id — и доставляет их через собственный канал потребителя по правилу, которому следует каждое сопоставление (см. Что может переписать сопоставление). Компилятор передаёт таблицу, написанную FeatureRecipe, и ничего в ней не читает.

Шаблон compose-bridge

FeatureRecipe compose-bridge — канонический шаблон FR с областью границы, и это содержимое каталога, написанное с помощью описанных выше механизмов: ни компилятор, ни провайдер compose не содержат никакой логики моста, поэтому каталог может реализовать Feature core/compose-bridge иначе. Функция core/compose-bridge присоединяется к родительской границе, содержащей две вложенные границы (например, services-net и data-net) с общим directory:, каждая из которых несёт собственную аннотацию aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net), чтобы каждая попала в собственную сеть; без аннотаций обе разделяют одну сеть, названную по пути их файла compose, и достигают друг друга без моста. Её executionScope: boundary запускает FR один раз на каждое присоединение к родительской границе.

Её provides: один раз вычисляет таблицу моста. Из .boundary.internal_uses_edges она оставляет рёбра, обе конечные точки которых собраны в её собственный файл compose — source_assembly_path и target_assembly_path оба равны .boundary.assembly_path — и находятся в разных сетях этого файла; сеть конечной точки — это её aggrega.ai/namespace, а при его отсутствии — её путь сборки. Ребро между двумя файлами compose не связывается мостом, и его потребитель сохраняет собственное имя цели. Каждое связываемое ребро получает порт прослушивания — собственный порт цели или, если более раннее ребро уже прослушивает его, первый свободный порт не ниже portBase присоединения (по умолчанию 10000) — и upstream: опубликованный хост цели (поле provides, которое называет providesField присоединения, по умолчанию host) и её port; upstream выводится из ребра и никогда не пишется вручную. Из той же таблицы она вычисляет перезапись для каждого потребителя: переменная, которую ребро доставляет из поля хоста, становится aggrega-gw:<listen port>, или aggrega-gw, если то же ребро доставляет ещё и переменную из port, которая тогда становится портом прослушивания.

Её injectMapping доставляет строки каждого потребителя. Выполняясь в контексте каждого потребителя, он читает строки таблицы этого потребителя в .features.<attachment>.provides и доставляет их поверх значений, которые доставило собственное соединение потребителя (например, DB_HOST), — это перехват; потребитель без строки ничего не получает. Если этот ключ доставила другая Feature, присоединённая к потребителю, — через свой блок inject: или свой injectMapping, — сборка останавливается с указанием обеих Features, а не заменяет эту доставку (см. «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (две присоединённые Features доставляют один ключ, последняя — через injectMapping своей FeatureRecipe)» в fatal-halts.md). listen шлюза и перезапись потребителя читаются из одной таблицы, поэтому по построению согласуются для каждого ребра, включая коллизии, переназначенные через portBase.

Её valuesMapping пишет шлюз. Собственный фрагмент compose сущности FeatureRecipe объявляет сервис aggrega-gw. Если что-либо связывается мостом, её valuesMapping добавляет по одному блоку nginx stream server на каждое связываемое ребро (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, под директивой resolver, чтобы каждый upstream разрешался в момент соединения, а не один раз при запуске; $ в этих переменных записывается как $$, чтобы интерполяция $ в Docker Compose оставила для nginx буквальный $), доставляемый как смонтированная конфигурация compose — запись верхнего уровня configs: со встроенным content:, на которую ссылается aggrega-gw и которая монтируется в /etc/nginx/nginx.conf (поэтому nginx загружает её без написанной вручную command:). Встроенный configs.content требует Docker Compose ≥ 2.23.1. Она также перечисляет каждую связываемую конечную точку в x-aggrega-networks-of шлюза, которое провайдер compose разрешает в сети, где размещены эти конечные точки, поэтому шлюз подключается к каждой сети, которую охватывают его связываемые рёбра (сети потребителя и сети цели), — во время выполнения потребитель может достичь aggrega-gw:<port>, а шлюз может выполнить proxy_pass к цели. Если ничего не связывается мостом, шлюз, объявленный фрагментом, всё равно рендерится, но простаивает: без конфигурации, без дополнительной сети и без перезаписи.

Сборщик compose для каждой пары (путь, провайдер) объединяет шлюз с участниками отдельных компонентов по тому же вычисленному пути: один docker-compose.yaml, содержащий все компоненты и шлюз-мост. Если ни один из компонентов границы не собирается в файл шлюза, сборка останавливается, а не записывает шлюз в никуда. Upstream — детерминированный указатель на сервис compose, заданный во время компиляции; его разрешает DNS среды выполнения compose (без разрешения времени выполнения во время компиляции).

Рендеринг после вызывающих — spec.readsCallerRenderFacts

Необязательный ключ spec.readsCallerRenderFacts (логический, по умолчанию false) объявляет, что шаблоны этой сущности FeatureRecipe читают то, что отрендерили компоненты, подключающиеся к её хосту: факты рендеринга, которые провайдер каждого из этих вызывающих сообщает о выданном им выводе. Что сообщает провайдер и под какими именами — собственный контракт этого провайдера; в разделе Сообщение фактов о том, что выдал гость описаны факты, которые провайдер может сообщать.

Когда рендерится такое подключение. Сборка рендерит свои компоненты по одному, в фиксированном порядке, и подключение обычно рендерится сразу после компонента, к которому оно подключено. Компонент, который подключается к хосту и идёт в этом порядке позже, к этому моменту ещё не отрендерен, поэтому того, что он выдал, ещё нет и читать нечего. Подключение, чья сущность FeatureRecipe задаёт readsCallerRenderFacts: true, вместо этого рендерится после того, как отрендерены все компоненты сборки, вместе со всеми подключениями, которые не задают ни этот ключ, ни readsTargetRenderFacts, — поэтому рендеринг каждого вызывающего завершён до вычисления подключения. Его вывод попадает туда же, куда попал бы, и под теми же именами; ключ меняет то, когда подключение рендерится, а не то, что оно рендерит. Из более позднего рендеринга следует один порядок: если FeatureRecipe содержит pipeline, переписывающий документы компонента-хоста, а провайдер хоста записывает отдельные документы, эти шаги выполняются после конвейеров других подключений хоста, а не в порядке их подключения.

Что она читает. Когда ключ задан, каждая запись .context.used_by содержит .render_facts: факты рендеринга вызывающего компонента с ключами по имени факта. Каждый факт рендеринга — это список, поэтому шаблон всегда перебирает его через range, даже если в нём одна запись. Его записи могут происходить из собственного рендеринга вызывающего компонента и из рендерингов Features, присоединённых к нему: списки, которые одно имя получает от каждого из них, объединяются в один — сначала вызовы собственного провайдера вызывающего компонента, затем каждая из его Features в том порядке, в котором они рендерились. Feature вызывающего компонента, которая сама задаёт этот ключ, тоже рендерится после всех компонентов, поэтому то, что она сообщила, в эти списки не входит. Вызывающий компонент, провайдеры которого ничего не сообщают, содержит пустой .render_facts, поэтому имя, о котором никто не сообщил, читается как пустое значение:

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

Какие имена фактов существуют и что содержит каждая запись — документированный контракт провайдера вызывающего; например, у провайдера helm это его факты рендеринга, которые называют метки отрендеренных им подов. Факты вызывающих находятся на подключениях, которые читают valuesMapping:, workload: и artifacts: сущности FeatureRecipe; with: и when: шага pipeline: вообще не видят компоненты, подключающиеся к хосту, поэтому шаг читает только собственные факты хоста. Каждая сущность FeatureRecipe, подключённая к компоненту, — независимо от того, задаёт ли она ключ, — читает собственные факты компонента в .context.render_facts в той же форме; оба случая описаны в разделе контекст шаблона.

Объявляйте его всякий раз, когда шаблон читает факты. Шаблон, написанный непосредственно в FeatureRecipe, которая не задаёт этот ключ, — в её valuesMapping:, её workload: или в записи artifacts:, — и читающий render_facts внутри .context.used_by, останавливает сборку до начала рендеринга с указанием ссылки и поля, в котором он написан (см. «A template reads its callers’ render facts without declaring it (Шаблон читает факты рендеринга вызывающих компонентов, не объявив этого)» в fatal-halts.md). Проверка читает шаблон в том виде, в каком он написан, поэтому не видит ссылку, построенную во время выполнения шаблона, или ссылку в содержимом, импортированном из файла или библиотеки; а шаблон, который читает поле с именем render_facts из какого-либо другого списка помимо .context.used_by или читает собственные факты хоста как .render_facts внутри {{ with .context }} наряду с ним, считается читающим факты вызывающих компонентов; собственные факты хоста записывайте полностью как .context.render_facts. Момент рендеринга присоединения определяет ключ, а не проверка, поэтому задавайте его в каждой FeatureRecipe, шаблоны которой читают факты рендеринга вызывающих компонентов, каким бы путём они к ним ни обращались; задание ключа ничего не стоит, кроме более позднего рендеринга.

Шаг конвейера читает только собственные факты своего хоста. Шаг может переписывать собственные документы компонента-хоста, а собственный вывод компонента остаётся тем же, кто бы к нему ни подключался, поэтому with: и when: шага никогда не видят компоненты, подключающиеся к хосту, — независимо от того, задаёт ли FeatureRecipe ключ, который решает, когда рендерится подключение, и ничего не решает в том, что видит шаг. Поэтому записанные непосредственно with: или when: шага, читающие render_facts внутри .context.used_by, останавливают сборку до начала рендеринга с кратким кодом E0326, называя ссылку и поле шага, — вместо того чтобы отрендерить пустое значение. Читайте собственные факты хоста в шаге в .context.render_facts, записывая полностью, а факты вызывающих — в valuesMapping:, workload: или artifacts: сущности FeatureRecipe. Эта проверка читает шаблон в том виде, в каком он записан, с теми же ограничениями, что и описанная выше.

Область действия. Ключ применяется к сущности FeatureRecipe, которая рендерится один раз на компонент, — executionScope: component, по умолчанию. Сущность FeatureRecipe, объявляющая executionScope: boundary, рендерится там же, где всегда, независимо от того, задаёт ли она ключ, а шаблоны, создающие её ресурсы, читают .boundary, а не .context.

Рендеринг после целей — spec.readsTargetRenderFacts

Необязательный ключ spec.readsTargetRenderFacts (логический, по умолчанию false) объявляет, что шаблоны этого FeatureRecipe читают то, что отрендерили компоненты, к которым подключён его хост: факты рендеринга, которые провайдер каждой из этих целей сообщает о сгенерированном им выводе. Он читает другой конец соединения, чем readsCallerRenderFacts, — компоненты, на которые указывают записи uses хоста, а не компоненты, чьи записи uses указывают на хост, — а всё, что касается самих фактов, читается так же.

Любой из ключей заставляет присоединение рендериться после всех компонентов. Присоединение, чей FeatureRecipe задаёт readsCallerRenderFacts: true, readsTargetRenderFacts: true или оба, рендерится после того, как отрендерены все компоненты сборки, как описано в разделе выше: такой поздний рендеринг один, и его влияние на то, куда попадает вывод присоединения, и на порядок шагов его конвейера одинаково, какой бы ключ ни перенёс туда присоединение. Два ключа различаются только тем, какие соединения несут факты в контексте присоединения: цель, идущая в порядке сборки после хоста, к этому моменту уже отрендерена, так что сгенерированное ею доступно для чтения.

Что он читает. Когда ключ задан, каждая запись .context.uses содержит .render_facts: факты рендеринга цели, с ключами по имени факта, в той же форме, что и запись вызывающего компонента. Каждый факт рендеринга — это список, поэтому шаблон всегда перебирает его. Его записи могут поступать из собственного рендеринга цели и из рендерингов сущностей Features, прикреплённых к цели: сначала вызовы собственного провайдера цели, затем каждая из её сущностей Features в порядке их рендеринга; сущность Feature цели, которая сама рендерится после всех компонентов, в их число не входит. Цель, чьи провайдеры ничего не сообщают, содержит пустой .render_facts. Шаблон читает факты одного соединения под его псевдонимом, .context.uses.<alias>.render_facts.<name>, или факты каждого соединения по очереди:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

FeatureRecipe, не задающий ключ, не видит .render_facts ни на одном соединении, что бы ещё он ни задавал. Какие имена фактов существуют — это документированный контракт провайдера каждой цели: для провайдера helm это его факты рендеринга, которые называют метки, селекторы контроллеров и порты контейнеров отрендеренных им подов, то есть то, что нужно политике исходящего трафика, чтобы выбрать ровно те поды, к которым может обращаться её хост.

Объявляйте его всякий раз, когда шаблон читает факты. Шаблон, написанный inline в FeatureRecipe, который не задаёт этот ключ, — его valuesMapping:, его workload: или запись artifacts:, — и читающий render_facts под .context.uses, останавливает сборку до начала рендеринга с кратким кодом E0347, называя ссылку и поле, в котором она написана (см. «A template reads its targets’ render facts without declaring it (Шаблон читает факты рендеринга своих целей, не объявив этого)» в fatal-halts.md). Задание readsCallerRenderFacts эту ошибку не снимает. Проверка читает шаблон в том виде, в каком он написан, с теми же ограничениями, что и проверка для вызывающих компонентов: она не видит ссылку, построенную во время выполнения шаблона, или ссылку в содержимом, импортированном из файла или библиотеки, — а шаблон, который вообще читает .context.uses и при этом читает поле с именем render_facts из какого-либо другого значения, включая запись вызывающего компонента внутри {{ range .context.used_by }}, считается читающим факты своих целей. Шаблон, читающий факты обоих концов, задаёт оба ключа.

Шаг конвейера читает только собственные факты своего хоста. Поля with: и when: шага читают соединения, которые создаёт хост, так же, как их читает собственный Recipe хоста, и никогда — факты рендеринга их целей, независимо от того, задаёт ли FeatureRecipe этот ключ. Шаг может переписывать собственные документы компонента-хоста, а собственный рендеринг хоста читает то, что публикуют его цели, но никогда — то, что они сгенерировали. Поэтому написанное inline поле with: или when: шага, читающее render_facts под .context.uses, останавливает сборку до начала рендеринга с кратким кодом E0348, называя ссылку и поле шага, — вместо того чтобы отрендерить пустое значение. Читайте факты целей в valuesMapping:, workload: или artifacts: сущности FeatureRecipe.

Область действия. Как и для ключа вызывающих компонентов: он применяется к FeatureRecipe, который рендерится один раз на компонент. FeatureRecipe, объявляющий executionScope: boundary, рендерится там же, где всегда, независимо от того, задаёт ли он ключ, а соединения, которые он читает под .boundary, не несут фактов рендеринга.

Блок locals:

FeatureRecipe.spec.locals: — необязательная карта именованных строк шаблонов Go, отрендеренный результат которой предоставляет карту .locals.* каждому другому шаблону внутри того же FeatureRecipe. Это закрытый аналог locals: из Recipe для FeatureRecipe — место, где производные строки вычисляются один раз и затем используются в injectMapping, valuesMapping, pipeline[].with и provides без повторного вычисления. Блок assertions: сущности FeatureRecipe их не читает: .locals утверждения принадлежат сущности Recipe компонента-хоста, как указано в assertions-block.md. Отрендеренный результат каждой записи сохраняется без начальных и конечных пробельных символов. Блок является картой, а не телом одного шаблона; скаляр в этой позиции отклоняется схемой.

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

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

Каждая запись вычисляется в самодостаточном контексте: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra и уже разрешённые записи этого же блока. Этот контекст намеренно уже того, который читают остальные шаблоны FR: запись locals: не может обратиться к .context.annotations, .context.inject, .context.uses или .provides, и ссылка на любой из них останавливает сборку с указанием этой ссылки. Производные значения, которым нужны эти разделы, следует размещать в шаблоне, который их читает, а не в locals:.

Имена в этом контексте отвечают на разные вопросы, и запись locals: читает их точно так же, как остальные шаблоны FeatureRecipe:

  • .context.instance_id — это компонент-хост, для которого разрешается прикрепление. Оно означает компонент-хост на каждой поверхности шаблонов, которую вычисляет компилятор, поэтому одна и та же ссылка читается одинаково, блок какой бы сущности вы ни писали.
  • .context.rendered_name — это имя компонента-хоста в том виде, в каком его сообщает собственный провайдер хоста: для helm это имя релиза, то есть идентификатор хоста, записанный в алфавите, допустимом для имени Kubernetes. Оно присутствует, только если провайдер хоста сообщает имя; чтение его на хосте, провайдер которого имени не сообщает, останавливает сборку.
  • .attachment_name — это разрешаемый экземпляр прикрепления: слот, который он занимает в featuresSchema владеющей сущности, или свободное имя, которое вы ему дали.

Поэтому запись locals:, выводящая имя для создаваемого ресурса, составляет его из хоста и прикрепления, точно так же, как это сделал бы шаблон artifacts::

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

Если имя должно быть допустимым для платформы, а провайдер хоста сообщает его, составляйте его из .context.rendered_name: для хоста с именем my_api под helm и прикрепления scrape шаблон {{ .context.rendered_name }}-{{ .attachment_name }} даёт my-zuapi-scrape, тогда как идентификатор дал бы my_api-scrape, которое имя Kubernetes не допускает. См. Именование отрендеренного ресурса.

.values и .infra в записи locals: — это собственные разделы прикрепления, заданные в объявлении прикрепления, а не разделы компонента-хоста.

Порядок записей имеет значение

Записи разрешаются в том порядке, в котором они написаны, и запись может читать соседнюю запись, определённую выше, получая её разрешённое значение:

spec:
locals:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

Цепочка работает только сверху вниз. Когда одна запись читает другую, порядок записей определяет, завершится ли сборка успешно: переместите region_prefix ниже bucket — и сборка остановится. Компилятор никогда не переупорядочивает блок, чтобы ссылка разрешилась, поэтому изменение порядка в блоке locals: — это изменение поведения, а не косметическое.

Ссылка на запись, которую блок определяет позже, останавливает сборку с указанием на ошибку порядка (переместите определение выше места, где оно читается); ссылка на ключ, который блок вообще не объявляет, останавливает сборку с указанием этого ключа (исправьте написание). Проверка следует за псевдонимом блока: ключ, полученный через точку, которую переопределяет тело with .locals, или через переменную, связанную с .locals, останавливает сборку на тех же условиях, что и прямое написание, как и ключ, прочитанный из блока в скобках, — {{ (.locals).nope }} или {{ ($.locals).nope }}. Проверку обходит одно написание: ключ, полученный через вызов, результат которого текст шаблона не может назвать, — {{ index .locals "nope" }} или {{ (default dict .locals).nope }}. Поле, прочитанное из результата такого вызова, не останавливает сборку и выводит буквальный текст <no value>; чтение через index останавливает сборку с указанием ключа, потому что index останавливает сборку на любой поверхности шаблонов, когда читаемая им map не содержит ключа, — см. «A template indexes a map with a key the map does not hold (Шаблон индексирует map ключом, которого в map нет)» в errors/fatal-halts.md. provides: читает полностью разрешённый блок, потому что locals этой сущности FeatureRecipe разрешаются раньше её provides; шаблон provides:, называющий необъявленный ключ, останавливает сборку. Это те же правила, которым следует блок locals: сущности Recipe, — см. «Блок locals:» в entities/recipe.md.

Поведение в зависимости от области. При executionScope: component (по умолчанию) locals: вычисляется для каждого экземпляра прикреплённого компонента в описанном выше самодостаточном контексте. При executionScope: boundary locals: вычисляется для каждого прикрепления к границе в представлении области границы с корнем .boundary.*; поля уровня компонента (.context.instance_id, .context.inject, .context.uses) и .attachment_name недоступны, поскольку FeatureRecipe выполняется один раз для границы, а не для каждого компонента. Список разрешённых полей шаблонов области границы применяется к locals: так же, как к остальным авторским шаблонам FR. injectMapping, который выполняется для каждого компонента, которого достигает прикрепление, читает это единственное вычисление для границы как свои .locals. Контракт вычисления — порядок записей, чтение соседних записей только сверху вниз, две остановки — одинаков в обеих областях; различается только форма окружающего контекста.

Отличие от наложений injectMapping и сопоставлений pipeline[].with. locals: создаёт видимую в контексте карту для последующих шаблонов; он не вносит вклад в вывод. injectMapping записывает в канал .context.inject потребителя (изменение на стороне вызывающего). pipeline[].with передаёт полезную нагрузку args плагину Wasm. Эти три поверхности ортогональны: FeatureRecipe обычно использует все три вместе, причём locals: содержит общие производные строки, на которые ссылаются две другие.

Блок assertions:

FeatureRecipe.spec.assertions: — необязательная карта именованных правил, выражающих инварианты реализации FeatureRecipe: межполевые правила, которые выполняются с учётом конкретного конвейера Wasm-плагинов, чарта или механизма, на котором построен FeatureRecipe. Каждый ключ — идентификатор правила, который появляется в сообщении об ошибке; каждое значение — тело шаблона Go. Как и утверждения Recipe, утверждения FeatureRecipe являются свойствами конкретной реализации; правила контракта уровня Feature применяются независимо, на более ранней фазе конвейера.

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

Приведённое выше правило относится только к плагину aws-secrets-manager версии 1.x; оно не применяется, если привязывается другой FeatureRecipe для core/referenced-secret. Правила контракта уровня Feature из определения Feature при этом по-прежнему применяются.

Утверждения FeatureRecipe вычисляются после привязки FeatureRecipe и до генерации ресурсов. Контекст шаблона для FR с областью уровня компонента повторяет контекст утверждений Recipe (поля экземпляра сущности, а также .provides, .locals, .recipe.metadata, .recipe.source); для FR с областью уровня границы (executionScope: boundary) утверждения вычисляются относительно представления области границы (поля .boundary.* доступны, поля отдельных компонентов — нет). Полную грамматику написания и разобранные примеры см. в templates/assertions-block.md.

Поле omits: — исключение отрендеренных документов из источника

Большинству FeatureRecipes это не нужно. Поле предназначено для FeatureRecipe, чей source: — чарт, который вы берёте как есть (чаще всего полученный из реестра), и который рендерит документ, не допустимый для вывода подключения: Secret, который чарт заново генерирует при каждом рендеринге, или объект, который уже предоставляет хост-компонент или оператор. omits: исключает такой документ из того, что генерирует FeatureRecipe, — а для compose-файла, который является источником FeatureRecipe, исключает сервис, том или конфигурацию, которые подключение не должно добавлять, и для шаблона CloudFormation, который является её источником, — ресурс.

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

Ключ задаётся в сущности Recipe точно так же, и Recipe → Поле omits: — исключение отрендеренных документов служит его полным справочником: что выбирает каждое поле записи; то, что when: вычисляется первым и ложное значение отбрасывает запись; то, что каждая применимая запись должна что-то исключить, иначе сборка останавливается с указанием этой записи; то, что источник по-прежнему рендерится полностью и фильтруется только его вывод; и какие провайдеры поддерживают этот ключ. В сущности FeatureRecipe отличается только то, где вычисляются шаблоны:

  • Шаблоны каждой записи вычисляются в том же контексте, что и valuesMapping: этой FeatureRecipe, на уровне, который выбирает её executionScope. Записи FeatureRecipe уровня компонента вычисляются один раз на каждое подключение, с .values и .infra этого подключения; записи FeatureRecipe уровня границы — один раз на каждую границу, с представлением уровня границы и .infra подключения границы. Правила о том, что могут читать шаблоны подключения, применяются к записям так же, как к его valuesMapping:.
  • Фильтруется только то, что рендерит собственный source: этой FeatureRecipe. Её workload: и artifacts: не фильтруются, как и вывод хост-компонента: записи подключения затрагивают только его собственный чарт, собственный compose-файл или собственный шаблон CloudFormation и ничего больше — сервис compose, который хост объявляет под тем же ключом в docker-compose.yaml, куда собираются оба, остаётся нетронутым, как и ресурс, который хост объявляет под тем же логическим ID в стеке, куда собираются оба. Чтобы изменить документ, который рендерит хост, запись объявляет Recipe хоста, либо документ исправляет шаг pipeline:.

Остановка на записи указывает узел, провайдер, эту FeatureRecipe и позицию записи в её списке omits:; для FeatureRecipe уровня границы строка над сообщением указывает подключение и его границу.

Рабочий пример этого ключа, заданного в сущности Recipe, — исключение сгенерированного Secret полученного чарта, а также остановки без записи и на записи, которая ничему не соответствует, — см. в ai-gateway-own-webhook-certificate.