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

extends та implements

Успадкування через extends

Сутності каталогу (Component, Feature) підтримують одиничне успадкування через ключове слово extends, яке дає змогу архітекторам платформи будувати спеціалізовані сутності на основі спільної бази. Глибоке злиття оболонки YAML спільне для обох видів: метадані, мітки та декларативні структурні таблиці сутності, що розширює базу, перезаписують відповідні ключі в базі, а вкладені мапи обробляються рекурсивно. Розходяться ці два види в стовпах даних.

Ця сторінка описує види каталогу, і вони не єдині види, що оголошують extends. Сутності Release і Manifest теж його оголошують, і обидві є документами на боці розгортання, які пишуть поруч одне з одним, а не сутностями, індексованими в каталозі, — тож їхні посилання називають файли, а не сутності каталогу, і зливається поверхня авторингу, а не схема. Для них див. entities/release.md і entities/manifest.md.

extends у сутності Component компонує структуру й успадковує стовпи повністю

Для сутності Component extends компонує metadata.labels, metadata.annotations, spec.featuresSchema (слоти приєднання), spec.usesSchema (сокети топології) і spec.inject (список дозволених самоін’єкцій, записи якого об’єднуються спочатку з бази, без дублікатів). Три стовпи даних — values, infra, provides — не компонуються. Сутність Component, що розширює базу, не містить вмісту стовпів: вона записує буквальний маркер schema: inherited і отримує блок schema: бази точно таким, яким його написала база, на будь-якій глибині ланцюжка.

Опублікована схема Component робить цей маркер водночас обов’язковим і винятковим та відхиляє кожне відхилення від нього під час завантаження документа, з окремою діагностикою для кожного: вміст стовпів, написаний у schema: сутності Component, що оголошує extends:; повна відсутність schema: там; і schema: inherited у сутності Component, що не оголошує extends:.

З цього випливають два наслідки, і вони тягнуть у протилежні боки:

  • Набір ключів визначає база. Сутність Component, що розширює базу, не оголошує ключів стовпів, тож не може приховати, вилучити чи змінити тип ключа, оголошеного базою, і не додає власних. Екземпляр бази та екземпляр будь-чого, що її розширює, перевіряються за тим самим контрактом стовпів.
  • Посилення переходить до assertions:. Спеціалізація, яка має допускати менше, ніж успадковані стовпи, виражає це як предикат щодо себе, а не як звужений лист схеми. Якщо база core/base-server оголошує tls_enabled: { type: boolean, default: true }, спеціалізація, що вимагає TLS безумовно, пише:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/tls-only-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
extends: core/base-server
schema: inherited # values, infra and provides are the base's, verbatim
assertions:
tls-is-mandatory: |
{{- if not .values.tls_enabled -}}
{{- fail "this component requires tls_enabled: true" -}}
{{- end -}}

Правило відхиляє значення, яке успадкований блок стовпа приймає, а це саме те, що тут означає посилення. Зворотний напрямок узагалі не має вираження: спеціалізація не може послабити успадковане обмеження, бо не може повторно оголосити лист, що його містить. Повну таблицю композиції та розібрану пару бази й розширення див. у entities/component.md, розділ «Catalog Authoring: Extending Base Components».

extends у сутності Feature компонує її стовпи

Для сутності Feature schema: дочірньої сутності компонується з базовою за семантикою композиції JSON Schema 2020-12, утворюючи єдину злиту схему, за якою перевіряється написаний екземпляр. Облікові Features — ті, що мають мітку feature.aggrega.ai/kind: secret, — використовують це, щоб будувати на спільній базі: дочірня облікова Feature розширює батьківську, щоб успадкувати її схему запитів до сховища секретів, звужуючи обмеження.

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

Прив’язка до інтерфейсу через implements

