Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Стовпи даних

Концептуальне обґрунтування п’яти структурних ключових слів DSL — parameters, values, uses, infra, inject — наведено в architecture/06-data-taxonomy-and-composition.md. Ця сторінка охоплює канонічний список стовпів даних, семантику написання для кожного стовпа, міжстовпову механіку та словник значень за замовчуванням, з яким автори стикаються в різних стовпах. Доповнювальну тріаду топології (provides, inject, uses — ключові слова, що з’єднують ребра графа) задокументовано в topology-triad.md; словник метаданих, відмінний від стовпів даних (мітки, анотації, поля поверхні публікації), описано в labels-and-annotations.md і publishing-surface.md.

Канонічний перелік стовпів

Сутності Aggrega мають сім іменованих стовпів даних. П’ять беруть участь у потоці даних IR як живий стан аж до рендерингу; два є тимчасовими або приватними й існують лише на певних етапах компіляції.

СтовпДе розміщенийЖиттєвий циклРоль
valuesЕкземпляри компонентів / приєднань в AggregateЖивий до рендерингу включноКогнітивне корисне навантаження, створене розробником
infraЗаписи компонентів, приєднань і з’єднань у ReleaseЖивий до рендерингу включноФізичне розмірювання, створене оператором
providesБлок provides: у RecipeЖивий до рендерингу включно (похідний стовп — див. нижче)Публічні вихідні рядки, обчислені Recipe, які споживає топологічний канал
usesЕкземпляри компонентів / функцій в AggregateЖивий до рендерингу включноТопологічні ребра до інших компонентів / функцій
featuresЕкземпляри компонентів в Aggregate + Release; слоти оголошено в featuresSchema сутності каталогу — див. «Стовп Features» нижчеЖивий до рендерингу включноСтовп приєднань — одна форма для кожної родини приєднань
parametersКорені Aggregate + ReleaseДоступний для читання до кінця конвеєра, доки не завершаться всі фази рендерингу; доступний шаблонам шляхів під час рендерингу через асиметричний дозвіл; контексти шаблонів значень споживають літерали після інтерполяції, а не .parameters безпосередньоСлоти для окремих середовищ, які заповнює Release
localsБлок locals: у RecipeПриватний для Recipe — видимий лише у власних шаблонах RecipeОбчислений рядковий стан, який Recipes виводять у преамбулі locals

values / infra / provides / uses / features — це п’ять живих стовпів, які контекст шаблону під час виконання надає через .values, .infra, .provides, .context.uses і .features відповідно. parameters і locals не входять до переліку живих стовпів: parameters — тому що не переживає розв’язання; locals — тому що він приватний для Recipe і ніколи не перетинає меж сутностей.

Стовпи — це покажчики, а не стіни: рушій шаблонів дозволяє читання між стовпами в кожному місці, якщо це явно не заборонено правилами самодостатності (блоки provides: і source: у Recipe, що читають .context.inject / .context.uses; описано в templates/expansion-matrix.md). Межі стовпів — це дисципліна авторства, а не примус з боку мови.

Межі стовпів і дисципліна авторства

Читання між стовпами з шаблону Recipe не обмежене в жодному місці, де доступний повний контекст шаблону. Дисципліна авторства очікує, що автори:

  • Читають .values для когнітивного вмісту (намір, визначений розробником).
  • Читають .infra для фізичного розміру (розмір, визначений оператором).
  • Читають .context.uses[].provides.<key> для рядків-вказівників між компонентами (потік даних топологічної тріади).
  • Читають .context.inject для каналу доставки після гідратації (зібраного з джерел inject у component.inject, uses[].inject і перехоплень injectMapping у FeatureRecipe).

Ця дисципліна — дороговкази, а не стіни. Шаблон Recipe, який читає .infra.replicas, щоб керувати полем values:, працює; рушій шаблонів не блокує таке читання. Архітектура розглядає межі стовпів як опис наміру авторства — кому належать дані, — а не як обмеження під час виконання. Домовленості відповідають поділу на чотири домени: значення, визначені розробником, беруться з .values; розмір, визначений оператором, береться з .infra; координати між компонентами беруться з топологічного каналу.

Коли потрібен навмисний міст між стовпами — наприклад, schema: сутності Component відкриває орієнтований на розробника параметр, який шаблон valuesMapping: сутності Recipe передає у вихідні дані формату infra: на боці Ops згідно з vocabulary/inheritance-and-interface.md, — архітектура розглядає такий міст як позначений дороговказом виняток. Див. «Механізми між стовпами» нижче.

Values

Стовп values: несе когнітивне навантаження, яке створює розробник, — параметри форми застосунку, які розробник задає для кожного екземпляра компонента. schema: сутності Component оголошує форму значень; Aggregate розробника заповнює конкретні значення для кожного екземпляра. Це домен розробника.

Де задається:

  • Aggregate components.<id>.values: — когнітивне навантаження для кожного екземпляра компонента.
  • Aggregate subsystems.<name>.components.<id>.values: — те саме, усередині компонентів, згрупованих у підсистеми.
  • Aggregate components.<id>.features.<name>.values: і features.<name>.values: підсистеми — навантаження значень прикріплення, хоч до якої родини належить прикріплена сутність Feature (параметри запиту до сховища секретів для прикріплення облікових даних задаються тут, як і будь-які інші).

