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

Схема Aggrega Infrastructure Base (FeatureRecipe)

Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.

Идентификатор схемы: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json

Определения, создаваемые Ops, которые сопоставляют абстрактную сущность Feature из каталога с конкретной версионированной реализацией для одной возможности провайдера. Строго 1:1 с физическим провайдером и функцией каталога.

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

Тип верхнего уровня: object

Свойства

СвойствоТипОбязательноОписание
apiVersionconst “aggrega.ai/v1beta1”даКонстанта: "aggrega.ai/v1beta1"
kindconst “FeatureRecipe”даКонстанта: "FeatureRecipe"
metadataobjectда
specobjectдаПривязка к возможности провайдера, сопоставление, конвейер и сопоставление внедрения для сущности FeatureRecipe. Содержит те же три вида входных данных, что и Recipe (sourced, synthesized, artifacts), а также injectMapping, доступный только в FeatureRecipe; FeatureRecipe, выполняющая только связывание и объявляющая лишь capability и implements, допустима и ничего не рендерит.

Дополнительные свойства не допускаются.

featurerecipe.metadata

СвойствоТипОбязательноОписание
namestringдаНе менее 1 символа.
versionstringдаВерсия сущности 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-]+)*))?$.
descriptionstringнетЧто представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что нужно читателю, чтобы выбрать её и правильно использовать: чего она ожидает от сущности Release, которая её развёртывает, и всё неожиданное в её поведении. Обычно достаточно короткого абзаца.
maintainersobject[]нетСписок сопровождающих, которым принадлежит эта сущность.
licensestringнетИдентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла.
repositorystringнетURL Git-репозитория, в котором находятся исходные файлы.
homestringнетURL домашней страницы, вики или документации этой сущности.
keywordsstring[]нетСписок описательных ключевых слов для удобства поиска в интерфейсе.

Дополнительные свойства не допускаются.

featurerecipe.metadata.maintainers[]
СвойствоТипОбязательноОписание
namestringда
emailstringнет
urlstringнет

Дополнительные свойства не допускаются.

featurerecipe.spec

Привязка к возможности провайдера, сопоставление, конвейер и сопоставление внедрения для сущности FeatureRecipe. Содержит те же три вида входных данных, что и Recipe (sourced, synthesized, artifacts), а также injectMapping, доступный только в FeatureRecipe; FeatureRecipe, выполняющая только связывание и объявляющая лишь capability и implements, допустима и ничего не рендерит.

