Блок `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 -}}Прохід (range) обходить з’єднання сокета в алфавітному порядку їхніх псевдонімів — тут 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/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 є частиною реалізації. Коли архітектор обирає чарт Bitnami 20.x як Recipe, цей чарт має свої особливості (вимога
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> усюди, де повідомлення його цитує, тож називати в повідомленні значення оголошеного поля безпечно: діагностика все одно називає правило й поле, приховується лише значення. Перевірка, результат якої залежить від вмісту такого значення — порівняння з літералом, перевірка префікса, — повідомляє, що текст її невдачі приховано, замість свого повідомлення. Повне правило наведено в vocabulary/compact-form-authoring.md «What a refusal says about a declared value» («Що повідомляє відмова про оголошене значення»).
Що не замінює assertions:
assertions: — це місце для правил, що охоплюють кілька полів. Воно не замінює:
- Обмеження JSON Schema всередині
schema:— правила для окремих полів (діапазон, шаблон, перелік, формат, тип) належать до власних ключових слів 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 налаштовано.