Блок `assertions:`
Сущности Component, Feature, Recipe и FeatureRecipe содержат необязательное поле spec.assertions: — словарь именованных правил, которые компилятор вычисляет после проверки по схеме, но до рендеринга. Каждый ключ — это идентификатор правила, который появляется в сообщении об ошибке; каждое значение — тело шаблона Go. Одиночное тело шаблона, записанное непосредственно под assertions:, не соответствует форме поля и отклоняется при чтении сущности, поэтому каждое правило записывается под собственным именем. Блок выражает межполевые правила, которые JSON Schema не может компактно описать: инварианты, затрагивающие несколько полей, где ни одно поле не является «тем, которое проверяется». На этой странице описаны грамматика написания, фаза вычисления, контекст шаблона и разделение ответственности между утверждениями Component / Feature (архитектурные инварианты контракта) и утверждениями Recipe / FeatureRecipe (инварианты реализации конкретного провайдера).
Для ограничений отдельного поля (диапазон, шаблон, перечисление, формат) используйте встроенные ключевые слова JSON Schema внутри schema:. Для пользовательских предикатов отдельного поля используйте поле validate: компактной формы. Для условной формы используйте when:. Поле assertions: дополняет их — это место для настоящих межполевых правил.
Где встречается это поле
Четыре сущности, которые могут содержать assertions::
- Component — архитектурные инварианты контракта Component.
- Feature — архитектурные инварианты контракта Feature.
- Recipe — инварианты реализации чарта или модуля, лежащего в основе сущности Recipe.
- FeatureRecipe — инварианты реализации механизма, лежащего в основе сущности FeatureRecipe.
Для каждой из них поле необязательно. Сущности без межполевых правил полностью опускают это поле.
Когда выполняются проверки
Фазы вычисления проверок находятся в конвейере компиляции между валидацией по схеме и рендерингом:
- Разрешение: валидация и интерполяция параметров, затем валидация по схеме относительно
schema:/usesSchema:/featuresSchema:. - Построение топологии и финализация графа: граф собирается.
- Статический анализ: селектор каждого сокета
uses:проверяется по меткам компонентов, к которым ведут его соединения. - Проверки Component / Feature вычисляются для каждого экземпляра.
- Привязка Recipe.
- Проверки Recipe / FeatureRecipe вычисляются для привязанного экземпляра.
- Рендеринг: вычисляются шаблоны сопоставления, формируется результат.
Обе фазы проверок выполняются до какого-либо рендеринга — ни один чарт не отрендерен, ни один файл Compose не сгенерирован. Единственное, что запрашивается у провайдера до выполнения проверок Recipe, — это имя, которое он даёт ресурсам каждого привязанного узла и которое может прочитать provides сущности Recipe. Проваленная проверка немедленно останавливает сборку с конкретным сообщением об ошибке этой проверки; последующие шаги не выполняются.
Разделение на две фазы отражает разделение ответственности: правила уровня Component применяются независимо от того, какой Recipe привязывается, поэтому срабатывают до привязки; правила уровня Recipe применяются при конкретном выборе Recipe, поэтому срабатывают после привязки.
Контекст шаблона
Для assertions: сущностей Component и Feature контекст шаблона предоставляет разрешённое состояние экземпляра:
.values— содержимоеvaluesот разработчика..infra— содержимоеinfraот Ops (из сущности Aggregate или Release)..uses— разрешённые соединенияuses:, каждое из которых уже проверено по селектору своего сокета, в той форме, в какой их пишет автор: с ключами по имени сокета, а внутри каждого сокета — по псевдониму каждого соединения на нём, то есть по имени, которое автор дал соединению под сокетом, или, для соединения, записанного как элемент списка, по его цели. Запись каждого соединения описывает само соединение и не содержит ничего из того, что опубликовала его цель.target— идентификатор экземпляра разрешённой цели,aliasповторяет имя, по которому запись проиндексирована, аorigin_featureприсутствует, когда соединение создано присоединением Feature. Рядом с ними находятся три факта под теми же именами, под которыми шаблон Recipe читает их в записи.context.uses.<alias>того же соединения; что содержит каждый из них, описано в template-context-contract.md:labels— метки цели, а не метки компонента, на котором выполняется утверждение, —values, значения, записанные на соединении, иfeatures, присоединения, записанные на соединении, с ключами по слоту, который заполняет каждое из них. Каждый из трёх фактов присутствует на каждом соединении и пуст, если соединение ничего такого не несёт, а присоединение вfeaturesимеет ту форму, которую.featuresописывает ниже. Таким образом,.uses.<socket>.<alias>.targetчитает разрешённую цель одного соединения,.uses.<socket>.<alias>.labels— метки этой цели, сокет с несколькими соединениями содержит запись для каждого из них, а ссылка, которая через эту карту обращается к значению, опубликованному целью, приводит к остановке, потому что в записи нет такого поля..features— разрешённые присоединения с ключами по имени экземпляра, которое автор дал каждому из них. Каждая запись содержитtype(URI каталога присоединённой сущности Feature),resolved_version(версию, привязанную для этой сборки) иvalues(собственное содержимое присоединения, выражающее намерение разработчика). Присоединения, записанного на одном из соединений компонента, среди них нет, точно так же как его нет среди.featuresшаблона Recipe: оно читается под своим соединением, по пути.uses.<socket>.<alias>.features.<slot>, в той же форме..metadata— вычисляемый экземпляр: егоinstance_id, его типcomponentиresolved_version, егоboundary_path, а такжеaggregate_name,aggregate_versionиrelease_versionсборки.
Для assertions: сущностей Recipe и FeatureRecipe контекст добавляет поля, специфичные для Recipe:
.provides— разрешённые значенияprovides:оцениваемого компонента, уже вычисленные к моменту выполнения утверждения. Опубликованных значений цели на этой поверхности нет; они попадают к вызывающей стороне через контекст рендеринга..locals— локальные переменные Recipe..recipe.metadata—nameиversionсущности Recipe, а также еёcapability..recipe.source— указатель на источник Recipe.
Доступ к полям использует стандартный синтаксис шаблонов Go (.values.architecture, .uses.databases.primary.target); останавливающая конструкция — {{ fail "message" }} согласно контракту Loud Guardrails: проваленное утверждение порождает ясную, конкретную ошибку времени сборки с указанием нарушенного инварианта.
Эта поверхность вычисляется с missingkey=error. Ссылка на ключ, которого нет в контексте, останавливает сборку — с указанием сущности, экземпляра, утверждения и отсутствующего ключа, — а не отрисовывается как пустота. Именно эта строгость делает утверждение надёжным: предикат, ссылка которого отрисовалась бы пустой, сравнивал бы с пустотой и проходил, так что одна опечатка незаметно отменила бы правило, для соблюдения которого утверждение было написано. Это также означает, что простая ссылка разрешается раньше, чем может сработать любой запасной вариант, поэтому для необязательного поля нужна форма, учитывающая его наличие; в errors/fatal-halts.md описаны политика отсутствующих ключей для каждой поверхности и формы, которые работают при ней.
Чтение соединений сокета. Запись сокета имеет одну форму, что бы он ни содержал: одна запись на соединение, под его псевдонимом. Утверждение читает одно соединение по его псевдониму, подсчитывает или перебирает сокет, чтобы увидеть все соединения на нём, и проверяет собственный ключ сокета, чтобы узнать, подключён ли он вообще. Для компонента, запись которого в Aggregate имеет вид
uses: models: local: { target: llama } fast: { target: turbo }эти утверждения читают его каждым из способов:
assertions: # The socket's presence: the socket key alone, however many connections it holds. models-wired: | {{- if not (hasKey .uses "models") -}} {{- fail "wire at least one model to the models socket" -}} {{- end -}} # Every connection on the socket: a range visits each one. every-model-distinct: | {{- $seen := list -}} {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- if has $connection.target $seen -}} {{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}} {{- end -}} {{- $seen = append $seen $connection.target -}} {{- end -}} # One connection, by the alias it was written under; guarded, because the # connection is optional. fast-is-not-local: | {{- with (optional .uses "models" dict) -}} {{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}} {{- fail (printf "the fast and local connections both point at %s" .local.target) -}} {{- end -}} {{- end -}}Перебор обходит соединения сокета в алфавитном порядке их псевдонимов — здесь fast перед local, — а не в том порядке, в котором их записал Aggregate. Сокет с единственным соединением читается так же: .uses.models.local.target читает llama независимо от того, подключён ли рядом fast, а .uses.models.target не адресует ни одного соединения и приводит к остановке.
У каждого соединения компонента здесь есть собственная запись, потому что никакие два соединения одного компонента не имеют общего псевдонима — ни на одном сокете, ни на двух, каким бы документом или присоединением ни было создано каждое из них. Сборка отвергает такую пару, указывая оба соединения и место, где записано каждое, до выполнения любого утверждения. Список, дважды называющий одну цель, образует такую пару, поскольку псевдоним элемента списка — его цель; такую же пару образуют собственное соединение local компонента и соединение local присоединения на том же компоненте.
Чтение того, что несёт соединение. Правило о соединении может читать, чем является его цель, что разработчик записал на соединении и что к нему присоединено, поэтому оно действует, какая бы Recipe ни была привязана. Сущность Component, сокет models которой объявляет значение unauthenticated и слот credential, может отвергнуть соединение с целью, которую её каталог помечает как размещённый сервис, если это соединение не несёт ни учётных данных, ни отказа от них:
assertions: hosted-model-needs-a-credential: | {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}} {{- $optedOut := optional $connection.values "unauthenticated" false -}} {{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}} {{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}} {{- end -}} {{- end -}}Метка читается из labels, которые принадлежат цели — модели, — а не самому компоненту; отказ читается из values соединения; а учётные данные — это слот в features соединения. Каждое из них читается с помощью optional или hasKey, потому что у цели может не быть такой метки, а у соединения — такого значения. Что означает метка, определяется соглашением каталога: сборка передаёт строку, а утверждение решает, что она означает.
.uses утверждения — это не .context.uses шаблона Recipe, и ссылка, написанная для одного, не переносится на другое. Контекст рендеринга несёт более богатую проекцию тех же рёбер: с ключами только по псевдониму, с именем сокета в виде поля записи и с опубликованными значениями каждой цели, вложенными в provides, — поэтому шаблон Recipe читает .context.uses.<alias>.provides.<name> там, где утверждение читает .uses.<socket>.<alias>.target. Факты, которые несут оба представления, имеют общие имена, но не общие пути: .context.uses.<alias>.labels и .uses.<socket>.<alias>.labels — это метки одной и той же цели, и values и features аналогично читают одно и то же соединение в любом из них. Обе фазы утверждений выполняются до рендеринга, поэтому представление ребра в утверждении не несёт ничего из опубликованного его целью, а присоединение на нём не несёт provides.
Общую форму контекста шаблона и семантику доступности каждого поля см. в template-context-contract.md.
Числа на этой поверхности
Утверждение читает записанное автором число ровно так же, как шаблон значений, — см. Числа в шаблоне значений:
- Сравнения. Шесть сравнений читают два числа по значению, каким бы видом ни было представлено каждое:
lt .values.replicas 1.5иeq .values.replicas 3.0отвечают здесь так же, как в шаблоне значений, записанное автором0.1eqзначению0.1, записанному в утверждении, а сравнение числа с текстом в кавычках приводит к остановке с тем же сообщением. - Пустота. Записанный автором
0пуст: ложен дляifиwith, истинен дляemptyи заменяется черезdefault. Правило, которое спрашивает, записал ли автор значение — включая0, — спрашивает это с помощью функций проверки наличия: для записанного автором0выражениеhasKey .values "replicas"истинно, аoptional .values "replicas" 1возвращает0. Правило, которое спрашивает, равно ли значение нулю, сравнивает:eq .values.replicas 0. В разделе Наличие и пустота эти два вопроса рассмотрены рядом. - Вывод. Число, которое выводит сообщение
fail, выглядит так же, как в выводе шаблона значений: целое число — целым, поэтомуprintf "%d"выводит его цифры, а любое другое число — в кратчайшей точной десятичной форме, поэтому записанное автором0.0000001выглядит как0.0000001.
Утверждения Component / Feature — архитектурные инварианты
Они выражают правила, которые выполняются независимо от того, какой Recipe привязан к сущности Component. Правило — это свойство контракта, а не реализации.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: architecture: { type: string, enum: [standalone, replication], default: standalone } primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } secondary: replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions: # Replication mode requires at least 2 secondary replicas. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node count limit for safe replication coordination. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count must not exceed 9; got %d" $total) -}} {{- end -}}Оба правила выражают свойства контракта MariaDB. Какой бы Recipe ни был привязан — чарт Bitnami или самостоятельно написанная альтернатива, — правила применяются.
Управление пробелами {{- ... -}} имеет значение: шаблоны утверждений не производят вывода, только побочные эффекты через {{ fail }}. Обрезка пробелов оставляет тело отрисованного шаблона пустым в случае успеха.
Проверки Recipe / FeatureRecipe — инварианты реализации
Они выражают правила, которые действуют для конкретного чарта или модуля, источником которого служит Recipe. Правило является свойством реализации, а не контракта.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: bitnami/datastore/mariadb/k8s version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:^1.0.0 source: # Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead. chart: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0"
valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions: # Bitnami chart 20.x requires an explicit ServiceMonitor namespace when # replication and metrics scraping are both enabled. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# ARM-node incompatibility. arm-rejects-hard-anti-affinity: | {{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}} {{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}} {{- end -}}Каждое правило относится только к реализации на чарте Bitnami 20.x. Если привязывается другой Recipe для MariaDB — самописный чарт, альтернативная реализация, — эти правила не применяются. Правила уровня Component (replication-needs-two-secondaries, total-node-count-within-cap) по-прежнему применяются, поскольку они являются свойствами контракта.
Почему утверждения Component и Recipe разделены
Две роли выглядят похоже (обе выполняют остановки {{ fail }} по правилам, связывающим несколько полей), но разделение ответственности здесь несущее:
- Утверждения Component — часть контракта. Когда разработчик указывает
architecture: replicationвместе сsecondary.replicaCount: 1, сборка отказывает независимо от того, какой Recipe привязан. Будущий альтернативный Recipe этого не меняет. - Утверждения Recipe — часть реализации. Когда архитектор выбирает в качестве Recipe чарт Bitnami 20.x, у этого чарта есть свои особенности (требование
serviceMonitor.namespace, ошибка на ARM-узлах). К другому чарту они не относятся.
Если разместить правила обоих типов в сущности Component, контракт переплетётся со своими реализациями: сущности Component пришлось бы ссылаться на привязанный Recipe, чтобы знать, какие правила реализации применять, а это нарушило бы разделение Component и Recipe. Размещение правил там, где им естественно находиться, сохраняет модель ответственности чистой. Затраты на такое разделение во время выполнения пренебрежимо малы: обе фазы выполняются до рендеринга и останавливают сборку с одной и той же диагностикой Loud Guardrails, E0033, называющей сущность, экземпляр и правило.
Соглашение о сообщениях fail
Аргумент {{ fail "..." }} — это ошибка времени сборки, которую видит пользователь. Соглашения:
- Называйте ограничение — «architecture=replication requires secondary.replicaCount >= 2».
- Называйте значение, когда это уместно — «total node count must not exceed 9; got 12».
- Предлагайте исправление, когда это возможно — «use ‘soft’ or omit the field».
- Избегайте жаргона — читатель сообщения — это разработчик, написавший Aggregate, а не архитектор, написавший проверку.
Для длинных сообщений или сообщений со значениями используйте printf:
{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}Компилятор выводит сообщение в формате ошибок Loud Guardrails с именем сущности, местом проверки в исходном коде и сообщением о сбое. Диагностика достаточно конкретна, чтобы разработчик мог найти и устранить первопричину.
Значение, которое автор объявил как sensitive: true, отображается в этом сообщении как <redacted> везде, где сообщение его цитирует, поэтому называть в сообщении значение объявленного поля безопасно: диагностика по-прежнему называет правило и поле, скрывается только значение. Проверка, результат которой зависит от содержимого такого значения — сравнение с литералом, проверка префикса, — вместо своего сообщения сообщает, что текст сбоя скрыт. Полное правило описано в разделе «What a refusal says about a declared value» (Что отказ сообщает об объявленном значении) документа vocabulary/compact-form-authoring.md.
Что assertions: не заменяет
assertions: — место для правил, охватывающих несколько полей. Этот блок не заменяет:
- Ограничения JSON Schema внутри
schema:— правила для отдельных полей (диапазон, шаблон, enum, формат, тип) задаются собственными ключевыми словами JSON Schema. - Поле
validate:компактной формы — пользовательские предикаты для отдельного поля с областью действия в одно поле. Используйтеvalidate:, когда правило относится к конкретному полю; используйтеassertions:, когда правило затрагивает несколько полей и ни одно из них не является «тем, которое проверяется». - Поле
when:компактной формы — условная структура (применяются ли ограничения поддерева). Используйтеwhen:для вариаций структуры; используйтеassertions:, когда сочетание значений недопустимо так, что это лучше выразить предикатом в свободной форме. - Проверки во время выполнения —
assertions:выполняется только во время компиляции. Всё, что зависит от состояния кластера во время выполнения (текущие IP-адреса, содержимое хранилища секретов, статус подов), должно выражаться детерминированными строками-указателями (см. контракт AOT-чистоты).
Разобранные примеры
Минимальный — одно архитектурное правило
spec: assertions: replication-needs-two-secondaries: | {{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}} {{- fail "replication requires secondary.replicaCount >= 2" -}} {{- end -}}Средний — контракт сущности Component из нескольких правил
spec: assertions: # Replication minimum. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node limit. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)" $total .values.primary.replicaCount .values.secondary.replicaCount) -}} {{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one. service-monitor-needs-metrics: | {{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}} {{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}} {{- end -}}Производственный — сущность Recipe с правилами реализации
spec: assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# TLS certificate consistency. tls-needs-both-certificate-files: | {{- if .values.tls.enabled -}} {{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}} {{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}} {{- end -}} {{- end -}}
# Replication-mode storage class consistency. replication-needs-one-storage-class: | {{- if eq .values.architecture "replication" -}} {{- $primaryClass := .values.primary.persistence.storageClass -}} {{- $secondaryClass := .values.secondary.persistence.storageClass -}} {{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}} {{- fail "replication mode requires primary and secondary to use the same storageClass" -}} {{- end -}} {{- end -}}Интеграция с инструментами
aggrega buildвычисляет проверки между валидацией по схеме и рендерингом; непройденная проверка останавливает сборку с сообщением{{ fail }}этой проверки.aggrega validateприменяет ту же проверку корректности до рендеринга, не записывая артефакты: для сущности Recipe, источник которой не загружается, она запускает настоящий конвейер компиляции вокруг синтезированных минимальных сущностей Aggregate, Manifest и Release, так что некорректный шаблон проверки или проверка, ссылающаяся на неизвестное поле, выявляется как ошибка корректности; проверки сущности Recipe, источник которой загружается, вычисляются при сборке. Проверка, которая при этом вызываетfail, сообщается как предупреждение с её сообщением, и проверка корректности проходит: синтезированная сущность Release содержит заполнители и значения по умолчанию, а не значения, которые задаёт настоящая сущность Release, поэтому вердикт по проверке остаётся за сборкой — см. непройденная проверка — это предупреждение. (aggrega lintохватывает соглашения о публикации, а не корректность проверок.)- IDE с поддержкой шаблонов Sprig подсвечивают ссылки
.values.X; всплывающая документация ведёт к определению в схеме, если интеграция с IDE настроена.