СвойствоТипОбязательноОписание
capabilitystringдаЯвная возможность провайдера, к которой привязан этот рецепт (например, ‘helm’, ‘terraform’, ‘compose’), — вид провайдера, который его рендерит.
implementsstringдаОбъявляет, какой тип Feature из каталога этот рецепт способен реализовать (включая Features учётных данных с меткой feature.aggrega.ai/kind: secret; точная версия, диапазон, совместимый по мажорной версии ’^’, или без версии). Компилятор использует это для проверки сопоставлений в Manifest и для предложения кандидатов в диагностике и автодополнении в редакторе; сборку это никогда не разрешает. Сопоставление в Manifest — явный выбор реализации пользователем, зафиксированный в lock-файле сущности Release.
localsmap of stringнетПриватное состояние Ops. Внутренние результаты вычислений, доступные только в шаблонах этой FeatureRecipe как ‘.locals.*’. Каждая запись сама является шаблоном Go, вычисляемым в самодостаточном контексте: ‘.context.instance_id’ (КОМПОНЕНТ-ХОСТ, для которого разрешается это присоединение, — именно его обозначает эта ссылка на каждой поверхности шаблонов), ‘.attachment_name’ (разрешаемый экземпляр присоединения и единственный путь к этому имени из локальной записи), собственные ‘.values’ и ‘.infra’ присоединения, а также уже разрешённые записи этого же блока. Записи разрешаются в порядке их написания, и запись МОЖЕТ читать соседнюю запись, определённую ВЫШЕ неё, получая её разрешённое значение, а не текст шаблона. Порядок автора входит в контракт везде, где одна запись читает другую: перенос определения ниже читающей его записи ломает сборку, и блок никогда не переупорядочивается ради разрешения ссылки. Ссылка ‘.locals.’ на запись, которую этот блок определяет ПОЗЖЕ, останавливает сборку с указанием ошибки порядка; ссылка на ключ, который блок вообще не объявляет, останавливает сборку с указанием ключа. Обе проверки читают путь, в который ссылка РАЗРЕШАЕТСЯ, а не набранный текст, поэтому одинаково охватывают прямую форму, чтение внутри блока ’{{ with .locals }}’, чтение через переменную, привязанную непосредственно к ‘.locals’, и ключ, читаемый из блока в скобках, ‘(.locals).’ или ’($.locals).’. Одно написание они не охватывают: ссылку, путь которой текст шаблона не определяет, — полученную через функцию, например ‘index .locals’ или ‘(default dict .locals).’, или через блок ‘with’ либо привязку переменной, конвейер которых применяет функцию, поскольку результат такого конвейера определяется при вычислении, а не его текстом. Она не анализируется, и отсутствующий ключ, полученный таким способом, не останавливает сборку: он рендерит буквальный текст '', а не пустоту. Единственное исключение — сам ‘index’: на каждой поверхности шаблонов он останавливает сборку с указанием ключа, если читаемая им карта не содержит запрошенного ключа, поэтому отсутствующий ключ, полученный через ‘index .locals’, останавливает сборку. Локальные записи этой FeatureRecipe разрешаются ДО её provides, поэтому шаблон provides может читать ‘.locals’ и получает разрешённые значения, а шаблон provides, ссылающийся на ключ, не объявленный этим блоком, останавливает сборку. Это те же правила, которым следует блок locals сущности Recipe. Если executionScope равен boundary, блок вычисляется один раз для присоединения к границе, в контексте шаблонов области границы, а не компонента, и каждый компонент, которого достигает присоединение, читает эти разрешённые записи, включая ‘.locals’, которые читает его injectMapping. Используется для экспорта физических реалий (например, целевых контейнеров, путей JSON) для последующих плагинов Wasm. Никогда не доступно вызывающим — для публичного API используйте provides.
providesmap of stringнетПубличный API разработчика. Контрактные выходные переменные, доступные для разрешения inject вызывающей стороной ниже по потоку. Если executionScope равен boundary, provides вычисляются один раз для присоединения к границе, в контексте шаблонов области границы, и каждый компонент, которого достигает присоединение, читает это единственное вычисление по пути ‘.features..provides’, как и соединение, которое несёт присоединение; контракт provides, объявленный реализуемой сущностью Feature, проверяется один раз, на этом вычислении, с указанием присоединения к границе.
sourcestring или objectнетНеобязательный путь к инфраструктурному коду. Принимает строку URI или открытый структурированный объект. Если указан вместе с valuesMapping, компилятор рендерит его, и отрендеренные документы присоединяются к выходным данным FeatureRecipe до выполнения её шагов конвейера.
valuesMappingstring или objectнетСодержимое сопоставления значений с тремя режимами написания, выбираемыми по форме содержимого. Режим 1 (встроенный): скалярная строка шаблона Go, порождающая формат значений, ожидаемый провайдером. Режим 2 (импорт файла): карта YAML ровно с одним ключом, $import: ./relative/path.tmpl, указывающая на локальный файл шаблона Go. Режим 3 (импорт из библиотеки): карта YAML ровно с одним ключом, $import: <Library>#/mappings/<entry>, ссылающаяся на запись MappingLibrary по голому имени (версию задаёт lock-файл каждого Release; хост реестра в ссылке не указывается). В объектной форме $import не должен соответствовать ^oci://; соответствующее значение отклоняется.
workloadstring или 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._-]*$.
omitsobject[]нетЧто исключить из результата рендеринга источника этой сущности 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 записи.
injectMappingstringнетНеобязательный встроенный шаблон Go, вычисляемый на этапе Pre-Render Interception один раз для каждого компонента, которого достигает присоединение, в контексте шаблона этого компонента: он читает ‘.context’ и ‘.features’ компонента, а также ‘.attachment_name’, ‘.values’, ‘.infra’ и ‘.locals’ присоединения, что бы ни было указано в executionScope, а ссылка на ‘.boundary’, которого нет в контексте ни одного компонента, останавливает сборку. Выдаёт словарь JSON/YAML, который компилятор Go нативно глубоко сливает поверх канала памяти ‘.context.inject’ вызывающей стороны. Используется для изменения переменных окружения и контрактов доставки на стороне вызывающего без Wasm.
pipelineobject[]нетПоследовательный список шагов конвейера Wasm, выполняемых после рендеринга над набором отрендеренных документов; каждый шаг возвращает патчи RFC 6902 и побочные эффекты.
executionScopestring (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
assertionsmap 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[]
СвойствоТипОбязательноОписание
kindstringдаВид исключаемой единицы в терминах провайдера, который рендерит источник: для чарта — собственный kind отрендеренного документа, например Secret; для compose-файла — service, volume или config; для шаблона CloudFormation — Type ресурса, например AWS::S3::Bucket. Указывает вид, который рендерит источник, и не связан с kind:, который содержит структурированный source:. Шаблон.
namestringдаИмя исключаемой единицы в терминах провайдера, который рендерит источник: для чарта — собственное metadata.name отрендеренного документа; для compose-файла — ключ единицы в services:, volumes: или configs:; для шаблона CloudFormation — логический ID ресурса, его ключ в Resources. Шаблон.
namespacestringнетПространство имён, в котором находится исключаемая единица, если запись должна соответствовать только единице в этом пространстве имён, — для провайдера, вывод которого имеет пространства имён, как отрендеренные документы чарта. Если поле отсутствует или рендерится в пустую строку, запись соответствует единице своего вида и имени независимо от её пространства имён. У compose-файла и шаблона CloudFormation нет пространств имён, и их провайдеры отклоняют запись, в которой оно указано. Шаблон.
subchartstringнетСабчарт, из которого получена исключаемая единица, — когда запись должна соответствовать только копии, которую рендерит один сабчарт, — для источника, собранного из вложенных источников, как чарт собирается из своих сабчартов. Для чарта — собственное имя сабчарта или псевдоним, который ему даёт зависимость родителя; имена вложенного сабчарта соединяются через /, начиная с внешнего: operator или operator/webhooks. Тогда запись соответствует документу, отрендеренному из собственных templates/ или crds/ этого сабчарта, и не соответствует ни документу, который рендерит сам чарт, ни документу, который рендерит вложенный в него сабчарт. Если поле отсутствует или рендерится в пустую строку, запись соответствует единице своего вида и имени, откуда бы та ни была получена. Чарт, который не рендерит сабчарт с таким именем, останавливает сборку с указанием записи. У compose-файла и шаблона CloudFormation нет сабчартов, и их провайдеры отклоняют запись, которая его указывает. Шаблон.
whenstringнетВстроенный шаблон Go, вычисляемый до остальных полей записи. Если он рендерит ложное значение, запись отбрасывается: её остальные поля не вычисляются, из-за неё ничего не исключается, и она не обязана чему-либо соответствовать. Пустой или отсутствующий when сохраняет запись. Истинность определяется стандартным соглашением для логического вывода шаблонов: строки true/True/TRUE, любое ненулевое число и любая другая непустая строка истинны, а false/False/FALSE, пустая строка и ноль ложны. when, который не удаётся отрендерить, останавливает сборку.

Дополнительные свойства не допускаются.

featurerecipe.spec.pipeline[]
СвойствоТипОбязательноОписание
idstringдаПрограммный идентификатор этого шага, уникальный среди шагов этого конвейера: документ, объявляющий один идентификатор в двух своих шагах, отклоняется при чтении. Более поздний шаг того же конвейера читает выходные данные этого шага как .steps.<id>.outputs. Шаблон: ^[a-zA-Z0-9_]+$.
pluginstringдаСсылка на сущность Plugin, которую запускает этот шаг, всегда с указанием типа сокета самого плагина: <pluginType>/<name> с необязательной версией, например parser/yaml или parser/yaml:1.0.0. Область обязательна, а не является одной из нескольких допустимых форм: ссылка без области name:version отклоняется, поскольку два сокета могут содержать плагины с одинаковым именем, и именно область делает сущность разрешимой. Сборка разрешает сущность в её адресуемый по содержимому артефакт .wasm — расположение которого определяется по идентичности плагина и настроенному реестру, а дайджест закреплён в lock-файле — и загружает байты. Голая ссылка на .wasm или артефакт здесь не принимается.
functionstringдаЭкспортируемая функция Wasm, которую следует вызвать.
withstringнетВстроенный шаблон Go, вычисляемый в словарь JSON/YAML, который строго соответствует явной входной схеме этого плагина.
optionalлогическаянетЕсли true, сбой этого шага (ловушка гостевого кода, патч, нацеленный на документ, отсутствующий в наборе, некорректный патч или диагностика с уровнем остановки) понижается до заметного предупреждения: набор документов восстанавливается в состояние до шага, вывод этого шага отбрасывается, и конвейер продолжает работу. Если false или поле отсутствует, любой сбой шага останавливает сборку после восстановления набора документов в состояние до шага.
whenstringнетВстроенный шаблон Go, вычисляемый во время обхода конвейера. Если он рендерит ложное значение, шаг пропускается и работает как сквозной: набор документов передаётся следующему шагу без изменений, без патчей, побочных эффектов и записи о шаге. Пустой или отсутствующий when всегда запускает шаг. Истинность определяется стандартным соглашением для логического вывода шаблонов: строки true/True/TRUE, любое ненулевое число и любая другая непустая строка истинны, а false/False/FALSE, пустая строка и ноль ложны. when и optional независимы: шаг может объявлять оба.

Дополнительные свойства не допускаются.