Схема Aggrega Infrastructure Base (FeatureRecipe)
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
Определения, создаваемые Ops, которые сопоставляют абстрактную сущность Feature из каталога с конкретной версионированной реализацией для одной возможности провайдера. Строго 1:1 с физическим провайдером и функцией каталога.
Описание создания сущностей FeatureRecipe см. в справочнике по созданию сущностей FeatureRecipe; на этой странице описана структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “FeatureRecipe” | да | Константа: "FeatureRecipe" |
metadata | object | да | |
spec | object | да | Привязка к возможности провайдера, сопоставление, конвейер и сопоставление внедрения для сущности FeatureRecipe. Содержит те же три вида входных данных, что и Recipe (sourced, synthesized, artifacts), а также injectMapping, доступный только в FeatureRecipe; FeatureRecipe, выполняющая только связывание и объявляющая лишь capability и implements, допустима и ничего не рендерит. |
Дополнительные свойства не допускаются.
featurerecipe.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
version | string | да | Версия сущности FeatureRecipe по строгому семантическому версионированию (например, 1.2.5). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | нет | Что представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что нужно читателю, чтобы выбрать её и правильно использовать: чего она ожидает от сущности Release, которая её развёртывает, и всё неожиданное в её поведении. Обычно достаточно короткого абзаца. |
maintainers | object[] | нет | Список сопровождающих, которым принадлежит эта сущность. |
license | string | нет | Идентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла. |
repository | string | нет | URL Git-репозитория, в котором находятся исходные файлы. |
home | string | нет | URL домашней страницы, вики или документации этой сущности. |
keywords | string[] | нет | Список описательных ключевых слов для удобства поиска в интерфейсе. |
Дополнительные свойства не допускаются.
featurerecipe.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
featurerecipe.spec
Привязка к возможности провайдера, сопоставление, конвейер и сопоставление внедрения для сущности FeatureRecipe. Содержит те же три вида входных данных, что и Recipe (sourced, synthesized, artifacts), а также injectMapping, доступный только в FeatureRecipe; FeatureRecipe, выполняющая только связывание и объявляющая лишь capability и implements, допустима и ничего не рендерит.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
capability | string | да | Явная возможность провайдера, к которой привязан этот рецепт (например, ‘helm’, ‘terraform’, ‘compose’), — вид провайдера, который его рендерит. |
implements | string | да | Объявляет, какой тип Feature из каталога этот рецепт способен реализовать (включая Features учётных данных с меткой feature.aggrega.ai/kind: secret; точная версия, диапазон, совместимый по мажорной версии ’^’, или без версии). Компилятор использует это для проверки сопоставлений в Manifest и для предложения кандидатов в диагностике и автодополнении в редакторе; сборку это никогда не разрешает. Сопоставление в Manifest — явный выбор реализации пользователем, зафиксированный в lock-файле сущности Release. |
locals | map of string | нет | Приватное состояние Ops. Внутренние результаты вычислений, доступные только в шаблонах этой FeatureRecipe как ‘.locals.*’. Каждая запись сама является шаблоном Go, вычисляемым в самодостаточном контексте: ‘.context.instance_id’ (КОМПОНЕНТ-ХОСТ, для которого разрешается это присоединение, — именно его обозначает эта ссылка на каждой поверхности шаблонов), ‘.attachment_name’ (разрешаемый экземпляр присоединения и единственный путь к этому имени из локальной записи), собственные ‘.values’ и ‘.infra’ присоединения, а также уже разрешённые записи этого же блока. Записи разрешаются в порядке их написания, и запись МОЖЕТ читать соседнюю запись, определённую ВЫШЕ неё, получая её разрешённое значение, а не текст шаблона. Порядок автора входит в контракт везде, где одна запись читает другую: перенос определения ниже читающей его записи ломает сборку, и блок никогда не переупорядочивается ради разрешения ссылки. Ссылка ‘.locals. |
provides | map of string | нет | Публичный API разработчика. Контрактные выходные переменные, доступные для разрешения inject вызывающей стороной ниже по потоку. Если executionScope равен boundary, provides вычисляются один раз для присоединения к границе, в контексте шаблонов области границы, и каждый компонент, которого достигает присоединение, читает это единственное вычисление по пути ‘.features. |
source | string или object | нет | Необязательный путь к инфраструктурному коду. Принимает строку URI или открытый структурированный объект. Если указан вместе с valuesMapping, компилятор рендерит его, и отрендеренные документы присоединяются к выходным данным FeatureRecipe до выполнения её шагов конвейера. |
valuesMapping | string или object | нет | Содержимое сопоставления значений с тремя режимами написания, выбираемыми по форме содержимого. Режим 1 (встроенный): скалярная строка шаблона Go, порождающая формат значений, ожидаемый провайдером. Режим 2 (импорт файла): карта YAML ровно с одним ключом, $import: ./relative/path.tmpl, указывающая на локальный файл шаблона Go. Режим 3 (импорт из библиотеки): карта YAML ровно с одним ключом, $import: <Library>#/mappings/<entry>, ссылающаяся на запись MappingLibrary по голому имени (версию задаёт lock-файл каждого Release; хост реестра в ссылке не указывается). В объектной форме $import не должен соответствовать ^oci://; соответствующее значение отклоняется. |
workload | string или object | нет | Генератор YAML для Workload с тремя режимами написания, выбираемыми по форме содержимого. Режим 1 (встроенный): скалярная строка шаблона Go, вывод которой разбирается как ‘aggrega.ai/v1beta1 Workload’. Режим 2 (импорт файла): карта YAML ровно с одним ключом, $import: ./relative/path.yaml, указывающая на локальный файл шаблона Go. Режим 3 (импорт из библиотеки): карта YAML ровно с одним ключом, $import: <Library>#/workloads/<entry>, ссылающаяся на запись WorkloadLibrary по голому имени (версию задаёт lock-файл каждого Release; хост реестра в ссылке не указывается). Целевой Provider должен поддерживать синтез рабочих нагрузок; каталог стандартной библиотеки объявляет workloadSchema у таких провайдеров как документированный контракт. FeatureRecipe с workload:, привязанная к провайдеру, который не умеет синтезировать, явно останавливает сборку во время рендеринга. Синтезированная рабочая нагрузка FeatureRecipe выводит нативные для провайдера манифесты в выходной каталог возможности. В объектной форме $import не должен соответствовать ^oci://; соответствующее значение отклоняется. |
artifacts | карта string или object | нет | Словарь, сопоставляющий имени записи описание содержимого артефакта. Значение каждой записи задаётся в одном из трёх режимов, выбираемых по форме содержимого. Режим 1 (встроенный): скалярная строка шаблона Go, результат которой является телом артефакта. Режим 2 (импорт файла): YAML-словарь ровно с одним ключом, $import: ./relative/path.yaml, указывающий на локальный файл шаблона Go. Режим 3 (импорт из библиотеки): YAML-словарь ровно с одним ключом, $import: <Library>#/artifacts/<entry>, ссылающийся на пакет ArtifactLibrary по идентичности голого имени (версию предоставляет lock-файл каждой сущности Release; хост реестра в ссылке не указывается). Пакет разворачивается в один вывод на каждый файл, каждый из которых вложен под ключ записи как <key>/<filename>. Ключ задаёт имя вывода записи: ключ записи в режиме 1 или 2 — это имя её выходного файла, используемое как написано, а импортированный файл записи в режиме 2 предоставляет содержимое, не задавая имени вывода, поэтому две записи, импортирующие разные файлы с одинаковым именем, дают два разных вывода. Вспомогательные ресурсы, которые выдаёт генерирующая ресурсы сущность FeatureRecipe (ConfigMap, ServiceMonitor, NetworkPolicy, CRD ExternalSecret и т. д.), имеют форму артефактов; artifacts: — основной механизм генерации ресурсов. Конфликты между записями артефактов, файлами пакетов, выводом источника и синтезом рабочей нагрузки останавливают сборку при рендеринге узла. Блок artifacts описывается одинаково в Recipe и в FeatureRecipe — те же три режима, то же правило сопоставления ключа выводу и то же поведение при конфликтах, — поэтому эта часть описания одинакова для обоих видов; пример, написанный для одного, без изменений подходит для другого. В объектной форме $import не должен соответствовать ^oci://; такое значение отклоняется. Ключи: ключ задаёт имя вывода записи, поэтому он ограничен одним именем файла: он начинается с буквы или цифры и продолжается буквами, цифрами, точками, дефисами или подчёркиваниями. Точки после первого символа сохраняют расширения, которые несут ключи артефактов (main.tf, template.yaml, serviceaccount.yaml). Символ / превратил бы имя ключа в путь, а не файл, а начальная . допустила бы .., обозначающее расположение вне выходного каталога, — класс первого символа запрещает и то, и другое. При импорте из библиотеки ключ задаёт каталог, под которым вложены файлы пакета, поэтому действует то же ограничение. Шаблон: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | нет | Что исключить из результата рендеринга источника этой сущности FeatureRecipe — для источника, взятого как есть, который рендерит то, что сущность Release не должна поставлять: документ, который рендерит загруженный чарт, например Secret с ключом, который чарт заново генерирует при каждом рендеринге; сервис, том или конфигурацию, которые включает загруженный compose-файл; или ресурс, который объявляет загруженный шаблон CloudFormation. Большинству сущностей FeatureRecipes это никогда не требуется. Каждая запись называет одну единицу, которую рендерит источник, по её виду, имени и, если запись их указывает, пространству имён и сабчарту, из которого она получена, — каждое в терминах провайдера, рендерящего источник: для чарта — документ по его собственным kind и metadata.name; для compose-файла — service, volume или config по ключу в services:, volumes: или configs:; для шаблона CloudFormation — ресурс по его Type и логическому ID. Этот провайдер исключает каждую единицу, которой соответствует запись, а то, чему соответствует запись и что провайдер отклоняет из-за записи, определяется собственным документированным контрактом этого провайдера. Провайдер, который не может ничего исключать, отклоняет сущность FeatureRecipe с этим ключом до какого-либо рендеринга. Фильтруется только то, что рендерит source:, — запись workload: или artifacts: не фильтруется никогда, — поэтому ключ требует source. Каждое значение является шаблоном и вычисляется в том же контексте, что и valuesMapping. Сначала вычисляется when записи, и запись, чей when даёт ложное значение, отбрасывается. Каждая оставшаяся активной запись должна что-то исключать: активная запись, не соответствующая ничему из отрендеренного источником, останавливает сборку с указанием записи. Источник по-прежнему рендерится полностью — каждый шаблон чарта по-прежнему выполняется, поэтому сбойный шаблон по-прежнему проваливает сборку, — исключается только его вывод. Ключ описывается одинаково в Recipe и в FeatureRecipe. Не менее 1 записи. |
injectMapping | string | нет | Необязательный встроенный шаблон Go, вычисляемый на этапе Pre-Render Interception один раз для каждого компонента, которого достигает присоединение, в контексте шаблона этого компонента: он читает ‘.context’ и ‘.features’ компонента, а также ‘.attachment_name’, ‘.values’, ‘.infra’ и ‘.locals’ присоединения, что бы ни было указано в executionScope, а ссылка на ‘.boundary’, которого нет в контексте ни одного компонента, останавливает сборку. Выдаёт словарь JSON/YAML, который компилятор Go нативно глубоко сливает поверх канала памяти ‘.context.inject’ вызывающей стороны. Используется для изменения переменных окружения и контрактов доставки на стороне вызывающего без Wasm. |
pipeline | object[] | нет | Последовательный список шагов конвейера Wasm, выполняемых после рендеринга над набором отрендеренных документов; каждый шаг возвращает патчи RFC 6902 и побочные эффекты. |
executionScope | string (enum) | нет | Выполняется ли генерация ресурсов этой сущности FeatureRecipe для каждого компонента (по умолчанию) или один раз на присоединение к границе. Сущности FeatureRecipes с областью границы дедуплицируются по (boundary_path, экземпляр FeatureRecipe), и каждый шаблон, кроме injectMapping, читает контекст шаблона области границы: столпы .boundary.* вместо покомпонентных столпов .context.*, ссылка на которые останавливает сборку. injectMapping выполняется один раз для каждого компонента, которого достигает присоединение, независимо от executionScope, поэтому он читает контекст этого компонента и никогда не читает .boundary. Допустимые значения: "component", "boundary" По умолчанию: "component" |
readsCallerRenderFacts | логическая | нет | Объявляет, что шаблоны этой сущности FeatureRecipe читают результаты рендеринга сущностей Components, подключающихся к той, к которой она присоединена: факты рендеринга, которые провайдер каждого из этих вызывающих сообщает о собственном выводе. Если значение true и FeatureRecipe рендерится для каждого компонента, каждое её присоединение рендерится после того, как отрендерены все сущности Component в сборке, а не сразу после сущности Component, к которой оно присоединено, поэтому рендеринг каждого вызывающего завершается до вычисления присоединения. Если значение false или отсутствует, ни одна запись вызывающего в ‘.context.used_by’ не несёт фактов рендеринга, присоединение рендерится сразу после своей сущности Component, если только readsTargetRenderFacts не равно true, а сборка останавливается на шаблоне, написанном встроенно в этой FeatureRecipe, который читает факты рендеринга вызывающего в ‘.context.used_by’. По умолчанию: false |
readsTargetRenderFacts | логическая | нет | Объявляет, что шаблоны этой сущности FeatureRecipe читают результаты рендеринга сущностей Components, с которыми связана та, к которой она присоединена: факты рендеринга, которые провайдер каждой из этих целей сообщает о собственном выводе, в каждой записи ‘.context.uses’. Если значение true и FeatureRecipe рендерится для каждого компонента, каждое её присоединение рендерится после того, как отрендерены все сущности Component в сборке, а не сразу после сущности Component, к которой оно присоединено, поэтому рендеринг каждой цели завершается до вычисления присоединения. Это тот же отложенный рендеринг, который вызывает readsCallerRenderFacts, поэтому установка любого из ключей или обоих приводит к рендерингу присоединения в этот момент. Если значение false или отсутствует, ни одна запись в ‘.context.uses’ не несёт фактов рендеринга, присоединение рендерится сразу после своей сущности Component, если только readsCallerRenderFacts не равно true, а сборка останавливается на шаблоне, написанном встроенно в этой FeatureRecipe, который читает факты рендеринга цели в ‘.context.uses’. По умолчанию: false |
assertions | map of string | нет | Межполевая проверка во время сборки. Каждая запись — именованное утверждение: ключ — стабильный идентификатор правила, выводимый в сообщениях об ошибках; значение — строка шаблона Go с семантикой остановки {{ fail "message" }}. Несколько именованных утверждений в сущности вычисляются для каждого экземпляра в порядке, заданном автором; первое не выполнившееся утверждение останавливает сборку. Утверждения FeatureRecipe вычисляются после привязки рецепта и после вычисления provides, до рендеринга, и выражают инварианты реализации конкретного чарта или модуля, который использует FeatureRecipe. Контекст шаблона: .values / .infra / .uses / .features / .metadata, а также .provides / .locals / .recipe. Вычислитель использует missingkey=error: ссылки на неопределённые ключи приводят к остановке с диагностикой об отсутствии ключа. Поскольку голая ссылка останавливает выполнение до того, как может сработать какой-либо запасной вариант, простой default не обеспечивает запасного значения для необязательного поля в этом контексте — защитите ссылку с помощью hasKey или используйте вспомогательную функцию optional, которая непосредственно выполняет проверку наличия. Чтение ключа через index тоже не обеспечивает его: index останавливается на ключе, которого нет в словаре, указывая этот ключ. |
Дополнительные свойства не допускаются.
featurerecipe.spec.omits[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
kind | string | да | Вид исключаемой единицы в терминах провайдера, который рендерит источник: для чарта — собственный kind отрендеренного документа, например Secret; для compose-файла — service, volume или config; для шаблона CloudFormation — Type ресурса, например AWS::S3::Bucket. Указывает вид, который рендерит источник, и не связан с kind:, который содержит структурированный source:. Шаблон. |
name | string | да | Имя исключаемой единицы в терминах провайдера, который рендерит источник: для чарта — собственное metadata.name отрендеренного документа; для compose-файла — ключ единицы в services:, volumes: или configs:; для шаблона CloudFormation — логический ID ресурса, его ключ в Resources. Шаблон. |
namespace | string | нет | Пространство имён, в котором находится исключаемая единица, если запись должна соответствовать только единице в этом пространстве имён, — для провайдера, вывод которого имеет пространства имён, как отрендеренные документы чарта. Если поле отсутствует или рендерится в пустую строку, запись соответствует единице своего вида и имени независимо от её пространства имён. У compose-файла и шаблона CloudFormation нет пространств имён, и их провайдеры отклоняют запись, в которой оно указано. Шаблон. |
subchart | string | нет | Сабчарт, из которого получена исключаемая единица, — когда запись должна соответствовать только копии, которую рендерит один сабчарт, — для источника, собранного из вложенных источников, как чарт собирается из своих сабчартов. Для чарта — собственное имя сабчарта или псевдоним, который ему даёт зависимость родителя; имена вложенного сабчарта соединяются через /, начиная с внешнего: operator или operator/webhooks. Тогда запись соответствует документу, отрендеренному из собственных templates/ или crds/ этого сабчарта, и не соответствует ни документу, который рендерит сам чарт, ни документу, который рендерит вложенный в него сабчарт. Если поле отсутствует или рендерится в пустую строку, запись соответствует единице своего вида и имени, откуда бы та ни была получена. Чарт, который не рендерит сабчарт с таким именем, останавливает сборку с указанием записи. У compose-файла и шаблона CloudFormation нет сабчартов, и их провайдеры отклоняют запись, которая его указывает. Шаблон. |
when | string | нет | Встроенный шаблон Go, вычисляемый до остальных полей записи. Если он рендерит ложное значение, запись отбрасывается: её остальные поля не вычисляются, из-за неё ничего не исключается, и она не обязана чему-либо соответствовать. Пустой или отсутствующий when сохраняет запись. Истинность определяется стандартным соглашением для логического вывода шаблонов: строки true/True/TRUE, любое ненулевое число и любая другая непустая строка истинны, а false/False/FALSE, пустая строка и ноль ложны. when, который не удаётся отрендерить, останавливает сборку. |
Дополнительные свойства не допускаются.
featurerecipe.spec.pipeline[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
id | string | да | Программный идентификатор этого шага, уникальный среди шагов этого конвейера: документ, объявляющий один идентификатор в двух своих шагах, отклоняется при чтении. Более поздний шаг того же конвейера читает выходные данные этого шага как .steps.<id>.outputs. Шаблон: ^[a-zA-Z0-9_]+$. |
plugin | string | да | Ссылка на сущность Plugin, которую запускает этот шаг, всегда с указанием типа сокета самого плагина: <pluginType>/<name> с необязательной версией, например parser/yaml или parser/yaml:1.0.0. Область обязательна, а не является одной из нескольких допустимых форм: ссылка без области name:version отклоняется, поскольку два сокета могут содержать плагины с одинаковым именем, и именно область делает сущность разрешимой. Сборка разрешает сущность в её адресуемый по содержимому артефакт .wasm — расположение которого определяется по идентичности плагина и настроенному реестру, а дайджест закреплён в lock-файле — и загружает байты. Голая ссылка на .wasm или артефакт здесь не принимается. |
function | string | да | Экспортируемая функция Wasm, которую следует вызвать. |
with | string | нет | Встроенный шаблон Go, вычисляемый в словарь JSON/YAML, который строго соответствует явной входной схеме этого плагина. |
optional | логическая | нет | Если true, сбой этого шага (ловушка гостевого кода, патч, нацеленный на документ, отсутствующий в наборе, некорректный патч или диагностика с уровнем остановки) понижается до заметного предупреждения: набор документов восстанавливается в состояние до шага, вывод этого шага отбрасывается, и конвейер продолжает работу. Если false или поле отсутствует, любой сбой шага останавливает сборку после восстановления набора документов в состояние до шага. |
when | string | нет | Встроенный шаблон Go, вычисляемый во время обхода конвейера. Если он рендерит ложное значение, шаг пропускается и работает как сквозной: набор документов передаётся следующему шагу без изменений, без патчей, побочных эффектов и записи о шаге. Пустой или отсутствующий when всегда запускает шаг. Истинность определяется стандартным соглашением для логического вывода шаблонов: строки true/True/TRUE, любое ненулевое число и любая другая непустая строка истинны, а false/False/FALSE, пустая строка и ноль ложны. when и optional независимы: шаг может объявлять оба. |
Дополнительные свойства не допускаются.