Перейти к содержимому
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.

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-рендеринга устроена проще: она ищет простое 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. Интерполяция. Компилятор читает значения параметров Prod-файла Release и подставляет 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 остаётся агностичным по отношению к возможностям.