Огляд довідника сутностей
Словник авторингу 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 — створений командою Ops переклад сутності Component для конкретного провайдера. Поєднує три види вхідних даних (
source:+valuesMapping:,workload:,artifacts:— кожен приймає вбудований вміст або$import:згідно з уніфікованим словником імпорту файлів), а також блокprovides, що утворює контракт ін’єкції з боку виклику. - FeatureRecipe — створений командою Ops переклад сутності 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, розподіляє компоненти за фізичними межами, надає значення параметрів для кожного середовища та приєднує керовані Ops сутності 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:); описує форму розгортання, яку провайдер синтезує в нативні для провайдера маніфести.