Заборонено в:

  • Сутності Release (схема Release забороняє блок values: на будь-якому рівні вкладеності — підтримуваним шляхом для варіацій між середовищами є підняття параметрів (Parameter Hoisting); див. Parameters нижче).

Валідується: блоком values: у schema сутності Component (і блоком values: у schema сутності Feature для прикріплень Feature), який під час завантаження Component / Feature перетворюється на JSON Schema 2020-12 відповідно до vocabulary/validation-surface.md, рівень 2.

Споживається: шаблонами valuesMapping: сутності Recipe через .values. Повний контекст шаблону надає словник розв’язаних значень у кожному місці шаблону базового рендерингу.

Infra

Опора infra: містить фізичне визначення розмірів, яке задає оператор: репліки, запити ресурсів, ліміти IOPS, прив’язку до регіону, клас машини. Вона виражає де і наскільки великим, доповнюючи що і як воно поводиться з values. Це сфера оператора.

Чотири поверхні авторингу

Автори зустрічають infra: на чотирьох окремих поверхнях, кожна з власною областю застосування і власною поведінкою каскаду:

#ІнструментОбласть застосуванняПріоритет злиття
1Межа Release components.<id>.infra: (spec.components.<id>.infra: у сутності Release без меж)Один екземпляр компонентаВласні розміри компонента; жодна інша поверхня їх не записує
2Межа Release features.<name>.infra:Приєднання на всю межу, на кожному компоненті межіНайнижчий для цього приєднання — поверхня 3 перевизначає його поле за полем
3Межа Release components.<id>.features.<name>.infra:Одне приєднання на одному компонентіПеревизначає поверхню 2 для цього приєднання, поле за полем
4Release components.<id>.uses.<socket>.<alias>.infra:Одне з’єднанняПеревіряється за infraSchema сокета; доходить лише до рендерингу компонента-споживача

Поверхню 1 пишуть найчастіше: оператор задає розміри кожного компонента, який розміщує сутність Release. Межа не має власного infra: — схема Release його відхиляє, — тож розміри, спільні для кількох компонентів, записують на кожному з них або успадковують від батьківської сутності Release через extends: (нижче). Поверхні 2 і 3 охоплюють розміри приєднань Feature — Features несуть власний вміст infra, який FeatureRecipe використовує під час синтезу sidecar-контейнерів або ресурсів для кожної Feature: приєднання на всю межу отримує розміри один раз, а окремий компонент коригує одне його поле.

«Infra переважно локалізована» — правило з винятками

Архітектурна мета для infra: — локальність у межах компонента: розміри компонента застосовуються до цього екземпляра компонента і не поширюються на інші компоненти. Саме цей механізм дає змогу операторам збільшити IOPS бази даних, не впливаючи на запит CPU сервера API.

Правило: infra: переважно локалізована на поверхні, де її задано. Винятки каскаду існують за задумом:

  • Каскад анотацій межі. annotations: межі каскадно переходять через вкладені межі до внутрішніх компонентів (поверхня 5 матриці анотацій у labels-and-annotations.md). Анотації, які Recipes використовують як вхідні дані маршрутизації, стають непрямим впливом infra — анотація рівня межі проходить через .context.annotations.release у відрендерений вивід Recipe для кожного вузла.
  • Успадкування Release через extends:. Release, що виконує extends: батьківського Release, успадковує оголошення infra батька на кожній поверхні, яка їх містить, якщо дочірній не перевизначає їх поключово. Значення дочірнього перемагає ключ за ключем, аж до першого неподільного значення — скаляра, списку, шаблону, — яке замінюється повністю, а ключ, який дочірній записує як null, видаляється, а не встановлюється в порожнє значення. Успадкування свідомо перетинає межу окремого Release; повне правило згортання та те, що ще передається разом із ним, див. у entities/release.md.
  • Міжопорне передавання через міст схеми. schema: сутності Component може відкривати орієнтований на розробника перемикач values:, який шаблон valuesMapping: сутності Recipe передає у вивід постачальника у формі infra: (див. «Міжопорні механізми — міжопорне передавання через міст схеми» нижче). Строго кажучи, значення походить із values: і потрапляє у відрендерений вивід; каскад відбувається в межах екземпляра, але між опорами.

Локалізація є метою дизайну, а не стіною, яку забезпечує рушій: наведені вище каскади — свідомі винятки, кожен із яких задокументовано на поверхні, що його несе.

Розподіл за сторонами й опорами для розгортання Feature на основі анотацій. Інваріант «Aggregate як поверхня авторингу» поширюється на шлях розгортання Feature на основі анотацій: анотації на боці Aggregate (область підсистеми та екземпляра компонента) можуть запускати лише підключі maps.values; анотації на боці Release (область межі та екземпляра компонента) можуть запускати лише підключі maps.infra. Прив’язка Manifest може оголошувати шляхи в обох опорах; кожна сторона запускає лише сумісну з нею підмножину, а композиція між сторонами зливає внески поштучно за полями під час побудови IR. Розподіл зберігає розділення авторингу «values — розробник / infra — оператор» на поверхні анотацій — те саме розділення, яке values: і infra: забезпечують на поверхнях явного приєднання. Пояснення для кожного підключа та шаблон композиції між сторонами див. у providers/well-known-annotations.md §«Side-vs-pillar partition per subkey».

