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

Обзор справочника по сущностям

Словарь авторинга 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:); описывает форму развёртывания, которую провайдер синтезирует в собственные манифесты провайдера.