Release
Концептуальну роль сутності Release (Домен 4 — маршрутизатор розгортання, що прив’язує Aggregate до Manifest і відображає компоненти на фізичні межі) описано в architecture/04-entity-taxonomy.md. Механізм часового впорядкування (syncWave для кожної межі), Dynamic Addressing Polyfill і патерн Parameter Hoisting описано в architecture/12-day-two-lifecycles.md. Ця сторінка охоплює засоби створення сутності Release.
Роль сутності Release
Сутність Release прив’язує aggregate до manifest і розподіляє компоненти між фізичними межами розгортання (наприклад, aws-eks-production). Це єдина точка входу для компіляції: aggrega build --release release.yaml.
Сутність Release виконує абстрактний контракт агрегату, вносячи фізичні реалії суворо в блок parameters, а фізичні розміри (як-от CPU чи порти) вносить через паралельний простір імен infra.
Кожна сутність Release оголошує поле manifest:, яке називає її сутність Manifest (якщо тільки Release не використовує extends:, що успадковує вказівник на маніфест від батьківської сутності). CLI aggrega build читає це поле безпосередньо; прапорця CLI --manifest не існує, тож специфікація залежностей зберігається в Git поруч із самою сутністю Release, і історію розгортань можна перевірити через власну історію Git сутності Release.
Поля aggregate: і manifest: розв’язуються за ідентичністю або за файлом із відносним шляхом — так само, як решта мови розв’язує посилання, — і ніколи як основа імені файлу відносно релізу. Значення ./ або ../ — це явний локальний файл, який читається безпосередньо відносно сутності Release. Окремий токен — це ідентичність: metadata.name сутності, на яку посилаються. Ідентичність manifest: розв’язується скануванням власного каталогу сутності Release (Manifest — це конфігурація оператора на боці розгортання, тож для нього немає рівня каталогу чи реєстру). Ідентичність aggregate: розв’язується через повний каскад — каталог сутності Release, потім каталог, потім реєстр, — тож сутність Release може назвати опублікований Aggregate за ідентичністю, і той самий опублікований модуль розв’язується незалежно від того, чи це spec.aggregate верхнього рівня сутності Release, чи вкладений агрегат усередині іншого Aggregate. Ця модель «ідентичність або шлях» дає змогу спільному Aggregate лежати в основі багатьох варіантів Release без прив’язки посилання до імені файлу, а опублікований Aggregate — розгортати безпосередньо за іменем.
Шлях залишається всередині робочого простору. Значення ./ або ../ називає файл, що належить робочому простору, як і кожен інший шлях, який записує сутність Release, — її extends: і $import: параметрів, див. нижче. Шлях, що в записаному вигляді виходить за межі робочого простору або який символьне посилання дорогою виводить за його межі, відхиляється ще до того, як із названого ним файлу буде щось прочитано. Щоб розгорнути Aggregate, що зберігається поза робочим простором, назвіть його за ідентичністю і вкажіть каталог, у якому він міститься, як каталог каталогу в конфігурації робочого простору; Manifest, сутність Release, яку називає extends:, і файл параметрів читаються поруч із сутністю Release і ніколи не шукаються за іменем, тому їх зберігають усередині робочого простору. Сутність Release поза робочим простором, яку ви вказуєте в командному рядку або яку називає конфігурація робочого простору, є окремим коренем: кожен шлях, який вона записує, — і кожен шлях, який записує сутність Release, до якої веде її ланцюжок extends:, — має вести до файлу всередині каталогу, що містить цю сутність Release, а шлях, що виходить за межі цього каталогу або який посилання виводить за його межі, відхиляється так само. Зберігайте те, що називає така сутність Release, поруч із нею або збирайте її в робочому просторі, що містить і те, і інше. Див. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Посилання на інший файл виводить за межі каталогу, в якому воно має залишатися)”.
Сутність Release визначає місце призначення скомпільованих артефактів; диспетчеризація провайдерів належить сутності Manifest, на яку вказує Release (розподіл ролей описано в розділі Manifest і Release: розділення відповідальності).
Метадані середовища
Кожен блок метаданих сутності Release приймає поле environment: — довільний рядок, що ідентифікує середовище, у яке розгортається Release (типові значення: production, staging, dev). Поле має інформаційний характер: воно не має переліку допустимих значень, шаблону на рівні схеми чи перевірки між сутностями, окрім type: string. Компілятор виводить його значення як мітку aggrega.ai/environment на кожному маніфесті Kubernetes, який рендерить провайдер helm, разом з рештою набору міток походження Aggrega, — у записаному вигляді, якщо це допустиме значення мітки Kubernetes, а інакше переписаним у допустиме значення, при цьому точне значення передається в анотації aggrega.ai/environment (тож eu/prod отримує мітку eu-prod); провайдер helm-chart додає ті самі мітки до кожного завантаженого через $import: артефакту, який він розміщує в підчарті, тоді як власні шаблони підчарту містять те, що написав їхній автор. Провайдер compose передає те саме значення як мітку aggrega.ai/environment на кожному сервісі, який він виводить.
П’ять практичних сценаріїв визначають, як заповнювати environment::
-
Розподіл витрат OTel/FinOps. Панелі хмарних витрат (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) фільтрують поди Kubernetes за тегом середовища. Мітка
aggrega.ai/environment: productionпотрапляє в мітки подів через механізм додавання міток провайдера Helm; звіти про витрати групують їх заaggrega.ai/environmentбез ручного тегування кожного ресурсу. -
Фільтрація трасувань і журналів OTel. Панелі спостережуваності (Datadog, New Relic, Honeycomb, Grafana Tempo) фільтрують телеметрію за міткою середовища.
aggrega.ai/environment: stagingдає операторам змогу обмежити запити до журналів і пошук трасувань середовищем staging без фільтрації за домовленостями щодо просторів імен чи назвами чартів — одна канонічна мітка на всій відрендереній поверхні. -
Націлювання операторів Kubernetes. Контролери GitOps (ArgoCD, Flux) і оператори політик (Kyverno, OPA Gatekeeper) іноді фільтрують ресурси за міткою середовища для політик, специфічних для середовища (наприклад, «ресурси лише для production потребують мітки схваленого джерела образу»). Мітка
aggrega.ai/environmentнадає стабільний селектор, незалежний від домовленостей щодо просторів імен чи шаблонів іменування. -
Розрізнення production у кількох регіонах. Команда, що запускає сутність Release
production-us-eastпоряд із сутністю Releaseproduction-eu-west— обидві зmetadata.environment: production, — отримує однакову міткуaggrega.ai/environment: productionв усіх регіонах. У поєднанні з окремою міткою регіону це дає змогу зводити витрати між регіонами («загальні витрати на production») і деталізувати їх за кожним регіоном. -
Визначення обсягу відповідності. Збір доказів для SOC 2, PCI та HIPAA обмежується середовищем (аудит лише production тощо). Мітку
aggrega.ai/environmentвикористовують інструменти збору доказів відповідності (Vanta, Drata), щоб фільтрувати ресурси за обсягом аудиту.
Схема вимагає environment: у кожній сутності Release; значення має інформаційний характер, і компілятор читає його лише для того, щоб записати мітку aggrega.ai/environment.
Обмеження на рівні схеми
Дві структурні гарантії захищають сутність Aggregate як єдине джерело істини:
values:заборонено. Щоб захистити сутність Aggregate як єдине джерело істини, схема Release механічно забороняє блокvalues:— оператор не може оголоситиvaluesдля жодної сутності Component чи Feature із сутності Release. Заборона поширюється на ребраuses: записusesдля окремого ребра в сутності Release міститьinfraі вкладення, які він записує на з’єднанні, і ці вкладення теж містятьinfra— ніколиvalues(значення окремого ребра, призначені для розробника, і значення вкладення на з’єднанні залишаються в сутності Aggregate). Варіювання значень, призначених для розробника, між середовищами відбувається через підняття параметрів: розробник надає типізоване полеparameters.*у сутності Aggregate, шаблонvaluesсутності Component посилається на нього, а сутність Release задає значення параметра для свого середовища. Явне формулювання заборони на рівні схеми див. у architecture/06-data-taxonomy-and-composition.md §8 Обмеження 4. Поверхню реберusesсутності Release — що вона може налаштовувати та з’єднувати — описано нижче в розділі Налаштування з’єднання для окремого ребра.extends+aggregate:відхиляється. Щоб запобігти сутностям Releases, які непомітно «змінюють aggregate» і які неможливо відстежити, схема Release відхиляє оголошення вказівникаaggregate, коли сутність Release використовуєextends. Дочірній реліз має відповідати точно тому самому наміру розробника, що й батьківський. Натомістьmanifestстає необов’язковим, що відкриває «пізнє зв’язування»: оператор може успадкувати всю фізичну топологію, але точково замінити сутність Manifest.
Блок parameters:
Release виконує типізований контракт параметрів, який оголошує Aggregate. spec.parameters: — це поверхня для авторингу: YAML-мапа, ключі якої відповідають оголошенням parameters.* в Aggregate, а значення надають виконання для конкретного середовища.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: parameters: db_size: { type: string, required: true } timeout_seconds: { type: integer, default: 30 } region: { type: string, enum: [us-east-1, eu-west-1], required: true }# Release fulfills the contract for this environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"Кожне значення проходить перевірку за схемою, оголошеною в Aggregate, на рівні контракту параметрів, і збирання зупиняється, коли Release пропускає обов’язковий параметр (E0165, parameter-missing) або надає значення, яке відхиляє контракт його слота (E0164, parameter-contract-violation). Параметри, оголошені з default:, отримують значення за замовчуванням, коли Release пропускає слот; типізований контракт — єдиний словник для авторингу.
Два режими авторингу — диспетчеризація за формою вмісту. parameters: приймає або вбудовану YAML-мапу (режим 1, показаний вище), або єдиний ключ $import:, що вказує на локальний файл (режим 2):
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yamlВідносний шлях $import: розв’язується від каталогу, що містить Release, у якому його записано, незалежно від того, звідки запущено команду, тож командний рядок і редактор читають той самий файл; абсолютний шлях сам вказує своє місце, і будь-який із них має вести до файлу всередині робочого простору — або, для сутності Release, названої поза робочим простором, всередині каталогу, що її містить. У цьому місці два режими взаємовиключні, і імпортувати можна лише один файл. Багатофайлове нашарування параметрів — це завдання ланцюжків extends: сутності Release: батьківська сутність Release надає базовий набір параметрів, а дочірня розширює та перевизначає їх для кожного середовища. Див. Composite Release / успадкування extends: нижче, щоб ознайомитися з цим шаблоном.
Межа між параметрами та infra. Параметри несуть когнітивний намір розробника, виражений як типізовані слоти, які оголошує Aggregate; Release їх виконує. infra: у Release несе фізичне визначення розмірів від оператора (кількість реплік, межі CPU/пам’яті, класи сховища), прив’язане до конкретних компонентів або прикріплень Feature. Параметри потрапляють у шаблони values: в Aggregate через .parameters.X; infra: потрапляє в шаблон valuesMapping: у Recipe через .infra.X. Див. architecture/06-data-taxonomy-and-composition.md §3 щодо таксономії стовпів даних і templates/parameters-context.md щодо життєвого циклу параметрів у конвеєрі.
Межі та область за замовчуванням
Release групує компоненти в межі — фізичні одиниці розгортання, кожна з власним вихідним каталогом і каскадом анотацій. Випадок з однією межею є найпоширенішим, тому він не потребує жодних формальностей.
Одна область (за замовчуванням). Опишіть компоненти безпосередньо в spec.components: і пропустіть блок boundaries:. Компілятор згортає їх у синтезовану межу default, вихід якої плаский — артефакти потрапляють безпосередньо в dist/ (окремо для кожного провайдера, через безпечне значення subDirectory за замовчуванням, описане нижче: dist/compose/, dist/helm/, …), без сегмента з назвою межі в шляху. Це найпростіше розгортання: aggrega build для плаского Compose або цілі з одним кластером без іменування меж.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Кілька областей. Коли сутність Release охоплює більше ніж одне фізичне групування — окремі кластери, регіони чи хвилі синхронізації, — оголосіть іменовані межі в boundaries:. Кожна межа має власні directory:, каскад анотацій і syncWave:, а до компонентів звертаються в межах їхньої межі.
Взаємна виключність. spec.components: і spec.boundaries: взаємно виключні в корені Release — Release описує одне або інше, але ніколи обидва. Документ, що оголошує обидва, зупиняється під час завантаження з помилкою конверта. Поверхня верхнього рівня components має ту саму операторську форму для кожного компонента, що й components межі (infra:, annotations:, uses:).
Оголошена межа з назвою default. Плаский вихід — це властивість синтезованої межі за замовчуванням, а не назви. Release, що явно оголошує межу з назвою default у boundaries:, — це звичайна іменована межа: її вихід визначається її directory: (за замовчуванням dist/boundaries/default/), так само як і для будь-якої іншої оголошеної межі.
Див. architecture/06-data-taxonomy-and-composition.md §7 щодо шаблону області за замовчуванням.
Просторове розділення та шляхи виводу
Кожна межа оголошує фізичний каталог виводу directory для своїх скомпільованих артефактів; компоненти в межах можуть перевизначити його через subDirectory на рівні компонента. Компілятор обчислює остаточний шлях артефакту, об’єднуючи їх, у формі з прямими скісними рисками на кожній платформі: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Один каталог — одне написання. Обчислений шлях очищується один раз, тож
out/a,out//a,./out/aіout/a/— це один каталог. Межі, шляхи яких після очищення вказують на той самий каталог і які рендеряться через той самий провайдер, збираються разом — так само, як межі, записані з однаковими шляхами. - Шлях залишається всередині кореня виводу. Шлях, що виходить за межі кореня виводу (
..,../escape,a/../..), абсолютний шлях або шлях, що не називає жодного каталогу — порожній чи такий, що після очищення збігається з самим коренем виводу, — зупиняє збирання ще до того, як щось буде записано. Повідомлення називає сутність Release, межу, хибне поле (directory:абоsubDirectory:) і значення, до якого воно обчислилося, оскільки це значення часто є результатом шаблону. - Безпечне значення за замовчуванням. Якщо
subDirectoryпропущено або воно порожнє, компілятор автоматично застосовуєsubDirectory: "{{ .capability }}"— артефакти кожної можливості рендерингу (Helm, Helm-chart, Compose, Terraform, CloudFormation) потрапляють до власної підтеки, що запобігає колізіям змішаних артефактів у подальших інструментах CI/CD. Явно записанеsubDirectory: ""трактується так само, як пропущене, тож теж отримує це значення за замовчуванням. - Пласке перевизначення. Щоб повністю вимкнути підкаталоги (усі артефакти безпосередньо в
directory), задайтеsubDirectory: ".". ШаблонsubDirectory, що обчислюється в порожній рядок — скажімо,"{{ .parameters.sub }}"ізsub, встановленим у"", — також їх вимикає. - Змінні шаблону.
directoryобчислюється з{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}і{{ .parent_boundary.* }}для каскадних даних з охопної межі.subDirectoryобчислюється з тим самим набором плюс{{ .component_id }}(лише для перевизначень на рівні компонента). Компілятор обчислює шаблони шляхів ізmissingkey=error— посилання на неоголошену змінну зупиняє збирання з точною діагностикою. Див. змінні шаблонів шляхів, щоб ознайомитися з матрицею за контекстами та правилами каскаду батьківської межі.
Анотації межі каскадно передаються вниз до кожного вкладеного компонента; infra залишається суворо локалізованим у компоненті, на який він спрямований. Рекурсивна мапа boundaries дозволяє довільне вкладення (межа в межі в межі), а інваріанти каскаду анотацій і локальності infra зберігаються на кожному рівні.
Робочий приклад:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" # Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`. annotations: "aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations components: api-server: infra: { replicas: 5 } # Strictly local aws-rds: # Scenario B: Bespoke Enterprise Naming. subDirectory: provisioning postgres-db: # Scenario C: The Flat Directory Override. subDirectory: "." # not "", which takes the defaultАнотації, передані цим механізмом, з’являються в подальших шаблонах Recipe через .context.annotations.release; див. створення Recipe і матрицю розгортання шаблонів, щоб дізнатися, як їх споживають рендерери.
Структуровані значення анотацій. Коли прив’язка Manifest оголошує кілька шляхів маршрутизації до стовпа infra для одного ключа анотації, значення анотації на боці Release може бути структурованим об’єктом, що в одному оголошенні містить значення для кількох полів схеми Feature:
boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100 components: api: annotations: feature.myco/db-pool: max_connections: 200 # closer-level override # pool_size not listed → inherits 20 from boundaryСтруктуровані значення передаються каскадно з глибоким злиттям на рівні підключів; підключі ближчого рівня перевизначають батьківські. null на рівні підключа вимикає один підключ, тоді як сусідні підключі зберігаються. Бік Release спрацьовує лише для підключів, стовп яких у мапі прив’язки — infra; підключі, що маршрутизуються до values, належать до анотацій на боці Aggregate. Повний опис структурованих значень — композиція між боками, перевірка типів на рівні підключів, дисципліна послабленого значення за замовчуванням — див. у providers/well-known-annotations.md §«Structured annotation values».
Загальновідомі анотації. Окрім довільних ключів, стандартна бібліотека Aggrega визначає набір загальновідомих анотацій у просторах імен aggrega.ai/ і feature.aggrega.ai/, згрупованих у категорії розміщення, мережі, безпеки та спостережуваності. Авторам, які додають анотації до межі Release, слід звернутися до providers/well-known-annotations.md, щоб ознайомитися з повною матрицею та правилами споживання для кожного провайдера — сторінка документує, які провайдери застосовують кожен загальновідомий ключ і яку поведінку вони видають, коли ключ присутній.
Конфігурація з’єднання для кожного ребра
Компонент межі може містити блок uses:, який конфігурує або з’єднує ребра топології в межах сокетів, що їх оголошує usesSchema каталогу сутності Component. Це поверхня оператора для кожного з’єднання, обмежена так, щоб розробник зберігав власність над архітектурою, яку він створив:
- Конфігурування наявного ребра. Задайте
infraдля ребра, яке розробник уже оголосив. Запис називає псевдонім розробника й надаєinfra; він або називає ту саму ціль, яку з’єднав розробник, або пропускає ціль.infraперевіряється на відповідністьinfraSchemaсокета. - З’єднання незв’язаного сокета. Створіть ребро до сокета, який оголошує
usesSchemaсутності Component, але розробник залишив незв’язаним, спрямувавши його на наявний компонент. Створене ребро також може міститиinfraдля цього ребра. - Вкладення на з’єднанні. Вкладення розміщуються під
features:запису з ключем — слотом, який сокет оголошує у своїйfeaturesSchema, — тими самими слотами, які заповнює запис з’єднання розробника. Кожне міститьtype, необов’язковийdescriptionтаinfraі ніколи не міститьvalues. Під слотом, який розробник уже заповнив на тому самому з’єднанні, запис задає розміри цього вкладення: пишіть лишеinfra, оскільки тип і значення надходять із сутності Aggregate (type, записаний тут, має збігатися з типом у сутності Aggregate, інакше збірка зупиняється на цьому записі, називаючи обидва). Під слотом, який розробник залишив порожнім, вкладення належить самій сутності Release, іtypeобов’язковий. В обох випадках заповнення підпорядковуєтьсяselectorслота і зараховується до слотаrequiredтак само, як заповнення розробника.
Ця поверхня працює за принципом «створювати, а не перенаправляти»: сутність Release може додати ребро до незв’язаного сокета, але не може перенаправити ребро, яке розробник уже оголосив. Запис для ребра, що називає іншу ціль, ніж ребро розробника, зупиняє збірку; запис, що називає ту саму ціль (або пропускає її), конфігурує це ребро. Сутність Release також не може оголошувати values на ребрі чи на приєднанні, яке вона там записує (значення, призначені для розробника, залишаються в сутності Aggregate), зв’язувати сокет, який не оголошує usesSchema, або спрямовувати ребро на компонент, якого не існує, — кожне з цього є фатальною зупинкою. Так само і запис, що задає infra або features на з’єднанні, якого не існує після побудови всіх ребер, якщо тільки споживчий компонент не вимкнено за допомогою active: false. Див. errors/fatal-halts.md §«When building the topology».
Ще три зупинки утримують приєднання з’єднання на їхньому з’єднанні:
- Ім’я, для якого сокет не оголошує слота, зупиняє збірку — так само, як і в записі з’єднання сутності Aggregate, — на цьому записі в сутності Release, називаючи слоти, які оголошує сокет, і ті з них, від яких це ім’я відрізняється на одне редагування.
- Приєднання, яке створює лише сутність Release, записане без
type, зупиняє збірку на записі з’єднання, називаючи слот. Приєднання, яке створює сутність Release, не міститьvalues, тому воно підходить для сутності Feature, чиїvaluesнічого не вимагають; приєднання, схема якого вимагає значення, зупиняє збірку через відсутнє значення на тому самому записі. Сутності Features облікових даних зі стандартної бібліотеки, що містять локатор викликача, нічого не вимагають уvalues: кожна з них приймає його також уinfra(див. нижче). - Складене ім’я, записане будь-де, крім з’єднання, зупиняє збірку. Приєднання з’єднання стає приєднанням споживчого компонента з іменем
<alias>.<slot>(див. запис з’єднання сутності Aggregate), а і власні ключіfeatures:запису компонента, і ключі межі допускають крапку. Запис компонента, що містить це ім’я, або межа, що записує його так, що воно досягає компонента, з’єднання якого його містить, — компонента, розміщеного в цій межі або у вкладеній у неї, чи включеного компонента маршрутизованого підмодуля, — зупиняє збірку, називаючи обидва написання, по одному разу для кожного компонента, якого воно досягає. Слот сокета заповнюється на кожному з’єднанні й ніколи — приєднанням, що каскадується з ширшої області.
spec: components: router: uses: models: # Size the attachment the Aggregate declared on the "gpt" connection: infra only. gpt: features: credential: infra: { rotation: hourly } # Attach on a connection the developer left without one: the type is required. plain: features: credential: type: core/generated-secretОблікові дані на з’єднанні, яке створює сутність Release, називають свій секрет в infra. З’єднання, яке створює сутність Release, не має запису в сутності Aggregate, тож там ніщо не записує values облікових даних, а сутність Release ніде не записує values. Тому кожна Feature облікових даних зі стандартної бібліотеки, що містить локатор викликача, — core/referenced-secret, core/referenced-secret-set, core/secret-value і core/secret-provided — приймає його в infra так само, як і в values: origin або entries для core/referenced-secret-set, з тією самою формою і тим самим оголошенням sensitive: true в обох стовпах. Кожна реалізація читає той стовп, який його містить.
spec: components: router: uses: models: gpt: target: gpt # wire the socket the developer left unbound features: credential: type: core/referenced-secret infra: origin: openai-team-a # the secret the operator namesЛокатор записується рівно в одному стовпі для кожного вкладення. Вкладення, яке містить його в обох — у values сутності Aggregate та в infra сутності Release для того самого слота — або в жодному, зупиняється на власному твердженні Feature (E0033), яке називає Feature, вкладення й компонент і вказує, який із двох випадків стався. Це правило належить каталожним сутностям цих Features, а не компілятору, який обчислює їхнє твердження так само, як твердження будь-якої Feature. Поля, окрім локатора, залишаються у своєму стовпі: key лишається листком values, тож вкладення, яке створює лише сутність Release, читає типовий ключ даних Feature — value. Заборона values: не змінюється — локатор оператора розміщується в infra.
core/secret-provided — єдина, що не підходить для з’єднання: вона публікує своє значення, щоб його доставив власний блок inject: вкладення, а вкладення з’єднання не містить блоку inject: у жодному з документів, тож на з’єднанні жоден блок inject: його не доставляє. Використовуйте там core/referenced-secret або core/secret-value.
spec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: components: api-server: uses: databases: # Configure the developer-declared edge "primary": add per-edge infra. # The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget. primary: infra: { storage_class: fast-ssd } caches: # Wire an edge into the declared-but-unbound "caches" socket to an existing component. main: target: redis-prod infra: { storage_class: standard }Розв’язаний infra для ребра потрапляє в контекст рендерингу споживчого компонента за шляхом .context.uses.<alias>.infra.<key>; він ніколи не з’являється в контексті цільового компонента, тож рендерований вивід цілі інваріантний щодо споживачів, які конфігурують ребра до неї. Вкладення на з’єднанні так само потрапляє до споживчого компонента як одне з його вкладень: його infra об’єднується з values сутності Aggregate для того самого слота, і його FeatureRecipe рендериться з урахуванням обох. Recipe споживчого компонента читає його під його з’єднанням, за шляхом .context.uses.<alias>.features.<slot>, а його Workload доставляє його, називаючи з’єднання поряд зі слотом — див. Доставлення облікових даних, які містить з’єднання.
Поле aggregates: — маршрутизація вкладених підмодулів у межі
Коли Aggregate оголошує вкладені підмодулі через spec.aggregates:, Release визначає, у яку межу потрапляють компоненти кожного підмодуля, оголошуючи aggregates: поруч із components: усередині цільової межі:
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: aggregates: finance: type: finance-module:1.2.0 analytics: type: analytics-module:2.0.0 components: gateway: type: core/ingress---# Release routes each sub-aggregate into a specific boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Розмістіть кожен піделемент aggregate, перелічений у Aggregate.spec.aggregates:, рівно в одній межі.
Маршрутизація розміщує компоненти. Кожен компонент маршрутизованого підмодуля потрапляє в межу, яка його маршрутизує, і отримує directory, subDirectory, syncWave і каскад анотацій цієї межі — той самий контекст, що й компонент, названий безпосередньо в components:, включно з позначкою походження aggrega.ai/boundary-path на згенерованих артефактах. Тому маршрутизація підмодуля та адресування кожного з його компонентів кваліфікованим шляхом через крапку з порожнім тілом дають ідентичні артефакти; маршрутизація — коротший спосіб це сказати, і єдиний спосіб сказати це, не знаючи вмісту підмодуля.
Компонент належить рівно одній межі, і збирання зупиняється, коли документ розміщує його двічі: той самий підмодуль маршрутизовано у дві межі, підмодуль маршрутизовано в одну межу, а один із його компонентів названо в іншій, або компонент названо і безпосередньо, і через запис маршрутизації. Діагностика називає обидва місця, бо вирішувати, яке з них залишити, має автор. Маршрутизація підмодуля в межу й називання одного з його компонентів у тій самій межі не є конфліктом: маршрутизація розміщує компонент, а названий запис його конфігурує.
Піделемент aggregate, який Release ніде не розміщує, зупиняє збирання. Розміщення визначається за обома записами, тому збирання зупиняється лише тоді, коли жоден із них не досягає підмодуля: жодна межа не маршрутизує його в aggregates:, і жодна межа не називає жодного з його компонентів у components: кваліфікованим шляхом через крапку. Будь-який із записів сам по собі його розміщує, а підмодулю, усі компоненти якого названо окремо, запис маршрутизації не потрібен. Виправлення належить до блоку aggregates: тієї сутності Aggregate, яка імпортувала підмодуль: для безпосередньо імпортованого — це Aggregate, який розгортає Release, а для вкладеного — власний документ підмодуля, що його імпортує. Діагностика називає цей запис за ключем, яким його записує документ, що імпортує, тож для вкладеного підмодуля вона показує локальне ім’я, а не шлях через крапку.
Два випадки навмисно не зупиняють збирання. Підмодулю, що не додає компонентів, нічого розміщувати. Підмодуль, перемикач active: якого набуває значення false, ніколи не компонувався, тож жоден із його компонентів не існує, щоб бути розміщеним.
Часткове розміщення не зупиняє збирання за цим правилом: підмодуль вважається розміщеним, щойно будь-який із його компонентів досягає межі, тож називання одного з них задовольняє підмодуль. З цього не випливає, що решту можна пропустити. Кожен компонент, якого межа не назвала, тоді не розміщено нічим, і наведене нижче правило для компонентів повідомляє про нього за його власним ключем — тож частково розміщений підмодуль зупиняє збирання по разу на кожен пропущений компонент, а не на рівні підмодуля. Два записи, що розміщують увесь підмодуль одним рядком, — це запис маршрутизації та називання кожного компонента; усе між ними розміщує лише те, що називає.
Компонент, який Release ніде не розміщує, теж зупиняє збирання, на рівень глибше. Правило вище перевіряє, чи досяг підмодуль межі; це правило перевіряє те саме для кожного компонента композиції. Компонент досягає межі, якщо його названо в components: цієї межі або якщо він міститься в підмодулі, який межа маршрутизує. Компонент, що не досягає межі жодним способом, рендериться поза всіма межами, які оголошує Release, і бере свої directory, subDirectory, syncWave, каскад анотацій та покомпонентне infra: нізвідки — тому збирання зупиняється й називає компонент, а не генерує артефакти, яких конфігурація меж так і не досягла.
Два правила розподіляють сфери, питаючи про підмодуль компонента, а не лише про те, чи він у нього є. Компонент підмодуля, який Release не розмістив ніде, залишено правилу підмодуля, яке повідомляє про цю одну помилку автора один раз на записі aggregates:, а не по разу на кожен компонент модуля. Компонент підмодуля, який Release розмістив частково, належить цьому правилу, бо правило підмодуля вважає такий модуль розміщеним і нічого про нього не каже — тож про кожен компонент, якого межа не назвала, повідомляється тут, за його власним ключем у документі, що його оголошує. Тому часткове розміщення підмодуля називає саме те, що ви хотіли назвати, і повідомляє вам про кожен компонент, якого ви не назвали.
І запис межі, що називає компонент, якого немає в розгорнутому Aggregate, зупиняє збирання. Два правила вище перевіряють розміщення з боку компонента: чи розмістило його щось. Це правило перевіряє з боку Release: чи розв’язується ім’я. Запис, що ні на що не розв’язується, нічого не розміщує, тож його subDirectory, анотації, покомпонентне infra: і uses: конфігурують компонент, якого немає, і збирання зупиняється, а не генерує розгортання, якого запис так і не досяг. Перевіряються обидва записи: ім’я в components: межі читається як id, який компонент має після завершення композиції, а ім’я в components: запису маршрутизації — як локальне ім’я компонента всередині підмодуля. Діагностика повідомляє id, до якого звертався запис, і для маршрутизованого запису це не ім’я у файлі: файл містить локальну частину, а підмодуль додає свій префікс.
Ім’я відхиляється за те, що ні на що не розв’язується, і ніколи — за його форму: ім’я з крапкою є звичайним, бо компонент на рівень глибше має префікс свого модуля. Компонент, перемикач active: якого набуває значення false, залишається доступним для називання — вимкнення компонента не вимагає редагувати Release, що його конфігурує.
Підсистема нічого не додає до кваліфікованого шляху, тож межа адресує компонент за його простим іменем, хоч би як Aggregate його групував. Кваліфікує id лише композиція підмодулів. Компонент розгорнутого Aggregate має ім’я store незалежно від того, чи автор записав його на верхньому рівні, чи всередині підсистеми з назвою data; компонент на рівень глибше — це data.store, і data там є префіксом модуля, а не підсистеми. Тому запис межі data.store для компонента в підсистемі з назвою data нічого не адресує: сам запис зупиняє збирання за правилом вище, і компонент, для якого він призначався, теж не досягає жодної межі. Виправлення запису на store усуває обидві проблеми.
Тому розміщення підмодуля вимагає boundaries:. Форма з єдиною областю не має поверхні маршрутизації — aggregates: є ключем межі, а не spec:, — а мапа components: верхнього рівня приймає лише некваліфіковані імена, тож сутність Release, що розгортає Aggregate, який імпортує підмодулі, оголошує boundaries:.
Рекурсивна маршрутизація. aggregates: є рекурсивним — кожен запис у aggregates: межі може сам оголошувати вкладену мапу aggregates: для глибоко вкладеної композиції модулів.
Блок маршрутизації для кожного aggregate. Запис маршрутизації приймає рівно два ключі й нічого іншого: components: — для конфігурування окремих компонентів цього підмодуля, і вкладений aggregates: — для глибше вкладених модулів. annotations: належить межі, а покомпонентне infra: належить запису у власному components: запису маршрутизації.
Усередині запису маршрутизації компонент задається за ім’ям, яке він має всередині свого підмодуля — consumer, а не data.consumer, — бо це єдине ім’я, яке він там має. Кваліфікований шлях через крапку — це спосіб, яким власна мапа components: межі адресує той самий компонент; ці два записи не взаємозамінні, і запис маршрутизації відхиляє ключ із крапкою.
boundaries: eu-prod: directory: "deploy/eu-prod" annotations: aggrega.ai/namespace: "finance-zone" aggregates: finance: components: ledger: # the component's name inside the finance module infra: replicas: 3 aggregates: reporting: {} # a module nested inside financeВласні компоненти та Features піделемента aggregate не оголошуються повторно в Release — Release маршрутизує їх, а не повторює, і називає компонент лише для того, щоб його сконфігурувати.
Часова послідовність — syncWave для кожної межі
Кожна межа в сутності Release може оголосити цілочисельне поле syncWave:, що дає Operator явний контроль над порядком розгортання, не торкаючись сутності Aggregate розробника. Номер хвилі є властивістю самої межі; кожен компонент у піддереві межі успадковує значення хвилі своєї межі під час генерування артефактів.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest boundaries: infra: directory: "deploy/infra" syncWave: 0 components: core-vpc: {} postgres-db: {} migrations: directory: "deploy/migrations" syncWave: 1 components: db-migration-task: {} apps: directory: "deploy/apps" syncWave: 2 components: web-server: {} ai-agent: {}Семантика значення хвилі. syncWave: — це ціле число зі знаком (додатне, нуль або від’ємне). Якщо поле пропущено, типовим значенням є 0. Значення хвиль не успадковуються від батьківської межі: кожна межа, якій потрібна нетипова хвиля, оголошує її явно. Components не можуть перевизначити хвилю своєї межі (хвиля є властивістю просторової одиниці, а не окремих компонентів).
Генерування для кожного провайдера. Компілятор записує значення хвилі межі у згенерований вивід у рідній для провайдера формі. Три форми розібрано нижче; що хвиля робить на кожному провайдері стандартної бібліотеки, включно з terraform, зведено в таблицю в providers/reference-matrix.md, розділ «What a boundary’s syncWave does on each provider».
- Kubernetes (провайдер helm / helm-chart). Якщо хвиля не дорівнює
0, кожен ресурс Kubernetes, який провайдер helm рендерить для межі, має стандартну для GitOps анотаціюargocd.argoproj.io/sync-wave: "<N>"; хуки Helm додатково мають анотаціюhelm.sh/hook-weight: "<N>", тож те саме значення хвилі керує власним упорядкуванням pre/post-install у Helm. ArgoCD читає анотацію sync-wave, а Helm — вагу хука, і кожен із них відповідно впорядковує застосування ресурсів. Провайдер helm-chart копіює шаблони вихідного чарту так, як їх написав автор, тож власні ресурси підчарту мають хвилю лише там, де її записують ці шаблони; завантажений через$import:артефакт, який він додає, маєargocd.argoproj.io/sync-waveі не маєhelm.sh/hook-weight(див.providers/helm-chart.md). - Compose. Кожен сервіс у compose-файлі, у який генерується межа, через
depends_onочікує на сервіси безпосередньо попередньої хвилі, що потрапили в той самий файл, — з умовою на стан здоров’я цілі, якщо ціль оголошуєhealthcheck, і на її запуск, якщо ні. Отже, хвиля впорядковує сервіси одного файлу й нічого поза ним: межі, що генеруються в окремі файлиdocker-compose.yaml, є окремими compose-проєктами, і їх упорядкування — справа оператора. Ребраuses:і далі задають упорядкування для окремих ребер поряд із хвилею. Див.providers/compose.md. - CloudFormation. Кожен ресурс у зібраному шаблоні стека залежить, через
DependsOn, від ресурсів безпосередньо попередньої хвилі, що зробили внесок у той самий стек, — тож хвиля фіксує порядок створення ресурсів і, у зворотному напрямку, порядок їх видалення. Це не впорядкування за готовністю: шаблон стека не має поняття про те, що ресурс готовий до обслуговування. ВласнийDependsOnфрагмента розширюється, а не замінюється. Components, що збираються в інший стек, лежать поза досяжністю, а впорядкування двох стеків — справа оператора. Див.providers/cloudformation.md.
Одиниця задання хвиль і одиниця розгортання. Межа — це одиниця задання хвиль. Одиниця розгортання — це шлях збирання, у який генеруються компоненти: типово 1:1 із межею, але дві сусідні межі зі спільним directory: зливаються в один зібраний вивід (один Chart.yaml, один docker-compose.yaml). У такому разі зібраний вивід може містити ресурси з кількох хвиль; ArgoCD Application, що його читає, упорядковує в межах Application кожен ресурс за анотацією sync-wave, яку має цей ресурс: у helm — кожен ресурс, відрендерений для ненульової хвилі, а в helm-chart — лише завантажений через $import: артефакт, причому власні шаблони підчарту містять те, що написав їхній автор. Упорядкування між Application на різних шляхах — справа CI оператора.
Сценарії використання. Упорядкування хвиль важливе щоразу, коли запуск однієї межі залежить від попереднього завершення іншої. Канонічний шаблон: межа infra на хвилі 0 (VPC + база даних), межа migrations на хвилі 1 (завдання міграції схеми) і межа apps на хвилі 2 (застосунок, що використовує мігровану схему). Без явних хвиль усі три розгортаються одночасно, і застосунок потрапляє в цикл аварійних перезапусків, чекаючи завершення міграції.
Повне архітектурне обґрунтування — модель виконання DAG, причини розміщення часової послідовності в сутності Release, а не в сутності Aggregate, і розрізнення одиниці задання хвиль та одиниці розгортання — див. у architecture/12-day-two-lifecycles.md §1.
Підключення Feature
Сутність Release може підключати Features як на рівні межі (загальна політика), так і на рівні окремого компонента (точне націлювання), а виконання відбувається за 5-рівневою моделлю «цибулі», визначеною в architecture/10-compilation-pipeline.md. Features, оголошені в сутності Release, додають type, infra і uses; оголошувати values вони не можуть (див. розділ «Обмеження на рівні схеми» вище).
Сутність Feature, підключена на рівні межі, має ключ — назву екземпляра, яку ви обираєте, і ця назва не може бути . або ... У провайдері, який надає кожному учаснику власний каталог, — terraform у modules/ і helm-chart у charts/ — файли Feature рівня межі записуються в каталог, названий лише за екземпляром, а жодна з цих назв не є окремим каталогом: збірка зупиняється із зазначенням сутності Release, межі та екземпляра. Назва, яка лише містить крапки, як-от audit.v2, є звичайною назвою.
features: — єдина точка підключення в сутності Release на обох рівнях, так само як і в сутності Aggregate. Облікові дані — це сутність Feature з міткою feature.aggrega.ai/kind: secret, тож облікові дані, підключені оператором, підключаються в features: як будь-яка інша Feature і називають свій секрет в infra так само, як це робиться на з’єднанні (див. Налаштування з’єднання для кожного ребра) — на компоненті, який Aggregate залишив без них, або як параметри розміру підключення, яке Aggregate оголосив, не назвавши секрету. Другого ключового слова для підключення немає на жодному рівні; документ, що його оголошує, відхиляється під час завантаження з помилкою оболонки, яка називає неочікувану властивість.
Feature, підключена на всю межу, може мати блок uses:, і цей блок проєктується на кожен компонент, спрямований у межу: кожен компонент отримує ребро залежності до названих цілей Feature, і в нього впроваджуються provides цих цілей. Так спільна залежність виражається один раз на рівні межі — «кожен компонент у цій межі звертається до спільного кешу / колектора / шини повідомлень» — замість повторення того самого ребра uses: на кожному компоненті. Підключення Feature на рівні підсистеми в сутності Aggregate так само проєктує свій uses: на компоненти підсистеми. uses — це декларація зв’язування топології, а не значення, тому вона дозволена в сутності Release. Проєкція не залежить від області виконання підключеної Feature: Feature, чий FeatureRecipe рендериться один раз на межу, все одно проєктує свій uses: на кожен компонент, тоді як сам спільний ресурс рендериться один раз.
Feature, підключена до одного компонента, має той самий блок uses: і прокладає те саме ребро від цього одного компонента: компонент отримує ребро залежності до кожної названої цілі, у нього впроваджуються provides цих цілей, а ребро записує підключення як своє походження точно так само, як і форма на всю межу. Це одна декларація з двома ширинами охоплення — підключіть на межі, щоб зв’язати кожен компонент у ній, підключіть на компоненті, щоб зв’язати лише його, — і вибір між ними стосується лише охоплення, а не того, що робить зв’язування. Жодна з них не створює обчислювальних ресурсів: ціль має вже називати компонент, оголошений сутністю Aggregate, а ціль, яка цього не робить, зупиняє збірку. З’єднання, яке прокладає Feature, не має власних підключень: його запис приймає target та inject, а ключ features: там відхиляється під час завантаження сутності Release.
boundaries: cluster: directory: ./dist/cluster components: api: features: shared_backend: type: core/shared-backend uses: backend: primary: target: db # a component of the assembled graph inject: env: - in: DB_HOST from: host # db's `host` provides reaches api as DB_HOST db: {}Як записується ціль. Ціль ребра називає компонент зібраного графа, тому її записують кваліфікованим шляхом через крапку — data.store, а не store, — щоразу, коли ціль належить до спрямованого підмодуля. Це діє навіть там, де саме підключення розташоване під записом маршрутизації, чиї ключі components: локальні для модуля: ключ вказує, на якому компоненті розміщено підключення, а ціль — до якого компонента веде ребро, і лише друге є назвою на рівні всього графа. Ціль, записана локальною для модуля назвою, не відповідає жодному компоненту і зупиняє збірку з тим самим діагностичним повідомленням, що й будь-яке висяче ребро.
Складений Release і успадкування через extends:
Release може оголосити spec.extends:, що вказує на базовий Release, поверхню авторингу якого він успадковує.
Посилання — це шлях до файлу поруч з Release, що його оголошує — ./base-release.yaml або ../shared/base-release.yaml. Release належить до боку розгортання й не індексується в каталозі, тож посилання extends: ніколи не розв’язується через каталог. Відносний шлях — єдина форма, яку воно приймає: посилання, записане як координата реєстру, відхиляється, як і просте ім’я, і в кожному разі діагностика називає форму відносного шляху. extends: сутності Manifest — близький сусід, який читається інакше: він приймає відносний шлях або просте metadata.name сутності Manifest поруч з Release, — тож ці дві форми не взаємозамінні, і просте ім’я, яке розв’язалося б для Manifest, тут не розв’язується. Кожна ланка ланцюжка читається так само: батьківський Release, що зберігається в іншому каталозі, називає свого батька шляхом поруч із собою, хоч би де лежав названий вами Release, — так само, як поруч із ним розв’язується його $import: параметрів. Шлях має вести до Release всередині робочого простору, як і кожен шлях, який записує Release, — або, для Release, названого поза робочим простором, всередині каталогу, що містить цей Release, чого дотримується кожна ланка його ланцюжка: шлях, що виходить назовні або який виводить назовні якась ланка, відхиляється ще до читання файлу, який він називає.
Компілятор проходить ланцюжок під час завантаження Release — відхиляючи ланцюжок, що повертається до файлу, який уже є в ньому, ланцюжок, що перевищує межу глибини, і посилання, яке нічого не називає, — а потім згортає ланцюжок в один розв’язаний Release.
Успадковане можна замінювати ключ за ключем. Ваше значення перемагає на всю глибину, доки ви не дійдете до значення, яке є однією неподільною річчю — скаляра, списку, шаблону, — і його ви берете або замінюєте цілком. Щоб вилучити успадковане, запишіть його як null. Це те саме правило, якого дотримуються розширювані Component, Feature і Manifest, тож автор, який знає одне, знає всі.
Для Release: boundaries компонуються за іменем межі, а межа — за ключем, components — за іменем компонента, infra — глибоко, features — за іменем екземпляра, а потім за стовпом; uses компонента — за сокетом, а потім за з’єднанням, де target, записаний нащадком, замінює успадкований, infra з’єднання компонується ключ за ключем, а його features компонуються за слотом, а потім за стовпом за тим самим правилом, якого дотримуються власні features компонента; directory, subDirectory, syncWave і вказівники на Aggregate та Manifest — скаляри, які замінюються.
Дві речі не передаються:
- Ідентичність і походження. Жодне поле
metadataне успадковується. Варто знати проmetadata.environment: воно обов’язкове для кожного Release і за природою належить окремому Release, тож нащадок рендериться зі своїм власним середовищем у мітках походження, а не з батьківським. - Вказівник на Aggregate успадковується, а не перевизначається. Нащадок не може оголосити
aggregate:— схема відхиляєextends:іaggregate:в одному документі, — тож нащадок розгортає той самий намір розробника (Developer Intent), що й його база.
Нащадок може пропустити manifest:, успадкувавши вказівник бази, або перевизначити його для пізнього зв’язування (Late Binding).
Одна форма маршрутизації на весь ланцюжок. boundaries: і components: взаємовиключні в межах одного Release, і це діє також для ланцюжка: база, що оголошує іменовані межі, і нащадок, що оголошує компоненти верхнього рівня, відхиляються, а діагностика називає обидва файли й обидва ключі. Виберіть одну форму маршрутизації та використовуйте її на всю глибину.
Шаблон містка для локальної розробки. Канонічний сценарій — розробник запускає продакшн-Aggregate своєї команди локально, не форкаючи Aggregate і не дублюючи топологію меж. Команда публікує продакшн-Release; локальний Release виконує extends: щодо нього й перевизначає лише вказівник на Manifest, замінюючи хмарні Recipes локальними відповідниками:
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release environment: production version: "1.0.0"spec: aggregate: my-app manifest: prod-manifest parameters: region: us-east-1 db_size: 100Gi out_dir: prod boundaries: prod: # A directory is a TEMPLATE, not a fixed path. Writing it against a # parameter is what lets a child render somewhere else without # restating the boundary topology. directory: deploy/{{ .parameters.out_dir }} components: api: { infra: { replicas: 5 } } db: {}
---# Local Release (developer-side; inherits everything, swaps the Manifest)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: local-release environment: local version: "1.0.0"spec: extends: ./prod-release.yaml manifest: local-manifest # surgically overrides for local parameters: region: dev-local db_size: 1Gi out_dir: local # the inherited directory resolves here insteadlocal-release успадковує топологію меж своєї бази, прикріплення Feature і перевизначення компонентів; розробник зберігає один local-release.yaml і запускає aggrega build --release local-release.yaml, не дублюючи жодної продакшн-конфігурації.
Записуйте directory: через параметр. Оскільки каталог успадковується як будь-який інший скаляр, нащадок, що успадковує каталог без змінної шаблону, рендериться в той самий шлях, що і його база, і жоден параметр командного рядка цього не перенаправляє. Це допустимо, коли ви саме цього хотіли — наприклад, замінити лише Recipes, щоб порівняти їхній вивід, — тож збірка повідомляє про це й продовжується, а не відхиляє. Запис каталогу через параметр, як вище, тримає топологію в одному місці й водночас спрямовує вивід кожного Release у власне місце.
Багатофайлове нашарування параметрів. Успадкування Release — місце для багатофайлового нашарування параметрів. Базовий Release надає спільний набір параметрів; нащадки для окремих середовищ виконують extends: щодо бази й перевизначають слоти, що відрізняються:
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifestКожен нащадок бачить успадковані параметри бази, об’єднані з власними. Параметри-мапи глибоко об’єднуються з перевагою ключа нащадка; скалярні параметри замінюються нащадком; ключ, який нащадок записує як null, вилучається, а не встановлюється в порожнє значення.
База може імпортувати свої параметри, а нащадок усе одно може перевизначати окремі ключі. Два режими авторингу, описані вище в розділі parameters:, — вбудований або єдиний $import: — це правило про один документ, а не про ланцюжок: кожен Release у ланцюжку оголошує той чи інший режим, і імпорт кожного розв’язується відносно каталогу, що містить цей Release, до згортання ланцюжка. Тож база, що імпортує спільний файл, і нащадок, що записує кілька ключів вбудовано, компонуються за ключем — так само, як два вбудовані блоки:
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported fileРежими помилок. Циклічні ланцюжки extends:, відсутні вказівники на батьків і оголошення aggregate: у нащадку зупиняють завантаження робочого простору з явною діагностикою, що називає проблемний Release і порушення на рівні схеми. Форми повідомлень для кожної помилки див. у errors/fatal-halts.md.