Feature
Концептуальная роль сущности Feature (модульной операционной характеристики в домене 2) описана в architecture/04-entity-taxonomy.md. Различие между операционными сущностями Features и сущностями Features для учётных данных (помеченными feature.aggrega.ai/kind: secret) описано в architecture/08-credential-model.md. Словарь семантических меток, используемый селекторами сущностей Feature, описан в entities/component. Эта страница посвящена средствам создания каталога сущностей Feature.
Расположение в каталоге
В отличие от сущностей Components (которые используют трёхсегментные URI с подкаталогами категорий), сущности Features организованы плоско: для каждой сущности Feature есть один каталог в каталоге её издателя, содержащий по одному каталогу на каждую версию.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...OCI URI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (например, hub.aggrega.ai/feature/core/data-masking:1.0.0).
Контракт описания
Features объявляют:
metadata.labels: используйтеfeature.aggrega.ai/kind: secret, чтобы пометить Feature как учётную Feature. Метка — это описательные метаданные для автора, для сайта каталога и для селекторов меток; ни одна ветвь компилятора её не читает, а то, что создаёт присоединение, определяется сущностью FeatureRecipe, с которой Manifest сопоставляет её тип, а не меткой. Учётная Feature и обычная Feature присоединяются одинаково, на одной и той же поверхности присоединения, в любой области действия. Семейство учётных данных стандартной библиотеки делится по результату:core/secret-valueдоставляет значение в канал внедрения;core/referenced-secretназывает ресурс секрета, на который можно сослаться (Kubernetes Secret, секрет AWS Secrets Manager, запись Vault), — созданный выводом её FeatureRecipe или уже существующий — и объявляет выходной контрактschema.provides—name(не зависящий от провайдера локатор ресурса) иkey(поле данных внутри него), — который потребитель читает как.features.<slot>.provides.<key>, чтобы сослаться на ресурс, не вычисляя заново его имя;core/referenced-secret-setматериализует один ресурс с переданным вызывающей стороной набором ключей данных и публикует только локатор — для потребителя, цель которого уже знает имена читаемых ключей;core/secret-providedпредоставляет значение уже существующего секрета;core/generated-secretничего не создаёт, поскольку целевой движок сам генерирует учётные данные и управляет ими, поэтому она не объявляет ниvalues, ниprovides, а её FeatureRecipes — чистое связывание, не выводящее ни одного байта. Членов семейства разделяют две оси: кто предоставляет материал — автор записывает его или указывает, откуда его получить, либо целевой движок полностью владеет им, как в случаеcore/generated-secret, — и что даёт присоединение: внедрённое значение, ресурс, на который можно сослаться, или вообще ничего выводимого. Каждый член семейства равноправен с остальными на одной и той же поверхности присоединения, поэтому слот учётных данных всегда связан, а между сущностями Releases различается лишь то, что его связывает. Учётная Feature, объявляющая контрактschema.provides, обязывает каждую реализующую её FeatureRecipe публиковать эти ключи — иначе сборка останавливается, — аselectorслотаfeaturesSchemaнацеливается на нужного ему члена семейства.usesSchema(необязательно): объявляет топологические сокеты, которые Feature может потреблять (например, сокетpath/keyучётной Feature, нацеленный на хранилище секретов). Механизм Split Schema описан в architecture/13-catalog-and-registry.md §2.schema: проверяет блокиvaluesиinfraприсоединения Feature — когнитивное намерение, которое разработчик настраивает в каждом присоединении в Aggregate (values— область разработчика, и схема Release запрещаетvalues:в присоединениях Feature), и мощности, которые оператор определяет для каждого окружения в Release (infra). Поле, объявляющееdefault:, и проверяется по нему, и подставляется в выводимый столп, если его никто не задал; см. Область действия Feature и форма описания. Принимает JSON Schema 2020-12 в компактной сокращённой записи YAML (по умолчанию; см.vocabulary/compact-form-authoring.md) или в полной записи JSON Schema YAML, с межфайловыми$ref:на записи SchemaLibrary для общих форм (см.vocabulary/cross-document-ref.md). Лист, содержащий секретный материал, объявляетsensitive: true— учётные Features стандартной библиотеки помечают лист с материалом и намеренно оставляют свои публикуемые локаторы непомеченными, поскольку имя ресурса и ключ данных публичны. Ключевое слово и предел того, чего позволяет добиться его объявление, описаны вvocabulary/compact-form-authoring.md, раздел «Declaring a leaf sensitive».featuresSchema(необязательно): объявляет слоты присоединения, нужные Feature для собственной работы, — Feature объявляет слоты точно так же, как Component, поэтому Feature, которой самой нужны учётные данные (например, API-ключ Feature сайдкара Datadog), называет точку связывания, а не обращается к слотам Component-хоста. Пример того, как Feature объявляет собственный слот, а FeatureRecipe читает то, что его заполняет, приведён в разделе Собственные учётные данные сущности Feature. Каждый слот принимает те же поля, что и слотfeaturesSchemaу Component, с той же семантикой — включая необязательныйselector(селектор меток в стиле Kubernetes, ограничивающий, какая Feature может заполнить слот, — аналог селектора сокетаusesSchemaдля слота; заполнение, метки которого ему не удовлетворяют, останавливает сборку, а селектор вычисляется только по меткам присоединённой Feature), необязательныйsensitive(объявление того, что всё, что связывает слот, работает с секретным материалом, — утверждение о точке связывания, а не о конкретном заполнении) и ту же открытость: объявление слота никогда не запрещает присоединение под именем, которого не объявляет ни один слот. Полная таблица полей, объявление чувствительности на уровне слота и его отличие от объявления для листа схемы, а также две формы, в которых развёртывается одна сущность, объявляющая слоты, описаны в entities/component.md «Attachment Slots».appliesTo/appliesToAnyOf: селекторы меток, определяющие, к каким Components может присоединяться Feature. Вычисляются встроенным механизмом сопоставления меток компилятора на этапе статического анализа. Справку по синтаксису селекторов см. в разделе Присоединение по меткам ниже и в architecture/13-catalog-and-registry.md §2 «Kubernetes-Style Selectors».interoperability(необязательно): вложенный блок, содержащийconflictsWith— Features, вместе с которыми данная Feature не может оказаться на одном компоненте. Сборка останавливается до рендеринга, если на одном компоненте в итоге оказываются обе, независимо от того, на каком уровне была подключена каждая из них. Полное описание см. в разделе Блокinteroperabilityниже.
Структурный вывод Feature привязан к соответствующей ей FeatureRecipe, которая сопоставляет интерфейс Feature с конкретной реализацией инфраструктуры.
Подключение на основе меток
Два селектора применимости в схеме Feature определяют, к каким Components подключается Feature; они вычисляются встроенным механизмом сопоставления меток компилятора на этапе статического анализа:
appliesTo— строка селектора меток в стиле Kubernetes; механизм композиции через И. Все требования, разделённые запятыми, должны выполняться; доступен полный набор операторов:key=value,key!=value,key in (v1, v2),key notin (v1, v2), простоkey(метка присутствует),!key(метка отсутствует). Сущность Feature, объявляющаяappliesTo: "datastore.aggrega.ai/engine=vector", подключается только к Components, помеченным именно этой парой ключ-значение;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"выражает «любой server или worker, не хранящий данные с ограниченным доступом» одной строкой селектора.appliesToAnyOf— механизм композиции через ИЛИ. Список элементов селектора, для которого достаточно совпадения любого одного элемента. Каждый элемент — либо селектор в строковой форме (та же грамматика, что уappliesTo; требования внутри строки объединяются через И), либо плоская карта ключ-значение для сопоставления только на равенство. Используется, когда Feature подходит для нескольких не связанных между собой форм компонентов — например, Feature наблюдаемости, применимая либо к{ component.aggrega.ai/type: worker }, ЛИБО к{ component.aggrega.ai/type: task }, без необходимости сводить их в одну строку селектора.
Без формы «любой из» архитекторам пришлось бы дублировать один и тот же YAML сущности Feature для каждой не связанной формы компонента, которой подходит Feature. Две формы сочетаются: Feature может объявить обе, и результаты объединяются через И — строка appliesTo должна выполняться, и хотя бы один элемент appliesToAnyOf должен совпасть. Опущенный или пустой селектор не объявляет ограничений и совпадает с любым набором меток.
Строка селектора проверяется на соответствие шести формам каждый раз, когда вычисляется подключение сущности Feature, и требование вне этих форм останавливает сборку, а не трактуется как какой-то другой селектор: пустое требование (запятая в начале, в конце или двойная, либо строка из одних разделителей), ключ, содержащий пробельные символы или любой из символов =, !, (, ) и запятую, а также незакрытое множество in ( или notin (. Именно это выявляет ошибки, которые иначе незаметно выбрали бы противоположное задуманному: appliesTo: "!tier=frontend", написанное, чтобы не подключать Feature к фронтендам, отклоняется, поскольку ! обозначает только ключ метки и ничего больше — значение исключается так: tier!=frontend, — а tier in frontend отклоняется в пользу tier in (frontend). Значение — это текст после оператора, какие бы символы он ни содержал, поэтому tier==frontend запрашивает метку со значением =frontend. В сообщении об остановке указываются Feature, её селектор и требование, которое не удалось разобрать. Сущность Feature, которую ничто не подключает, никогда не вычисляется, поэтому о некорректном селекторе в ней не сообщается, пока на неё не сошлётся какое-либо подключение.
Справочник по синтаксису селекторов см. в architecture/13-catalog-and-registry.md §2 «Kubernetes-Style Selectors»: селектор сущности Feature принимает ту же грамматику, что и селекторы сокетов usesSchema, — это строковая форма, знакомая пользователям Kubernetes по kubectl get -l.
Блок interoperability
Схема Feature объявляет необязательный блок spec.interoperability с одним параметром управления: с какими другими Features эта Feature может сосуществовать на одном компоненте.
interoperability.conflictsWith — список Features, взаимно исключающих определяемую Feature; каждая записывается так, как поле type привязки называет Feature. Это предотвращает генерацию несовместимых конфигураций — например, привязку к одному компоненту одновременно mesh, работающего только с TCP, и прокси с поддержкой HTTP.
Сборка останавливается до какого-либо рендеринга, если на одном компоненте в итоге оказываются эта Feature и Feature, названная в её списке. Значение имеет охват: привязка охватывает компонент, на котором она записана, и каждый компонент внутри подсистемы или границы, на которой она записана, включая вложенные границы; привязка, записанная в записи компонента сущности Release или созданная расширением на основе аннотаций, охватывает свой компонент так же. Поэтому объявленный конфликт останавливает сборку, когда две Features привязаны к одному компоненту, когда одна находится на границе, а другая — на компоненте внутри неё, когда одна находится на внешней границе, а другая — на вложенной в неё границе, содержащей компонент, и когда одна находится на подсистеме, а другая — на компоненте этой подсистемы. Две Features, привязанные к соседним границам без общих компонентов, никогда не встречаются, а граница, не содержащая компонентов, ничего не охватывает — ни в одном из этих случаев сборка не останавливается.
- Достаточно одного объявления. Сборка останавливается, если список любой из двух Features называет другую; второй Feature не нужно в ответ перечислять первую.
- Имена, независимо от версий. Каждая запись и тип каждой привязки сравниваются без учёта версии, поэтому запись
core/fixed-replica-controllerсовпадает с привязкойcore/fixed-replica-controller:2.0.0, а запись с версией совпадает с любой версией названной в ней Feature. - Читаются только имена. Компилятор сравнивает имена, объявленные автором Feature, с Features, которые несёт компонент, — это такая же оценка, как для
appliesTo, по данным, записанным автором. Несовместимы ли две Features, решает автор, а список — место, где это решение зафиксировано.
Сообщение об остановке называет Feature, список которой называет другую, каждое место, где была привязана каждая из двух, — на компоненте в сущности Aggregate, на подсистеме, на границе сущности Release с её путём, в записи компонента сущности Release или расширением на основе именованной аннотации, — и компонент, на котором они встречаются. Пара, встречающаяся на нескольких компонентах, сообщается один раз для каждого. Текст сообщения см. в errors/fatal-halts.md.
Пример:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerЭта Feature привязывается только к Components типа server и объявляет несовместимость с другой Feature, управляющей репликами: сборка, в которой какой-либо компонент в итоге несёт обе, останавливается до рендеринга. FeatureRecipe, которой нужно имя компонента, к которому она привязана, — например, чтобы направить автомасштабировщик на его цель, — читает его из своего контекста шаблона и записывает туда, где оно нужно в её выводе: .context.instance_id — идентификатор компонента, а .context.rendered_name — имя, которое собственный провайдер компонента даёт ресурсам, отрисовываемым для него, и именно по нему следует нацеливаться на ресурс: в helm это имя Deployment, создаваемого синтезированной рабочей нагрузкой, и имя релиза, из которого чарт строит собственные имена.
Наследование через extends
Сущность Feature может объявить spec.extends: <feature-name>, указывающий на базовую сущность Feature, поверхность описания которой она наследует. Ссылка называет базовую сущность по её metadata.name, а не по координате реестра, под которой публикуется Feature, и принимает те же три формы версии, что и любая ссылка на каталог: без версии (core/queue) — для наивысшего доступного релиза, точную (core/queue:1.0.0) или диапазон с кареткой (core/queue:^1.0.0). Компилятор обходит цепочку родителей при загрузке каталога, проверяет отсутствие циклов в цепочке, а затем сливает спецификации родителей в дочернюю, получая одну разрешённую сущность Feature. При совпадении ключей приоритет имеют поля, описанные в дочерней сущности; metadata.labels и metadata.annotations родителя, селекторы appliesTo / appliesToAnyOf, блок interoperability, usesSchema, featuresSchema и объявления JSON Schema 2020-12 в schema автоматически сливаются вниз. Все остальные поля metadata берутся из дочерней сущности дословно, поэтому идентичность и происхождение никогда не наследуются.
Что наследует metadata: сущности Feature. labels и annotations сливаются по ключам вдоль цепочки, начиная с базовой сущности, причём при общем ключе побеждает значение расширяющей сущности Feature — то же правило, которому следуют Components. Остальная часть metadata: не передаётся: name, version, description, maintainers, license, repository, home и keywords принадлежат расширяющей сущности Feature, точно в том виде, в каком описаны.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Слитая core/kafka-queue наследует appliesTo от родителя, наследует свойства values.qos и infra.partition_count и добавляет сверху values.compression_codec. Дочерняя сущность, явно объявляющая appliesTo, полностью переопределяет селектор родителя (слияние селекторов меток не глубокое — селектор дочерней сущности заменяет селектор родителя). schema.values.qos дочерней сущности переопределяет объявление родителя для этого свойства.
Как наследуется каждая часть поверхности присоединения. Две формы селектора наследуются независимо друг от друга, потому что они комбинируются, а не заменяют друг друга: каждая присутствующая форма должна выполняться — строка appliesTo должна совпасть, и хотя бы один элемент appliesToAnyOf должен совпасть, — а отсутствующая форма ничего не ограничивает. Поэтому сущность Feature может взять AND-селектор базовой сущности, объявив собственный OR-набор. Блок interoperability наследуется по полям: дочерняя сущность, объявившая блок без списка conflictsWith, по-прежнему несёт список, объявленный базовой, а дочерняя сущность, объявившая собственный conflictsWith, заменяет список базовой, а не дополняет его. Сущность Feature, не объявившая ни одного из трёх, присоединяется ровно там же, где и её базовая.
Наследование — это слияние схем, а не привязка к интерфейсу. Цепочка extends: сущности Feature порождает одну разрешённую сущность Feature, а не полиморфное семейство. На URI базовой сущности Feature из цепочки не ссылается поле feature: привязки в Manifest — Manifests привязываются по URI конечной сущности Feature, а разрешённая схема включает унаследованные свойства. Контракт Feature, который реализует FeatureRecipe через implements:, — это так же URI конечной сущности; FeatureRecipes не обходят цепочку наследования.
aggrega pull получает базу. Базовая сущность Feature — зависимость каждой сущности Release, которая присоединяет сущность Feature, расширяющую эту базу, независимо от того, называет ли её что-либо ещё. aggrega pull проходит каждый extends: до конца цепочки, получает из реестра базу, которой нет ни в одной директории каталога, и записывает каждую базу в lock-файл сущности Release со ссылкой из spec.extends сущности Feature, которая её называет; сборка читает базу оттуда.
Режимы ошибок. Циклическая цепочка extends: и родитель, которого не предоставляет ни одна сущность каталога, останавливают сборку с указанием Feature, с которой началось разрешение, Feature, чью строку extends: нужно открыть, и объявленной ею ссылки. Сообщения приведены в Cyclic extends on Components or Features (Циклическое extends у сущностей Component или Feature) и An extends: chain cannot be assembled (Цепочку невозможно собрать).
Более широкий словарь наследования и интерфейсов для Components, Features и учётных Features см. в vocabulary/inheritance-and-interface.md.
Композируемость: общественный договор о чистоте
Соглашение стандартной библиотеки — одна сущность Feature, одна внутренняя функция: sidecar наблюдаемости — это Feature наблюдаемости; sidecar сетевого прокси — это Feature сетевого прокси; они не объединяются в один составной элемент с двумя несвязанными задачами. Это соглашение сохраняет отдельные Features композируемыми, независимо версионируемыми и независимо подключаемыми.
Основной компилятор на Go не обеспечивает соблюдение этого соглашения. Определения Feature со смешанными задачами синтаксически допустимы и компилируются без ошибок. Проверка включается по желанию:
- Предприятия, создающие внутренние каталоги, могут написать собственный плагин-линтер, который проверяет определения Feature в CI/CD и выдаёт предупреждение, когда метки
appliesToодной сущности Feature охватывают несвязанные области возможностей. - Автор сущности Feature, который указывает в
interoperability.conflictsWith, что две Features будут пересекаться, включает проверку во время сборки: компилятор останавливается везде, где обе достигают одного компонента. Он сравнивает только объявленные имена, поэтому обеспечивает соблюдение объявления, написанного автором, а не самого соглашения о чистоте.
Features стандартной библиотеки с открытым исходным кодом следуют соглашению о чистоте за счёт дисциплины авторов; корпоративные каталоги вправе отступать от него, когда тесно связанный составной элемент действительно соответствует модели развёртывания.
Что заслуживает Feature и где место собственной настройки продукта
Feature — это подключение: она привносит то, что разработчик или оператор подключает намеренно, — ресурсы, шаг конвейера, связывание, — и соглашение стандартной библиотеки состоит в том, что её должны поддерживать как минимум два независимых продукта. Именно эту вторую часть следует проверить, прежде чем создавать сущность Feature, потому что переносимость — это то, что обещает слово подключение. Подключение означает, что возможность переносится: подключите её к одному компоненту, подключите к другому, и реализация каждого продукта выполнит её в своих собственных терминах.
Возможность, которая есть только у одного продукта в отрасли, — это собственная настройка этого продукта, а не Feature. Её место — авторское значение на собственной поверхности этого продукта, которое задаёт в своём столпе автор, принимающий это решение, и которое читается рядом со всем остальным, что настраивает тот же продукт. Публикация её в виде Feature вместо этого предлагает переносимость, которую не может обеспечить ни один другой продукт: подключение по построению называет один продукт, поэтому автор, подключивший его к следующему выбранному продукту, получит сборку, которая останавливается с указанием типа, а Feature научила возможности, которой у неё никогда не было.
Проверка считает продукты в отрасли, а не компоненты в этом каталоге, причём каждый оценивается по его собственному актуальному справочнику конфигурации. Два независимых продукта, реализующих возможность, делают её переносимой независимо от того, сколько из них поставляется здесь, поэтому Feature можно объявить ещё до того, как что-либо в каталоге её реализует, — тогда её подключение останавливает сборку с указанием типа, — а каждая поставляемая реализация — это FeatureRecipe для одного продукта, выполняющий подключение тем способом, каким этот продукт его настраивает.
Закрепление сертификата вышестоящего сервиса — разобранный пример. Закрепление — это контроль над тем, какой ключ может предъявить вышестоящий сервис: принимается только сертификат, открытый ключ которого совпадает с ключом, предоставленным сущностью Release. Это иное утверждение, чем требование, чтобы сертификат вышестоящего сервиса выстраивал цепочку до якоря доверия, предоставленного сущностью Release, и тем более иное, чем утверждение о том, что говорит субъект сертификата: оба этих утверждения определяют, что сертификат должен говорить, тогда как закрепление определяет, каким ключом он должен быть. Несколько шлюзов здесь умеют проверять по якорю, поэтому dataplane.aggrega.ai/upstream-tls: trust-anchor — значение, которому может соответствовать селектор. Закрепление — отдельная возможность, и как минимум два независимых продукта реализуют её для соединений, которые они открывают к вышестоящему сервису: Tyk принимает открытый ключ вышестоящего сервиса в формате PEM, а Envoy — его хеш. Поэтому это Feature, core/upstream-key-pinning, чей селектор называет dataplane.aggrega.ai/upstream-pinning: public-key, а то, что реализует этот каталог, решается для каждого продукта отдельно: core/gateway/tyk несёт это значение и FeatureRecipe для каждой из своих целей, тогда как шлюзы здесь, встраивающие Envoy, предоставляют его настройку закрепления только для сертификатов, предъявляемых клиентами, или не предоставляют её вовсе, поэтому они не несут значения, и подключение к ним останавливается на селекторе. Закрепление сужает то, что может предъявить вышестоящий сервис; это контроль, а не гарантия того, что соединение надёжно в остальном.
У проверки две границы, и вторую чаще всего упускают:
- Это дисциплина авторства, а не проверка компилятора. Feature, объявляющая параметры, которые не реализует ни один продукт, одинаково проходит валидацию схемы, линтер публикации и рендеринг: компилятор не интерпретирует то, что обещает Feature. Суждение остаётся за автором каталога.
- Неспособность одного продукта поддержать параметр — не основание отказываться от этого параметра. Если два или более продукта поставляют возможность под названиями, которые группируются вместе, возможность переносима, и Feature её сохраняет; продукт, который не может её поддержать, от неё отказывается. Feature, урезанной до того, что поддерживает каждый продукт, почти нечего сказать.
Область действия Feature и форма её описания
spec.schema сущности Feature определяет собственные формы Feature values: и infra: — когнитивное намерение, которое разработчик (Developer) настраивает для каждого подключения Feature в Aggregate (values), в отличие от показателей ёмкости, которые оператор (Operator) определяет для каждого окружения (infra). Опоры Feature находятся в собственных пространствах имён и проверяются независимо от опор хост-сущности Component. Когда разработчик подключает Feature autoscaler к Component web-server в Aggregate, Aggregate содержит values: сущности Component (форма хоста) и values: сущности Feature (форма намерения масштабирования — какая метрика управляет масштабированием); показатели ёмкости, относящиеся к оператору (min_replicas / max_replicas), передаются через блок infra: сущности Release в подключении Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10schema: сущности Feature проверяет собственные блоки values: и infra: подключения Feature. schema: сущности Component проверяет собственные блоки Component. Они оцениваются независимо на этапе статического анализа; опора подключения, не соответствующая schema: сущности Feature, останавливает сборку с ошибкой, привязанной к месту подключения Feature, а не к хост-сущности Component. Проверяется итоговая конфигурация подключения — результат объединения всех областей, которые её настраивали, — поэтому значение, приведённое в соответствие в одной области и затем переопределённое недопустимым в более узкой, будет обнаружено.
Объявленные значения по умолчанию материализуются в отрисованных опорах подключения. Помимо проверки, default:, объявленный для поля values или infra сущности Feature, при сборке подставляется в отрисованную опору этого подключения для каждого ключа, который никто не задал, — поэтому шаблон FeatureRecipe, читающий {{ .infra.tier }}, получает значение, объявленное в схеме, а не пустое. Значения, заданные автором, всегда имеют приоритет, а значение по умолчанию заполняет только опущенные ключи: подключение, задающее один ключ схемы Feature, всё равно получает объявленные значения по умолчанию для остальных ключей этой схемы, а частично заданный вложенный объект сохраняет написанное и получает незаданные соседние поля.
При описании полезно знать три свойства этого заполнения:
- Значение по умолчанию никогда не вытесняет значение, заданное какой-либо областью. Если Feature подключена в нескольких областях — например, на границе Release и в одном из её компонентов, — действует значение более узкой области, а значение по умолчанию заполняет только то, что не задала ни одна область.
- Значение по умолчанию заполняет подключение, но никогда не создаёт его. Объявление значений по умолчанию для Feature, которую никто не подключает, ничего не добавляет в вывод, поэтому схема Feature не может добавить конфигурацию, которую не запрашивал ни один автор.
- Подключение, объявленное на границе Release, а не в отдельном компоненте, заполняет только
infra, поскольку эта поверхность не содержит блокаvalues:для заполнения.
Поскольку материализация использует то же разрешение схем, что и проверка, значение по умолчанию, объявленное в родительской Feature, доходит до подключений дочерней сущности extends:, а значения по умолчанию, достигнутые через межфайловую ссылку $ref: в SchemaLibrary, тоже материализуются. Значения по умолчанию, объявленные только внутри локальной ссылки #/$defs/ в том же документе или в ветви allOf / oneOf / anyOf, не материализуются.
Одно следствие стоит сформулировать прямо, поскольку одна лишь проверка его не выявит: поле required:, которое также содержит default:, удовлетворяется этим значением по умолчанию, поэтому его можно опустить — и значение, которое приняла проверка, и есть значение в отрисованном выводе.
Контекст шаблонов компилятора открывает состояние экземпляра Feature для связанного FeatureRecipe через поле .features.<alias> (содержащее .type, .resolved_version, .labels, .values, .infra и .provides для каждого подключения). Шаблоны внутри FeatureRecipe читают собственные values: сущности Feature через .values.<field> в собственной области шаблонов FeatureRecipe; values: хостовой сущности Component не видны напрямую шаблонам FeatureRecipe, если Feature явно не объявляет сокет uses: к хостовой сущности Component.
Такое разделение областей делает Features компонуемыми: Feature autoscaler не зависит от того, к какой сущности Component он подключается; его schema: описывает намерение автомасштабирования независимо от хоста. values: хостовой сущности Component — забота хоста; values: сущности Feature — забота Feature; два столпа компонуются, не допуская утечки имён полей через границу.
Цели привязок аннотаций
Feature не объявляет привязки аннотаций сама; их содержит карта mappings.features.annotations в Manifest. Feature участвует в отношении привязки косвенно — как цель маршрутизации: каждая привязка называет тип Feature через своё поле feature:, а списки maps.infra и maps.values привязки объявляют пути через точку к свойствам spec.schema.infra.<path> и spec.schema.values.<path> указанной Feature.
При загрузке каталога компилятор проверяет, что каждый путь через точку в списках maps привязки соответствует свойству, которое spec.schema целевой Feature действительно объявляет в указанном столпе. Привязка, ведущая к пути, который схема Feature не объявляет, останавливает загрузку каталога с понятной ошибкой OPS_ERROR, где названы привязка, целевая Feature, а также столп и путь, через которые шла маршрутизация, — привязка записана в Manifest, а это документ оператора. Поэтому авторы схем знают, что любое свойство, объявленное ими в spec.schema.values.<path> или spec.schema.infra.<path>, доступно как цель привязки; и наоборот, любое свойство, через которое маршрутизирует привязка Manifest, должно существовать в схеме целевой Feature.
Когда аннотация на стороне Aggregate или на стороне Release совпадает с привязкой, компилятор синтезирует подключение Feature, полезная нагрузка столпов которого направляет значение аннотации по указанным путям. Синтезированное подключение структурно неотличимо от явного подключения Feature, объявленного автором в том же месте; последующий рендеринг, валидация и контекст шаблона FeatureRecipe одинаково обрабатывают обе формы. Форму привязки, разделение по стороне и столпу и принцип приоритета явного подключения см. в entities/manifest.md, раздел «Annotation-Driven Feature Bindings». Правило каскада на стороне Aggregate и пример написания см. в providers/well-known-annotations.md, раздел «Aggregate-side annotation cascade».
Блок assertions:
Feature.spec.assertions: — необязательная карта именованных правил, выражающих архитектурные инварианты контракта Feature: межполевые правила над values: сущности Feature и разрешённым состоянием присоединённой сущности Component. Каждый ключ — идентификатор правила, который появляется в сообщении об ошибке; каждое значение — тело шаблона Go. Компилятор вычисляет их после проверки по схеме и до рендеринга связанного FeatureRecipe, в том порядке, в котором они записаны, и первое не выполненное правило останавливает сборку с собственным сообщением об ошибке этого правила.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Как и утверждения сущности Component, утверждения сущности Feature выражают инварианты уровня контракта — свойства, которым присоединение Feature должно удовлетворять независимо от того, какой FeatureRecipe реализует рендеринг. Для межполевых правил, зависящих от конкретной реализации (требование Wasm-плагина, особенность чарта), используйте вместо этого поле assertions: сущности FeatureRecipe. Полную грамматику написания, контекст шаблона и разделение ответственности между утверждениями Feature и FeatureRecipe см. в templates/assertions-block.md.