Recipes і FeatureRecipes прив’язуються до інтерфейсу Component або Feature за допомогою ключового слова implements: на початку свого spec. Прив’язка оголошує, конкретною реалізацією якого інтерфейсу каталогу є цей Recipe / FeatureRecipe, і підтримує три форми зіставлення версій:

  • Точна — implements: core/api-server:1.0.0 — відповідає одній конкретній версії типу Component.
  • Діапазон, сумісний за мажорною версією — implements: core/api-server:^1.0.0 — відповідає будь-якій версії, що задовольняє >=1.0.0, <2.0.0 (сумісність за мажорною версією SemVer). Використовується, коли Recipe підтримує сумісний діапазон, а не одну зафіксовану версію.
  • Без версії — implements: core/api-server — відповідає будь-якій версії типу Component. Використовується, коли Recipe обслуговує всі версії типу.

implements: ніколи не вибирає Recipe: це робить зіставлення в Manifest. Оголошення визначає перевірку узгодженості для кожного запису зіставлення — версія зіставленого типу має задовольняти implements: зіставленого Recipe в одній із трьох форм, або Recipe має реалізовувати базовий тип, який розширює цей тип, — а також список кандидатів, який пропонують діагностика відсутнього зіставлення та автодоповнення в редакторі. Запис зіставлення, чий Recipe має implements:, що не відповідає ні зіставленому типу, ні жодному з його базових, зупиняє збірку із зазначенням зіставлення, Recipe та значення його implements:. Коли ключ components.type охоплює екземпляр компонента у версії, якої ключ не називає, — кожен екземпляр, якщо ключ записано без версії, — перевірка виконується знову з власним типом цього екземпляра, у версії, в якій збірка його компілює, і Recipe, що її не задовольняє, так само зупиняє збірку із зазначенням екземпляра.

Прив’язка implements: — це механізм, завдяки якому працює принцип «той самий тип Component, різні Recipes для різних провайдерів»: Component core/postgres може мати один Recipe, що реалізує його для провайдера helm, і інший Recipe, що реалізує його для провайдера compose. Кожен Recipe оголошує те саме значення implements:, а Manifest, з яким збирається Release, зіставляє тип із тим, який йому потрібен.

Recipe, написаний для бази, обслуговує все, що її розширює

implements: називає базу, і Recipe, що її називає, є конкретною реалізацією для кожного Component, який розширює цю базу, на будь-якій глибині ланцюжка. Тож спеціалізація, побудована за допомогою extends, не потребує власного Recipe — саме це робить використання опублікованої обгортки дешевим: команда, що її публікує, створює Component, а команди, що її розгортають, повторно використовують Recipes бази на кожній цілі.

Тут одночасно діють два факти, і вони окремі. Читач, який зводить їх до «спеціалізації нічого не потрібно», пише Manifest, який не спрацьовує, і шукатиме причину не в тому файлі:

  • Recipe збігається. Перевірка узгодженості між ключем типу зіставлення в Manifest і implements: зіставленого Recipe приймає зіставлення, коли Recipe реалізує сам зіставлений тип або будь-яку базу, яку цей тип розширює. Три форми версій, описані вище, застосовуються до бази так само, як до самого типу: Recipe, що оголошує implements: core/base-server:^1.0.0, задовольняє спеціалізацію, база якої має версію 1.4.0, і не задовольняє ту, база якої має версію 2.0.0.
  • Manifest однаково зіставляє власний тип спеціалізації. Recipe вибирається за точним ключем зіставлення. Екземпляру enterprise/labelled-server потрібен власний запис mappings.components.type; він не успадковує запис, написаний для core/base-server. Спеціалізація без власного запису зупиняє збирання з діагностикою незіставленого екземпляра, навіть коли її базу зіставлено.

Отже, вартість створення спеціалізації — один рядок у Manifest і жодного нового Recipe:

# The wrapper extends core/base-server and authors no pillars.
# core/helm/base-server declares: implements: core/base-server
spec:
mappings:
components:
type:
enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0

