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

Recipe

Концептуальная роль сущности Recipe (шаблона трансляции, создаваемого Ops, который отображает намерение разработчика (Developer Intent) в физический формат) описана в architecture/04-entity-taxonomy.md. На этой странице рассматриваются средства создания сущности Recipe: указатель (source), маппер (valuesMapping:), встроенная поддержка IaC и разобранные примеры.

Архитектура Recipe: указатели и маппер

Сущность Recipe выполняет ровно две функции:

  1. Указатель (source): сообщает компилятору, где именно находится код инфраструктуры.
  2. Mapper (valuesMapping): внедряет абстрактный контекст Aggrega в конкретные переменные, которые ожидает нижележащий код. Поле представляет собой единую поверхность Go-шаблона с тремя режимами написания — встроенный блочный скаляр, файловый $import: или библиотечный $import:, — выбор между которыми выполняется по форме содержимого. См. раздел Поле valuesMapping — три режима написания ниже.

Поскольку сущность Recipe строго соответствует одной возможности рендеринга (1:1), эта возможность (spec.capability) явно объявляется на корневом уровне, чтобы компилятор Go точно знал, какой нижестоящий Wasm-плагин рендеринга вызвать.

spec.implements объявляет, какой тип компонента каталога может реализовать сущность Recipe. Компилятор использует его, чтобы проверять сопоставления в сущности Manifest (поле implements сопоставленной сущности Recipe должно совпадать с сопоставленным типом) и предлагать кандидатов — рецепты, перечисляемые в диагностике об отсутствии сопоставления и выводимые первыми в автодополнении редактора. Сборку он никогда не разрешает: сопоставление в сущности Manifest — явный выбор развёртывания пользователем, закреплённый в lock-файле. Сущность Recipe, у которой implements не версионирован, точен или задан диапазоном, совместимым по мажорной версии, всё равно лишь предлагает себя для типа; выбор закрепляет пользователь. FeatureRecipe.spec.implements выполняет ту же роль для типов функций.

A. Схемы источников на основе Wasm