Provides

Стовп provides: є похідним — його оголошує Recipe, але, на відміну від values / infra, розробник не пише його безпосередньо. Recipes обчислюють публічні вихідні рядки, які споживатиме топологічний канал.

Блок provides: сутності Recipe — це мапа пар <key>: <template>. Під час обчислення provides кожен шаблон обчислюється відносно власної самодостатньої поверхні Recipe (.values, .infra, .context.instance_id, .context.rendered_name, якщо provider вузла його повідомляє, і розв’язані .locals вузла). Отримані рядки доступні через .provides і споживаються блоками uses[].inject викликачів через посилання from: "<key>". .locals доступні тому, що locals вузла розв’язуються в преамбулі цього етапу, раніше за його provides (див. Locals нижче); звернення до ключа, якого блок locals не оголошує, зупиняє компіляцію.

Інваріант самодостатності. Шаблони provides: сутності Recipe не повинні посилатися на .context.inject або .context.uses. Обчислення provides виконує ці шаблони в довільному порядку — вони замикаються лише на власних даних вузла, тож порядок не має значення. Посилання між вузлами пов’язали б це обчислення з порядком топологічного обходу, чого дизайн свідомо уникає. Правило та його обґрунтування див. у рядку 6 templates/expansion-matrix.md.

Чому provides: — це стовп. Вихідні рядки є канонічною публічною поверхнею кожного Recipe; споживачі нижче за потоком (uses[].inject викликача, блоки injectMapping сутності FeatureRecipe, що читають розв’язані provides цілі через .context.uses) розглядають цей словник як типізований контракт. Називаючи provides: стовпом, ми визнаємо його повноправний статус поряд із values / infra / uses / features. Розгляд його як «просто внутрішньої частини Recipe» применшує його роль як основного джерела даних топологічного каналу.

Uses

Стовп uses: — це оголошення топологічних ребер. Блок uses: екземпляра компонента називає ребра, у яких бере участь компонент, — сокети, через які він споживає цілі. Повну граматику задокументовано в topology-triad.md; у цьому розділі uses: названо стовпом для повноти.

uses: розміщується в екземплярах компонентів сутності Aggregate та в прикріпленнях функціональності; контекст шаблонів під час виконання надає по одному запису на кожне вихідне з’єднання, з його псевдонімом як ключем, як .context.uses. Проєкція містить розв’язані метадані цілі кожного ребра (provides цілі, мітки, анотації), щоб Recipes викликачів могли читати рядки-вказівники між компонентами під час обчислення шаблонів базового рендерингу, а також прикріплення, записані на цьому з’єднанні, за адресою .context.uses.<alias>.features.<slot>.

Стовп Features

features: — це стовп приєднань: одне ключове слово, одна форма, усі приєднання. Операційна сутність Feature, Feature облікових даних і Feature ідентичності оголошуються тут під іменем екземпляра, яке обирає автор. Контекст шаблонів під час виконання надає приєднання вузла як .features.<name>, кожне з яких містить type, values, infra і розв’язані provides приєднання. Приєднання, записане на одному зі з’єднань компонента, натомість надається в тій самій формі під з’єднанням, за шляхом .context.uses.<alias>.features.<slot>, і ніколи не під .features — тож Recipe, що перебирає .features, бачить лише власні приєднання компонента (див. контракт контексту шаблонів).

Приєднання, ім’я екземпляра якого збігається зі слотом, що його сутність оголошує в featuresSchema, заповнює цей слот; будь-яке інше ім’я екземпляра означає вільне приєднання. Саме заповнення слота поєднує чотири поверхні, якими проходять облікові дані на основі слота:

ІнструментДе пишетьсяРоль
Component / Feature featuresSchema:сутність каталогуОголошує слоти, яких очікує сутність; для кожного слота обмежує список дозволених способів доставки (env / file / blackbox) і, за потреби, селектор міток, якому має відповідати заповнення
Aggregate components.<id>.features.<slot>:Екземпляр компонента в сутності AggregateЗаповнює слот приєднанням; надає власні values: приєднання, а для прозорого слота — його відображення inject:
Workload containers.<name>.attachments.<KEY>.from/as:Тіло Workload у сутності RecipeПосилається на оголошений слот — або, поряд із connection: <alias>, на слот, який оголошує сокет цього з’єднання, — і визначає доставку того, що його заповнило, для кожного контейнера
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:)прив’язана FeatureRecipeСтворює результат приєднання — згенерований ресурс, переписування доставки або обидва

Ім’я слота є ключовим ідентифікатором для всіх чотирьох: поверхня 1 його оголошує, поверхні 2–4 на нього посилаються, а потік даних однонапрямлений (оголошення → заповнення → посилання → створення).

Контрольний список для авторів див. у examples/04-secrets.md, розділ «The secret-delivery checklist».

Locals

Стовп locals: — це приватний стан сутності Recipe. Увесь блок розв’язується в преамбулі locals, до provides: цього вузла; отримані рядки видимі всім пізнішим шаблонам самої сутності Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Шаблон provides:, що називає ключ, не оголошений у блоці, зупиняє компіляцію.

