Метки и аннотации
Сущности Aggrega несут два структурно схожих механизма метаданных — metadata.labels и metadata.annotations, — а также поля с аннотациями, разбросанные по точкам каскадирования через границы и точкам прикрепления фич. Шесть различных точек задают или несут содержимое аннотаций и меток, и у каждой свои правила каскадирования, свои потребители и свои соглашения о префиксах. На этой странице все эти точки описаны в одном месте, определены три семантические группы, которые предоставляет контекст шаблонов во время выполнения, названа дисциплина префиксов, которой следует придерживаться авторам, и рядом друг с другом описаны пять точек прикрепления сущностей Feature, чтобы их было видно вместе с более широким словарём меток и аннотаций.
Шесть точек размещения аннотаций и меток
Авторы встречают метки и аннотации в шести различных точках. У каждой своя область действия, своё правило каскадирования и свой потребитель.
| # | Точка вывода | Область действия | Правило каскадирования | Основной потребитель |
|---|---|---|---|---|
| 1 | metadata.labels сущности каталога | Идентичность отдельной сущности (Component, Feature, Aggregate) | Не каскадируется на экземпляры; хранится в самой сущности каталога | aggrega search -l для Components и Features; метки сущности Aggregate хранятся в её документе, и ни одна команда их не читает |
| 2 | metadata.labels сущности Component (внутренние) | Свойства отдельного экземпляра Component (component.aggrega.ai/type и т. д.) | Каскадируется в .context.labels каждого узла IR после изменений label-transform | Сопоставление селекторов (объявления selector: в usesSchema, передаваемые как x-aggrega-selector: в синтезированной JSON Schema), логика шаблонов Recipe |
| 3 | metadata.annotations сущности Component | Признаки отдельного экземпляра Component, задаваемые архитектором | Каскадируется в корзину .context.annotations.catalog каждого узла IR | роли вердиктов управления (политики внутренних признаков), логика шаблонов Recipe |
| 4 | annotations: сущности Aggregate / подсистемы | Когнитивные метаданные на стороне Aggregate | Каскадируется в корзину .context.annotations.aggregate каждого узла IR | valuesMapping: сущности Recipe для когнитивной маршрутизации |
| 5 | annotations: границы Release | Физические метаданные на стороне эксплуатации, включая общеизвестные аннотации aggrega.ai/* | Каскадируется в корзину .context.annotations.release каждого узла IR | Providers (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 сущности Manifest | feature.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-name | metadata.name сущности Aggregate | Когда задано |
aggrega.ai/compiler-version | Версия компилятора, проставляемая во время сборки | Когда задано |
aggrega.ai/provider | Провайдер, отрисовавший ресурс (helm, helm-chart, compose) | Да |
aggrega.ai/provider-version | Версия этого провайдера | Да |
aggrega.ai/environment | metadata.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, не объявляющая ни одного из этих полей, не задаёт требований и применима где угодно.
Итоговый набор меток собирается в два шага, и ни один из них не совпадает с тем, что чаще всего предполагают авторы.
- Узел получает метки от каталожной сущности Component, которую называет его
type:. Они являются свойством типа компонента, а не экземпляра: Aggregate не может назначить метки экземпляру компонента, и Release тоже. Собственныеmetadata.labelsсущности Aggregate описывают Aggregate как переиспользуемый модуль и не распространяются на компоненты внутри него. Поэтому два экземпляра одного типа несут одинаковые метки, а чтобы изменить метки узла, нужно изменить тип, на который он указывает, — или изменить сущность этого типа. - Затем подключение
label-transformможет их переписать. Если конфигурация рабочего пространства подключает плагин управления в ролиlabel-transform, он запускается при построении топологии и может добавлять, изменять или удалять метки узлов до того, как по ним что-либо проверяется. Больше он ничего затронуть не может, поэтому метки — единственная часть узла, которую он способен изменить, и именно от них зависит применимость.
Поэтому предположение, сделанное по меткам, объявленным в одном документе, является приближением, а не прогнозом. Чтение metadata.labels сущности Component показывает, с какими метками начинает узел этого типа; это достаточно часто верный ответ, чтобы быть полезным, но он ошибочен в двух конкретных случаях: документ, который лишь совпадает с узлом по имени, — это другой объект с другими метками, а подключение label-transform может изменить набор независимо от любого документа. Инструменты, предлагающие варианты подключения только по исходникам, работают с этим приближением; сборка же выносит решение по итоговому набору.
Приоритет вложений
Когда два вклада задают одно и то же поле одного подключения, четыре правила определяют, какой из них попадёт в результат рендеринга. Они применяются в этом порядке, и именно порядок делает результат предсказуемым:
- Происхождение. Явно написанный вклад побеждает вклад из аннотации, в какой бы области ни был объявлен каждый из них. Запись поля в блоке
features:— это способ, которым автор переопределяет то, что внесла бы аннотация, и аннотация никогда незаметно не вытесняет написанное вручную. Компилятор записывает подавленную аннотацию рядом с победившим значением и сообщает о ней как о рекомендации, поэтому переопределение остаётся видимым, а не загадочным. - Владение столпами. Каждая область заполняет свой столп: точки Aggregate вносят
values, точки Release вносятinfra. Поскольку стороны никогда не пишут в один столп, вклад разработчика и вклад оператора не могут претендовать на одно поле — вопроса о приоритете разработчика над оператором не возникает. - Приоритет композиции. Объявление в развёртываемом Aggregate важнее объявления внутри Aggregate, который он включает, даже если включённый Aggregate объявил его в более узкой области. Композиция сохраняет приоритет: модуль не может перебить использующий его Aggregate, просто выбрав более узкую область.
- Специфичность. В пределах одного уровня авторинга и одного столпа более узкая область уточняет более широкую поле за полем. Подключение на уровне компонента переопределяет подключение на уровне подсистемы или границы с тем же именем экземпляра — но только для тех полей, которые оно явно упоминает. Поля, которые узкая область не задаёт, сохраняют значения широкой, поэтому общее подключение может задавать общую конфигурацию, а отдельный компонент — изменять одно её поле. Два вклада в одной области разрешаются по порядку записи: побеждает более поздний, благодаря чему внутренняя подсистема может уточнять внешнюю, а более глубокая граница — менее глубокую.
Приоритет управляет значениями полей. Он не меняет порядок вычисления: последовательность, в которой компилятор сворачивает точки и выполняет 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) остаются на сущности каталога. Они не передаются экземплярам; потребители читают их, напрямую просматривая содержимое каталога.
metadata.labelsсущности Component (поверхность 2) передаются в.context.labelsкаждого узла после необязательного проходаlabel-transformпри построении топологии.metadata.annotationsсущности Component (поверхность 3) передаются в корзину.context.annotations.catalogкаждого узла.annotations:сущности Aggregate / подсистемы (поверхность 4) каскадируются по иерархии подсистем, накапливаясь от внешних подсистем к внутренним, в корзину.context.annotations.aggregateкаждого узла.annotations:границ сущности Release (поверхность 5) каскадируются по иерархии границ от внешних границ к внутренним в корзину.context.annotations.releaseкаждого узла.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.