Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Блок `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.

Для каждой из них поле необязательно. Сущности без межполевых правил полностью опускают это поле.

Когда выполняются проверки

Фазы вычисления проверок находятся в конвейере компиляции между валидацией по схеме и рендерингом:

  1. Разрешение: валидация и интерполяция параметров, затем валидация по схеме относительно schema: / usesSchema: / featuresSchema:.
  2. Построение топологии и финализация графа: граф собирается.
  3. Статический анализ: селектор каждого сокета uses: проверяется по меткам компонентов, к которым ведут его соединения.
  4. Проверки Component / Feature вычисляются для каждого экземпляра.
  5. Привязка Recipe.
  6. Проверки Recipe / FeatureRecipe вычисляются для привязанного экземпляра.
  7. Рендеринг: вычисляются шаблоны сопоставления, формируется результат.

Обе фазы проверок выполняются до какого-либо рендеринга — ни один чарт не отрендерен, ни один файл 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.1 eq значению 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/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
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/v1beta1
kind: Recipe
metadata:
name: bitnami/datastore/mariadb/k8s
version: 1.0.0
spec:
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 настроена.