Де задається: блок spec.locals: сутності Recipe — мапа пар <key>: <template>, що обчислюються щодо самодостатньої локальної для вузла поверхні: .context.instance_id, .values, .infra та вже розв’язані записи того самого блоку. Більше на ній нічого немає: .provides, .metadata та решти .context.* там немає, і посилання на будь-що з них зупиняє компіляцію.

Порядок має вирішальне значення. Записи розв’язуються в порядку написання, і запис може читати сусідній запис, визначений вище за нього, отримуючи його розв’язане значення. Ланцюжки працюють лише згори вниз — якщо один запис читає інший, перенесення визначення нижче за того, хто його читає, відхиляється, і компілятор ніколи не переставляє блок, щоб посилання розв’язалося. Посилання на пізніший запис зупиняє компіляцію з повідомленням про помилку порядку; посилання на неоголошений ключ зупиняє її з назвою ключа. Для сутності Recipe, чий source: є структурованим блоком, обидві помилки відхиляються ще під час закріплення артефакту, який він називає, тож aggrega pull повідомляє про них раніше, ніж будь-яка збірка згенерує вивід. Перевірка читає шлях, до якого посилання розв’язується, а не набраний текст, тож охоплює і пряму форму, і блок with .locals, і змінну, прив’язану до .locals, і блок у дужках, (.locals).<key> або ($.locals).<key>. Один запис вона не охоплює: ключ, отриманий через функцію, як-от index .locals або (default dict .locals).<key>. Відсутній ключ, отриманий у такий спосіб, не зупиняє компіляцію і генерує буквальний текст <no value>, а не порожнечу — крім випадку самої index, яка на кожній поверхні шаблонів зупиняє компіляцію з назвою ключа, коли мапа, яку вона читає, його не містить.

Видимість: приватна для сутності Recipe. Поля .context.uses[].locals немає — викликач не може прочитати locals своєї цілі через ребро. Викликач може читати provides: цілі.

