Feature
Концептуальну роль сутності Feature (модульної операційної риси в Домені 2) описано в architecture/04-entity-taxonomy.md. Різницю між операційними сутностями Features і сутностями Features для облікових даних (тими, що мають мітку feature.aggrega.ai/kind: secret) описано в architecture/08-credential-model.md. Словник семантичних міток, який використовують селектори сутностей Feature, наведено в entities/component. Ця сторінка описує інтерфейс створення каталогу сутностей Feature.
Розташування в каталозі
На відміну від Components (які використовують трисегментні URI з підкаталогами категорій), Features організовано пласко: один каталог на кожну Feature у каталозі її видавця, що містить по одному каталогу на кожну версію.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...OCI URI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (наприклад, hub.aggrega.ai/feature/core/data-masking:1.0.0).
Контракт створення
Features оголошують:
metadata.labels: використовуйтеfeature.aggrega.ai/kind: secret, щоб позначити Feature як облікову Feature. Мітка — це описові метадані для автора, для сайту каталогу та для селекторів міток; жодна гілка компілятора її не читає, і те, що створює приєднання, визначає FeatureRecipe, на яку Manifest відображає її тип, а не мітка. Облікова Feature і звичайна Feature приєднуються однаково, на тій самій поверхні приєднання, на будь-якому рівні. Сімейство облікових даних стандартної бібліотеки поділяється за результатом:core/secret-valueдоставляє значення в канал впровадження;core/referenced-secretназиває ресурс секрету, на який можна посилатися (Kubernetes Secret, секрет AWS Secrets Manager, запис Vault), — такий, що його створює вивід її FeatureRecipe, або такий, що вже існує, — і оголошує вихідний контрактschema.provides—name(незалежний від постачальника локатор ресурсу) іkey(поле даних у ньому), — який споживач читає як.features.<slot>.provides.<key>, щоб посилатися на ресурс без повторного виведення його імені;core/referenced-secret-setматеріалізує один ресурс, що містить набір ключів даних, наданий викликачем, і публікує лише локатор — для споживача, чия ціль уже знає імена ключів, які читає;core/secret-providedнадає значення наявного секрету;core/generated-secretнічого не створює, бо цільовий рушій сам генерує облікові дані й керує ними, тож вона не оголошує ніvalues, ніprovides, а її FeatureRecipes — це чисте зв’язування, яке не рендерить жодного байта. Членів розрізняють дві осі: хто постачає матеріал — автор записує його або вказує, звідки його отримати, або цільовий рушій повністю ним володіє, як у випадкуcore/generated-secret, — і що дає приєднання: впроваджене значення, ресурс, на який можна посилатися, або взагалі нічого відрендереного. Кожен член рівноправний з іншими на тій самій поверхні приєднання, тож обліковий слот завжди прив’язаний, а між Releases різниться те, що його прив’язує. Облікова Feature, яка оголошує контрактschema.provides, зобов’язує кожну FeatureRecipe, що її реалізує, публікувати ці ключі — інакше збірка зупиняється, — аselectorслотаfeaturesSchemaнацілюється на потрібного йому члена сімейства.usesSchema(необов’язково): оголошує топологічні сокети, які Feature може споживати (наприклад, сокетpath/keyоблікової Feature, націлений на сховище секретів). Механізм Split Schema описано в architecture/13-catalog-and-registry.md §2.schema: валідує блокиvaluesіinfraприєднання Feature — когнітивний намір, який Developer налаштовує на кожному приєднанні в Aggregate (values— це сфера Developer, і схема Release забороняєvalues:у приєднаннях Feature), і потужності, які Operator визначає для кожного середовища в Release (infra). Поле, що оголошуєdefault:, і валідується за ним, і заповнюється ним у відрендереному стовпі, коли його ніхто не задає; див. Обсяг Feature і форма створення. Приймає JSON Schema 2020-12, виражену в компактній скороченій формі YAML (за замовчуванням; див.vocabulary/compact-form-authoring.md) або в повному YAML JSON Schema, з міждокументними$ref:на записи SchemaLibrary для спільних форм (див.vocabulary/cross-document-ref.md). Лист, що містить секретний матеріал, оголошуєsensitive: true— облікові Features стандартної бібліотеки позначають лист, що містить матеріал, і навмисно залишають свої опубліковані локатори непозначеними, оскільки ім’я ресурсу і ключ даних є публічними. Ключове слово та межу того, чого досягає його оголошення, описано вvocabulary/compact-form-authoring.md, розділ «Declaring a leaf sensitive».featuresSchema(необов’язково): оголошує слоти приєднання, потрібні Feature для власної роботи — Feature оголошує слоти так само, як Component, тож Feature, якій самій потрібні облікові дані (наприклад, ключ API Feature бічного контейнера Datadog), називає точку прив’язки, а не звертається до слотів хост-сутності Component. Приклад того, як Feature оголошує власний слот, а FeatureRecipe читає те, що його заповнює, див. у розділі Власні облікові дані Feature. Кожен слот приймає ті самі поля, що й слотfeaturesSchemaсутності Component, з тією самою семантикою — зокрема необов’язковийselector(селектор міток у стилі Kubernetes, що обмежує, яка Feature може заповнити слот, — аналог селектора сокетаusesSchemaдля слота; заповнення, мітки якого йому не відповідають, зупиняє збірку, і селектор обчислюється лише за мітками приєднаної Feature), необов’язковийsensitive(оголошує, що все, що прив’язує слот, обробляє секретний матеріал, — твердження про точку прив’язки, а не про якесь конкретне заповнення), і ту саму відкритість: оголошення слота ніколи не забороняє приєднання під іменем, якого не оголошує жоден слот. Повна таблиця полів, оголошення чутливості на рівні слота та його відмінність від оголошення листа схеми, а також дві форми, у яких розгортається одна сутність з оголошеними слотами, описано в entities/component.md «Attachment Slots».appliesTo/appliesToAnyOf: селектори міток, що визначають, до яких Components може приєднуватися Feature. Обчислюються вбудованим рушієм зіставлення міток компілятора на етапі статичного аналізу. Довідку щодо синтаксису селекторів див. у розділі Приєднання за мітками нижче та в architecture/13-catalog-and-registry.md §2 «Kubernetes-Style Selectors».interoperability(необов’язково): вкладений блок, що міститьconflictsWith— ті Features, разом із якими ця Feature не може потрапити до одного компонента. Збірка зупиняється до рендерингу, коли один компонент зрештою містить обидві, незалежно від того, на якому рівні кожну з них було приєднано. Повний опис див. у розділі Блокinteroperabilityнижче.
Структурний рендеринг Feature прив’язаний до відповідної їй FeatureRecipe, яка відображає інтерфейс Feature на конкретну реалізацію інфраструктури.
Приєднання на основі міток
Два applies-селектори в схемі Feature визначають, до яких Components приєднується Feature; їх обчислює власний механізм зіставлення міток компілятора на етапі статичного аналізу:
appliesTo— рядок селектора міток у стилі Kubernetes; поверхня композиції через AND. Усі вимоги, розділені комами, мають виконуватися, з повним набором операторів:key=value,key!=value,key in (v1, v2),key notin (v1, v2), простоkey(мітка присутня),!key(мітка відсутня). Feature, що оголошуєappliesTo: "datastore.aggrega.ai/engine=vector", приєднується лише до Components, позначених саме цією парою ключ-значення;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"виражає «будь-який server або worker, що не містить даних з обмеженим доступом» в одному рядку селектора.appliesToAnyOf— поверхня композиції через OR. Список елементів селектора, де достатньо збігу будь-якого одного елемента. Кожен елемент — або селектор у рядковій формі (та сама граматика, що й уappliesTo; вимоги всередині рядка об’єднуються через AND), або пласка мапа ключ-значення для зіставлення лише на рівність. Використовується, коли Feature підходить для кількох не пов’язаних між собою форм компонентів — наприклад, Feature спостережуваності, що застосовується або до{ component.aggrega.ai/type: worker }, АБО до{ component.aggrega.ai/type: task }, без потреби зводити їх в один рядок селектора.
Без форми any-of архітекторам довелося б дублювати той самий YAML сутності Feature для кожної не пов’язаної форми компонента, якій підходить Feature. Обидві форми поєднуються: Feature може оголосити обидві, і результати об’єднуються через AND між формами — рядок appliesTo має виконуватися і щонайменше один елемент appliesToAnyOf має збігтися. Пропущений або порожній селектор не оголошує жодного обмеження і збігається з будь-яким набором міток.
Рядок селектора зчитується відповідно до шести форм щоразу, коли обчислюється приєднання Feature, і вимога поза ними зупиняє збирання, а не зчитується як якийсь інший селектор: порожня вимога (початкова, кінцева чи подвоєна кома або рядок, що складається лише з роздільників), ключ, що містить пробіли або будь-що з =, !, (, ) і коми, а також незакритий набір in ( чи notin (. Саме це виявляє помилки, які інакше непомітно вибрали б протилежне задуманому: appliesTo: "!tier=frontend", написаний, щоб не допустити Feature до фронтендів, відхиляється, бо ! називає лише ключ мітки — значення виключають через tier!=frontend, — а tier in frontend відхиляється на користь tier in (frontend). Значення — це текст після оператора, хоч які символи він містить, тож tier==frontend шукає мітку зі значенням =frontend. Зупинка називає Feature, її селектор і вимогу, яку не вдалося прочитати. Feature, яку ніщо не приєднує, ніколи не обчислюється, тож про некоректний селектор у ній не повідомляється, доки на неї не посилається приєднання.
Довідку щодо синтаксису селекторів див. в architecture/13-catalog-and-registry.md §2 «Kubernetes-Style Selectors» — граматика, яку приймає селектор Feature, та сама, що її приймають селектори сокетів usesSchema, — рядкова форма, знайома користувачам Kubernetes з kubectl get -l.
Блок interoperability
Схема Feature оголошує необов’язковий блок spec.interoperability, що містить один параметр керування: з якими іншими Features цей Feature може співіснувати на компоненті.
interoperability.conflictsWith — список Features, взаємовиключних із Feature, що визначається; кожен записано так, як поле type вкладення називає Feature. Він запобігає генеруванню несумісних конфігурацій — наприклад, вкладенню на той самий компонент і mesh лише для TCP, і проксі з підтримкою HTTP.
Збірка зупиняється, ще нічого не відрендеривши, коли один компонент зрештою несе цей Feature і Feature, названий у його списку. Важить охоплення: вкладення охоплює компонент, на якому його записано, і кожен компонент усередині підсистеми чи межі, на якій його записано, включно з вкладеними межами; вкладення, записане в записі компонента сутності Release або створене розгортанням на основі анотацій, охоплює свій компонент так само. Тож оголошений конфлікт зупиняє збірку, коли два Features вкладено в той самий компонент, коли один на межі, а інший на компоненті всередині неї, коли один на зовнішній межі, а інший на вкладеній у неї межі, що містить компонент, і коли один на підсистемі, а інший на компоненті цієї підсистеми. Два Features, вкладені в сусідні межі без спільних компонентів, ніколи не зустрічаються, а межа без компонентів нічого не охоплює — жоден із цих випадків не зупиняє збірку.
- Достатньо одного оголошення. Збірка зупиняється, коли список будь-якого з двох Feature називає інший; другий Feature не мусить у відповідь називати перший.
- Імена, незалежно від версій. Кожен запис і тип кожного вкладення порівнюються без версії, тож запис
core/fixed-replica-controllerзбігається з вкладеннямcore/fixed-replica-controller:2.0.0, а запис із версією збігається з кожною версією Feature, який він називає. - Читаються лише імена. Компілятор порівнює імена, оголошені автором Feature, із Features, які несе компонент, — та сама різновид обчислення, що й
appliesTo, над даними, які написав автор. Чи несумісні два Features — вирішує автор, а список є місцем, де це рішення зафіксовано.
Повідомлення про зупинку називає Feature, чий список називає інший, кожне місце, де було вкладено кожен із двох, — на компоненті в сутності Aggregate, на підсистемі, на межі сутності Release із її шляхом, у записі компонента сутності Release або через розгортання на основі названої анотації, — і компонент, де вони зустрічаються. Пара, що зустрічається на кількох компонентах, повідомляється один раз для кожного. Текст повідомлення див. у errors/fatal-halts.md.
Приклад:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerЦей Feature вкладається лише в Components типу server і оголошує несумісність з іншим Feature, що керує репліками: збірка, у якій будь-який компонент зрештою несе обидва, зупиняється до рендерингу. FeatureRecipe, якому потрібне ім’я компонента, до якого його вкладено, — наприклад, щоб спрямувати автомасштабувальник на його ціль, — читає його зі свого контексту шаблону й записує туди, де воно потрібне у виводі: .context.instance_id — це ідентичність компонента, а .context.rendered_name — ім’я, яке власний провайдер компонента дає ресурсам, що рендерить для нього, і саме за ним слід націлюватися на ресурс — для helm це ім’я Deployment, який створює синтезоване навантаження, і ім’я релізу, з якого чарт будує власні імена.
Успадкування через extends
Сутність Feature може оголосити spec.extends: <feature-name>, що вказує на базову сутність Feature, поверхню авторингу якої вона успадковує. Посилання називає базову сутність за її metadata.name, а не за координатою реєстру, під якою публікується Feature, і приймає ті самі три форми версії, що й будь-яке посилання на каталог: без версії (core/queue) — для найвищого доступного релізу, точну (core/queue:1.0.0) або діапазон із кареткою (core/queue:^1.0.0). Компілятор обходить ланцюжок батьків під час завантаження каталогу, перевіряє, що ланцюжок ациклічний, а потім зливає специфікації батьків у дочірню, щоб отримати одну розв’язану сутність Feature. У разі збігу ключів перевагу мають поля, написані в дочірній сутності; батьківські metadata.labels і metadata.annotations, селектори appliesTo / appliesToAnyOf, блок interoperability, usesSchema, featuresSchema і оголошення JSON Schema 2020-12 у schema автоматично зливаються донизу. Кожне інше поле metadata береться з дочірньої сутності дослівно, тож ідентичність і походження ніколи не успадковуються.
Що успадковує metadata: сутності Feature. labels і annotations зливаються за ключами вздовж ланцюжка, починаючи з базової, причому для спільного ключа перемагає значення сутності Feature, що розширює, — те саме правило, якого дотримуються Components. Решта metadata: не переноситься: name, version, description, maintainers, license, repository, home і keywords належать самій сутності Feature, що розширює, точно так, як їх написано.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Злита core/kafka-queue успадковує appliesTo від батьківської, успадковує властивості values.qos і infra.partition_count і додає зверху values.compression_codec. Дочірня сутність, що явно оголошує appliesTo, повністю перевизначає батьківський селектор (злиття селекторів міток не глибоке — селектор дочірньої сутності замінює батьківський). schema.values.qos дочірньої сутності перевизначає батьківське оголошення цієї властивості.
Як успадковується кожна частина поверхні прикріплення. Дві форми селекторів успадковуються незалежно одна від одної, бо вони поєднуються, а не замінюють одна одну: кожна наявна форма має виконуватися — рядок appliesTo має збігтися, і має збігтися щонайменше один елемент appliesToAnyOf, — тоді як відсутня форма нічого не обмежує. Тож Feature може взяти AND-селектор своєї базової сутності й водночас оголосити власний OR-набір. Блок interoperability успадковується поле за полем: дочірня сутність, що оголошує блок без списку conflictsWith, усе одно містить список, оголошений її базовою, тоді як дочірня сутність, що оголошує власний conflictsWith, замінює список базової, а не доповнює його. Feature, що не оголошує жодного з трьох, прикріплюється саме там, де прикріплюється її базова сутність.
Успадкування — це злиття схем, а не прив’язка до інтерфейсу. Ланцюжок extends: сутності Feature створює одну розв’язану Feature, а не поліморфну родину. URI базової Feature з ланцюжка — не те, на що посилається поле feature: прив’язки Manifest: Manifests прив’язуються за URI кінцевої Feature, а розв’язана схема містить успадковані властивості. Контракт Feature, який FeatureRecipe implements:, так само є URI кінцевої сутності; FeatureRecipes не обходять ланцюжок успадкування.
aggrega pull отримує базу. Базова сутність Feature є залежністю кожної сутності Release, що приєднує сутність Feature, яка її розширює, незалежно від того, чи називає її щось інше. aggrega pull проходить кожен extends: до кінця ланцюжка, отримує з реєстру базу, якої немає в жодній директорії каталогу, і записує кожну базу в lock-файл сутності Release з посиланням зі spec.extends сутності Feature, що її називає; збірка читає базу звідти.
Режими помилок. Циклічний ланцюжок extends: і батьківська сутність, яку не надає жодна сутність каталогу, зупиняють збірку, називаючи Feature, з якої почалося розв’язання, Feature, чий рядок extends: слід відкрити, і посилання, яке вона оголошує. Повідомлення наведено в Cyclic extends on Components or Features (Циклічний extends у сутностях Component або Feature) і An extends: chain cannot be assembled (Ланцюжок неможливо зібрати).
Ширшу лексику успадкування та інтерфейсів для Components, Features і облікових Features див. у vocabulary/inheritance-and-interface.md.
Компонованість: суспільний договір про чистоту
Домовленість стандартної бібліотеки — одна сутність Feature, одна внутрішня функція: sidecar спостережуваності — це Feature спостережуваності; sidecar мережевого проксі — це Feature мережевого проксі; вони не об’єднуються в один композит із двома непов’язаними завданнями. Ця домовленість зберігає окремі Features компонованими, незалежно версіонованими та незалежно приєднуваними.
Основний компілятор на Go не забезпечує дотримання цієї домовленості. Визначення Feature зі змішаними завданнями синтаксично допустимі й компілюються без помилок. Перевірка вмикається за бажанням:
- Підприємства, які створюють внутрішні каталоги, можуть написати власний плагін-лінтер, що перевіряє визначення Feature у CI/CD і попереджає, коли мітки
appliesToоднієї сутності Feature охоплюють непов’язані домени можливостей. - Автор Feature, який фіксує в
interoperability.conflictsWith, що дві сутності Features перекриватимуться, вмикає перевірку під час збирання: компілятор зупиняється скрізь, де обидві потрапляють на один компонент. Він порівнює лише оголошені імена й нічого більше, тож забезпечує дотримання оголошення, яке написав автор, а не самої домовленості про чистоту.
Відкриті Features стандартної бібліотеки дотримуються домовленості про чистоту завдяки дисципліні авторів; корпоративні каталоги можуть відступати від неї, коли тісно пов’язаний композит справді відповідає моделі розгортання.
Що заслуговує на Feature і де місце власного регулятора продукту
Feature — це приєднання: воно привносить те, що розробник або оператор приєднує свідомо, — ресурси, крок конвеєра, зв’язування, — і домовленість стандартної бібліотеки полягає в тому, що його мають підтримувати щонайменше два незалежні продукти. Саме ця друга половина є перевіркою, яку слід застосувати перед створенням Feature, бо переносність — це те, що обіцяє слово приєднання. Приєднання означає, що можливість переноситься: приєднайте її до одного компонента, приєднайте до іншого, і реалізація кожного продукту підтримає її у власних термінах.
Можливість, яку має лише один продукт на ринку, — це власний регулятор цього продукту, а не Feature. Її місце — авторське значення на власній поверхні цього продукту, яке задає автор, що ухвалює це рішення, у своєму стовпі, і яке читається поруч з усім іншим, що налаштовує той самий продукт. Якщо натомість опублікувати її як Feature, це пропонує переносність, якої не може забезпечити жоден інший продукт: приєднання за побудовою називає один продукт, тож автор, який приєднає його до наступного обраного продукту, отримає збірку, що зупиняється з назвою типу, а Feature навчила можливості, якої ніколи не мала.
Перевірка рахує продукти на ринку, а не компоненти в цьому каталозі, і кожен із них оцінюється за його власним актуальним довідником конфігурації. Два незалежні продукти, що реалізують можливість, роблять її переносною незалежно від того, скільки з них постачається тут, тож Feature можна оголосити ще до того, як щось у каталозі її реалізує, — тоді її приєднання зупиняє збірку з назвою типу, — а кожна постачена реалізація є FeatureRecipe для одного продукту, що підтримує приєднання так, як цей продукт його налаштовує.
Закріплення сертифіката upstream — показовий приклад. Закріплення (pin) — це контроль над тим, який ключ може пред’явити upstream: приймати лише сертифікат, відкритий ключ якого збігається з ключем, який надає Release. Це інше твердження, ніж вимога, щоб сертифікат upstream вів ланцюжком до якоря довіри, який надає Release, і ще інше, ніж твердження про те, що каже суб’єкт сертифіката: обидва вони визначають, що сертифікат має казати, тоді як закріплення визначає, яким ключем він має бути. Кілька шлюзів тут можуть перевіряти за якорем, саме тому dataplane.aggrega.ai/upstream-tls: trust-anchor — це значення, з яким може збігтися селектор. Закріплення — окрема можливість, і щонайменше два незалежні продукти реалізують її для з’єднань, які вони відкривають до upstream: Tyk приймає відкритий ключ upstream у форматі PEM, а Envoy — його хеш. Тож це Feature, core/upstream-key-pinning, селектор якої називає dataplane.aggrega.ai/upstream-pinning: public-key, а те, що реалізує цей каталог, визначається продукт за продуктом: core/gateway/tyk містить значення і FeatureRecipe для кожної своєї цілі, тоді як шлюзи тут, що вбудовують Envoy, надають його налаштування закріплення лише для сертифікатів, які пред’являють клієнти, або не надають зовсім, тож вони не містять значення, і приєднання до них зупиняється на селекторі. Закріплення звужує те, що може пред’явити upstream; це контроль, а не гарантія того, що з’єднання в іншому надійне.
Перевірка має дві межі, і другу найлегше втратити:
- Це дисципліна авторства, а не перевірка компілятора. Feature, що оголошує опції, яких не реалізує жоден продукт, однаково проходить валідацію схеми, лінтер публікації та рендеринг — компілятор не інтерпретує, що обіцяє Feature. Судження залишається за автором каталогу.
- Нездатність одного продукту підтримати опцію не є підставою відкинути цю опцію. Якщо два або більше продуктів постачають можливість під назвами, які можна згрупувати, можливість є переносною і Feature її зберігає; продукт, що не може її підтримати, від неї відмовляється. Feature, урізаній до того, що підтримує кожен продукт, майже нічого сказати.
Область дії Feature і форма її написання
spec.schema сутності Feature визначає власні форми Feature values: і infra: — когнітивний намір, який Developer налаштовує для кожного приєднання Feature в Aggregate (values), на відміну від чисел потужності, які Operator визначає для кожного середовища (infra). Стовпи Feature живуть у власних просторах імен і валідуються незалежно від стовпів сутності Component, що є хостом. Коли Developer приєднує Feature autoscaler до Component web-server в Aggregate, Aggregate містить values: сутності Component (форма хоста) плюс values: сутності Feature (форма наміру масштабування — яка метрика керує масштабуванням); числа потужності для оператора (min_replicas / max_replicas) передаються через блок infra: сутності Release у приєднанні Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10schema: сутності Feature валідує власні блоки values: і infra: приєднання Feature. schema: сутності Component валідує власні блоки Component. Обидві оцінюються незалежно на етапі статичного аналізу; стовп приєднання, що не відповідає schema: сутності Feature, зупиняє збірку з помилкою, прив’язаною до місця приєднання Feature, а не до Component-хоста. Валідується ефективна конфігурація приєднання — результат композиції всіх областей, що її налаштували, — тож значення, зроблене відповідним в одній області, а потім перевизначене на недопустиме у вужчій, буде виявлено.
Оголошені значення за замовчуванням матеріалізуються у відрендерених стовпах приєднання. Окрім валідації, default:, оголошений у полі values або infra сутності Feature, під час збірки заповнюється у відрендерений стовп цього приєднання для кожного ключа, який ніхто не задав, — тож шаблон FeatureRecipe, що читає {{ .infra.tier }}, отримує оголошене у схемі значення, а не порожнє. Значення, задані автором, завжди мають перевагу, а значення за замовчуванням заповнює лише ключі, які автор пропустив: приєднання, що задає один ключ схеми Feature, усе одно отримує оголошені значення за замовчуванням для інших ключів цієї схеми, а частково заданий вкладений об’єкт зберігає написане й отримує незаписані сусідні поля.
Під час написання варто знати три властивості цього заповнення:
- Значення за замовчуванням ніколи не витісняє значення, задане будь-якою областю. Якщо Feature приєднано в кількох областях — скажімо, на межі Release і в одному з його компонентів, — діє значення вужчої області, а значення за замовчуванням заповнює лише те, чого не записала жодна область.
- Значення за замовчуванням заповнює приєднання, але ніколи його не створює. Оголошення значень за замовчуванням у Feature, яку ніщо не приєднує, нічого не додає до виводу, тож схема Feature не може додати конфігурацію, якої не просив жоден автор.
- Приєднання, оголошене на межі Release, а не на окремому компоненті, заповнює лише
infra, оскільки ця поверхня не має блокуvalues:для заповнення.
Оскільки матеріалізація використовує те саме розв’язання схеми, що й валідація, значення за замовчуванням, оголошене в батьківській Feature, доходить до приєднань дочірньої сутності extends:, а значення за замовчуванням, досягнуті через міждокументне посилання $ref: у SchemaLibrary, також матеріалізуються. Значення за замовчуванням, оголошені лише всередині локального внутрішньодокументного посилання #/$defs/ або в гілці allOf / oneOf / anyOf, не матеріалізуються.
Один наслідок варто сказати прямо, бо сама валідація його не виявить: поле required:, яке також має default:, задовольняється цим значенням за замовчуванням, тож його пропуск допустимий — і значення, на якому перевірка пройшла, є тим значенням, яке містить відрендерений вивід.
Контекст шаблонів компілятора надає стан екземпляра Feature прив’язаній FeatureRecipe через поле .features.<alias> (що містить .type, .resolved_version, .labels, .values, .infra і .provides для кожного приєднання). Шаблони всередині FeatureRecipe читають власні values: сутності Feature через .values.<field> у власній області шаблонів FeatureRecipe; values: Component-хоста не видимі напряму шаблонам FeatureRecipe, якщо Feature явно не оголошує сокет uses: до Component-хоста.
Таке розділення областей робить Features компонованими: Feature autoscaler не залежить від того, до якої Component її приєднано; її schema: описує намір автомасштабування незалежно від хоста. values: Component-хоста — справа хоста; values: сутності Feature — справа Feature; два стовпи компонуються, не пропускаючи назви полів через межу.
Цілі прив’язок анотацій
Feature сама не оголошує прив’язок анотацій; їх містить мапа mappings.features.annotations у Manifest. Feature бере участь у відношенні прив’язки опосередковано, як ціль маршрутизації: кожна прив’язка називає тип Feature через своє поле feature:, а списки maps.infra і maps.values прив’язки оголошують шляхи через крапку до властивостей spec.schema.infra.<path> і spec.schema.values.<path> названої Feature.
Під час завантаження каталогу компілятор перевіряє, що кожен шлях через крапку у списках maps прив’язки відповідає властивості, яку spec.schema цільової Feature справді оголошує у названому стовпі. Прив’язка, що спрямовує на шлях, якого схема Feature не оголошує, зупиняє завантаження каталогу зі зрозумілою помилкою OPS_ERROR, яка називає прив’язку, цільову Feature, а також стовп і шлях, через які пройшла маршрутизація, — адже прив’язку записано в Manifest, тобто в документі оператора. Отже, автори схем знають, що будь-яка властивість, оголошена ними в spec.schema.values.<path> або spec.schema.infra.<path>, досяжна як ціль прив’язки; і навпаки, будь-яка властивість, через яку спрямовує прив’язка в Manifest, мусить існувати у схемі цільової Feature.
Коли анотація з боку Aggregate або з боку Release збігається з прив’язкою, компілятор синтезує приєднання Feature, корисне навантаження стовпів якого спрямовує значення анотації за названими шляхами. Синтезоване приєднання структурно не відрізняється від явного приєднання Feature, оголошеного автором у тому самому місці; подальший рендеринг, валідація та контекст шаблону FeatureRecipe однаково обробляють обидві форми. Про форму прив’язки, поділ «бік проти стовпа» та принцип переваги явного приєднання див. entities/manifest.md §«Annotation-Driven Feature Bindings». Про правило каскаду анотацій з боку Aggregate та приклад написання див. providers/well-known-annotations.md §«Aggregate-side annotation cascade».
Блок assertions:
Feature.spec.assertions: — це необов’язкова мапа іменованих правил, що виражають архітектурні інваріанти контракту сутності Feature: міжпольові правила над values: сутності Feature та розв’язаним станом приєднаної сутності Component. Кожен ключ — це ідентифікатор правила, який з’являється в повідомленні про помилку; кожне значення — тіло шаблону Go. Компілятор обчислює їх після валідації схеми й до рендерингу пов’язаного FeatureRecipe, у тому порядку, у якому їх записано, і перше правило, що не виконується, зупиняє збірку з власним повідомленням про помилку цього правила.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Як і твердження Component, твердження Feature виражають інваріанти рівня контракту — властивості, яким приєднання Feature має відповідати незалежно від того, який FeatureRecipe реалізує рендеринг. Для міжпольових правил, що залежать від конкретної реалізації (вимога Wasm-плагіна, особливість чарта), натомість використовуйте поле assertions: сутності FeatureRecipe. Повну граматику написання, контекст шаблону та розподіл відповідальності між твердженнями Feature і FeatureRecipe див. у templates/assertions-block.md.