Схема Aggrega Infrastructure Base (Recipe)
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/recipe-v1beta1.schema.json
Создаваемый командой эксплуатации слой указателей и сопоставлений, связывающий намерения разработчиков с конкретным инфраструктурным провайдером. Строго 1:1 с физическим провайдером и компонентом каталога.
Руководство по созданию сущностей Recipe см. в справочнике по созданию сущностей Recipe; на этой странице описана структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “Recipe” | да | Константа: "Recipe" |
metadata | object | да | |
spec | object | да | Привязка к провайдеру, источник, сопоставление значений и конвейер для сущности Recipe. Поддерживает три вида входных данных, объединяемых сложением: sourced (source плюс наложение valuesMapping), synthesized (workload) и artifacts (именованные выходные файлы). Отдельно от них сущность Recipe может добавлять файлы в общий вывод границы, в которой она рендерится, в разделе ‘boundary’. |
Дополнительные свойства не допускаются.
recipe.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
version | string | да | Строгая семантическая версия реализующего рецепта (например, 2.1.0). Шаблон: ^(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[] | нет | Список описательных ключевых слов для удобства поиска в интерфейсе. |
Дополнительные свойства не допускаются.
recipe.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
recipe.spec
Привязка к провайдеру, источник, сопоставление значений и конвейер для сущности Recipe. Поддерживает три вида входных данных, объединяемых сложением: sourced (source плюс наложение valuesMapping), synthesized (workload) и artifacts (именованные выходные файлы). Отдельно от них сущность Recipe может добавлять файлы в общий вывод границы, в которой она рендерится, в разделе ‘boundary’.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
capability | string | да | Явная возможность провайдера, к которой привязан этот рецепт (например, ‘helm’, ‘terraform’, ‘compose’), — вид провайдера, который его рендерит. Допускает необязательную фиксацию версии в тех же трёх формах, что и ‘implements’: без версии (‘helm’), точная (‘helm:1.0.0’) или диапазон, совместимый по мажорной версии (‘helm:^1.0.0’). Голое имя выбирает вид провайдера; фиксация, если она указана, выбирает, какая версия плагина рендеринга провайдера, обслуживающего эту возможность, рендерит этот рецепт: наивысшая доступная без фиксации, точная при точной фиксации, наивысшая в диапазоне при каретке. Фиксация, которой не удовлетворяет ни одна версия обслуживающего плагина, явно останавливает сборку. Всё, что следует за выбором провайдера, — группировка вывода, сегменты путей, совместимость конвейера и выбор кодека — определяется голой возможностью, поэтому два рецепта, фиксирующие разные версии плагина одной и той же возможности, сосуществуют в одной сборке. |
implements | string | да | Объявляет, какой тип компонента каталога этот рецепт способен реализовать (точная версия ‘core/api-server:1.0.0’, диапазон, совместимый по мажорной версии, ‘core/api-server:^1.0.0’, или без версии ‘core/api-server’). Компилятор использует его для проверки сопоставлений в сущности Manifest и для предложения кандидатов в диагностике и автодополнении в редакторе; он никогда не разрешает сборку. aggrega lint тоже читает его, чтобы найти сущность Component, с объявленным контрактом provides которой сравниваются опубликованные ключи сущности Recipe. Сопоставление в сущности Manifest — явный выбор реализации пользователем, зафиксированный в lock-файле сущности Release. |
source | string или object | нет | Расположение кода инфраструктуры. Принимает строку URI или открытый структурированный объект, ключи которого, определяемые провайдером, доступны шаблонам сущности Recipe как ‘.source.*’. |
locals | map of string | нет | Приватное состояние Ops. Внутренние результаты вычислений, доступные в шаблонах этой сущности Recipe как ‘.locals.*’. Каждая запись сама является шаблоном Go, вычисляемым в самодостаточном локальном контексте узла: ‘.context.instance_id’, ‘.values’, ‘.infra’ и уже разрешённые записи этого же блока. Записи разрешаются в порядке их написания, и запись МОЖЕТ читать соседнюю запись, определённую ВЫШЕ неё, получая разрешённое значение этой записи, а не текст её шаблона. Порядок, заданный автором, является частью контракта везде, где одна запись читает другую: перемещение определения ниже читающей его записи ломает сборку, и блок никогда не переупорядочивается ради разрешения ссылки. Ссылка ‘.locals. |
provides | карта string, number или boolean | нет | Публичный API для разработчиков. Контрактные выходные переменные, доступные для разрешения inject у последующих вызывающих сторон. Компилятор вычисляет шаблоны provides в самодостаточном контексте, в любом порядке относительно друг друга — ни одна запись provides не читает другую. Locals узла разрешаются в преамбуле locals до его provides, поэтому шаблон provides может читать ‘.locals’ и получает разрешённые значения; указание ключа, который блок locals не объявляет, вызывает остановку. Вызывающие стороны разрешают ключи inject по этим значениям при гидратации inject. Значения являются скалярами — конвейер передаёт их дословно и детерминированно преобразует в строку на границе внедрения. |
valuesMapping | string или object | нет | Содержимое сопоставления значений с тремя режимами написания, выбираемыми по форме содержимого. Режим 1 (встроенный): скалярная строка шаблона Go (обычно блочный скаляр YAML |), формирующая значения в формате, ожидаемом провайдером, из контекста Aggrega (.values, .features, .infra). Режим 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 должен поддерживать синтез workload; каталог стандартной библиотеки объявляет workloadSchema у таких провайдеров как документированный контракт. Сущность Recipe с workload:, привязанная к провайдеру, который не умеет выполнять синтез, явно останавливается во время рендеринга. В объектной форме $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 даёт содержимое, но не имя вывода, поэтому две записи, импортирующие разные файлы с одинаковым именем, дают два разных вывода. Коллизии между записями артефактов, файлами пакетов, выводом источника и синтезом workload останавливают сборку при рендеринге узла. Блок artifacts пишется одинаково в Recipe и в FeatureRecipe — те же три режима, то же правило соответствия ключа и вывода и то же поведение при коллизиях, — поэтому эта часть описания одинакова для обоих видов; пример, написанный для одного, без изменений переносится на другой. В объектной форме $import не должен соответствовать ^oci://; значение, которое соответствует, отклоняется. Ключи: ключ задаёт имя вывода записи, поэтому он ограничен одним именем файла: начинается с буквы или цифры и продолжается буквами, цифрами, точками, дефисами или подчёркиваниями. Точки после первого символа сохраняют расширения, которые несут ключи артефактов (main.tf, template.yaml, serviceaccount.yaml). Символ / сделал бы имя ключа путём, а не файлом, а начальная . допустила бы .., что обозначает место за пределами выходного каталога, — класс первого символа исключает и то, и другое. При импорте из библиотеки ключ задаёт каталог, в который вкладываются файлы пакета, поэтому действует то же ограничение. Шаблон: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | нет | Что исключить из того, что рендерит источник этой сущности Recipe, — для источника, взятого как есть, который рендерит что-то, что Release не должен поставлять: документ, который рендерит загруженный chart, например Secret с ключом, который chart заново генерирует при каждом рендеринге; сервис, том или конфигурацию, которые содержит загруженный compose-файл; или ресурс, который объявляет загруженный шаблон CloudFormation. Большинству Recipes это никогда не нужно. Каждая запись называет одну единицу, которую рендерит источник, по её виду, имени и, если запись их указывает, пространству имён и subchart, из которого она получена, — каждое в терминах провайдера, рендерящего источник: для chart — документ по его собственным kind и metadata.name; для compose-файла — service, volume или config по ключу в services:, volumes: или configs:; для шаблона CloudFormation — ресурс по его Type и логическому ID. Этот провайдер исключает каждую единицу, которой соответствует запись, а чему соответствует запись и что провайдер отклоняет из-за записи, определяет его собственный документированный контракт. Провайдер, который не умеет ничего исключать, отклоняет Recipe с этим ключом до начала рендеринга. Фильтруется только то, что рендерит source:, — запись workload: или artifacts: никогда не фильтруется, — поэтому ключ требует source. Каждое значение — шаблон, вычисляемый в том же контексте, что и valuesMapping. Сначала вычисляется when записи, и запись, чей when даёт ложное значение, отбрасывается. Каждая оставшаяся активной запись должна что-то исключать: активная запись, которая не соответствует ничему из отрендеренного источником, останавливает сборку с указанием записи. Источник по-прежнему рендерится полностью — каждый шаблон chart по-прежнему выполняется, поэтому неудачный шаблон по-прежнему срывает сборку, — исключается только его вывод. Не менее 1 записи. |
boundary | object | нет | Что эта сущность Recipe добавляет в общий вывод границы, в которой она рендерится, а не в вывод собственного компонента. Большинству Recipes это никогда не нужно: блок предназначен для файла, который цель читает один раз для всей границы, — например, конфигурации провайдера Terraform, которую Terraform принимает только в корневой конфигурации границы и никогда внутри модуля отдельного компонента. Провайдер принимает такие файлы, только если его контракт объявляет boundaryArtifacts, а Recipe, объявляющий этот блок для провайдера без такого объявления, отклоняется до начала рендеринга. У FeatureRecipe такого блока нет. |
outputLabels | map of string | нет | Метки, объявленные автором Recipe, которые проставляются на каждый объект, создаваемый отрисованным выводом этого рецепта, и переводятся провайдером на поверхность меток каждого провайдера (Kubernetes metadata.labels для синтеза helm, source-render и artifacts; метки сервисов Compose; теги отдельных ресурсов в телах артефактов Terraform .tf.json). Они проходят тем же путём, что и фиксированные метки происхождения, но принадлежат автору, а не компилятору. Пространства имён aggrega.ai/ и app.kubernetes.io/ зарезервированы для встроенных меток происхождения платформы и отклоняются при загрузке. За ключ или значение, не являющиеся допустимой меткой для целевого провайдера, отвечает автор рецепта; ядро не проверяет набор символов меток сверх правила о зарезервированных пространствах имён. |
outputComponentLabels | string[] | нет | Ключи меток идентичности Component, которые этот рецепт переносит на свой отрисованный вывод. Каждая запись называет ключ метки; значение берётся из меток экземпляра компонента, который отрисовывает этот рецепт, поэтому проставленная метка несёт объявленное значение этого компонента, а не значение, повторённое здесь. Перенесённые метки попадают на ту же поверхность меток, что и outputLabels, который, напротив, содержит буквальные пары «ключ — значение», заданные на месте. Ключ, объявленный в обоих блоках, отклоняется при загрузке, так что у каждого проставленного ключа один источник. Пространства имён aggrega.ai/ и app.kubernetes.io/ зарезервированы для встроенных меток происхождения платформы и отклоняются при загрузке; ключ с областью, такой как component.aggrega.ai/hosting, находится вне этих зарезервированных корней и может быть перенесён. |
pipeline | object[] | нет | Последовательный список шагов конвейера Wasm, выполняемых после рендеринга над набором отрендеренных документов; каждый шаг возвращает патчи RFC 6902 и побочные эффекты. |
assertions | map of string | нет | Перекрёстная проверка полей во время сборки. Каждая запись — именованное утверждение: ключ — стабильный идентификатор правила, выводимый в сообщениях об ошибках; значение — строка шаблона Go с семантикой остановки {{ fail "message" }}. Несколько именованных утверждений одной сущности вычисляются для каждого экземпляра в порядке, объявленном автором; первое неуспешное утверждение останавливает сборку. Утверждения Recipe вычисляются после привязки рецепта и после вычисления provides, до рендеринга, и выражают инварианты реализации конкретного чарта или модуля, который использует Recipe. Контекст шаблона: .values / .infra / .uses / .features / .metadata, а также .provides / .locals / .recipe. Вычислитель использует missingkey=error: ссылки на неопределённые ключи останавливают сборку с диагностикой об отсутствующем ключе. Поскольку простая ссылка останавливает сборку раньше, чем может сработать какой-либо запасной вариант, обычный default не даёт значения по умолчанию для необязательного поля в этом контексте — защитите ссылку с помощью hasKey или используйте вспомогательную функцию optional, которая сама выполняет проверку наличия. Чтение ключа через index тоже не даёт такого значения: index останавливает сборку на ключе, которого нет в карте, называя этот ключ. |
Дополнительные свойства не допускаются.
recipe.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, который не удаётся отрендерить, останавливает сборку. |
Дополнительные свойства не допускаются.
recipe.spec.boundary
Что эта сущность Recipe добавляет в общий вывод границы, в которой она рендерится, а не в вывод собственного компонента. Большинству Recipes это никогда не нужно: блок предназначен для файла, который цель читает один раз для всей границы, — например, конфигурации провайдера Terraform, которую Terraform принимает только в корневой конфигурации границы и никогда внутри модуля отдельного компонента. Провайдер принимает такие файлы, только если его контракт объявляет boundaryArtifacts, а Recipe, объявляющий этот блок для провайдера без такого объявления, отклоняется до начала рендеринга. У FeatureRecipe такого блока нет.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
artifacts | карта string или object | да | Карта «имя файла — описание содержимого файла», устроенная точно так же, как собственный блок artifacts этого Recipe: те же три режима — встроенная строка шаблона Go, $import: локального файла шаблона Go или $import: пакета ArtifactLibrary, файлы которого вкладываются под ключ записи как <key>/<filename>, — то же правило соответствия ключа имени файла и тот же контекст шаблона, так что запись может читать .values, .infra, .locals и остальное точно так же, как запись artifacts. Отличается то, куда записывается каждый файл: один раз, в каталог с собранным выводом границы, рядом с файлами, которые туда записывает собственная сборка провайдера, а не в собственный каталог этого компонента. Каждая запись вычисляется для каждого компонента, который этот Recipe рендерит в границе, и получившиеся файлы объединяются по имени: одно имя, вычисленное в идентичные байты несколькими компонентами или несколькими Recipes, — это один файл, а одно имя, вычисленное в разные байты, останавливает сборку с указанием файла и всех участников; так же происходит с именем, которое уже записывает собственная сборка провайдера. В такой файл ничего не вписывается о том, какой компонент его записал, поскольку он принадлежит каждому компоненту, который его объявил. Запись, шаблон которой рендерится в пустоту, не создаёт файла. Записи не передаются провайдеру, который записывает остальной вывод границы, не читая их. В объектной форме $import не должен соответствовать ^oci://; соответствующее значение отклоняется. Ключи: ключ задаёт имя файла, поэтому ограничен одним именем файла по тому же правилу, что и ключ artifacts: он начинается с буквы или цифры и продолжается буквами, цифрами, точками, дефисами или подчёркиваниями. Символ / превратил бы имя ключа в путь, а не файл, а начальная . допустила бы .., что обозначает место вне выходного каталога границы, — класс первого символа исключает и то, и другое. При импорте из библиотеки ключ задаёт каталог, в который вкладываются файлы пакета, поэтому действует то же ограничение. Шаблон: ^[A-Za-z0-9][A-Za-z0-9._-]*$. Не менее 1 записи. |
Дополнительные свойства не допускаются.
recipe.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 независимы: шаг может объявлять оба. |
Дополнительные свойства не допускаются.