Сценарії використання:

  • Обчислення внутрішніх для Recipe рядків-вказівників (наприклад, secret_target_admin_password: "redis-auth", суфікс імені Secret), які споживають і valuesMapping:, і provides: цієї сутності Recipe і які FeatureRecipe для облікових даних, приєднаний до того самого компонента, читає як .locals.secret_target_admin_password — шаблони приєднання бачать розв’язані locals хостової сутності Recipe, об’єднані з власними locals приєднання. На цілі helm кожен із них записує повне ім’я як {{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: згенероване ім’я — це ім’я компонента, записане символами, дозволеними в іменах Kubernetes, і local не може його прочитати, тож local містить суфікс, а кожен читач поєднує обидві частини.
  • Усунення повторень обчислюваних значень в одній сутності Recipe (ім’я хоста, обчислене один раз і використане в кількох полях valuesMapping:).
  • Проміжні значення для складної логіки шаблонів, яка була б нечитабельною в рядку.

provides: і locals: — публічне й приватне обличчя

Два стовпи на боці Recipe мають навмисний розподіл видимості, про який авторам слід пам’ятати:

  • provides: — публічне обличчя. Кожен ключ є канонічною поверхнею топологічного каналу — блоки uses[].inject низхідних викликачів споживають їх через посилання from: "<key>". Словник provides: — це типізований контракт, від якого залежать викликачі; перейменування чи видалення ключа є несумісною зміною для кожної сутності Recipe, чиї оголошення uses[].inject на нього посилаються.
  • locals: — приватне обличчя. Кожен ключ є внутрішнім станом Recipe, видимим лише в подальших шаблонах самої сутності Recipe. Жоден викликач не може прочитати locals сутності Recipe; імена в locals: не входять до жодного опублікованого інтерфейсу, і їх перейменування — це внутрішній рефакторинг Recipe без наслідків для низхідних споживачів.

Вони також упорядковані: locals: розв’язується першим, тож provides: може читати .locals, але locals: не може читати .provides. Тому публікація значення local через provides: означає додавання запису provides, який читає цей local — вираз залишається в одному місці.

Розподіл навмисний і відповідає архітектурному відокремленню внутрішньої будови Recipe (приватної) від інтерфейсу Recipe (публічного). Автори, які розглядають provides: і locals: як один простір імен, втрачають розрізнення видимості й ризикують розкрити внутрішній стан через топологічний канал — кожен ключ, оголошений у provides:, стає частиною контрактної поверхні сутності Recipe, незалежно від того, чи мав це на увазі автор. Мета дисципліни: спершу оголошуйте ключ у locals:; переносьте до provides: лише тоді, коли він справді потрібен низхідному викликачеві.

Видимість визначає стовп, у якому оголошено ключ: позначки видимості для окремого ключа немає, тож значення, яке водночас приватне й опубліковане, — це запис locals: і запис provides:, що його читає.

Параметри

Схеми Aggregate і Release мають у корені словник parameters. Розробники оголошують ключі, яких очікує Aggregate; Ops заповнює значення з файлів Release для конкретного середовища. Це розділення є механізмом просування в GitOps: один незмінний Aggregate.yaml проходить середовища Dev, Staging і Production, а Release кожного середовища надає власні значення параметрів.

aggregate.yaml
spec:
parameters:
corp_db_name:
type: string
required: true
env_workers:
type: integer
required: true
region:
type: string
required: true
enable_debug:
type: boolean
required: true
components:
my-backend:
type: core/python-worker:1.0.0
values:
workers: {{ .parameters.env_workers }}
region: "{{ .parameters.region }}"
# release-prod.yaml — inline parameter values
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
corp_db_name: "enterprise_data"
env_workers: 10
region: "eu-west-1"
enable_debug: false

Для процесів CI/CD, які зберігають значення параметрів в окремому файлі (наприклад, у .yaml для кожного середовища, що зберігається поруч із Release), Release використовує форму $import:: parameters: { $import: ./prod-values.yaml }. Вміст файлу замінює вбудовану мапу на рівні Release. Шлях визначається відносно каталогу, що містить Release, незалежно від того, звідки запущено команду, і має вести до файлу всередині робочого простору, а для Release, вказаного поза робочим простором, — всередині каталогу, що його містить. Багатофайлове нашарування (поєднання базового файлу з накладкою для конкретного середовища) виражається ланцюжками extends: сутності Release: батьківська Release надає базові параметри, дочірня Release розширює їх і перевизначає за ключами.

Життєвий цикл параметрів. Компілятор визначає параметри у три фази. (1) Заповнення типовими значеннями — слоти, для яких визначено default: і немає значення з Release, отримують типове значення. (2) Перевірка контракту параметрів — типізований контракт parameters: перевіряє кожне значення на відповідність оголошеним обмеженням type / enum / min / max / pattern, включно із заповненим типовим значенням, тож типове значення, яке порушує власний контракт, зупиняє збірку. (3) Інтерполяція — компілятор обчислює весь текст Aggregate як шаблон і замінює кожне посилання {{ .parameters.<slot> }} визначеним значенням. Після цього об’єднана мапа залишається доступною для читання під час рендерингу, тож шаблони шляхів (directory: / subDirectory: на межі Release) можуть читати .parameters.<slot> безпосередньо відповідно до закритого списку дозволених змінних, описаного в ../path-template-variables.md. Поверхні шаблонів значень (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, тіла Workload) НЕ отримують .parameters у своєму контексті шаблону — вони використовують визначені значення, записані в навколишні рядки values: під час інтерполяції фази 3.

Контрольний список підняття параметрів

Кожне значення, що відрізняється між середовищами, послідовно проходить чотири точки авторингу. Ментальна модель для авторів: для будь-якого значення, що змінюється між Dev / Staging / Production, слід очікувати змін в Aggregate (оголошення), шаблоні значень (посилання), Release (заповнення) і шаблоні Recipe (використання).

КрокІнструментДія
1Aggregate spec.parameters.<name>Оголосіть параметр як частину типізованого контракту авторингу Aggregate. Кожен слот параметра має оголошений type (string, integer, number, boolean, array, object), необов’язковий description, необов’язковий default, необов’язкові обмеження простору значень (enum, min, max, pattern, minLength, maxLength) і необов’язкову вкладену структуру для слотів типу object. Контракт перевіряє кожне значення, надане Release, перед інтерполяцією.
2Шаблон values: сутності Component у тій самій сутності AggregateПошліться на параметр через {{ .parameters.<name> }} усередині блоку values: будь-якого компонента (або feature, або вкладеного aggregate), що його використовує. Посилання є виразом шаблону Go — компілятор обчислює його у фазі інтерполяції під час визначення.
3Release spec.parameters.<name> (вбудовано або parameters: { $import: ./path.yaml })Заповніть параметр значенням для конкретного середовища на рівні Release. Файли Release для різних середовищ надають різні значення для того самого ключа параметра без змін в Aggregate.
4Шаблон Recipe valuesMapping:Використайте визначене значення через {{ .values.<key> }} — Recipe є поверхнею шаблонів значень; її контекст шаблону не містить .parameters безпосередньо. Відмінності між середовищами доходять до Recipe через словник values: після інтерполяції, який записує описана вище фаза інтерполяції. (Виняток — шаблони шляхів на межах Release: вони читають .parameters.<slot> безпосередньо під час рендерингу згідно з асиметричним дозволом.)

Чотири точки послідовні й несучі: якщо пропустити оголошення в Aggregate, у Release не буде слота для заповнення; якщо пропустити посилання у values, у Recipe не буде значення для використання; якщо пропустити заповнення в Release, параметр залишиться порожнім. Компілятор перевіряє ланцюжок під час визначення (перевірка контракту параметрів щодо типізованого оголошення parameters:, потім інтерполяція в навколишні рядки values:, потім перевірка отриманого словника values: за JSON Schema щодо schema: сутності Component або Feature); невідповідності проявляються як порушення контракту параметрів (виявляється щодо типізованого оголошення parameters:), помилка незаповненого шаблону (виявляється під час інтерполяції) або порушення обмеження JSON Schema щодо схеми values: (виявляється під час перевірки схеми).

Цей шаблон є канонічним механізмом просування в GitOps: один незмінний Aggregate проходить середовища, а Release кожного середовища надає власні значення параметрів. Кожне значення, яке автор хоче змінювати між середовищами, має проходити ланцюжком параметрів, а не вбудовуватися безпосередньо в Aggregate.

Семантика злиття extends: для кожного стовпа

Коли сутність каталогу оголошує extends: і компілятор проходить ланцюжок успадкування, вміст кожного стовпа зливається за правилами, властивими цьому стовпу. Семантика відрізняється між стовпами; таблиця нижче є канонічним довідником для кожного стовпа.

СтовпПоведінка злиття в ланцюжку extends:
values (JSON Schema 2020-12)У ланцюжку Feature схеми компонуються через композицію JSON Schema 2020-12. Сутність Component, що розширює іншу, не створює вмісту стовпів і отримує блок своєї базової сутності точно таким, яким його створила база, на будь-якій глибині ланцюжка.
infra (фрагмент JSON Schema 2020-12)Так само, як values: компонується в ланцюжку Feature, успадковується цілком сутністю Component, що розширює іншу.
provides (мапа шаблонів Recipe)Поверхнева заміна на верхньому рівні: ключ дочірньої сутності повністю замінює ключ батьківської з тим самим іменем; сусідні ключі зберігаються з батьківської. Шаблони не компонуються; шаблон дочірньої сутності повністю володіє своїм слотом.
uses (usesSchema)Накладання цілих записів для кожного сокета за іменем сокета. Дочірня сутність додає сокети, яких не оголошує її база, а сокет, який вона повторно оголошує під наявним іменем, повністю замінює цей запис — разом зі схемами значень та інфраструктури і своїм selector. Записи сокетів не компонуються, і ніщо не порівнює повторно оголошений selector з базовим.
features (схема featuresSchema для кожного слота)Накладання цілих записів для кожного слота за іменем слота, на тих самих умовах, що й usesSchema. Дочірня сутність вільно додає слоти; слот, який вона повторно оголошує, повністю замінює запис бази, а не компонується з ним.
locals (мапа шаблонів Recipe)Поверхнева заміна на верхньому рівні — так само, як provides.
parameters (коренева мапа Aggregate)Сутність Aggregate не має поля extends:, тож жоден ланцюжок Aggregate не зливає параметрів. У ланцюжку extends: сутності Release параметр зі значенням-мапою зливається глибоко з перевагою ключа дочірньої сутності, скалярний параметр замінюється дочірньою, а ключ, який дочірня сутність записує як null, видаляється.

Загальний шаблон залежить від виду сутності та від інструмента. Стовпи сутності Feature, що валідуються схемою, компонуються за JSON Schema 2020-12. Стовпи сутності Component, що розширює іншу, успадковуються цілком — вона не створює жодного, тож її контракт точно збігається з контрактом бази, і тому обмеження бази за побудовою неможливо послабити. Інструменти фіксованої форми — usesSchema і featuresSchema — накладаються за іменем для обох видів: дочірня сутність додає записи, а запис, який вона повторно оголошує, повністю замінює запис бази. Стовпи, що створюються шаблонами, використовують поверхневу заміну за ключами, надаючи дочірній сутності повне володіння будь-яким оголошеним нею слотом шаблону.

Сутність Component, що розширює іншу, посилює обмеження через assertions:, а не через стовп — це предикат, який вона додає і який обчислюється разом з успадкованими. Див. inheritance-and-interface.md щодо цього механізму.

Про сам механізм успадкування див. inheritance-and-interface.md, розділ «Inheritance via extends», який охоплює види сутностей каталогу. Сутність Release не є сутністю каталогу і згортається за власним правилом; це правило наведено в entities/release.md, розділ «Composite Release and extends: inheritance».

Міжстовпова механіка

Підхід із дороговказами дозволяє міжстовпові зчитування всюди, крім задокументованих поверхонь самодостатності. Наведені нижче шаблони формалізують поширену міжстовпову механіку; задокументовано й одну ознаку поганого авторства, щоб автори розпізнавали компроміс.

Міжстовпова передача через схемний міст — дороговкази, а не стіни

Межі стовпів — це дисципліна авторства: архітектура вказує, що куди належить (values: для когнітивного наміру розробника, infra: для фізичного розміру з боку Ops, provides: для рядків, які видає Recipe, тощо), а рецензент каталогу забезпечує дотримання домовленості. Сам рушій шаблонів дозволяє міжстовпові зчитування, якщо їх не забороняють задокументовані правила самодостатності (provides: у Recipe не бачить .context.inject; provides: в області меж FeatureRecipe не бачить полів окремих споживачів). Стіни стовпів — це дороговкази, а не примус.

Канонічний виняток із дороговказом: schema: сутності Component може оголосити орієнтований на розробника регулятор values:, який шаблон valuesMapping: сутності Recipe передає у відрендерений вивід у формі infra:. Розробник задає намір через типізоване поле values:; шаблон Recipe передає отримане значення в інфраструктурний шар провайдера, і розробнику не треба писати інфраструктурний код. Робочий приклад:

# Component schema declares a developer-facing dial in values
spec:
schema:
values:
required_iops: { type: integer, min: 100 }
# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knob
valuesMapping:
iops_limit: "{{ .values.required_iops }}"

Міст задокументовано в inheritance-and-interface.md з робочими прикладами. Архітектурний намір (оголошений міжстовповий регулятор, який передає Recipe) має один напрямок — values: з боку розробника надходить у відрендерений вивід з боку Ops — і реалізується в шаблонах відображення Recipe, а не в самій схемі Component. Межа стовпа лишається дороговказом: розробник бачить values:, Recipe бачить і values:, і infra:, а відрендерений вивід поєднує їх.

Міжстовповий накопичувач inject

Канал .context.inject — точка злиття трьох джерел, що охоплюють кілька стовпів:

  1. Самовпровадження на рівні Component (component.inject) — бере рядки з власних values і власних provides компонента.
  2. Uses-inject (uses[].inject) — бере рядки з provides цілі.
  3. Перехоплення injectMapping: у FeatureRecipe — бере рядки з будь-якого з наведених вище джерел, а також із власного корисного навантаження infra: сутності FeatureRecipe.

На момент запуску базового рендерингу .context.inject.<mechanism>.<key> уже накопичив записи з усіх трьох джерел. Накопичувач міжстовповий за побудовою — записи, що походять із values, provides та infra, надходять в одну мапу .context.inject. Recipes, що споживають .context.inject, бачать стан після злиття, не знаючи, який стовп дав який запис.

Граматику inject і правила колізій див. у topology-triad.md.

Міжстовпове дублювання обмежень

Поле, що існує у двох стовпах з різними шарами валідації, може мати дубльовані обмеження. Канонічний приклад: номер порту, оголошений у usesSchema сутності Component (валідація JSON Schema, діапазон min: 1, max: 65535), і той самий номер порту, спожитий у полі services.<name>.ports.<port> сутності Workload, для якого spec.provider.workloadSchema плагіна рендерингу провайдера може додати правило min: 1024 для непривілейованих портів. spec.provider.workloadSchema сутності Plugin для рендерингу провайдера документує, як провайдер перетворює Workload, і позначає провайдера як здатного її синтезувати; вона нічого не валідує. Кожне тіло Workload валідується за схемою Workload платформи, хоч би яким був провайдер, тож обмеження, записане лише у workloadSchema, — скажімо, правило порту min: 1024 — не застосовується; щоб відхиляти таке значення, розмістіть обмеження в схемі сутності Component або в твердженні (assertion).

Ізоляція стовпів між приєднанням Feature і Component

Приєднання Feature не записує у стовпи батьківської сутності Component. Кожна приєднана Feature має власне корисне навантаження стовпів (власний блок values: і власний блок infra:). FeatureRecipe, що синтезує ресурси Feature, читає власне навантаження стовпів незалежно від навантаження Component. Ізоляція стосується входів: те, що читає приєднання, належить йому, хоч би що сталося з тим, що воно записує. Якщо провайдер цілі записує окремі документи, відрендерений вивід приєднання розміщується поруч із виводом Component у власному каталозі; якщо провайдер згортає учасників межі в один документ, приєднання робить внесок у цей документ так само, як Component, і кожен ресурс усе одно несе власну ідентичність приєднання, тож походження лишається зрозумілим.

Два наслідки для авторів:

  • Параметр values: у приєднанні Feature не з’являється в .values шаблону valuesMapping: сутності Component. Component бачить лише власні значення.
  • Корисне навантаження infra: сутності Feature не надходить у infra: сутності Component. Кожна приєднана Feature має власний фізичний розмір, обмежений ресурсами цієї Feature.

Ізоляція явна згідно з архітектурним розділенням відповідальностей: Features — незалежні учасники, що нашаровуються на Components через 5-рівневу модель цибулини. Поверхні приєднання й порядок див. у labels-and-annotations.md, «Feature attachment — five surfaces».

Однакова назва властивості в обох стовпах

Component або Feature, у яких spec.schema.values: і spec.schema.infra: оголошують однакову назву властивості — у корені, на будь-якій глибині вкладення або і там, і там, — це поширена ознака поганого авторства. Два стовпи за задумом є окремими просторами імен (компілятор приймає перетин), тож схема проходить валідацію, а відрендерений вивід коректний. Проблема когнітивна: читачі й автори шаблонів щоразу, переглядаючи схему чи пишучи шаблон для неї, стикаються з питанням «у якому стовпі той foo, який я читаю?».

# Smell — both pillars declare `mode`. A reader of the schema or a
# template against the Feature has to disambiguate every reference.
spec:
schema:
values:
mode: { type: string }
infra:
mode: { type: string }

Автори з навмисним перетином мають реальну причину зберегти обидва — наприклад, mode, що означає «робочий режим застосунку» у values ("debug" / "production") і «режим топології розгортання» в infra ("standalone" / "clustered"), має різну семантику, а назви просто збігаються. Автори з випадковим перетином (частіший випадок) перейменовують один запис.

Друга навмисна форма — одне значення, яке може надати будь-який з авторів. Облікові Features стандартної бібліотеки, що несуть локатор викликача, — core/referenced-secret, core/referenced-secret-set, core/secret-value і core/secret-provided — оголошують його в обох стовпах під однією назвою й в одній формі, тож розробник записує його у values або оператор в infra, а власна перевірка кожної Feature відхиляє приєднання, яке записує його в обох або в жодному. Наведене нижче попередження називає ці чотири під час кожного завантаження, що до них доходить; для них воно повідомляє про контракт, а не про помилку.

Завантаження каталогу видає попередження notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) для кожної однойменної властивості, перетин якої хоча б з одного боку зводиться до кінцевого листка. Однойменні властивості, що існують як спільні впорядкувальні простори імен (обидва стовпи мають об’єкт ingress з неперетинними підвластивостями), попередження не викликають; повідомляється лише перетин листків. Попередження лише інформативне — збирання триває.

Рівні валідації стовпів

Валідація стовпів відбувається на трьох рівнях. Кожен рівень охоплює окремий аспект; те саме поле може перевірятися більш ніж одним рівнем (див. «Дублювання обмежень між стовпами» вище).

РівеньЩо перевіряєДе виконується
1 — оболонка JSON SchemaСтруктурна форма (які ключі присутні, чи відповідають типи оголошенням полів)Розв’язання, під час завантаження кожного файлу
2 — схема окремого стовпа (schema / featuresSchema / usesSchema)Типізований вміст кожного стовпа, перевірений як JSON Schema 2020-12Розв’язання, після успішної перевірки оболонки
3 — шлюз можливостей провайдераВміст сутності Workload, обмежений можливістю синтезованого режиму прив’язаного провайдера, задокументованою в spec.provider.workloadSchema плагіна рендерингу провайдераБазовий рендеринг, після розв’язання valuesMapping

Таблицю форм помилок чотирьох шарів і префікси помилок для кожного шару див. у validation-surface.md.

Механізми значень за замовчуванням

Значення за замовчуванням з’являються в корпусі через кілька різних механізмів. Автори зустрічають слово «default» щонайменше в п’яти контекстах; таблиця нижче є канонічним довідником щодо того, який механізм дає значення, коли автор залишає поле порожнім.

#МеханізмДе пишетьсяТригер
1JSON Schema default: (компактна форма { default: <value> })Component / Feature schema:, Aggregate parameters:Поле проходить валідацію зі значенням за замовчуванням, коли розробник пропускає ключ. Для параметрів сутності Aggregate злиття параметрів заповнює оголошене значення за замовчуванням до запуску валідації контракту (див. templates/parameters-context.md).
2Шаблон Go optional .X `Y` <fallback>Recipe valuesMapping:, тіло Workload, шаблони FeatureRecipe, обчислювач твердженьРезервне значення з урахуванням наявності — повертає <fallback> лише тоді, коли ключ відсутній у мапі; авторське нульове / порожнє / false значення за ключем повертає саме це авторське значення. Канонічна форма резервного значення для відсутнього поля на боці Aggrega. Див. templates/sprig-functions.md.
3Шаблон Go | default <expr>Recipe valuesMapping:, тіло Workload, шаблони FeatureRecipeВбудований конвеєр, що спрацьовує на «порожнє» (перевірка порожнечі Sprig — нуль, порожній рядок, false, nil). Змішує відсутність у мапі з наявним, але нульовим/порожнім/false значенням. Доречний для семантики перевизначення в конкретному місці виклику (резервне значення прив’язки відрізняється від значення за замовчуванням поля на рівні схеми), де таке змішування прийнятне. Недоречний для резервного значення відсутнього поля, де авторське нульове / порожнє / false значення є легітимним наміром — для цього випадку використовуйте optional (механізм 2).
4Функція Sprig default ({{ default <expr> .field }})Те саме, що й 3Функціональна форма механізму 3 з тим самим змішуванням порожнечі.
5Резервне значення Recipe locals:Шаблон Recipe locals:Запис locals обчислює рядок зі значенням за замовчуванням, який використовує решта сутності Recipe

Рекомендації щодо розміщення. Коли значення за замовчуванням справді є частиною контракту типу (наприклад, «цей порт за замовчуванням 5432, якщо розробник його не перевизначить»), канонічним є JSON Schema default: (механізм 1) — автодоповнення IDE показує значення за замовчуванням; інструменти валідації його враховують; контракт супроводжує сутність каталогу Component / Feature АБО оголошення параметра Aggregate. Коли шаблону Recipe потрібне резервне значення для необов’язкового ключа мапи, канонічною формою резервного значення для відсутнього поля є хелпер optional (механізм 2) — він відрізняє авторське нульове / порожнє / false значення від відсутності. Шаблон Go | default (механізм 3) призначений для випадку перевизначення в конкретному місці виклику, де змішування відсутніх і хибних значень прийнятне; вдавайтеся до нього лише тоді, коли семантика перевизначення є явним наміром.

Перехресні посилання

  • inheritance-and-interface.md — механізм extends:, прив’язка інтерфейсу implements:, міжстовпове передавання через мости схем.
  • topology-triad.md — топологічна механіка provides, inject, uses.
  • labels-and-annotations.md — словник метаданих на боці вмісту, відмінний від стовпів даних (наведений вище канонічний перелік стовпів не містить міток, анотацій і полів публікації — це словник метаданих).
  • publishing-surface.md — словник метаданих на боці публікації, відмінний від стовпів даних.
  • validation-surface.md — чотири рівні валідації схем, зокрема три наведені вище рівні валідації стовпів.
  • templates/expansion-matrix.md — доступність міжстовпового читання для кожного місця шаблону та правила самодостатності в provides: і source: сутності Recipe.
  • examples/04-secrets.md — контрольний список доставки секретів із шести точок дотику.
  • architecture/06-data-taxonomy-and-composition.md — канонічне концептуальне обґрунтування п’яти структурних ключових слів DSL.