Коли ланцюжок extends зіставленого типу неможливо пройти — він утворює цикл або названа в ньому база відсутня в каталозі, — збирання зупиняється на цій помилці ланцюжка, а не на зіставленні, бо зіставлення не можна оцінити, доки не розв’язано ланцюжок, від якого воно залежить. Перевірка проходить ланцюжок лише через Components, які вже є на цій машині, — ті, що в каталозі, і ті, що локальний кеш артефактів зберігає під закріпленням у lock-файлі, — і ніколи не звертається до реєстру, тож база, яка є лише в реєстрі, тут вважається відсутньою. Отримує її команда aggrega pull: база є залежністю всього, що її розширює, тож pull проходить кожен ланцюжок extends:, до якого сягає сутність Release, отримує кожну базу, якої немає в жодному каталозі, і закріплює її в lock-файлі, де її знаходить наступне збирання. Сутності Manifest не потрібен рядок для самої бази, якщо тільки сутність Aggregate також не оголошує екземпляр бази.

Підказки Recipe залишаються вужчими за це правило зіставлення. Список кандидатів, який виводить діагностика відсутнього зіставлення, і впорядкування, яке автодоповнення редактора застосовує до значення зіставлення, називають рецепти, що реалізують сам запитаний тип; вони не розширюються до рецептів, що реалізують одну з його баз.

Покроковий наскрізний приклад, який можна запустити, — опублікована обгортка в каталозі, один рядок у Manifest, що її використовує, Recipe бази, який формує її відрендерений результат, і зупинка, яку спричиняє екземпляр обгортки без власного зіставлення, — див. у прикладі examples/extends-wrapper/.

Використання версій між сутностями

Кожен вид сутності Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — має обов’язкове поле metadata.version, яке перевіряється тим самим регулярним виразом SemVer (MAJOR.MINOR.PATCH згідно з architecture/02-ecosystem-philosophy.md). Версії однакові за формою; використання версій залежить від виду сутності. Одні версії активно беруть участь у розв’язанні; інші є описовими даними про походження, з якими компілятор нічого не зіставляє. Таблиця нижче охоплює види, що не є бібліотеками: вона називає, що компілятор робить із полем версії кожної сутності, і класифікує кожен режим використання за чотирма мітками статусу з 10-status.md. Чотири види бібліотек не входять до таблиці, бо їхній режим однаковий і відмінний: споживач посилається на бібліотеку за самим іменем, може вказати необов’язкову мінімальну версію :<version>, а lockfile кожної сутності Release містить розв’язану версію та дайджест її вмісту.

СутністьРежим використанняСтатус
ComponentРозв’язання посилань на тип; зіставлення implements: сутності Recipeavailable — точна форма, діапазон із кареткою (^MAJOR.MINOR.PATCH) і форма без версії в обох випадках (див. Розв’язання версій і Статус → Зіставлення версій)
FeatureРозв’язання посилань на підключення; зіставлення implements: сутності FeatureRecipeТак само, як для Component
RecipeРозв’язання рівнів зіставлень Manifestavailable — точна форма, форма з діапазоном із кареткою та форма без версії у значенні зіставлення, кожна з яких вибирає найвищу відповідну версію
FeatureRecipeРозв’язання рівнів зіставлень ManifestТак само, як для Recipe
AggregateРозв’язання батьківського посилання aggregates[].typeavailable — точна форма, діапазон із кареткою і форма без версії, кожна з яких вибирає найвищу відповідну версію (див. Розв’язання версій)
PluginДиспетчеризація Provider через recipe.spec.capability → spec.provider.capabilitiesavailable — сама назва capability вибирає провайдера, а закріплення версії на ній (helm:<version>, helm:^<version>) вибирає, яка версія цього плагіна виконує рендеринг; ідентичність плагіна — це посилання oci://<repository> без дайджесту плюс metadata.version, а дайджест вмісту записується в lockfile релізу, за яким збірка перевіряє завантажені байти
ManifestПоходження в графі IR (manifest_version)available (читається лише для походження; не бере участі в диспетчеризації розв’язання)
ReleaseПоходження в графі IR (release_version) + метадані шаблонів (.metadata.release_version)Так само, як для Manifest