Чтобы не допустить в компилятор предпочтений конкретных реализаций, блок source не является фиксированным набором инфраструктурных полей. Поле source поддерживает два формата:

  • Универсальная строка (быстро и чисто): лучше всего подходит для локальных путей, артефактов OCI и Git-репозиториев. Компилятор определяет способ загрузки по префиксу и суффиксу строки (./src, https://github.com/example/module.git, oci://...): URL, оканчивающийся на .git или записанный с git:// или ssh://, — это Git-репозиторий, загружаемый на его ветке по умолчанию, а URL https://, не указывающий ни на репозиторий, ни на чарт .tgz или фрагмент .yaml, отклоняется как неоднозначный.
  • Открытый структурированный объект: открытый словарь (additionalProperties: true), ключи которого определяются провайдером и доступны шаблонам сущности Recipe как .source.* (например, .source.chart). По замыслу каждый WebAssembly-сокет провайдера сам определяет и проверяет свою форму источника (например, registry/chart/appVersion для Helm).

Что разрешает ядро. Ни один провайдер не проверяет собственные ключи источника. Загружаемый источник разрешается встроенной идентичностью, поле kind которой выбирает резолвер: helm-oci-chart, helm-https-chart, compose-https-fragment и git-repository. Источник, предназначенный для загрузки, должен содержать kind и url; какая ещё координата выбирает содержимое, зависит от вида. Виды чартов и фрагментов принимают version и закрепляют её так, как она написана. git-repository принимает ref — тег, ветку или коммит — и, необязательно, module_subdir, указывающий каталог внутри репозитория, который является артефактом; поскольку только коммит обозначает содержимое, которое нельзя перенаправить, ссылка разрешается во время блокировки, а lock-файл записывает и написанную ссылку, и коммит, в который она разрешилась. Значение module_subdir, которое в написанном виде выходит за пределы репозитория (обратная косая черта считается разделителем), отклоняется до какой-либо загрузки. Репозиторий архивируется из собственной рабочей копии: закоммиченная в нём символическая ссылка архивируется как файл или каталог, на который она указывает, если цель находится внутри репозитория, а ссылка, ведущая наружу, останавливает загрузку с указанием её места в репозитории. Структурированный источник, у которого url: указывает путь файловой системы, не загружается: он читается с диска на тех же условиях, что и простая строка пути, причём относительный url: отсчитывается от каталога, содержащего файл сущности, в котором он объявлен. Структурированный источник без kind/url тоже не загружается, и если загрузка подразумевалась, сборка явно останавливается на этапе обхода источников при блокировке, а не разрешается молча в пустоту. Содержимое всегда закрепляется заранее; компилятор никогда не загружает живое состояние среды выполнения.

Что закрепляется рядом с Recipe. Для загружаемого источника, у которого kind, url, chart, module_subdir, version и ref написаны явно, а не шаблонами, aggrega pin записывает дайджест загруженного в entity.lock — файл в собственном каталоге сущности Recipe, который вы коммитите рядом с ней. Закрепление — шаг автора сущности Recipe, и сущность Release для него не нужна; загрузка по сущности Recipe, lock-файл которой не содержит закрепления, останавливается и называет его, если только загрузку не попросили выполнить тот же шаг. Сборка сравнивает этот дайджест с дайджестом, который lock-файл сущности Release записывает для того же источника, и останавливается при расхождении — кроме источника, заданного через git-ref:: его строка записывается по коммиту, в который разрешилась ссылка, и не сравнивается. Загружаемый источник, координаты которого заполняются из шаблона, закрепляется отдельно для каждой сущности Release, в её lock-файле. Источник, указывающий каталог или файл рядом с сущностью Recipe, не загружается: aggrega pin записывает по одному дайджесту на каждый файл, который он вносит в содержимое публикации сущности Recipe (для источника, написанного шаблоном, — каждый файл в каталоге сущности Recipe), и как только lock-файл их записал, сборка сравнивает с ними источник до того, как его прочитает провайдер, и останавливается на файле, добавленном, изменённом или удалённом после закрепления, — с E0305 или сначала с E0130, если lock-файл сущности Release, записанный до изменения, фиксирует сущность Recipe по её содержимому. Lock-файл без закрепления для такого источника не даёт сборке ничего для сравнения, а загрузка или публикация без закрепления его отклоняет. В сам файл сущности Recipe никогда ничего не записывается. В aggrega pull описан этот файл и то, как реагировать на каждую остановку.

spec.capability может содержать закрепление версии в формах, которые принимает implements, — точную (helm:<version>) или диапазон с кареткой (helm:^<version>), — выбирающее, какая версия плагина провайдера рендерит Recipe; закрепление, которому не удовлетворяет ни одна доступная версия, останавливает сборку. Без закрепления (spec.capability: "helm") рендерит самая высокая доступная версия. Доступные версии — те, что показывает aggrega plugin list: провайдеры, встроенные в aggrega, имеют версию самого компилятора. Закрепление не входит в имя Recipe: Manifest сопоставляет Recipe, объявляющий capability: "compose:1.2.3", как compose/<name>:<version>, точно так же, как незакреплённый, и изменение закрепления никогда его не переименовывает; значение сопоставления, записывающее закрепление в имя (compose:1.2.3/<name>:<version>), отклоняется как некорректная ссылка на recipe (E0095) до какого-либо поиска.

Модель для понимания: spec.capability называет нужный формат вывода (например, helm, terraform, compose); компилятор разрешает его в Wasm-плагин, который рендерит этот формат (например, provider/helm). Вы объявляете формат; Aggrega привязывает инструмент.

B. Внедрение контекста: семантический слой сопоставления

Чтобы компилятор не выполнял опасные недетерминированные глубокие слияния между несколькими окружениями, Recipe допускает только единственный источник истины для своего слоя сопоставления.

Инженеры эксплуатации пишут содержимое сопоставления, чтобы преобразовать абстрактный контекст до выполнения плагина рендеринга Wasm. Язык сопоставления — шаблоны Go (text/template + Sprig); библиотека Sprig зарегистрирована заранее; стандартные действия define и template поддерживаются, а include не зарегистрирован.

Имя поляОбласть действия и фаза выполненияЛучший сценарий использования
injectMapping (только FeatureRecipe)Перехват до рендеринга. Вычисляется в памяти Go до базового Recipe. Нативно выполняет глубокое слияние своего выходного словаря строго поверх канала .context.inject вызывающей стороны. Намеренно отсутствует в базовой схеме Recipe — архитектурное обоснование см. в entities/featurerecipe.Точечная перезапись внедрённых переменных env или форматирование FQDN для вызывающей стороны без использования Wasm JSONPatch.
valuesMappingБазовый рендеринг (шаблон Go). Вычисляется для сопоставления переменных с базовым инфраструктурным чартом или модулем source. Одно поле, три режима написания (встроенный, файловый $import:, библиотечный $import:). Механизм диспетчеризации описан в подразделе ниже.Сопоставление стандартных переменных (например, числа реплик или тегов образов) с чартом Helm непосредственно в YAML сущности Recipe или ссылка на общий шаблон через $import: для повторного использования в разных Recipes.

Примечание: injectMapping доступно только в FeatureRecipes и отделяет перехват переменных от valuesMapping. Поле valuesMapping базового Recipe, ничего не зная об этом, потребляет переписанные строки .context.inject, порождённые блоками injectMapping сущностей FeatureRecipe, поэтому они остаются развязанными.

Ключ, который valuesMapping записывает как null, поступает в провайдер как null, и что с ним происходит дальше, решает провайдер, поэтому это указано на странице каждого провайдера: helm удаляет значение чарта по умолчанию для этого ключа, helm-chart записывает его в значения зонтичного чарта, compose записывает его в файл compose, terraform записывает его как аргумент модуля null, а cloudformation его отклоняет.

Поле valuesMapping — три режима написания

Поле valuesMapping: сущности Recipe — единая поверхность шаблонов Go, принимающая три режима диспетчеризации. Компилятор выбирает режим по форме содержимого поля; аннотация $mode: не нужна.

Режим 1: встроенный шаблон Go (блочный скаляр YAML). Значение поля — строка, записанная в форме блочного скаляра YAML |:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

Встроенный режим — типичная форма для Recipes, у которых содержимое сопоставления невелико или среднего размера (примерно до 50 строк). Тело шаблона располагается вместе с остальной оболочкой Recipe; содержимое Recipe самодостаточно.

Режим 2: файловый $import:. Значение поля — словарь, содержащий только $import: с путём к локальному файлу:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

Компилятор загружает содержимое файла (шаблон Go), рендерит его в стандартном контексте шаблонов Recipe и использует результат как выход сопоставления. Путь разрешается относительно каталога Recipe — относительный путь привязан к каталогу, где лежит объявляющий его recipe.yaml, а не к каталогу, из которого запущена сборка, — и путь должен оставаться внутри этого каталога, как объясняется в разделе Пути к содержимому остаются внутри собственного каталога Recipe. Файловый режим подходит для сопоставлений среднего и большого объёма (~50+ строк) и для процессов ревью, где изменения сопоставления видны как отдельные диффы файлов.

Режим 3: библиотечный $import:. Значение поля — словарь, содержащий только $import: со ссылкой по идентичности (голому имени) на запись MappingLibrary:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

Компилятор разрешает ссылку по разрешённому набору MappingLibrary (локальный каталог плюс все библиотеки, закреплённые в lock-файле), загружает содержимое записи и использует его как выход сопоставления; запись, тело которой само является $import: в корне поля, разрешается рекурсивно. Ссылка не содержит хоста реестра — имя библиотеки разрешается по идентичности, а версия берётся из lock-файла конкретного Release, с необязательной нижней границей версии :<version> (<Library>:<version>#/mappings/<entry>). Содержимое библиотеки использует тот же стандартный контекст шаблонов Recipe. Библиотечный режим подходит для повторного использования в разных Recipes — шаблонов сопоставления, повторяющихся во многих Recipes (несколько Recipes хранилищ данных с общей вспомогательной логикой; несколько Recipes провайдера Helm с общими шаблонами подов). Сущность MappingLibrary обеспечивает версионирование, закрепление в lock-файле и отображение в UI хаба.

Правила диспетчеризации. Компилятор обходит узел YAML и выбирает режим по форме содержимого:

  1. Если узел — строковый скаляр, используется встроенный режим (режим 1).
  2. Иначе узел является словарём; проверяется наличие ключа $import:.
  3. Если значение $import: — библиотечная ссылка по голому имени (<Library>#/mappings/<Entry>, возможно с нижней границей :<version>), используется библиотечный режим (режим 3).
  4. Иначе (путь к локальному файлу) используется файловый режим (режим 2).
  5. Любая другая форма (словарь без $import:, словарь с дополнительными ключами помимо $import: и т. п.) приводит к ошибке во время сборки.

Только $import: с одним источником. $import: принимает один источник. Слияние нескольких источников в valuesMapping: не поддерживается. Recipe, которому нужно скомпоновать несколько фрагментов сопоставления, использует запись MappingLibrary с внутренней композицией через define / template шаблонов Go, локальный файл с директивами template шаблонов Go, вызывающими соседние файлы, или встроенную композицию для короткого содержимого. Сущность библиотеки описана в entities/mappinglibrary, более общее различие $ref: / $import: — в vocabulary/cross-document-ref.

Происхождение. Сообщения об ошибках рендеринга шаблонов указывают происхождение в соответствии с режимом: для встроенных шаблонов — файл:строку Recipe, где начинается блочный скаляр; для файловых импортов — содержимое импортированного файла; для библиотечных импортов — позицию записи MappingLibrary в исходнике, причём каноническим указателем для стабильных ссылок служит идентичность библиотеки без хоста (<Library>#/mappings/<entry>) — хост реестра в ссылке отклоняется, поэтому физическое расположение никогда не попадает в указатель.

C. Нативная поддержка IaC

Команда Ops, приносящая собственную инфраструктуру как код, хранит её в собственном каталоге Recipe — в каталоге модуля или шаблона, например ./src, указанном в source:, — или загружает её с помощью структурированного source: (модуль Terraform из его git-репозитория, с kind: git-repository), или пишет её как шаблонизированные тела в artifacts:. Слой сопоставления (valuesMapping: — встроенный, импорт файла или импорт из библиотеки) передаёт этому коду абстрактный контекст, а провайдер выдаёт результат в собственном формате цели; ни один язык конфигурации не преобразуется в другой:

  1. Terraform: модуль вендорится файл в файл, а написанное тело выдаётся точно в написанном виде, как нативный HCL (main.tf), так и Terraform JSON (.tf.json) — CLI terraform читает оба. Корневая конфигурация границы, aggrega.modules.tf, вызывает каталог каждого компонента как блок module, а вывод valuesMapping: модуля из источника становится аргументами этого блока. См. провайдер terraform.
  2. CloudFormation: шаблон из источника, YAML или JSON, и фрагменты ресурсов, которые пишет Recipe, нормализуются в развёрнутый JSON и сливаются в один шаблон стека на границу, причём вывод valuesMapping: заполняет параметры, объявленные шаблоном из источника. См. провайдер cloudformation.

Значение, которое существует только после применения инфраструктуры, остаётся указателем, который разрешает цель, — интерполяцией Terraform ${ ... }, Ref или Fn::GetAtt CloudFormation — и никогда не вычисляется во время сборки.

Пример A: удалённый чарт Helm (встроенное сопоставление и контракт locals)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

Пример B: локальный модуль Terraform (файловое сопоставление)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

Пример C: конкретный Component Recipe (привязывает инфраструктуру) Ops сопоставляет обобщённый интерфейс с физической реальностью. (Именно здесь привязываются сетевые детали уровня L4 — либо жёстко заданные, либо, как с портом прокси ниже, взятые из блока infra, который заполняет Release.)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Дисциплина именования облачных ресурсов.

Recipes, которые формируют имена облачных ресурсов — имена бакетов S3, идентификаторы баз данных RDS, имена ролей IAM, имена стеков CloudFormation и любые другие поля, значение которых занимает глобальное пространство имён у облачного провайдера, — должны включать {{ .metadata.release_name }} и/или {{ .context.instance_id }} в формируемое имя, чтобы избежать коллизий, когда один и тот же Recipe выполняется в нескольких Releases или экземплярах компонентов. Каноническим шаблоном служит bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" из примера B.

Дисциплина применяется везде, где имя ограничено единым глобальным пространством имён. Имена бакетов AWS S3 используют глобальное пространство имён для всех аккаунтов в регионе; два выпуска одного и того же Aggregate (prod-billing и staging-billing) не могут оба развернуть бакеты с именем customer-data — второе развёртывание завершится ошибкой во время выполнения из-за отказа на стороне AWS. Добавление release_name различает Release; добавление context.instance_id различает экземпляры компонентов; добавление обоих различает каждый компонент в каждом Release.

Что компилятор проверяет и чего не проверяет. Компилятор не проверяет выходные данные valuesMapping: на наличие полей с именами облачных ресурсов без этих интерполяций. Эту дисциплину соблюдают авторы Recipe (которые знают, какие поля именуют глобально уникальные ресурсы целевого провайдера) и рецензенты (которые замечают такие шаблоны при ревью PR). Плагин-линтер мог бы помечать Recipes, у которых выходные данные valuesMapping: ссылаются на поля с именами облачных ресурсов без интерполяции release_name / instance_id; сокет линтера поставляется и запускается через aggrega lint (см. plugins/plugin-contract.md, «Placement criterion: the linter socket vs the governance verdict roles»), и ни одно из правил линтера публикации этого не проверяет.

Эта дисциплина — один из нескольких общественных договоров, поддерживаемых соглашением, — дисциплина авторинга, которую авторы узнают из документации, а не из проверок компилятора. Полный список соглашений и архитектурное обоснование классификации каждого договора см. в vocabulary/social-contracts.md.

Шаблонизация поля source. Поле source сущности Recipe само является поверхностью шаблонизации. Обе формы source принимают шаблоны Go: универсальная строковая форма

source: "{{ optional .infra `module_path` \"./src\" }}"

и структурированная объектная форма (каждое строковое подполе вычисляется как шаблон; нестроковые подполя передаются без изменений). Что может читать шаблон источника, зависит от того, указывает ли источник на удалённый артефакт. Координата удалённого источника — version, chart, ref и module_subdir структурированного блока, указывающего на реестр, репозиторий чартов или git-репозиторий, — вычисляется, когда aggrega pull разрешает артефакт, чтобы закрепить его, и только относительно .values, .infra и .locals, со собственными вспомогательными функциями Aggrega (optional, capitalizedWords и index) и без функций Sprig. .context на этой поверхности недоступен, поэтому то, какой артефакт закрепляется для компонента, определяется переданными ему values и infra и никогда — именем его экземпляра. Вычисляемые там записи locals: — это те, которые читают эти поля, и те, которые в свою очередь читает такая запись: запись, которую не читает ни одно поле источника, не вычисляется при разрешении источника, поэтому local, нужный только для рендеринга, — вызывающий функцию Sprig или читающий .context.instance_id, — не влияет на закрепление и вычисляется при рендеринге узла. Если поле читает .locals способом, не называющим ни одной конкретной записи, например {{ index .locals "version" }}, вычисляются все записи. Источник, указывающий путь в рабочем пространстве, как в примере выше, для закрепления не разрешается: его шаблон вычисляется при рендеринге узла относительно того же самодостаточного контекста, что и locals сущности Recipe, — .context.instance_id, .values, .infra и .locals, весь разрешённый блок узла, — поэтому он допускает и отвергает те же корни ссылок, что и запись locals:, с одним отличием в его пользу: он может читать любую запись, объявленную в блоке, а не только записи выше него. Удалённая координата так же может читать любую запись, объявленную в блоке. .provides нет ни в одном из этих контекстов, и шаблон источника, обращающийся к provides собственного узла, останавливает сборку и называет проблемную ссылку. Это фиксированное свойство поверхности, а не пробел, ожидающий будущей работы: locals узла разрешаются раньше его provides, чтобы provides: мог читать .locals, а шаблон источника читает те же разрешённые locals вместо того, чтобы забегать вперёд к provides. Ссылки на .context.inject и .context.uses запрещены по тем же соображениям самодостаточности: URI источника должен разрешиться до того, как будет наполнен канал топологии, и до того, как что-либо ниже по потоку загрузит тело чарта, модуля или артефакта, на которое указывает URI. Полные правила доступности и обоснование запрещённых ссылок приведены в строке № 5 матрицы раскрытия шаблонов. Каноническое применение — переопределение infra.source_version, предоставляемое сущностью Component и передаваемое в поле версии источника, — см. entities/component, «Опора infra», — чтобы каталогу не приходилось заново публиковать Recipe при каждом совместимом повышении версии upstream.

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

ФормаПримерСтатус
Простой относительный путь в файловой системеsource: "./charts/postgres"available — каждый поставляемый провайдер (helm, helm-chart, compose, terraform, cloudformation) принимает строку с простым путём в файловой системе.
Простой абсолютный путь в файловой системеsource: "/abs/path/to/chart"accepted but blocked — схема его принимает, а каждая команда, читающая Recipe, его отклоняет: абсолютный путь называет место на машине, где он был написан, а не содержимое внутри собственного каталога Recipe, поэтому он не переносился бы вместе с Recipe. Переместите чарт в каталог Recipe и укажите его относительно этого каталога; см. Пути к содержимому остаются внутри собственного каталога Recipe.
Пустая строкаsource: ""accepted but blocked — схема принимает пустую строку, но каждая команда, загружающая сущность Recipe, отклоняет её при чтении сущности Recipe, потому что пустая строка не называет ни один из режимов. Отказ называет неоднозначность вместе с двумя выходами из неё: опустить поле для режима без source или указать реальный путь или URI для режима с source. aggrega validate <recipe-file> сообщает о ней для сущности Recipe, а aggrega pull, aggrega build и aggrega validate --release — для сущности Release, которая достигает этой сущности Recipe. См. errors/fatal-halts.md, «Recipe source: is an empty string (Recipe source: — пустая строка)».
Структурированный объект, у которого url: содержит транспортную схемуsource: { url: "oci://…/mariadb", version: "25.0.8" }available — встроенный распознаватель источников читает форму {kind, url, version, chart, ref, module_subdir} (схема в url: выбирает вид — oci:// → OCI-чарт, https://….tgz → архив чарта, корень репозитория https:// в паре с chart: → чарт из репозитория — либо вид задаётся через kind:), загружает и закрепляет артефакт при aggrega pull, а сборка извлекает его из кэша. Хранение копии чарта локально поддерживается как альтернатива и не обязательно. Схема допускает открытый структурированный объект. См. providers/helm.md «Набор ключей source:».
Структурированный объект, в котором url: указывает путь в файловой системеsource: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — url: без транспортной схемы указывает путь, поэтому ничего не загружается и не закрепляется; сборка читает содержимое с диска. Относительный url: привязывается к каталогу, содержащему объявляющий его recipe.yaml, а путь, выходящий за пределы этого каталога, — в том числе абсолютный, — отклоняется: так же трактуются оба варианта простого пути в строках выше, и форма записи на это не влияет. Откуда читается содержимое, определяет только url:; остальные поля выбирают, что было бы загружено, и по-прежнему доступны шаблонам Recipe как .source.*.
OCI URI (oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — целевая архитектура для распространения каталогов. Текущий трёхуровневый распознаватель (файлы, которые Release называет по пути, каталоги рабочего пространства, удалённый реестр OCI) описан в architecture/13-catalog-and-registry.md; распознаватель на уровне сущностей принимает OCI URI через этот каскад, но OCI-форма поля source: отдельного Recipe в провайдерах сейчас не подключена.
Другие схемы URL (https://, git+https:// и т. д.)(для иллюстрации)planned — описано как замысел в плане развития подключаемых источников в архитектуре; поддержки в провайдерах сейчас нет.

Как привязывается путь source:. Привязка применяется только к путям в файловой системе и применяется независимо от того, в какой из двух форм записан путь. Относительный путь привязывается к каталогу, содержащему объявляющий его recipe.yaml, а путь, выходящий за пределы этого каталога, — в том числе абсолютный, — отклоняется, как объясняется в разделе Пути к содержимому остаются внутри собственного каталога Recipe. Ссылка с транспортной схемой — oci://, https://, http://, git://, ssh://, git+ssh:// или любая ссылка, оканчивающаяся на .git, — указывает на то, что нужно загрузить, а не на путь, поэтому передаётся в точности так, как вы её написали, и никогда не присоединяется к каталогу.

В структурированной форме путём является поле url:, и оно читается так же: относительный url: привязывается к каталогу, содержащему recipe.yaml, выходящий за пределы этого каталога отклоняется, а содержащий транспортную схему загружается. Все прочие поля структурированного source: передаются без изменений, включая определяемые провайдером.

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

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

Этот перечень — канонический справочник о том, что авторы могут указать в source:; его метки — те, которые определяет 10-status.md.

Пути к содержимому остаются внутри собственного каталога Recipe

Содержимое Recipe находится в собственном каталоге Recipe, потому что каждый файл, который несёт его публикация, берётся оттуда. Каждый путь, который Recipe указывает для переносимого им содержимого, — его source:, будь то простой путь или url: структурированной формы, и каждый файл, который его записи valuesMapping:, workload: и artifacts: импортируют через $import:, — читается относительно каталога, содержащего recipe.yaml, и должен оставаться внутри него. Эти же пути определяют, что несёт публикация: названные ими файлы переносятся вместе с Recipe, а больше ничего из его каталога не переносится (см. aggrega push). Путь, выходящий за пределы каталога, указывает на файл, который не будет перенесён вместе с Recipe, поэтому этого файла не окажется у того, кто его использует, а закрепление, записанное для него, ручалось бы за байты, которые получить невозможно.

Выйти за пределы каталога можно двумя способами, и оба отклоняются:

  • путь, поднимающийся выше каталога, например ../shared/charts/app;
  • абсолютный путь, например /opt/charts/app, который указывает на место на машине, где он был написан.

Путь, который поднимается и возвращается обратно, — обычный путь внутри каталога: ./charts/../values.tmpl указывает на values.tmpl рядом с Recipe. Оценивается то, куда приводит путь, если отсчитывать его от каталога Recipe, не выходя за его пределы, — поэтому выход наружу, который на обратном пути снова называет этот каталог, например ../1.0.0/values.tmpl, записанный в каталоге 1.0.0, тоже отклоняется. Собственное имя каталога не переносится: опубликованный Recipe читается из каталога, имя которому даёт кеш потребителя, и там это имя ничего не находит.

Где отклоняется такой путь. Каждая команда, читающая Recipe, отклоняет такой путь при чтении, прежде чем что-либо будет загружено, отрисовано или опубликовано: aggrega validate — по каталогу или по собственному файлу Recipe, aggrega pull, aggrega build, aggrega pin и aggrega push. source:, записанный как шаблон, ничего не называет, пока сборка его не вычислит, поэтому шаблон, дающий путь за пределами каталога, отклоняется сборкой в момент появления значения. Остановка — A path names content outside the entity’s own directory (Путь указывает на содержимое за пределами собственного каталога сущности), и в ней указывается написанный вами путь.

Что делать вместо этого. Поместите файл в каталог Recipe или в каталог под ним и укажите его относительно Recipe: ./charts/app, ./extras/netpol.yaml. Чарт, используемый несколькими сущностями Recipes, копируется в каталог каждого Recipe, поскольку каждый Recipe публикуется отдельно; тело сопоставления, рабочей нагрузки или артефакта, общее для нескольких сущностей Recipes, следует поместить в MappingLibrary, WorkloadLibrary или ArtifactLibrary, на которую каждый Recipe ссылается по идентификатору.

Почему Release отличается. Release указывает на другие сущности — свой Aggregate, свой Manifest, Release, который он расширяет, — и никогда не публикуется, поэтому ничто из прочитанного им никуда не переносится. Эти ссылки и файл, который импортирует его parameters:, читаются так, как записаны, и именно это позволяет одному Aggregate использоваться вариантами Release в подкаталогах. См. entities/release.md.

То же ограничение действует для FeatureRecipe и для каждой схемы, которую импортирует Component или Feature.

Поле workload: — синтезируемый вид входных данных

Recipe.spec.workload: объявляет тело Workload, которое компилятор синтезирует в нативные ресурсы провайдера. Это один из трёх видов входных данных, которые может объявить Recipe, наряду с source: (рендеринг из источника) и artifacts: (вспомогательные манифесты). Для любого провайдера должен присутствовать хотя бы один из трёх; сервис, который сборка не предоставляет, объявляет workload: с form: reference.

Поле допускает три режима написания — встроенный блочный скаляр, файловый $import: или библиотечный $import:. Компилятор выбирает режим по форме содержимого поля; аннотация $mode: не нужна.

Режим 1: встроенный (строковый скаляр шаблона Go). Значение — блочный скаляр YAML, вывод которого разбирается как aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Поля Workload находятся в корне документа — обёртки spec: нет, — а containers: и ports: каждого контейнера являются отображениями с ключами-именами, а не последовательностями, причём авторский порядок сохраняется. Провайдер переводит эту форму в собственную нативную, поэтому запись отображения контейнеров появляется в выводе helm как элемент containers[], названный по её ключу; авторская форма — это отображение, а не отрендеренный список.

Режим 2: файловый $import:. Значение — отображение с единственным ключом $import:, указывающим на локальный файл шаблона Go:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

Разрешение путей такое же, как у valuesMapping:: относительный путь отсчитывается от каталога, содержащего объявляющий его recipe.yaml, а не от каталога, из которого запущена сборка, и должен оставаться внутри этого каталога. Импортированное тело — это шаблон Go, вычисляемый в контексте рендеринга сущности Recipe, точно так же, как встроенное тело.

Режим 3: библиотечный $import:. Значение — отображение с единственным ключом $import:, содержащим ссылку по идентичности с голым именем на запись WorkloadLibrary:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

Фрагмент #/workloads/ выбирает запись Workload, и именно он отличает эту ссылку от формы #/mappings/, используемой в valuesMapping:, — та адресует запись MappingLibrary и не называет тело Workload. Ссылка не содержит хоста реестра, разрешённая версия берётся из lock-файла каждой сущности Release, необязательный нижний порог минимальной версии :<version> можно указать как <Library>:<version>#/workloads/<Entry>, а запись, тело которой само является $import: в корне поля, разрешается рекурсивно. Импортированное тело — это шаблон Go, вычисляемый в контексте рендеринга использующей его сущности Recipe, поэтому .values, .infra и .features попадают в него точно так же, как во встроенное тело. Описание библиотечной сущности и полную грамматику ссылок см. в entities/workloadlibrary.

Целевой провайдер должен поддерживать синтез (каталог стандартной библиотеки по соглашению объявляет workloadSchema у таких провайдеров); выбор провайдера, который не может выполнять синтез, отклоняется при рендеринге узла с диагностикой возможностей провайдера — по возможностям провайдера, а не по наличию workloadSchema. Полную грамматику Workload, сквозные поля в форме K8s и поведение перевода для каждого провайдера см. в entities/workload.md. Общую модель трёх видов входных данных и сборщик, объединяющий синтез с выводом, отрендеренным из источника, и артефактами, см. в architecture/16-recipe-input-composition.md.

Передача собственных значений компонента в собственный образ разработчика. Согласно соглашению каталога стандартной библиотеки, от сущности Recipe, запускающей образ, который собирает разработчик, ожидается, что она будет передавать всё, что разрешили блоки inject: разработчика, из .context.inject; кроме того, она может передавать собственные значения компонента под выбранными ею именами. Там, где сущность Component объявляет spec.inject, имена выбирает собственный блок разработчика, а .context.self_inject сообщает сущности Recipe то единственное собственное значение, которое читает шаблон каждой записи, — values.<key> для записи, читающей ровно одно собственное значение и ничего больше. Соглашение каталога стандартной библиотеки состоит в том, чтобы рассматривать имена, которые Recipe даёт этим значениям, как значения по умолчанию, а не как контракт, который обязан читать код разработчика, и передавать значение под его именем по умолчанию, только если ни одна запись не отображается на него; корпоративный каталог может поступить иначе. Контракт контекста шаблонов приводит точные правила этой карты и полный пример шаблона.

Поле artifacts: — вспомогательные манифесты

Recipe.spec.artifacts: — это отображение «имя записи → описание тела артефакта», записи которого выводят дополнительные файлы манифестов рядом с основным выводом сущности Recipe, полученным из источника или синтезированным. Это один из трёх видов входных данных (из источника / синтезированные / артефакты): сущность Recipe может объявить только artifacts: или вместе с workload: и/или source:.

Значение каждой записи использует один из трёх режимов, выбираемых по форме содержимого, аналогично workload:: встроенное содержимое, файловый $import: или библиотечный $import:. Компилятор выбирает режим по форме содержимого значения; аннотация $mode: не нужна. Во всех трёх режимах ключ отображения называет то, что выводит запись: для двух однофайловых режимов это имя выходного файла, а для режима пакета — каталог, в который вкладываются файлы пакета. Поскольку ключ называет вывод, он ограничен тем, чем может быть одно имя файла: начальная буква или цифра, затем буквы, цифры, точки, дефисы и подчёркивания. Точки сохраняют расширение, которое ключ по соглашению несёт, — main.tf, template.yaml, serviceaccount.yaml, — а алфавит не допускает /, из-за которого ключ называл бы путь, а не файл, и начальную ., так что ключ никогда не может быть сегментом родительского каталога. Ключ вне этого алфавита не проходит проверку оболочки при загрузке рабочего пространства, при aggrega validate и в диагностике редактора.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

Режим 1: встроенный (строковый скаляр шаблона Go). Значение — блочный скаляр, а ключ отображения — имя выходного файла, используемое как написано: первая запись выше выводит extra-configmap.yaml.

Режим 2: файловый $import:. Значение — отображение с единственным ключом $import:, указывающим на локальный файл шаблона Go, и ключ отображения — имя выходного файла, точно как в режиме 1. Импортируемый файл предоставляет содержимое, но не имя. Вторая запись выше имеет ключ network-policy.yaml и выводит network-policy.yaml, хотя импортируемый ею файл называется network-policy.tmpl. Поэтому автор, которому нужно определённое имя выходного файла, пишет его как ключ, а две записи, импортирующие разные файлы с совпадающим именем — ./extras/shared.yaml и ./overrides/shared.yaml, — дают два разных вывода. Разрешение путей совпадает с valuesMapping: и workload:: относительный путь привязывается к каталогу, содержащему объявляющий его recipe.yaml, а не к каталогу, из которого запущена сборка, и должен оставаться внутри этого каталога.

Режим 3: библиотечный $import:. Значение — отображение с единственным ключом $import:, содержащим ссылку идентичности по простому имени на пакет ArtifactLibrary, <Library>#/artifacts/<name>. Пакет — это набор файлов, импортируемых как единое целое, поэтому одна запись разворачивается в один вывод на каждый файл пакета, каждый вложен под ключ отображения как <key>/<filename>: ключ называет место использования и является каталогом, в который попадают эти файлы, а не именем какого-либо из них. Третья запись выше имеет ключ operator-support; если PlatformArtifacts#/artifacts/OperatorSupport объявляет crd.yaml и rbac.yaml, эта единственная запись выводит operator-support/crd.yaml и operator-support/rbac.yaml. Ссылка не содержит хоста реестра — форма с хостом oci://… отклоняется, — разрешённая версия берётся из lock-файла каждой сущности Release, а необязательная нижняя граница минимальной версии :<version> может быть указана как <Library>:<version>#/artifacts/<name>. Описание библиотечной сущности и полную грамматику ссылок см. в entities/artifactlibrary.

Файловый $import: закрепляется рядом с сущностью Recipe. aggrega pin записывает дайджест байтов каждого импортированного файла в entity.lock в каталоге сущности Recipe с ключом по ключу отображения записи, а aggrega build снова вычисляет дайджест файла и останавливается с [CATALOG_ERROR E0026], если он больше не совпадает, — или раньше с E0130, если lock-файл сущности Release, записанный до правки, фиксирует сущность Recipe по её содержимому, — так что файл, отредактированный после закрепления, никогда не рендерится без проверки. Если изменение было намеренным, выполните aggrega pin для сущности Recipe, чтобы записать новый дайджест; иначе восстановите файл. Встроенная запись является частью файла сущности Recipe, а библиотечная запись закрепляется версией библиотеки, записанной в lock-файле, поэтому ни одна из них не имеет собственного закрепления. Файл описан в aggrega pull.

Шаблон каждой записи артефакта вычисляется в том же контексте шаблона, что и valuesMapping:, каким бы режимом ни было предоставлено её тело. Два вывода с одинаковым именем файла останавливают сборку при рендеринге узла. Две записи одного отображения artifacts: не могут назвать один вывод: ключ отображения уникален в пределах документа и задаёт одно имя файла, поэтому вывод однофайловой записи — её ключ, а файлы записи пакета лежат в каталоге, названном её ключом; первый сегмент каждого пути, выводимого записью, — породивший его ключ, так что разные ключи остаются разными именами вывода, как бы ни назывались импортированные файлы. Остановка охватывает одно имя файла, предоставленное двумя разными видами входных данных — например, шаблоном чарта и записью артефакта, оба создающие servicemonitor.yaml, — и сообщается для этой сущности Recipe с диагностикой, называющей каждый источник.

Сценарии использования. artifacts: — место для вспомогательных ресурсов, которые не создаёт основной чарт или модуль: NetworkPolicy рядом с рабочей нагрузкой, HPA в паре с Deployment, сопутствующий ConfigMap с ключом по instance_id. Сквозные вспомогательные ресурсы, применяемые ко многим компонентам (например, sidecar резервного копирования, подключаемый к каждому хранилищу данных), относятся к генерации ресурсов FeatureRecipe, а не к artifacts: отдельной сущности Recipe; описание поверхности расширения FeatureRecipe см. в entities/featurerecipe.md.

Блок boundary: — файлы для общего вывода границы

Большинству сущностей Recipes он никогда не нужен. Всё остальное, что пишет Recipe, принадлежит его собственному компоненту: провайдер размещает это под собственной позицией этого компонента в выводе границы. Некоторые файлы, напротив, принадлежат границе целиком — это файл, который целевая система читает один раз для всего, что развёртывает граница. Типичный случай — конфигурация провайдера Terraform: документация Terraform рекомендует не размещать блоки provider в модуле, который вызывает другая конфигурация, а модуль, содержащий собственный такой блок, нельзя вызвать с depends_on, count или for_each. spec.boundary.artifacts — место, где Recipe пишет такой файл.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

Блок — это artifacts: на второй области видимости. Его единственный член — artifacts, и он имеет в точности ту же форму, что и собственное поле artifacts: сущности Recipe: те же три режима — встроенное содержимое, файловый $import: и библиотечный $import:, файлы которого вкладываются под ключ записи как <key>/<filename>, — то же правило соответствия ключа имени файла и тот же алфавит для ключа, а также тот же контекст шаблона, так что запись читает .values, .infra, .locals и остальное в точности так же, как запись artifacts:. Блоку нужна хотя бы одна запись, а любой другой член под boundary: отклоняется при чтении сущности Recipe. У сущности FeatureRecipe такого блока нет.

Куда записывается файл. Один раз, в каталог, содержащий собранный вывод границы, рядом с файлами, которые туда записывает собственная сборка провайдера, — для terraform рядом с корневой конфигурацией aggrega.modules.tf, а не внутри модуля компонента. Провайдеру ни один из этих файлов не передаётся: компилятор вычисляет и записывает их сам и ничего не вписывает в файл, чтобы указать, от какого компонента он получен, поскольку файл принадлежит каждому компоненту, который его объявил. Запись, шаблон которой при рендеринге даёт пустой результат, файл не записывает.

Как сводятся несколько участников. Каждая запись вычисляется для каждого компонента, который Recipe рендерит в границе, и файлы, объявленные всеми участниками границы, объединяются по имени. Одно имя, вычисленное в одинаковые байты — двумя компонентами, привязанными к одному Recipe, или двумя Recipes, одинаково настраивающими один провайдер, — это один файл. Одно имя, вычисленное в разные байты, останавливает сборку с указанием файла и всех участников, поскольку ни один файл не совпадает с тем, что написали все они; то же происходит с именем, которое записывает собственная сборка провайдера, например aggrega.modules.tf. Оба случая — это коллизия собранного вывода. Два Recipes, настраивающих один провайдер под двумя разными именами файлов, не объединяются — записывается каждый файл, — и о дублирующейся конфигурации тогда сообщает целевая система, поэтому Recipes, которые должны совместно использовать конфигурацию провайдера, используют одно имя файла, по соглашению названное по провайдеру, который он настраивает.

Какие провайдеры его принимают. Имеет ли смысл файл, размещённый рядом с собранным выводом границы, — это свойство целевой системы провайдера, поэтому оно входит в собственное объявление провайдера. Recipe, объявляющий этот блок, чей провайдер его не принимает, отклоняется до начала рендеринга, во что бы ни рендерились его записи; см. The provider does not support boundary artifacts (Провайдер не поддерживает артефакты границы). В таблице возможностей указано, что заявляет каждый провайдер.

Providerboundary.artifacts:
terraformПринимается. Каждый файл записывается рядом с корневой конфигурацией границы, которую Terraform читает вместе со всеми остальными файлами конфигурации в этом каталоге.
helm, compose, helm-chart, cloudformationОтклоняется до начала рендеринга.

Файловый $import: здесь закрепляется так же, как файл, импортируемый записью artifacts:. Блокировка сущности записывает его дайджест в тот же список artifactDigests, но под boundary/<key>, а не под одним ключом, поэтому записи каждого из блоков, заданные под одним и тем же ключом, закрепляются раздельно. Шаг закрепления записывает его, pull без закрепления останавливается там, где закрепление отсутствует или больше не совпадает, а сборка отклоняет файл, изменённый после закрепления, в точности так же, как отклоняет файл записи artifacts:.

Поле outputLabels: — объявленные автором метки на сгенерированном выводе

Recipe.spec.outputLabels: — это отображение «ключ метки → значение», которое provider проставляет на каждый объект, порождаемый сгенерированным выводом сущности Recipe. Это подходящее место для признака реализации — свойства того, как конкретная сущность Recipe реализует компонент, в отличие от того, чем компонент является. Возьмём хранилище, с которым работает реализация, — ниже оно записано под иллюстративным ключом example.io/storage-backing: Recipe для Helm, монтирующий PersistentVolumeClaim, и Recipe для Compose, монтирующий именованный том, реализуют один и тот же компонент разными механизмами, поэтому они несут разные outputLabels, и последующие инструменты (распределение затрат, политики, инвентаризация) могут различить их по сгенерированным ресурсам. Ключ иллюстративный: example.io/ — пример пространства имён, а каталог сам выбирает ключи, которые читают его инструменты.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

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

Собственная метка идентичности компонента здесь не пишется — это соглашение каталога, а не правило, которое обеспечивает компилятор. Ключи, описывающие, чем компонент является, а не то, как его реализует одна сущность Recipe, — его когнитивная категория, операционный тип, метки возможностей по ролям, кто эксплуатирует базовый ресурс, класс лицензирования того, что он оборачивает, — объявляются в metadata.labels сущности Component; оси описаны в разделе «The Semantic Label Taxonomy» страницы entities/component. Recipe переносит такой ключ на свой сгенерированный вывод, называя его в outputComponentLabels: ниже, а не записывая здесь ключ и значение. Причина в том, что литеральная запись — это вторая копия значения, которое у компонента уже есть, а вторая копия может разойтись с первой: автор сущности Recipe может указать одну позицию на узле, чья сущность Component объявляет другую, и сообщить последующему читателю то, чего граф не говорит. Перенесённая запись копирует по ссылке, поэтому второй копии, которая могла бы разойтись, нет. Ядро принимает любой вариант, кроме нарушающих правило зарезервированных пространств имён ниже; соглашение поддерживают авторы каталогов.

Зарезервированные пространства имён. Пространства имён aggrega.ai/ и app.kubernetes.io/ зарезервированы для собственных меток происхождения платформы. Recipe, объявляющий ключ outputLabels с любым из этих префиксов, отклоняется при загрузке с понятной ошибкой каталога, называющей нарушающий ключ. Все остальные ключи принимаются. В остальном ядро не проверяет ключ или значение: ключ или значение, недопустимые для поверхности меток целевого движка, — ответственность автора, и их отклоняет последующая среда выполнения; помимо правила зарезервированных пространств имён компилятор не вмешивается.

Отображение по провайдерам. Каждый provider переносит метки на свою поверхность вывода:

  • helm, синтез рабочей нагрузки — и в metadata.labels объекта, и в metadata.labels шаблона пода, то есть там же, куда синтез помещает метки происхождения.
  • helm, source-render и artifacts — в metadata.labels объекта.
  • compose — в отображении labels: каждого сервиса.
  • terraform — как теги отдельных ресурсов в структурно адресуемых телах артефактов .tf.json, по возможности: блок ресурса, уже объявляющий отображение tags (AWS/azurerm) или labels (Google), получает выходные метки в нём, объявленный автором ключ никогда не перезаписывается, а ресурс без такого атрибута остаётся нетронутым (атрибут никогда не создаётся). Тела на нативном HCL (main.tf, *.tf) и вендорные модули выводятся дословно и не несут внедрённых тегов. Метки происхождения Terraform по-прежнему передаются в сопутствующем файле комментариев, отдельно от пути тегов.

Выходные метки — только метки; отдельной поверхности выходных аннотаций нет. outputLabels объявляет автор сущности Recipe (слой реализации, создаваемый эксплуатацией), а не Aggregate: они описывают реализацию, а не идентичность в абстрактном графе разработчика.

Поле outputComponentLabels: — перенос собственных меток компонента

Recipe.spec.outputComponentLabels: — это список ключей меток, а не пар «ключ — значение». Для каждого указанного ключа провайдер проставляет этот ключ на отрисованный вывод со значением, которое этот ключ имеет у отрисовываемого экземпляра компонента. Если outputLabels задаёт значение, то outputComponentLabels указывает, откуда это значение следует прочитать.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

Если у сущности Component в metadata.labels объявлено component.aggrega.ai/hosting: managed, то каждый объект, который этот Recipe отрисовывает для этого компонента, несёт component.aggrega.ai/hosting: managed. Привяжите тот же Recipe к компоненту, объявляющему self-hosted, и объекты этого компонента будут нести self-hosted — один Recipe, один указанный ключ, своё значение для каждого компонента.

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

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

Зарезервированные пространства имён. Пространства имён aggrega.ai/ и app.kubernetes.io/ зарезервированы для встроенных в платформу меток происхождения, и перенесённый ключ с любым из этих префиксов отклоняется при загрузке с ошибкой каталога, в которой названы ключ и поле, где он встречается. Проверяется именно сам префикс: ключ вроде component.aggrega.ai/hosting находится в собственном пространстве имён, а не под зарезервированным корнем, и его можно переносить.

Ключ принадлежит только одному из блоков. Объявление одного и того же ключа и в outputLabels, и в outputComponentLabels отклоняется при загрузке, так что у каждого проставляемого ключа один источник — либо литеральное значение, записанное в Recipe, либо собственная метка компонента, но не оба сразу.

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

Компоненты с единственным вариантом — соглашение, а не правило. Перенос передаёт любое значение, объявленное компонентом, и компилятор это значение не интерпретирует. Поэтому компонент, метка идентичности которого содержит заполнитель, означающий «бывает по-разному», переносит этот заполнитель на каждый объект, отрисованный для него. Если у компонента действительно больше одного варианта, соглашение каталога стандартной библиотеки состоит в том, чтобы каждый Recipe указывал вариант своей собственной реализации через ключ outputLabels, которым владеет этот Recipe, а не через ключ идентичности компонента, который то же соглашение направляет через outputComponentLabels:, — или не проставлял ничего. Эти два ключа отвечают на разные вопросы и не заменяют друг друга: ключ идентичности говорит, чем является компонент во всех реализациях, а ключ, принадлежащий Recipe, — что делает именно эта реализация. Это соглашение каталога, которое соблюдают его авторы, а не ограничение, навязываемое компилятором.

Блок locals:

Recipe.spec.locals: — это Private Ops State (частное операционное состояние): словарь именованных строк-шаблонов Go, отрисованный результат которых предоставляет словарь .locals.* последующим шаблонам сущности Recipe. Это рабочее пространство, в котором физические реалии (целевые контейнеры, пути JSON, производные имена хостов) вычисляются один раз и повторно используются в provides:, source:, valuesMapping:, workload:, artifacts:, assertions: и полезных нагрузках pipeline[].with без повторного вычисления. Отрисованный результат каждой записи сохраняется без начальных и конечных пробельных символов.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: никогда не предоставляется вызывающим сторонам: нижестоящие компоненты, использующие эту сущность Recipe через uses:, видят только provides:. Собственные шаблоны provides:, source:, valuesMapping:, workload:, artifacts:, assertions: и pipeline[].with сущности Recipe видят разрешённый словарь .locals.*. Значения отдельных ключей могут быть простыми строками или шаблонами Go; компилятор разрешает весь блок в преамбуле locals, до provides: этого узла, поэтому каждый последующий шаблон получает стабильные разрешённые значения.

Каждая запись вычисляется в самодостаточном локальном для узла контексте: .context.instance_id, .values, .infra и уже разрешённые записи этого же блока. Локальная запись не может читать .provides: этой опоры нет на данной поверхности, и запись, обращающаяся к ней, вызывает остановку. Не может она читать и .context.rendered_name — имя, которое провайдер, например helm, даёт ресурсам, отрисовываемым для узла. Поэтому локальная запись, именующая один из таких ресурсов, содержит только часть после этого имени, как secret_target_db_password выше, а шаблон, записывающий полное имя, соединяет обе части.

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

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

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

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

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

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

Проверка учитывает псевдонимы блока. Ключ, полученный через точку, которую переопределяет тело with .locals, или через переменную, привязанную к .locals, проверяется точно так же, как прямое написание: {{ with .locals }}{{ .nope }}{{ end }} и {{ $l := .locals }}{{ $l.nope }} оба вызывают остановку с указанием .locals.nope, как и {{ .locals.nope }}; так же ведут себя {{ (.locals).nope }} и {{ ($.locals).nope }}, поскольку скобки дают сам блок и ничего больше. Одно написание обходит проверку: ключ, полученный через вызов, результат которого текст шаблона не может назвать, — {{ index .locals "nope" }} или {{ (default dict .locals).nope }}, — поскольку то, что возвращает такой вызов, определяется при выполнении шаблона, а не написанным текстом. Отсутствующий ключ, читаемый как поле из результата такого вызова, не вызывает остановку и отрисовывает буквальный текст <no value>, а не пустоту. Отсутствующий ключ, полученный через index, вызывает остановку с указанием ключа, поскольку index останавливает сборку на любой поверхности шаблонов, когда читаемый словарь не содержит запрошенного ключа, — это другое сообщение, чем у данной проверки, описанное в errors/fatal-halts.md в разделе «A template indexes a map with a key the map does not hold (Шаблон индексирует словарь ключом, которого нет в словаре)». Поэтому index остаётся способом получить ключ, имя которого само вычисляется, например {{ index .locals (printf "secret_target_%s" .values.slot) }}, и вычисленное имя, не объявленное блоком, по-прежнему сообщается по его ключу.

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

Об аналоге для публичного API см. описание блока provides: ниже. Поверхность FeatureRecipe следует тем же правилам — см. entities/featurerecipe.md, раздел «Блок locals:».

Блок provides:

Recipe.spec.provides: — это публичный API для разработчиков: отображение «имя → строка Go-шаблона», объявляющее значения, которые этот Recipe передаёт в каналы .context.inject и .context.uses нижестоящих вызывающих сторон. Компилятор вычисляет шаблоны provides: на этапе вычисления provides (самодостаточно, в любом порядке); ключи inject вызывающих сторон разрешаются по этим значениям на этапе гидратации inject.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

Шаблон каждой записи вычисляется на самодостаточной поверхности вычисления provides: .context.instance_id, .context.rendered_name (если провайдер узла его сообщает), .values, .infra, разрешённые .locals узла и статический текст. Пространства имён, в которое помещён узел, на ней нет, поэтому опубликованный хост его не содержит: потребитель в другом пространстве имён уточняет его на своей стороне. .locals на ней есть, поскольку locals узла разрешаются в преамбуле того же этапа, до его provides; шаблон provides, ссылающийся на ключ, который блок locals не объявляет, вызывает остановку. Разделение вычисления provides и гидратации inject имеет принципиальное значение: provides: сущности Recipe не может ссылаться на состояние какой-либо вызывающей стороны, поскольку вызывающие стороны ещё не разрешены, когда выполняется вычисление provides, — provides: самодостаточен согласно архитектурному инварианту. Затем вызывающие стороны читают эти значения через .context.uses.<alias>.provides.<provided-name> в своих шаблонах: предоставленные имена вложены в provides на ребре, рядом с другими полями ребра. Вызывающая сторона, объявляющая на ребре список разрешений inject:, получает те же значения через свой канал .context.inject.

Ключи provides: входят в контрактную поверхность сущности Recipe. Переименование или удаление ключа — это критическое изменение для каждой вызывающей стороны, полагающейся на старое имя; версия интерфейса implements: должна отражать эволюцию контракта. Семантику каскадного разрешения, контракт канала inject и разобранные примеры маршрутизации между пространствами имён и регионами см. в architecture/06-data-taxonomy-and-composition.md §3 и templates/expansion-matrix.md.

Чтение опубликованных значений вложения

Сущность Recipe читает Features, прикреплённые к её компоненту, в .features.<instance-name>, а Features учётных данных — в .features.<slot>. И те и другие имеют одинаковую форму вложения — .type, .values, .infra, .provides, — поэтому вложение читается одинаково, какая бы карта его ни содержала; различаются они тем, что вложение производит.

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

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

Чтение опубликованного значения вместо его повторного вычисления из тех же входных данных values/infra — это разница между одним определением имени и двумя, которые могут разойтись. Полная форма с описанием каждого поля, включая правила доступности, приведена в templates/template-context-contract.md.

Вложение, записанное в одном из подключений компонента, — учётные данные, которые компонент предъявляет одной цели, — читается в той же форме внутри этого подключения, в .context.uses.<alias>.features.<slot>, и никогда не входит в .features. Сущность Recipe, обращающаяся к нескольким целям, читает учётные данные каждой цели под псевдонимом этой цели, а цикл по .features, отбирающий вложения по типу, встречает только собственные вложения компонента:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

Форма и порядок, в котором шаблон перебирает подключения, описаны в разделе Вложения подключения.

Поле pipeline:

Recipe.spec.pipeline: — это последовательный массив шагов конвейера Wasm, которые выполняются после рендеринга над набором отрендеренных документов, и каждый возвращает патчи RFC 6902 и побочные эффекты. Каждая запись объявляет id (идентификатор шага: буквы, цифры и подчёркивания), plugin (сущность Plugin, которую выполняет шаг, ограниченная её типом плагина, — pipeline-step/<name>, при необходимости с версией; голая ссылка на .wasm или артефакт отклоняется), function (вызываемый экспорт плагина), необязательное тело Go-шаблона with:, задающее полезную нагрузку плагина, и необязательный Go-шаблон when:, который определяет, выполняется ли шаг: ложный результат пропускает шаг как сквозной, оставляя набор документов без изменений. Условие when:, его независимость от optional: и его правило истинности подробно описаны в entities/featurerecipe.md, в разделе «Условные шаги — when:»:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

Компилятор выполняет шаги pipeline: базовой сущности Recipe в объявленном порядке так же, как выполняет pipeline: сущности FeatureRecipe: он вызывает указанный в каждом шаге плагин Wasm над отрендеренным выводом, применяет возвращённые операции JSON Patch к адресуемым документам и порождает побочные эффекты шага. Поле pipeline: сущности FeatureRecipe имеет ту же форму схемы и то же выполнение — см. entities/featurerecipe.md, раздел «Authoring Contract», и Состояние языка, где указано состояние выполнения каждой поверхности.

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

Блок assertions:

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

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

Приведённое выше правило относится только к чарту Bitnami 20.x; оно не применяется, если привязан другой Recipe для MariaDB. Правила уровня Component из контракта по-прежнему применяются наряду с ним и вычисляются на более ранней фазе конвейера.

Проверки Recipe вычисляются после привязки Recipe и до рендеринга, когда для каждого узла уже разрешены locals и provides. Контекст шаблона включает .provides, .locals и .recipe.source сущности Recipe в дополнение к полям экземпляра сущности (.values, .infra, .uses, .features). .uses и .features здесь имеют более узкую форму, принятую для проверок, а не форму шаблона Recipe: запись подключения содержит его цель и псевдоним, labels цели, собственные values подключения и вложения, записанные в нём в features, но ничего из того, что публикует цель; а запись вложения — собственного вложения компонента или вложения подключения — содержит его type, resolved_version и values, но не содержит ни его infra, ни его provides: на момент выполнения проверки FeatureRecipe вложения ещё не разрешил свои provides. Поэтому обращение к .features.<name>.provides останавливает сборку, а чтение с учётом наличия возвращает своё значение по умолчанию. Полную грамматику написания, разделение ответственности между правилами уровня контракта и уровня реализации, а также разобранные примеры см. в templates/assertions-block.md.

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

Большинству сущностей Recipes это никогда не понадобится. Поле предназначено для источника, который вы берёте как есть — чаще всего это chart, загруженный из реестра, — и который рендерит документ, который ваш Release не должен поставлять: например, Secret, который chart генерирует заново при каждом рендеринге, из-за чего две сборки различаются, а после применения он перезаписывает Secret, предоставленный оператором. Загруженный chart не редактируют, и никакое правило игнорирования до него не дотягивается, поэтому omits: — это способ, которым Recipe исключает такой документ из сборки. Загруженный compose-файл — тот же случай: он может содержать service, volume или config, которых в Release быть не должно, а оверлей valuesMapping: может изменить такой элемент, но не удалить его. То же относится к загруженному шаблону CloudFormation, который может объявлять ресурс, который Release не должен создавать: valuesMapping: может заполнить объявленные в нём параметры, но никогда не удалит один из его ресурсов.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

Что охватывает поле. Только то, что рендерит source:. Поле workload: и записи artifacts: никогда не фильтруются: их вы пишете в Recipe сами, поэтому документ, который вам там не нужен, достаточно просто не писать. Ключ требует наличия source:; документ, нарушающий это правило, отклоняется при чтении с указанием правила.

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

  • kind — вид того, что рендерит источник: для chart — kind отрендеренного документа, например Secret, ConfigMap, Deployment; для compose-файла — service, volume или config; для шаблона CloudFormation — Type ресурса, например AWS::S3::Bucket. Это поле не связано с kind: структурированного source:, который указывает, как загружается источник.
  • name — его имя: metadata.name документа; ключ единицы compose в services:, volumes: или configs:; логический ID ресурса CloudFormation, то есть его ключ в Resources.
  • namespace (необязательно) — пространство имён, в котором находится документ, для провайдера, вывод которого имеет пространства имён. Без него запись указывает kind и имя в любом пространстве имён; namespace, который рендерится в пустое значение, считается отсутствующим.
  • when (необязательно) — применяется ли запись к данной сборке. Оно вычисляется первым и интерпретируется по тому же правилу, что и when: шага конвейера: ложный результат отбрасывает запись, так что её остальные поля не вычисляются и она не передаётся провайдеру и не проверяется, а отсутствующее или пустое when: сохраняет её.

kind и name обязательны, а запись с любым другим полем отклоняется при чтении Recipe.

Каждое значение — шаблон, вычисляемый в том же контексте, что и valuesMapping:. Этот контекст содержит .context.rendered_name — имя, которое провайдер даёт ресурсам узла и по которому chart обычно их называет, поэтому запись может указать документ точно так же, как его назовёт chart. Шаблон, который не удаётся отрендерить, останавливает сборку так же, как ошибочный шаблон valuesMapping:.

Каждая применяемая запись должна что-то исключить. Провайдер сообщает, сколько единиц исключила каждая запись, и запись, не исключившая ничего, останавливает сборку с указанием этой записи; см. An omits entry left out nothing the source rendered (Запись omits не исключила ничего из отрендеренного источником). Обычная причина — обновление источника, которое переименовывает или удаляет документ, и именно эта остановка не даёт переименованному документу незаметно попасть в ваш вывод. Чтобы исключать документ лишь иногда, укажите это через when:, а не полагайтесь на отсутствие документа.

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

Release влияет на ключ через infra и parameters. Ключ принадлежит Recipe, поэтому Release не может его записать. Но он всё же может определять, что делает запись: шаблоны записи читают infra, которое заполняет Release, а передаваемые им parameters попадают в .values сущности Recipe везде, где Aggregate их туда направляет. Таким образом, Release включает или выключает запись с помощью when:, как это делает вторая запись выше, или определяет, что она указывает.

За то, что вы исключаете, отвечаете вы. Ничто в сборке не знает, для чего нужен документ. Исключение документа, от которого остальная часть chart зависит во время выполнения, — Secret, который монтирует Deployment, или ServiceAccount, от имени которого работает pod, — даёт вывод, который чисто собирается, а затем отказывает при применении, если только этот документ не предоставляет что-то другое, применяемое рядом. Для compose-файла и шаблона CloudFormation сборка выполняет проверку, поскольку каждый из них явно указывает свои ссылки: если оставшееся по-прежнему ссылается на исключённую единицу — service на исключённый service, ресурс или output на исключённый ресурс, — сборка останавливается, как описано в таблице ниже.

Какие провайдеры поддерживают поле. Исключить документ может только провайдер, поскольку только провайдер знает, что рендерит его источник, поэтому поддержка ключа — часть собственного объявления провайдера. Recipe, объявляющий omits:, провайдер которого его не поддерживает, отклоняется до какого-либо рендеринга, во что бы ни рендерились when: его записей; см. The provider does not support omits (Провайдер не поддерживает omits).

Provideromits:
helmПоддерживается. Запись указывает документ, который рендерит chart, — из шаблона или из его каталога crds/ — по собственным kind, metadata.name документа и, если запись его указывает, по пространству имён, в котором находится документ. См. helm → Sourced mode.
composeПоддерживается. Запись указывает service, volume или config загруженного compose-файла по его ключу в services:, volumes: или configs:, сопоставляемому после слияния valuesMapping: с файлом, и не указывает пространства имён: запись с другим kind или с пространством имён останавливает сборку при рендеринге компонента. Файл, в котором оставшееся по-прежнему ссылается на исключённую единицу — через depends_on, links, volumes_from, сетевой режим или режим пространства имён service:, extends, контекст сборки или запись volumes: или configs:, — останавливает сборку с указанием каждой ссылки. См. compose → Sourced mode.
cloudformationПоддерживается. Запись указывает ресурс загруженного шаблона по его Type и логическому ID во всех шаблонах источника-каталога и не указывает пространства имён: запись, содержащая его, останавливает сборку при рендеринге компонента. Шаблон, в котором оставшееся по-прежнему ссылается на исключённый ресурс — через Ref, Fn::GetAtt, DependsOn или переменную Fn::Sub, — останавливает сборку с указанием каждой ссылки. См. cloudformation → Исключение ресурсов из загруженного шаблона.
helm-chart, terraformОтклоняется: провайдер передаёт свой источник на рендеринг при развёртывании, поэтому во время сборки нет документа, который можно было бы исключить. Для локального chart или модуля вместо этого файл можно исключить строкой в .aggregaignore рядом с Recipe.

Тот же ключ задаётся в FeatureRecipe; см. entities/featurerecipe.md.

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