Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Мітки та анотації

Сутності Aggrega мають два структурно подібні механізми метаданих — metadata.labels і metadata.annotations, — а також поля з анотаціями, розкидані по поверхнях каскадування меж і прикріплення можливостей. Шість окремих поверхонь задають або переносять вміст анотацій і міток, і кожна має власні правила каскадування, власних споживачів і власні домовленості щодо префіксів. Ця сторінка описує всі поверхні в одному місці, визначає три семантичні групи, які надає контекст шаблонів під час виконання, називає дисципліну префіксів, якої слід дотримуватися авторам, і описує п’ять поверхонь прикріплення сутності Feature поруч одна з одною, щоб їх було видно разом із ширшим словником міток і анотацій.

Шість інструментів, що несуть анотації та мітки

Автори стикаються з мітками та анотаціями в шести різних інструментах. Кожен має власну область застосування, власне правило каскадування та власного споживача.

#ІнструментОбласть застосуванняПравило каскадуванняОсновний споживач
1metadata.labels сутності каталогуІдентичність окремої сутності (Component, Feature, Aggregate)Не каскадується на екземпляри; міститься в самій сутності каталогуaggrega search -l для Components і Features; мітки сутності Aggregate зберігаються в її документі, і жодна команда їх не читає
2metadata.labels сутності Component (внутрішні)Властивості окремого екземпляра сутності Component (component.aggrega.ai/type тощо)Каскадується в .context.labels кожного вузла IR після мутацій label-transformЗіставлення селекторів (оголошення selector: у usesSchema, що передаються як x-aggrega-selector: у синтезованій JSON Schema), логіка шаблонів Recipe
3metadata.annotations сутності ComponentРиси окремого екземпляра сутності Component, задані архітекторомКаскадується в кошик .context.annotations.catalog кожного вузла IRролі вердиктів керування (політики внутрішніх рис), логіка шаблонів Recipe
4annotations: сутності Aggregate / підсистемиКогнітивні метадані з боку AggregateКаскадується в кошик .context.annotations.aggregate кожного вузла IRvaluesMapping: у Recipe для когнітивної маршрутизації
5annotations: межі ReleaseФізичні метадані з боку Ops, зокрема загальновідомі анотації aggrega.ai/*Каскадується в кошик .context.annotations.release кожного вузла IRProviders (helm читає aggrega.ai/namespace; compose виводить назву мережі з того самого ключа); injectMapping: у FeatureRecipe для маршрутизації між межами
6Прив’язки features.annotations у ManifestПрив’язка ключа анотації до типу Feature з маршрутизацією підключів, згрупованих за стовпами (maps.infra / maps.values), для приєднання Feature на основі анотаційПідфаза розгортання анотацій під час розв’язання обходить межі Release (ззовні всередину) та підсистеми Aggregate (ззовні всередину); діють перевизначення для окремого компонента та відмова через null для всього значення / окремого підключа; перевірка відповідності боку та стовпа визначає, який стовп спрацьовує для кожного боку авторстваРозгортання Feature на основі анотацій (синтетичні приєднання Feature, що записуються в граф IR з origin: annotation)

Інструменти 4 і 5 мають однакову форму YAML (мапа annotations: на каскадній межі), але каскадуються в різні кошики IR — розрізнення кошиків є ключовим правилом, яке надає середовище виконання. Інструмент 6 структурно відокремлений: він міститься в сутності Manifest, а не у вмісті Aggregate / Release, і його споживання регулюється проходом розгортання на основі анотацій.

Семантика трьох кошиків .context.annotations.*

Коли рендерер обчислює шаблон сутності Recipe, поле .context.annotations кожного вузла містить три іменовані кошики. Кожен кошик — це плоска мапа string → string з ключами-назвами анотацій; кошик визначає, хто створив анотацію і яке її призначення.

  • .context.annotations.release — анотації межі Release (інструмент 5). Використовуються для керування фізичними реаліями; рендерери за потреби спрямовують їх у поля infra:. Загальновідомі анотації aggrega.ai/* містяться в цьому кошику.
  • .context.annotations.catalog — анотації метаданих сутності Component (інструмент 3). Незмінні внутрішні ознаки, створені архітектором; переважно їх використовують політичні плагіни Wasm.
  • .context.annotations.aggregate — анотації підсистем Aggregate (інструмент 4). Когнітивні метадані; рендерери за потреби спрямовують їх у корисні навантаження values:.

Розділення на три кошики — це суспільний договір

Компілятор не забезпечує дотримання меж кошиків. Три кошики мають однакову плоску форму string → string; шаблон сутності Recipe може читати всі три, і ніщо не заважає інтерпретувати анотацію межі Release як поле когнітивних метаданих або спрямувати анотацію каталогу в infra:. Розділення — це дисципліна авторства, а не гарантія компілятора.

Мета дисципліни — те, що кошики мають виражати:

  • release = «де працює цей компонент, під керуванням Ops»
  • catalog = «чим є цей компонент, створено архітектором»
  • aggregate = «що робить цей компонент, створено розробником»

Коли автори дотримуються розділення, подальші інструменти можуть читати потрібний кошик для відповідного завдання. Коли автори порушують його (наприклад, розміщують когнітивні метадані в анотаціях release, бо файл Release зручний), середовище виконання все одно працює, але призначення кошика розмивається.

Сокет лінтера — позначення читання між кошиками

Плагін-лінтер (позасмуговий, рекомендаційний; критерій розміщення див. у plugins/plugin-contract.md) може позначати читання між кошиками, коли шаблон сутності Recipe бере дані з кошика, призначення якого не відповідає полю, що заповнюється. Критерій:

  • Читання .context.annotations.release для заповнення поля values: — позначити (когнітивні метадані мають надходити з кошика aggregate).
  • Читання .context.annotations.aggregate для заповнення поля infra: — позначити (фізичні метадані мають надходити з кошика release).
  • Читання .context.annotations.catalog для заповнення values: або infra: — зазвичай лише рекомендація (анотації каталогу є внутрішніми ознаками; спрямування їх у стовпи незвичне, але не завжди хибне).

Лінтер публікації не має правила для цього критерію, і збірка його не перевіряє; це може зробити ваш власний плагін-лінтер через сокет лінтера, який запускає aggrega lint. Цю дисципліну підтримують рецензенти та автори, які дотримуються домовленості про призначення кошиків.

Дисципліна префіксів

Ключі анотацій і міток мають однорідну форму <namespace>/<name>. Наведені нижче родини префіксів показують, хто створює ключі в кожній із них і як це підтримується — один префікс зарезервовано, і збірка зупиняється там, де прив’язка Manifest або вихідна мітка Recipe заявляє новий ключ у ньому; решта є домовленістю каталогу, і ніщо не відхиляє ключ. Різниця між ними полягає в тому, чи зупиняється збірка, тож прочитайте середній стовпець раніше за інші.

ПрефіксХто створює тут ключіЯк це підтримуєтьсяПризначенняПриклади
aggrega.ai/Лише платформа AggregaЗарезервовано й примусово перевіряється. Ключі тут визначає платформа, а ви записуєте ті, які вона визначає, — наприклад, aggrega.ai/namespace на межі Release. Заявлення нового ключа в цьому префіксі зупиняє збірку: як прив’язка features.annotations у Manifest під голим префіксом, так і ключ вихідної мітки Recipe під ним у outputLabels: чи outputComponentLabels:. Анотація, записана під ним, яку платформа не визначає, не відхиляється: збірка її переносить, а якщо вона розташована на сутності Release, ціль, яка на неї не реагує, повідомляє про це попередженням. Див. errors/fatal-halts.md «A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Прив’язка анотації Manifest заявляє зарезервований префікс)» і «An output-label key uses a reserved namespace (Ключ вихідної мітки використовує зарезервований простір імен)».Нативні анотації платформи, які безпосередньо використовує провайдерaggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Офіційна стандартна бібліотекаДомовленість. Ніщо не відхиляє тут ключ; словник належить стандартній бібліотеці за згодою, а не завдяки перевірці.Скорочення анотацій Feature, прив’язані в features.annotations сутності Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Офіційна стандартна бібліотекаДомовленість. Ніщо не відхиляє тут ключ.Мітки внутрішніх ознак Component (тут розміщено ключ селектора component.aggrega.ai/type)component.aggrega.ai/type
aggregate.aggrega.ai/Офіційна стандартна бібліотекаДомовленість. Ніщо не відхиляє тут ключ.Мітки ідентичності сутності Aggregate на рівні модуляaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Офіційна стандартна бібліотека, а також підприємства у власних каталогахДомовленість. Ніщо не відхиляє тут ключ.Мітки можливостей — поведінкові виміри, за якими розрізняє селектор usesSchema або appliesTo сутності Feature. <role> називає аспект, до якого належить вимір: або роль компонента, або наскрізний аспект, спільний для кількох ролей.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Підприємство / спільнотаВідкрито. Створюйте ключі в домені, який ви контролюєте.Власні анотації та міткиacme.com/billing-tier, corp/cost-center

Автори власних анотацій використовують домен, який вони контролюють (зазвичай у стилі зворотного DNS). Створення ключів безпосередньо під aggrega.ai/ (без підпрефікса) зарезервовано для платформи; прив’язки features.annotations сутності Manifest також не можуть прив’язувати ключі безпосередньо під aggrega.ai/ — див. entities/manifest.md «Резервування префікса aggrega.ai/».

Іменування префікса можливості

Ключ можливості має вигляд <role>.aggrega.ai/<dimension>, і саме <role> — та частина, що потребує судження. Нею керують три правила, і перше найчастіше розуміють навпаки.

  • Називайте аспект, а не вид компонента, який першим його має. Коли вимір описує щось спільне для кількох видів компонентів, префікс називає спільний аспект, щоб наступний вид, який його набуде, повторно використав словник, а не вигадував паралельний. component.aggrega.ai/hosting — це аспект: хто керує базовим ресурсом; він описує базу даних і API моделі однаковими словами; dataplane.aggrega.ai/* називає позицію на шляху трафіку, тож проксі, вхідний шлюз і service mesh описують себе однаково. Вимір, справді специфічний для однієї ролі, отримує назву цієї ролі, як це робить model.aggrega.ai/capability.
  • Одне слово в нижньому регістрі, без дефіса, у префіксі. Дефіс належить до половини <dimension>, де складене слово читається природно (request-mirroring, data-class, upstream-licensing).
  • Вимір додають, коли він потрібен селектору, і кожне оголошене ним значення має компонент, який його несе. Кожне слово тут автор каталогу мусить вивчити, а автор Feature може зустріти, тож вимір заслуговує на своє місце, розрізняючи те, про що справді питає usesSchema або appliesTo. Значення, якого не несе жоден компонент, гірше за відсутнє: селектор, що його називає, проходить розбір, нічому не відповідає й нічого не повідомляє — тому значення, яке каталог не може продемонструвати, не входить до словника, доки його не понесе компонент. Винятком є ключ, значення якого — твердження середовища про те, як воно використовує власні компоненти, а не властивість продукту, і compliance.aggrega.ai/data-class — саме такий випадок: клас даних компонента залежить від того, як середовище використовує компонент, тож жодна сутність Component стандартної бібліотеки не несе жодного з його значень, і жоден сокет чи Feature стандартної бібліотеки не вибирає за ними. Ключ і його значення оголошено для того, щоб власні Components середовища та політики, які воно приєднує, мали одне написання; селектор або політика, що називає значення, знаходить відповідність лише в каталозі, чиї Components його несуть. policy-data-class-route показує одну таку сутність Component і політику, яка її читає.

Резервування і визначений платформою ключ — не одне й те саме

Резервування стосується голого кореня aggrega.ai/. Кожен простір імен <scope>.aggrega.ai/ під ним — окремий простір ключів, яким платформа не володіє, і саме це зберігає розширюваність словника каталогу: корпоративний каталог може створити acme.aggrega.ai/team, не конфліктуючи ні з чим, що проставляє збірка.

Утім, кілька ключів у цих відкритих просторах імен визначено платформою й читає збірка, і це не робить їхній простір імен зарезервованим:

  • component.aggrega.ai/type обов’язковий у metadata.labels кожної сутності Component і набуває одного зі значень фіксованого набору. Селектори зіставляють за ним; компілятор не розгалужується залежно від його значення.
  • features.aggrega.ai/requiredType.<label>, записаний у metadata.annotations сутності Component, оголошує, що має бути приєднано Feature названого типу. Збірка перевіряє цю вимогу щодо остаточного набору приєднань кожного вузла й зупиняється там, де ніщо її не задовольняє, — див. errors/fatal-halts.md «Required feature not attached (Обов’язкову функцію не приєднано)». Зверніть увагу на множину: features.aggrega.ai/ — окремий простір імен, відмінний від однини feature.aggrega.ai/ у таблиці вище, що містить скорочення прив’язок Manifest.

Розумійте різницю так: зарезервований префікс відхиляє ключ, який ви намагаєтеся визначити в ньому, тоді як визначений платформою ключ — це один названий ключ, про який знає збірка, розташований у просторі імен, де ви в іншому вільні створювати ключі. Кожен інший ключ під component.aggrega.ai/, features.aggrega.ai/ та іншими — це метадані, які збірка переносить без інтерпретації.

Один такий ключ у metadata.annotations сутності Component читає не збірка, а стандартний лінтер публікації: observability.aggrega.ai/metrics-credential вказує, як автентифікуються метрики продукту: none — вони віддаються без облікових даних; target-key — вони приймають ключ, якого Component вимагає від кожного клієнта; separate-token — вони приймають власний токен. Збірка переносить його як будь-яку іншу анотацію. Лінтер читає його, щоб визначити, чи порівнюються облікові дані з’єднання збору з ключем клієнта цілі, і вимагає його узгодженості з ключем provides metrics_credential_required, який оголошує Component, — див. «Правила дисципліни» в cli/aggrega-lint.md.

Мітки походження у відрендереному виводі

Окрім вхідних анотацій, які споживають провайдери, Aggrega також додає мітки походження до кожного маніфесту Kubernetes, який рендерить провайдер helm, і кожного згенерованого сервісу compose, а провайдер helm-chart записує той самий набір, так само як його записує провайдер helm, на кожен артефакт, який він завантажує через $import:. Цей набір міток дає змогу інструментам нижчого рівня (панелям витрат, стекам спостережуваності, контролерам GitOps) пов’язувати ресурси під час виконання з вмістом каталогу, який їх створив. Власні шаблони вкладеного чарта helm-chart копіюються так, як їх написав автор, тож вони несуть ті мітки, які написав цей автор.

Набір, який генерують провайдери helm і compose, — у helm три ключі записуються як анотації, а не мітки, як зазначено в таблиці:

МіткаДжерелоДодається завжди?
app.kubernetes.io/nameІдентичність Component — ім’я, яке ви написали, або, для компонента, який додає імпортована сутність Aggregate, його кваліфіковане ім’я з виписаним роздільником модуля (див. нижче); або, для ресурсу, який виводить FeatureRecipe, ідентифікатор, виведений для цього приєднанняТак для маніфестів Kubernetes; не додається до сервісів compose (стандартна мітка специфічна для K8s)
aggrega.ai/component-idІдентичність Component — ім’я, яке ви написали, або, для компонента, який додає імпортована сутність Aggregate, його кваліфіковане ім’я з виписаним роздільником модуля (див. нижче); або, для ресурсу, який виводить FeatureRecipe, ідентифікатор, виведений для цього приєднанняТак
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> сутності Recipe, що створила ресурс (або сутності FeatureRecipe для ресурсів, які додає FR)Коли для сутності, що створила ресурс, задано і ім’я, і версію; у helm — анотація
aggrega.ai/boundary-pathШлях межі, до якої спрямовано компонентКоли шлях межі непорожній; у helm — анотація
aggrega.ai/aggregate-namemetadata.name сутності AggregateКоли задано
aggrega.ai/compiler-versionВерсія компілятора, проставлена під час збіркиКоли задано
aggrega.ai/providerПровайдер, який відрендерив ресурс (helm, helm-chart, compose)Так
aggrega.ai/provider-versionВерсія цього провайдераТак
aggrega.ai/environmentmetadata.environment сутності ReleaseТак — кожна сутність Release його оголошує
aggrega.ai/sync-waveЦіле число syncWave для кожної межі — порядок, у якому інструмент GitOps застосовує ресурсиКоли не дорівнює нулю; у helm — анотація поруч з argocd.argoproj.io/sync-wave

Назва агрегату, середовище, версія компілятора, а також назва й версія провайдера — це рядки, які обрали ви або збірка, і жоден із них не підпадає під правила Kubernetes для значень міток у місці, де його записано. У helm кожна з цих міток містить значення в записаному вигляді, якщо воно вже є допустимим значенням мітки — літери, цифри, -, _ і ., літера або цифра на обох кінцях, щонайбільше 63 символи, — а інакше значення, переписане в допустиме, з дослівним значенням, доданим як анотація під тим самим ключем: сутність Aggregate з назвою imported/flow отримує мітку aggrega.ai/aggregate-name: imported-flow і анотацію aggrega.ai/aggregate-name: imported/flow. Значення, яке вже відповідає правилам, не додає анотації. Compose містить дослівне значення як мітку. Правило переписування наведено в providers/well-known-annotations.md «Мітки походження, які створюють провайдери».

Для ресурсів, які додає сутність FeatureRecipe, значення aggrega.ai/component-id будується з приєднання, а не з імені компонента-хоста — для кожного способу, яким FeatureRecipe може постачати ці ресурси: чи синтезує вона робоче навантаження, чи додає окремий набір артефактів, чи рендерить чарт або фрагмент, наданий її автором. Тож запит, що вибирає ресурси приєднання за ідентичністю, повертає їх усі, і жоден із них не є невідрізненним від ресурсу, який додав сам компонент-хост. Спосіб побудови значення залежить від того, до чого приєднано сутність Feature; у будь-якому разі результат є допустимим рядком мітки Kubernetes.

Для компонента, який додає імпортована сутність Aggregate, ідентичністю є кваліфіковане ім’я цього компонента, у якому роздільник між модулем і компонентом розписано — data-layer.main-db проставляється як data-layer-zdmain-db, — бо крапка не є символом, який ім’я ресурсу чи адреса в кластері можуть безпечно містити. Написане вами ім’я без роздільника проставляється байт у байт.

Ідентичність каже, чому ресурс належить. Це інше питання, ніж те, як ресурс називається, і для одного способу постачання відповіді на них різні:

  • Коли FeatureRecipe синтезує робоче навантаження, Aggrega будує ці ресурси сама, тож і називає їх за ідентичністю: ідентичність потрапляє в їхні metadata.name, мітки селектора та імена згенерованих файлів, а не лише в мітки. Це ім’я всередині кластера, а не тільки мітка.
  • Коли FeatureRecipe постачає чарт або фрагмент, написаний її автором, імена належать тому, хто його написав. Ім’я релізу Helm, з яким рендеряться ці шаблони, — і префікс файлів, які додає цей рендеринг, — залишаються іменами компонента-хоста. Чарти зазвичай називають свої ресурси за іменем релізу, тож його зміна перейменувала б ресурси, які оголошує сам чарт, у кластері, де їх уже розгорнуто, з причини, що не має жодного стосунку до чарту. Мітки все одно несуть власну ідентичність приєднання, завдяки чому ресурси приєднання можна знайти.
  • Коли сутність Feature приєднано до межі, немає компонента-хоста, ім’я якого могло б її замінити, тож складена ідентичність там є і основою імен, і міткою.

У будь-якому разі значення складається з написаних вами частин, з’єднаних --, після фіксованого початку, який вказує, який із двох це випадок. Використовуються два початки, і ідентичність компонента, яку ви пишете, не може починатися з жодного з них — саме це не дає сплутати написане вами ім’я з ім’ям, яке склала Aggrega.

Коли сутність Feature приєднано до компонента, частинами є фіксований початок cfr, ідентичність компонента, до якого приєднано Feature, і ключ, під яким її приєднано. Сутність Feature, приєднана до компонента api під mon, дає cfr--api--mon. Компонент-хост входить до значення, бо одне ім’я Feature, приєднане до кількох компонентів, додає окремий набір ресурсів на кожному, і кожному набору потрібна власна ідентичність: приєднання mon і до api, і до worker дає cfr--api--mon і cfr--worker--mon, а не одне значення для обох. З тієї ж причини приєднання, назване точно як компонент, що його містить, дає значення, відмінне від власного значення цього компонента — mon, приєднане до mon, дає cfr--mon--mon.

Коли сутність Feature приєднано до межі — канонічним прикладом є сервіс шлюзу compose-bridge, — частинами є фіксований початок bfr, потім кожен сегмент шляху межі, починаючи із зовнішнього, потім ім’я, під яким приєднано Feature. Сутність Feature з іменем gateway на межі bridge дає bfr--bridge--gateway; та сама Feature на межі prod/eu дає bfr--prod--eu--gateway.

Символ, якого значення не може містити, розписується, а не замінюється, і оскільки значення є не лише міткою, а й іменем усередині кластера, воно обмежене символами, які допускає ім’я ресурсу Kubernetes будь-якого виду: малими літерами, цифрами та дефісом. Тож записаний вами дефіс лишається дефісом, мала літера чи цифра лишається як є, а все інше — включно з великою літерою, яку значення мітки допускає, а ім’я ресурсу відхиляє, — стає короткою екранованою послідовністю: приєднання з іменем my_zone дає my-zuzone, а компонент myApi із приєднанням worker отримує cfr--my-zx000041pi--worker. Саме цим екранованим значенням ресурси приєднання позначаються й вибираються на кожній цілі, за ним іменується й зберігається у файли робоче навантаження, яке синтезує приєднання, і з нього виводиться ім’я релізу приєднання межі. Велика літера — єдиний символ, який правило імен ресурсів додає до того, що розписала б сама мітка, тож складене значення, частини якого не містять великих літер, — cfr--api--mon, bfr--prod--eu--gateway — збігається зі значенням, яке несла б сама мітка. Тому два приєднання, які ви можете розрізнити, отримують два значення — хоч як ви їх назвали і хоч як глибоко розташована межа, — оскільки -- є послідовністю, якої не може містити жодна записана частина, тож перенесення поділу між частинами змінює значення, а не спричиняє колізію.

Яку довжину може мати складене значення, визначає ціль, а не число, яке зберігає Aggrega: ціль, для якої рендеряться ресурси, опитується, і значення скорочується, доки ця ціль його не прийме. Значення мітки Kubernetes містить щонайбільше 63 символи, а ім’я релізу Helm, виведене з тієї самої ідентичності, обмежене ще сильніше, тож те саме приєднання може бути коротшим для однієї цілі, ніж для іншої. Значення, що вміщується, додається точно в складеному вигляді — це звичайний випадок і випадок кожного приєднання в каталозі стандартної бібліотеки. Значення, що не вміщується, скорочується: кожна частина зберігає свій початок, а десятисимвольний дайджест усієї ідентичності додається після маркера, якого не створює жодне ім’я, яке ви можете написати, — тож скорочене значення можна впізнати як таке, і його ніколи не можна прочитати як значення, що вмістилося. Тому глибоко вкладене приєднання gateway може рендеритися як bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Збіг двох скорочених значень дуже малоймовірний, а якщо він стається, збірка зупиняється, а не дозволяє двом із них мати одне ім’я.

Див. errors/fatal-halts.md «The same name is derived more than once inside the output (Те саме ім’я виводиться у виводі більш ніж один раз)», щоб дізнатися, які пари спричиняють зупинку і як їх розділити.

aggrega.ai/recipe-uri для ресурсу, який додає FR, вказує на власне name:version сутності FeatureRecipe, а не на ідентичність сутності Recipe, що її використовує, — тож інструменти нижчого рівня, які читають recipe-uri, щоб визначити сутність-джерело, отримують правильне походження і для виводу компонентів, і для виводу FR.

Подробиці додавання міток для кожного провайдера (куди у відрендереному виводі потрапляють мітки і як кожен провайдер їх серіалізує) див. у providers/well-known-annotations.md «Мітки походження, які додають провайдери».

Вихідні мітки, оголошені в Recipe

Окрім набору міток походження, яким володіє компілятор, автор сутності Recipe може оголосити власні мітки, що проставляються на відрендерений вивід цієї Recipe, через Recipe.spec.outputLabels:. Вони рухаються тим самим шляхом емісії, що й мітки походження — їх об’єднують у той самий набір міток, і вони потрапляють туди ж, куди й мітки походження, — але належать автору, а не компілятору. Призначення — ознака реалізації: властивість того, як конкретна Recipe реалізує компонент (наприклад, hosting: managed проти hosting: self-hosted для Recipe керованого сервісу проти Recipe самостійно розгорнутого чарту для того самого типу компонента), виведена на вивід, щоб інструменти обліку витрат, політик та інвентаризації могли робити за нею запити.

Простори імен aggrega.ai/ та app.kubernetes.io/ зарезервовано для набору міток походження; ключ із будь-яким із цих префіксів відхиляється під час завантаження — і в outputLabels:, і в outputComponentLabels:, супровідному блоці, який називає ключ мітки компонента і проставляє значення, оголошене самим компонентом. Тому перевірений набір вихідних міток завжди не перетинається з ключами походження, і в об’єднаному виводі вони ніколи не конфліктують. Перевіряється лише корінь: ключ з областю, як-от component.aggrega.ai/hosting, належить до власного простору імен і його можна записати буквально або підвищити. Розміщення для кожного провайдера (об’єкт і шаблон пода helm під час синтезу; об’єкт під час source-render та для артефактів; мітки сервісів compose; теги terraform для кожного ресурсу в тілах артефактів .tf.json) збігається з розміщенням міток походження і повністю описане на сторінці сутності Recipe у розділах «Поле outputLabels:» та «Поле outputComponentLabels:».

Приєднання Feature — п’ять інструментів

Features приєднуються до Components через п’ять окремих інструментів авторингу, кожен з власною областю застосування, цільовим користувачем і пріоритетом упорядкування в 5-рівневій моделі «цибулі». Повний порядок приєднання і саму модель «цибулі» описано в architecture/10-compilation-pipeline.md; таблиця нижче перелічує п’ять інструментів поруч.

РівеньІнструментАвторОбласть застосуванняПравило каскадування
1Блок features: компонента в сутності AggregateРозробникОкремий екземпляр компонента (детально)Немає — безпосередньо від автора
2Блок features: підсистеми в сутності AggregateРозробникОбласть підсистеми (наскрізно в межах Aggregate)Каскадується на кожен компонент підсистеми
3Межа Release components.<id>.featuresOpsОкремий екземпляр компонента (детально, з боку Ops)Немає — безпосередньо від автора
4Блок features: межі ReleaseOpsОбласть межі (наскрізно в межах межі)Каскадується на кожен компонент у межі
5Розгортання features.annotations у сутності ManifestОператор платформиНа основі анотацій (синтетичне приєднання)Каскадується деревом меж (з боку Release) або деревом підсистем (з боку Aggregate); діють перевизначення для окремого компонента і відмова через null для окремого підключа

П’ять інструментів накопичуються: приєднання, присутнє в будь-якому з них, додається до розв’язаного набору можливостей сутності Component. Коли те саме ім’я екземпляра Feature з’являється в кількох інструментах, внески зливаються в одне приєднання, а не замінюють один одного, а невідповідність типів між ними зупиняє збирання з помилкою конфлікту злиття можливостей.

П’ять інструментів — не надлишковість, а свідомий наслідок розподілу відповідальності в архітектурі: розробник (рівні 1-2), Ops (рівні 3-4), оператор платформи (рівень 5). Автори обирають інструмент відповідно до того, кому належить приєднання і в якій області.

Які мітки визначають, чи застосовується Feature

Feature оголошує, куди її можна приєднати, через spec.appliesTo і spec.appliesToAnyOf, і збирання перевіряє це оголошення щодо остаточних міток вузла, до якого потрапляє приєднання. Приєднання Feature до вузла, мітки якого цьому не відповідають, зупиняє збирання; Feature, що не оголошує жодного з цих полів, не висуває вимог і застосовується будь-де.

Остаточний набір міток формується у два кроки, і жоден з них не є тим, що автори найчастіше припускають.

  1. Вузол отримує мітки від сутності каталогу Component, яку називає його type:. Вони є властивістю типу компонента, а не екземпляра: ні Aggregate, ні Release не можуть позначити екземпляр компонента. Власні metadata.labels сутності Aggregate описують Aggregate як модуль для повторного використання і не каскадуються на компоненти всередині нього. Тож два екземпляри одного типу мають однакові мітки, і щоб змінити мітки вузла, треба змінити тип, на який він вказує, — або сутність цього типу.
  2. Потім приєднання label-transform може їх переписати. Якщо конфігурація робочого простору приєднує плагін керування в ролі label-transform, він виконується під час побудови топології і може додавати, змінювати або видаляти мітки вузлів, перш ніж щось перевірятиметься щодо них. Нічого іншого він змінювати не може, тож мітки — єдина частина вузла, яку він здатен змінити, — і саме від них залежить застосовність.

Тому пропозиція, зроблена на основі міток, оголошених в одному документі, є наближенням, а не прогнозом. Читання metadata.labels сутності Component показує, з якими мітками починає вузол цього типу; це досить часто правильна відповідь, щоб бути корисною, і хибна у двох конкретних випадках: документ, який лише має спільне ім’я з вузлом, — це інший суб’єкт з іншими мітками, а приєднання label-transform може змінити набір незалежно від будь-якого документа. Інструменти, що пропонують приєднання лише на основі вихідного коду, працюють із цим наближенням; рішення збирання ухвалюється щодо остаточного набору.

Пріоритет приєднань

Коли два внески задають те саме поле того самого приєднання, чотири правила визначають, який з них потрапить у відрендерений результат. Вони застосовуються в такому порядку, і саме порядок робить результат передбачуваним:

  1. Походження. Явно написаний внесок переважає внесок на основі анотації, незалежно від того, в якій області кожен з них оголошено. Записати поле в блоці features: — це спосіб, яким автор перевизначає те, що дала б анотація, і анотація ніколи непомітно не витісняє написане вручну. Компілятор записує придушену анотацію поруч із переможним значенням і повідомляє про неї як про рекомендацію, тож перевизначення видиме, а не загадкове.
  2. Власність стовпа. Кожен домен заповнює власний стовп: інструменти Aggregate додають values, інструменти Release додають infra. Оскільки дві сторони ніколи не пишуть у той самий стовп, внесок розробника і внесок оператора не можуть змагатися за одне поле — питання пріоритету між розробником і оператором просто не виникає.
  3. Повноваження композиції. Оголошення в сутності Aggregate, яку ви розгортаєте, має вищий пріоритет, ніж оголошення всередині Aggregate, яку вона компонує, навіть якщо скомпонована Aggregate оголосила його у вужчій області. Композиція залишається авторитетною: модуль не може переважити Aggregate, що його використовує, лише обравши вужчу область.
  4. Специфічність. У межах одного рівня авторингу та одного стовпа вужча область уточнює ширшу, поле за полем. Приєднання в області компонента перевизначає приєднання з тим самим ім’ям екземпляра в області підсистеми чи межі — але лише для полів, які воно справді згадує. Поля, пропущені вужчою областю, зберігають значення ширшої, тож спільне приєднання може задавати загальну конфігурацію, а окремий компонент — змінювати одне її поле. Два внески в одній області розв’язуються за порядком автора, і перемагає пізніший; саме це дає змогу внутрішній підсистемі уточнювати зовнішню, а глибшій межі — мілкішу.

Пріоритет визначає значення полів. Він не змінює порядок обчислення: послідовність, у якій компілятор згортає інструменти та виконує injectMapping кожного приєднання перед рендерингом, — це фіксована п’ятирівнева послідовність, описана в architecture/10-compilation-pipeline.md. Написаний автором блок inject приєднання дотримується цієї послідовності обчислення, а не наведеного вище ранжування областей, тож одне приєднання ніколи не має двох конкурентних порядків.

Які види мають metadata.labels і metadata.annotations

metadata.labels є в сутностях Component, Feature, Aggregate і чотирьох видах бібліотек; metadata.annotations — у тих самих видах, крім Aggregate. Сутності Manifest, Release, Recipe, FeatureRecipe і Plugin не мають жодного з них.

Підсумок каскадування

Правила каскадування для шести поверхонь у тому вигляді, як їх обчислює компілятор:

  1. Мітки сутностей каталогу (поверхня 1) залишаються на сутності каталогу. Вони не переходять до екземплярів; споживачі читають їх, безпосередньо переглядаючи вміст каталогу.
  2. metadata.labels сутності Component (поверхня 2) переходять у .context.labels кожного вузла після необов’язкового проходу label-transform під час побудови топології.
  3. metadata.annotations сутності Component (поверхня 3) переходять у кошик .context.annotations.catalog кожного вузла.
  4. annotations: сутності Aggregate / підсистеми (поверхня 4) каскадуються ієрархією підсистем, накопичуючись від зовнішніх підсистем усередину, у кошик .context.annotations.aggregate кожного вузла.
  5. annotations: меж сутності Release (поверхня 5) каскадуються ієрархією меж від зовнішніх меж усередину, у кошик .context.annotations.release кожного вузла.
  6. features.annotations сутності Manifest (поверхня 6) не каскадуються безпосередньо до даних IR кожного вузла; підфаза розв’язання, що виконує розгортання на основі анотацій, споживає прив’язки, щоб синтезувати для кожного вузла прикріплення сутностей Feature, які граф IR (--ir-graph) записує з origin: annotation. Після розв’язання синтетичні прикріплення структурно не відрізняються від явних, окрім як через це походження — повний опис розгортання див. у providers/well-known-annotations.md, а механіку під час завантаження каталогу та перевірки — у architecture/13-catalog-and-registry.md, розділ «Annotation-driven Feature expansion».

Канонічний дизайн каскадних анотацій див. у architecture/06-data-taxonomy-and-composition.md, §2 (потік 5).

Перехресні посилання