Режими розв’язання через каталог (Component, Feature, Aggregate, Plugin). Посилання на один із цих видів — type компонента, type підключення функції, aggregates[].type імпорту вкладеного агрегату, plugin кроку конвеєра — розв’язується за правилом, яке описує Розв’язання версій: точне посилання, діапазон із кареткою або посилання без версії вибирає найвищу відповідну версію серед тих, що є в каталозі, і завантаження, збірка, перевірка, редактор та інструменти для асистента однаково застосовують це єдине правило. Для Component або Feature зіставлення implements: читає ті самі три форми з іншого боку — конкретну версію типу проти форми, яку оголошує Recipe або FeatureRecipe, — як перевірку узгодженості, описану нижче, а не як вибір. Диспетчеризація плагінів Provider-rendering має простішу форму: вона шукає саме значення recipe.spec.capability у spec.provider.capabilities плагіна рендерингу провайдера за назвою, а закріплення версії, записане на capability, вибирає, яка версія цього плагіна виконує рендеринг, і зупиняє роботу, якщо жодна версія його не задовольняє.

Розв’язання рівнів зіставлень Manifest. Механізм розв’язання пласких mappings.{components,features} у Manifest (з рівнями name і type, де ім’я має перевагу над типом, а тип із версією — над типом без версії) описано в entities/manifest.md. Резолвер використовує ці зіставлення: вибір Recipe і FeatureRecipe — це прямий пошук значення зіставлення в lockfile і каталозі, а компонент чи підключення, тип якого не має зіставлення, зупиняє збірку. spec.implements не вибирає Recipe — це перевірка узгодженості під час завантаження для зіставлення, яке автор уже написав, і джерело списку кандидатів, який пропонують діагностика відсутнього зіставлення та автодоповнення в редакторі. Диспетчеризація можливостей далі випливає з поля spec.capability розв’язаної сутності Recipe, а не зі структурної форми Manifest.

Режими описового походження (Manifest, Release). metadata.version сутності Manifest і metadata.version сутності Release читаються, коли компілятор заповнює дані про походження, і з’являються в блоці походження графа IR як manifest_version і release_version; жодна мітка у відрендереному результаті їх не містить. Шаблони також бачать версію Release як .metadata.release_version. Жодна з цих версій не зіставляється з версією іншої сутності для диспетчеризації розв’язання; це суто дані про походження.

Як читати таблицю. Класифікація з чотирма мітками розрізняє «поле версії приймається схемою та існує в сутності» (завжди так — однаковий регулярний вираз SemVer) і «компілятор зіставляє цю версію під час розв’язання» (залежить від сутності).

Наскрізна передача між стовпами через міст схеми: від наміру до інфраструктури

Aggrega забезпечує чітке розділення відповідальності між доменом 1 і доменом 4: розробник пише когнітивну логіку в блоці values, а оператор визначає фізичні розміри в блоці infra. Схема Aggregate.yaml втілює один конкретний наслідок: ключове слово infra відсутнє в екземплярах компонентів сутності Aggregate і в їхніх приєднаннях features, а в поєднанні з additionalProperties: false воно відхиляється валідацією схеми. Розробникам не слід визначати фізичні розміри в намірі розробника; коли конкретне значення відповідає випадку застосунку (наприклад, жорстко заданий порт або конкретна кількість CPU), архітектор може явно відкрити його в декларації schema: сутності Component, і значення передається через values.

Для випадків, коли конкретне інфраструктурне обмеження є невіддільною частиною контракту компонента — високопродуктивна торгова база даних, якій потрібно 10 000 виділених IOPS, ML-навантаження, яке має працювати рівно на 4 GPU, — архітектори платформи відкривають це обмеження через спеціально створену сутність Component за шаблоном наскрізної передачі між стовпами через міст схеми.

Шаблон мосту схеми для компонентів, що враховують інфраструктуру. Сутність Component відкриває конкретний інфраструктурний параметр у блоці values розробника через свою декларацію schema:, а шаблон valuesMapping: прив’язаної сутності Recipe передає значення у відрендерений вивід у формі infra:. Результатом є типізований міст між когнітивним наміром і фізичними розмірами: розробник визначає апаратне обмеження через валідоване поле, а обмеження доходить до Ops, і жодній стороні не доводиться писати сирий інфраструктурний код. Цей параметр є ключем стовпа, тому його оголошують у сутності Component, контракту якої він належить, — сутність Component, що використовує extends: для базової, не оголошує ключів стовпів і тому не може додати новий.

