Обзор справочника по сущностям
Словарь авторинга Aggrega включает Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary и ArtifactLibrary, а также принадлежащий платформе вид Workload, встроенный в синтезированные входные данные сущности Recipe. Каждая сущность — это документ YAML, соответствующий JSON Schema; каждое поле, ключевое слово и межсущностная ссылка, описанные в этом справочнике, являются частью этого авторского контракта.
Этот набор глав охватывает поверхность авторинга: какие поля принимает каждая сущность, что каждое поле означает для автора, как поля взаимодействуют между сущностями (implements: сущности Recipe, называющее сущность Component, которую она реализует, указатель manifest: сущности Release на сущность Manifest, containers.<name>.attachments сущности Workload, ссылающиеся на слоты, объявленные в featuresSchema сущности Component). Концептуальная роль каждой сущности — почему таксономия имеет именно такую форму, какой домен владеет какой сущностью, как четыре домена разделяют задачи авторинга — описана в ../architecture/04-entity-taxonomy.md. Архитектурная роль вида Workload как одного из трёх видов входных данных сущности Recipe описана в ../architecture/16-recipe-input-composition.md.
Как организован этот справочник
Словарь авторинга документируют две поверхности, и они отвечают на разные вопросы.
Для каждого перечисленного выше вида есть сгенерированный справочник по схеме. Эти страницы генерируются из схем, которые публикует сам компилятор, а schema/README.md индексирует полный набор — виды сущностей, формы обмена с плагинами и файлы рабочего пространства. Обращайтесь к справочнику по схеме, чтобы ответить на вопрос «что может содержать этот документ»: каждое поле, его тип, является ли оно обязательным и ограничения, которые применяет оболочка.
Страницы ниже — руководства по авторингу. Они написаны вручную, чтобы объяснить то, чего не может схема: для чего нужен вид, как его поля взаимодействуют с другими видами, какая форма авторинга подходит для какой ситуации и каким соглашениям следует каталог стандартной библиотеки. Обращайтесь к руководству по авторингу, чтобы ответить на вопрос «как его написать и почему он устроен именно так».
Справочник по отдельным сущностям
- Aggregate — декларативный артефакт намерения разработчика. Объявляет компоненты, их топологию через
uses, контракты параметров для вариаций по окружениям и подключения сущностей Feature. - Component — сущность каталога, создаваемая архитектором платформы и определяющая повторно используемый вид компонента. Объявляет свои схемы
valuesиinfra(каждая — объявление JSON Schema 2020-12 в компактной или полной форме), свой выходной контрактprovides, контракт входящих рёберusesSchemaи слоты учётных данных черезfeaturesSchema. - Feature — сущность каталога, создаваемая архитектором платформы, для сквозной задачи (sidecar мониторинга, маскирование данных, политика маршрутизации). Объявляет свои схемы
valuesиinfra(каждая — объявление JSON Schema 2020-12), селекторы подключенияappliesToи ограничения совместимости. - Recipe — создаваемая командой эксплуатации трансляция сущности Component для конкретного провайдера. Объединяет три вида входных данных (
source:+valuesMapping:,workload:,artifacts:— каждый принимает встроенное содержимое или$import:согласно единому словарю импорта файлов), а также блокprovides, образующий контракт внедрения со стороны вызывающего. - FeatureRecipe — создаваемая командой эксплуатации трансляция сущности Feature для конкретного провайдера. Использует тот же контракт трёх видов входных данных, что и Recipe, плюс
injectMapping, который перехватывает канал внедрения для переписывания переменных на стороне вызывающего. - Plugin — адресуемый по содержимому плагин WebAssembly. Объявляет единственный тип сокета, который он реализует, —
provider,linter,pipeline-step,governance,cli,parserилиimporter, — свою версию ABI и возможности, которые обслуживает этот тип сокета. Сущность Plugin, выполняющая рендеринг для провайдера (pluginType: provider), объявляет имя или имена обслуживаемых провайдеров вspec.provider.capabilitiesи содержит метаданные сокета провайдера —workloadSchemaиwellKnownAnnotations— в том же блокеspec.provider. - Manifest — таблица сопоставлений проекта. Привязывает абстрактные типы Component и Feature к конкретным URI сущностей Recipe и FeatureRecipe в разделах
componentsиfeaturesс порядком поискаname> версионированныйtype> неверсионированныйtype. - Release — маршрутизатор развёртывания для окружения. Привязывает сущность Aggregate к сущности Manifest, распределяет компоненты по физическим границам, задаёт значения параметров для окружения и подключает управляемые командой эксплуатации сущности Features.
Сущности-библиотеки
Четыре вида библиотек относятся к уровню 3 — это необязательные сущности для повторного использования. Каталог объявляет такую сущность, когда одно и то же содержимое повторяется в его сущностях, а в противном случае обходится без них. Каждая содержит один тип содержимого, а фрагмент в ссылке (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) указывает, к какой библиотеке обращается ссылка.
- SchemaLibrary — повторно используемые определения JSON Schema 2020-12 и необязательные параметризованные помощники, на которые ссылаются схемы сущностей Component или Feature через
$ref: <Library>#/schemas/<name>. - MappingLibrary — повторно используемые фрагменты шаблонов Go, импортируемые в
valuesMapping:сущности Recipe или FeatureRecipe через$import: <Library>#/mappings/<name>. - WorkloadLibrary — повторно используемое содержимое Workload, импортируемое в
workload:сущности Recipe или FeatureRecipe через$import: <Library>#/workloads/<name>. - ArtifactLibrary — повторно используемые пакеты вспомогательных выходных файлов, импортируемые в
artifacts:сущности Recipe или FeatureRecipe через$import: <Library>#/artifacts/<name>. Единица повторного использования — пакет: один импорт разворачивается в один выходной файл на каждый файл пакета.
Виды, принадлежащие платформе
- Workload — принадлежащий платформе вид компилятора (не создаваемая пользователем сущность каталога). Встраивается в поле
workload:сущности Recipe (непосредственно или через$import:); описывает форму развёртывания, которую провайдер синтезирует в собственные манифесты провайдера.