Перейти к содержимому
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Физические метаданные на стороне эксплуатации, включая общеизвестные аннотации 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/* называет позицию на пути трафика, поэтому прокси, входной шлюз и сервисная сетка описывают себя одинаково. Измерение, действительно специфичное для одной роли, получает имя этой роли, как это делает 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 может доставить эти ресурсы: синтезирует ли она рабочую нагрузку, выпускает автономный набор артефактов или отрисовывает chart или фрагмент, предоставленный её автором. Поэтому запрос, выбирающий ресурсы присоединения по идентичности, возвращает их все, и ни один из них не неотличим от ресурса, выпущенного самим компонентом-хостом. Способ построения значения зависит от того, к чему присоединена сущность Feature; в любом случае результат — допустимая строка метки Kubernetes.

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

Идентичность говорит, к чему ресурс относится. Это иной вопрос, чем то, как ресурс называется, и для одного способа доставки ответы на них различаются:

  • Когда FeatureRecipe синтезирует рабочую нагрузку, Aggrega строит эти ресурсы сама и поэтому называет их тоже по идентичности: идентичность попадает в их metadata.name, их метки селектора и имена выпускаемых файлов, а не только в метки. Это имя внутри кластера, а не только метка.
  • Когда FeatureRecipe доставляет chart или фрагмент, написанный её автором, имена принадлежат тому, кто его написал. Имя релиза Helm, с которым отрисовываются эти шаблоны, и префикс файлов, выпускаемых этой отрисовкой, остаются именем компонента-хоста. Charts обычно называют свои ресурсы по имени релиза, поэтому его изменение переименовало бы ресурсы, объявленные самим chart, в кластере, где они уже развёрнуты, по причине, не имеющей отношения к chart. Метки при этом несут собственную идентичность присоединения, благодаря чему ресурсы присоединения остаются находимыми.
  • Когда сущность 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 любого вида: строчными буквами, цифрами и дефисом. Поэтому написанный вами дефис остаётся дефисом, строчная буква или цифра остаётся как есть, а всё остальное — включая заглавную букву, которую значение метки допускает, а имя ресурса отклоняет, — становится короткой escape-последовательностью: вложение с именем 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, раздел «Provenance labels emitted by providers».

Выходные метки, объявленные в 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 и шаблон пода при синтезе; объект при отрисовке исходников и для артефактов; метки сервисов compose; теги terraform для каждого ресурса в телах артефактов .tf.json) совпадает с размещением меток происхождения и полностью описано на странице сущности Recipe в разделах «Поле outputLabels:» и «Поле outputComponentLabels:».

Подключение Feature — пять точек

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

УровеньТочка выводаАвторОбласть действияПравило каскадирования
1Блок features: компонента в AggregateРазработчикДля каждого экземпляра компонента (детально)Нет — задаётся автором напрямую
2Блок features: подсистемы в AggregateРазработчикОбласть подсистемы (сквозная в пределах Aggregate)Распространяется на каждый компонент подсистемы
3Граница Release components.<id>.featuresЭксплуатацияДля каждого экземпляра компонента (детально, со стороны эксплуатации)Нет — задаётся автором напрямую
4Блок features: границы ReleaseЭксплуатацияОбласть границы (сквозная в пределах границы)Распространяется на каждый компонент границы
5Раскрытие features.annotations в ManifestОператор платформыПо аннотациям (синтетическое подключение)Распространяется по дереву границ (со стороны Release) или по дереву подсистем (со стороны Aggregate); действуют переопределение на уровне компонента и отказ через null для отдельного подключа

Пять точек накапливаются: подключение в любой из них входит в итоговый набор функций сущности Component. Если одно и то же имя экземпляра Feature встречается в нескольких точках, вклады сливаются в одно подключение, а не заменяют друг друга, а несовпадение типов между ними останавливает сборку с ошибкой конфликта слияния функций.

Пять точек введены намеренно в соответствии с разделением ответственности в архитектуре — разработчик (уровни 1–2), эксплуатация (уровни 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).

Перекрёстные ссылки

  • templates/template-context-contract.md — представление .context.labels и трёх корзин .context.annotations.* во время выполнения.
  • providers/well-known-annotations.md — матрица аннотаций границ по провайдерам и асимметрия выдачи меток происхождения.
  • entities/manifest.md — поверхность привязок features.annotations сущности Manifest (поверхность 6).
  • vocabulary/publishing-surface.md — единый словарь метаданных, дополняющий метки и аннотации на стороне публикации.
  • plugins/plugin-contract.md — критерий размещения в сокете линтера рекомендательных проверок чтения между корзинами.
  • architecture/06-data-taxonomy-and-composition.md — каноническая схема каскадных аннотаций.
  • architecture/10-compilation-pipeline.md — пятиуровневая луковичная модель, задающая порядок присоединения сущностей Feature.