# Domain 2: The Platform Catalog (the schema-bridge Component)
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/high-perf-postgres
version: 1.0.0
labels:
component.aggrega.ai/type: "stateful-server"
spec:
schema:
values:
# Expose the dial safely to the Developer with a typed contract.
required_iops: { type: integer, min: 1000, max: 100000, required: true }
infra:
# Operator-owned sizing the Recipe below reads alongside the dial.
storage: { size: { type: string, default: 100Gi } }
compute: { instance_class: { type: string, default: db.m5.large } }
# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-rds-high-perf-postgres
version: 1.0.0
spec:
implements: core/high-perf-postgres:^1.0.0
capability: terraform
source: ./modules/rds
valuesMapping: |
# The Recipe pipes the developer's values.required_iops into the provider's infra-side knob.
iops: {{ .values.required_iops }}
allocated_storage: "{{ .infra.storage.size }}"
instance_class: "{{ .infra.compute.instance_class }}"
# Domain 1: The Developer Intent (remains capability-agnostic)
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: 10000 # Developer dictates the hardware constraint safely

Масштабування між середовищами (вимога підняття параметрів). Щоб масштабувати це апаратне обмеження між середовищами GitOps (Dev і Prod), не змінюючи Aggregate.yaml розробника, розробник піднімає значення до типізованого контракту parameters. Ops задовольняє конкретну вимогу щодо IOPS через специфічні для середовища файли Release. Порядок виконання компілятора захищає цей потік: валідація контракту параметрів виконується під час розв’язання; інтерполяція підставляє параметр у навколишній рядок values:; шаблон valuesMapping: сутності Recipe передає розв’язане значення у відрендерений вивід.

1. Намір розробника (абстрагування параметра). Розробник знає, що йому потрібно керувати IOPS, але абстрагує конкретне число до рівня середовища через типізований контракт parameters.

spec:
parameters:
env_iops:
type: integer
min: 1000
max: 100000
description: Provisioned IOPS for the trading-db instance
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: {{ .parameters.env_iops }} # Hoisted to the environment

2. Сутності Releases у GitOps (виконання з боку Ops). Ops задовольняє контракт parameters у специфічних для середовища файлах Release. Типізований контракт валідує кожне значення, надане сутністю Release, до виконання інтерполяції.

  • Середовище Dev (release-dev.yaml): env_iops: 1000
  • Середовище Prod (release-prod.yaml): env_iops: 25000

Порядок компіляції. Цей механізм захищено суворим порядком виконання компілятора під час розв’язання:

  1. Валідація контракту параметрів. Кожне значення параметра, надане сутністю Release, валідується за типізованою декларацією parameters: сутності Aggregate. Значення Prod 25000 проходить валідацію (у межах min: 1000, max: 100000); значення 500 зупинило б збирання зі зрозумілою помилкою.
  2. Інтерполяція. Компілятор читає значення параметрів сутності Release для Prod та інтерполює 25000 у рядок YAML сутності Aggregate у values.required_iops. Об’єднана мапа параметрів залишається доступною протягом рендерингу, тож поверхні шаблонів шляхів можуть читати .parameters.<slot> напряму; поверхні шаблонів значень використовують літерал після інтерполяції, уже записаний у блок values: сутності Aggregate. Мапа залишається доступною для читання, доки не завершаться всі фази рендерингу, і досяжна лише з тієї компіляції, для якої її було розв’язано.
  3. Валідація схеми. Декларація schema: сутності Component валідує отриманий словник values:; values.required_iops: 25000 задовольняє обмеження схеми min: 1000, max: 100000.
  4. Рендеринг valuesMapping сутності Recipe. Шаблон valuesMapping: прив’язаної сутності Recipe передає values.required_iops у вивід провайдера у формі infra (iops: 25000). Плагін провайдера Wasm генерує правильну фізичну конфігурацію бази даних. Розробник отримує явний контроль над апаратним забезпеченням, Ops — масштабування для кожного середовища, а Aggregate залишається агностичним щодо можливостей.