Recipe
Концептуальну роль сутності Recipe (шаблону трансляції, який створює Ops і який відображає намір розробника у фізичний формат) описано в architecture/04-entity-taxonomy.md. Ця сторінка охоплює поверхню створення сутності Recipe — вказівник (source), відображувач (valuesMapping:), нативну підтримку IaC і робочі приклади.
Архітектура Recipe: вказівники та відображувачі
Сутність Recipe виконує рівно дві функції:
- Вказівник (
source): точно повідомляє компілятору, де розташований код інфраструктури. - Відображувач (
valuesMapping): підставляє абстрактний контекст Aggrega у конкретні змінні, яких очікує базовий код. Це поле — єдина поверхня шаблонів Go з трьома режимами написання: вбудований блоковий скаляр, файловий$import:або бібліотечний$import:; режим обирається за формою вмісту. Див. ПолеvaluesMapping— три режими написання нижче.
Оскільки Recipe суворо відповідає 1:1 одній можливості рендерингу, цю можливість (spec.capability) явно оголошують на кореневому рівні, щоб компілятор Go точно знав, який подальший плагін рендерингу Wasm викликати.
spec.implements оголошує, який тип компонента з каталогу може реалізувати Recipe. Компілятор використовує його, щоб перевіряти відображення в Manifest (implements відображеної сутності Recipe має збігатися з відображеним типом) і щоб пропонувати кандидатів — рецепти, перелічені в діагностиці про відсутність відображення та поставлені першими в автодоповненні редактора. Він ніколи не визначає збірку: відображення в Manifest — це явний вибір розгортання користувача, закріплений у lock-файлі. Recipe, чий implements не має версії, вказує точну версію або діапазон, сумісний за мажорною версією, все одно лише пропонує себе для типу; вибір закріплює користувач. FeatureRecipe.spec.implements виконує ту саму роль для типів функцій.
A. Схеми джерел на основі Wasm
Щоб не допустити до компілятора упереджень реалізації, блок source не є фіксованим набором полів інфраструктури. Поле source підтримує два формати:
- Універсальний рядок (швидко й чисто): найкраще підходить для локальних шляхів, артефактів OCI та репозиторіїв Git. Компілятор визначає спосіб отримання за префіксом і суфіксом рядка (
./src,https://github.com/example/module.git,oci://...): URL, що закінчується на.gitабо записаний ізgit://чиssh://, — це репозиторій Git, який отримується на його гілці за замовчуванням, а URLhttps://, що не вказує ні на репозиторій, ні на чарт.tgzчи фрагмент.yaml, відхиляється як неоднозначний. - Відкритий структурований об’єкт: відкритий словник (
additionalProperties: true), ключі якого визначає провайдер і які доступні в шаблонах сутності Recipe як.source.*(наприклад,.source.chart). За задумом, сокет WebAssembly кожного провайдера визначає та перевіряє власну форму джерела (наприклад,registry/chart/appVersionдля Helm).
Що визначає ядро. Жоден провайдер не перевіряє власних ключів джерела. Отримуване джерело визначається вбудованою ідентичністю, чий kind обирає розпізнавач — helm-oci-chart, helm-https-chart, compose-https-fragment і git-repository. Джерело, призначене для отримання, має містити kind і url; яка ще координата обирає вміст, залежить від типу. Типи для чартів і фрагментів приймають version і закріплюють її так, як її записано. git-repository приймає ref — тег, гілку або коміт — і, за бажання, module_subdir, що називає каталог усередині репозиторію, який і є артефактом; оскільки лише коміт називає вміст, який не можна перенаправити, посилання визначається під час блокування, і lock-файл записує як написане посилання, так і коміт, до якого воно звелося. module_subdir, який у записаному вигляді виходить за межі репозиторію (зворотна скісна риска вважається роздільником), відхиляється ще до будь-якого отримання. Репозиторій архівується з власного checkout: закомічене в ньому символьне посилання архівується як файл або каталог, на який воно вказує, якщо той лежить усередині репозиторію, а посилання, що веде за його межі, зупиняє pull і називає посилання за його місцем у репозиторії. Структуроване джерело, чий url: називає шлях файлової системи, не отримується: воно читається з диска на тих самих умовах, що й простий рядок шляху, а відносний url: прив’язується до каталогу з файлом сутності, що його оголошує. Структуроване джерело без kind/url також не отримується, і якщо отримання передбачалося, збірка гучно зупиняється під час обходу джерел на етапі блокування, а не мовчки зводиться до нічого. Вміст завжди закріплюється заздалегідь; компілятор ніколи не отримує живий стан середовища виконання.
Що закріплюється поруч із Recipe. Для отримуваного джерела, у якого kind, url, chart, module_subdir, version і ref записано явно, а не шаблоном, aggrega pin записує дайджест отриманого в entity.lock — файл у власному каталозі сутності Recipe, який ви комітите поруч із нею. Закріплення — це крок автора сутності Recipe, і він не потребує Release; pull для сутності Recipe, чий lock не містить закріплення, зупиняється і називає його, якщо pull не попросили виконати той самий крок. Збірка порівнює цей дайджест із тим, який lock-файл сутності Release записує для того самого джерела, і зупиняється, якщо вони розходяться — крім джерела, записаного з git ref:, чий рядок записано за комітом, до якого звівся ref, і який не порівнюється. Отримуване джерело, координати якого заповнюються з шаблону, натомість закріплюється для кожної сутності Release окремо, у її lock-файлі. Джерело, що називає каталог або файл поруч із Recipe, не отримується: aggrega pin записує по одному дайджесту на кожен файл, який воно додає до вмісту публікації сутності Recipe — кожен файл у каталозі Recipe, якщо джерело записано шаблоном, — і щойно lock їх містить, збірка порівнює з ними джерело, перш ніж провайдер його прочитає, і зупиняється на файлі, доданому, зміненому чи вилученому після закріплення — з E0305 або спершу з E0130, якщо lock-файл сутності Release, записаний до зміни, фіксує Recipe за її вмістом. Lock, що не містить закріплення для такого джерела, не дає збірці з чим порівнювати, а pull чи публікація, що не закріплює, його відхиляє. У сам файл Recipe ніколи нічого не записується. aggrega pull описує цей файл і те, як реагувати на кожну зупинку.
spec.capability може містити закріплення версії у формах, які приймає implements, — точне (helm:<version>) або діапазон із кареткою (helm:^<version>), — що обирає, яка версія плагіна провайдера рендерить Recipe; закріплення, якому не відповідає жодна доступна версія, зупиняє збірку. Без закріплення (spec.capability: "helm") рендерить найвища доступна версія. Доступні версії — ті, що показує aggrega plugin list: провайдери, вбудовані в aggrega, мають версію самого компілятора. Закріплення не є частиною імені Recipe: Manifest зіставляє Recipe, що оголошує capability: "compose:1.2.3", як compose/<name>:<version>, точно так само, як незакріплений, і зміна закріплення ніколи його не перейменовує; значення зіставлення, що записує закріплення в ім’я (compose:1.2.3/<name>:<version>), відхиляється як некоректне посилання на recipe (E0095) ще до будь-якого пошуку.
Ментальна модель: spec.capability називає потрібний вам формат виводу (наприклад, helm, terraform, compose); компілятор зводить його до плагіна Wasm, що рендерить цей формат (наприклад, provider/helm). Ви оголошуєте формат; Aggrega прив’язує інструмент.
B. Впровадження контексту: семантичний шар відображення
Щоб компілятор не виконував небезпечних недетермінованих глибоких злиттів між кількома середовищами, Recipe допускає лише одне джерело істини для свого шару відображення.
Інженери з експлуатації пишуть вміст відображення, щоб перекласти абстрактний контекст до виконання Wasm-плагіна рендерингу. Мова відображення — Go template (text/template + Sprig); бібліотеку Sprig зареєстровано заздалегідь; стандартні дії define і template підтримуються, а include не зареєстровано.
| Назва поля | Область дії та фаза виконання | Найкращий сценарій використання |
|---|---|---|
injectMapping (лише FeatureRecipe) | Перехоплення до рендерингу. Обчислюється в пам’яті Go до базового Recipe. Нативно глибоко зливає свій вихідний словник строго поверх каналу .context.inject викликача. Навмисно відсутнє в базовій схемі Recipe — архітектурне обґрунтування див. у entities/featurerecipe. | Точкове переписування впроваджених змінних env або форматування FQDN для викликача без потреби у Wasm JSONPatch. |
valuesMapping | Базовий рендеринг (Go template). Обчислюється, щоб відобразити змінні в базовий інфраструктурний chart/модуль source. Одне поле, три режими написання (вбудований, файловий $import:, бібліотечний $import:). Механізм диспетчеризації описано в підрозділі нижче. | Відображення стандартних змінних (як-от кількість реплік чи теги образів) у Helm chart безпосередньо в YAML сутності Recipe або посилання на спільний шаблон через $import: для повторного використання між Recipes. |
Примітка: injectMapping доступне лише у FeatureRecipes і відокремлює перехоплення змінних від valuesMapping. valuesMapping базового Recipe, нічого про це не знаючи, споживає переписані рядки .context.inject, згенеровані блоками injectMapping сутності FeatureRecipe, тож вони залишаються розв’язаними.
Ключ, який valuesMapping записує як null, надходить до провайдера як null, і що з ним відбувається далі, вирішує провайдер, тож це вказано на сторінці кожного провайдера: helm видаляє значення chart за замовчуванням для цього ключа, helm-chart записує його в значення umbrella, compose записує його у файл compose, terraform записує його як аргумент модуля null, а cloudformation його відхиляє.
Поле valuesMapping — три режими написання
valuesMapping: сутності Recipe — це єдина поверхня Go template, що приймає три режими диспетчеризації. Компілятор обирає режим за формою вмісту поля; анотація $mode: не потрібна.
Режим 1: вбудований Go template (блоковий скаляр YAML). Значення поля — рядок, записаний у формі блокового скаляра YAML |:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}Вбудований режим — типова форма написання для Recipes, вміст відображення яких малий або середній (менше ~50 рядків). Тіло шаблону розміщено разом з рештою оболонки Recipe; вміст Recipe самодостатній.
Режим 2: файловий $import:. Значення поля — мапа, що містить лише $import: із шляхом до локального файлу:
spec: valuesMapping: $import: ./mappings/api-server.tmplКомпілятор завантажує вміст файлу (Go template), рендерить його зі стандартним контекстом шаблону Recipe і вважає результат виходом відображення. Шлях розв’язується відносно каталогу Recipe — відносний шлях прив’язано до каталогу, де лежить recipe.yaml, що його оголошує, а не до каталогу, з якого запущено збірку, — і шлях має залишатися в межах цього каталогу, як пояснює розділ Шляхи до вмісту залишаються в межах власного каталогу Recipe. Файловий режим підходить для середнього й великого вмісту відображення (~50+ рядків) і для рецензування, де зміни відображення видно як окремі diff файлів.
Режим 3: бібліотечний $import:. Значення поля — мапа, що містить лише $import: із посиланням за ідентичністю на простому імені на запис MappingLibrary:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreКомпілятор розв’язує посилання щодо розв’язаного набору MappingLibraries (локальний каталог плюс будь-які бібліотеки, закріплені в lockfile), завантажує вміст запису і вважає його виходом відображення; запис, тіло якого саме є кореневим $import: поля, розв’язується рекурсивно. Посилання не містить хоста реєстру — ім’я бібліотеки розв’язується за ідентичністю, а версія береться з lockfile кожного Release, з необов’язковою нижньою межею мінімальної версії :<version> (<Library>:<version>#/mappings/<entry>). Вміст бібліотеки використовує стандартний контекст шаблону Recipe. Бібліотечний режим підходить для повторного використання між Recipes — шаблонів відображення, що повторюються в багатьох Recipes (кілька Recipes сховищ даних зі спільною допоміжною логікою; кілька Recipes Helm-провайдера зі спільними шаблонами pod). Сутність MappingLibrary забезпечує версіонування, закріплення в lockfile і показ в інтерфейсі хабу.
Правила диспетчеризації. Компілятор обходить вузол YAML і обирає режим за формою вмісту:
- Якщо вузол — рядковий скаляр, обирається вбудований режим (режим 1).
- Інакше вузол є мапою; перевіряється наявність ключа
$import:. - Якщо значення
$import:— бібліотечне посилання на простому імені (<Library>#/mappings/<Entry>, за потреби з нижньою межею:<version>), обирається бібліотечний режим (режим 3). - Інакше (шлях до локального файлу) обирається файловий режим (режим 2).
- Будь-яка інша форма (мапа без
$import:, мапа з додатковими ключами, крім$import:, тощо) спричиняє помилку під час збірки.
Лише одноджерельний $import:. $import: приймає одне джерело. Злиття кількох джерел у valuesMapping: не підтримується. Recipe, якому потрібно скомпонувати кілька фрагментів відображення, використовує запис MappingLibrary із внутрішньою композицією Go template define / template, локальний файл із директивами Go template template, що викликають сусідні файли, або вбудовану композицію для короткого вмісту. Про сутність бібліотеки див. entities/mappinglibrary, про ширше розрізнення $ref: / $import: — vocabulary/cross-document-ref.
Походження. Повідомлення про помилки рендерингу шаблонів вказують відповідне походження для кожного режиму: вбудовані шаблони вказують file:line сутності Recipe, де починається блоковий скаляр; файлові імпорти вказують вміст імпортованого файлу; бібліотечні імпорти вказують позицію запису MappingLibrary у джерелі, а ідентичність бібліотеки без хоста (<Library>#/mappings/<entry>) слугує канонічним вказівником для стабільних посилань — хост реєстру в посиланні відхиляється, тож фізичне розташування ніколи не потрапляє до вказівника.
C. Нативна підтримка IaC
Команда Ops, що приносить власну інфраструктуру як код, зберігає її у власному каталозі Recipe — у каталозі модуля або шаблону, як-от ./src, названому в source:, — або отримує її через структуроване source: (модуль Terraform із його git-репозиторію, з kind: git-repository), або пише її як шаблонізовані тіла в artifacts:. Шар зіставлення (valuesMapping: — вбудований, імпорт файлу або імпорт із бібліотеки) надає цьому коду абстрактний контекст, а провайдер видає результат у власному форматі цілі; жодна мова конфігурації не перетворюється на іншу:
- Terraform: модуль вендорується файл у файл, а написане тіло видається точно так, як його записано, як нативний HCL (
main.tf), так і Terraform JSON (.tf.json) — CLIterraformчитає обидва. Коренева конфігурація межі,aggrega.modules.tf, викликає каталог кожного компонента як блокmodule, а вивідvaluesMapping:модуля з джерела стає аргументами цього блоку. Див. провайдер terraform. - CloudFormation: шаблон із джерела, YAML або JSON, і фрагменти ресурсів, які пише Recipe, нормалізуються до розгорнутого JSON і зливаються в один шаблон стека на межу, а вивід
valuesMapping:заповнює параметри, оголошені шаблоном із джерела. Див. провайдер cloudformation.
Значення, яке існує лише після застосування інфраструктури, залишається вказівником, який розв’язує ціль, — інтерполяцією Terraform ${ ... }, Ref або Fn::GetAtt CloudFormation — і ніколи не обчислюється під час збірки.
Приклад A: віддалений Helm chart (вбудоване відображення і контракт locals)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Приклад B: локальний модуль Terraform (файлове зіставлення)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Приклад C: конкретний Component Recipe (прив’язує інфраструктуру)
Ops відображає загальний інтерфейс на фізичну реальність. (Саме тут прив’язуються мережеві деталі рівня L4 — або жорстко закодовані, або, як порт проксі нижче, взяті з блоку infra, який заповнює Release.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Дисципліна іменування хмарних ресурсів.
Recipes, що генерують імена хмарних ресурсів — імена бакетів S3, ідентифікатори баз даних RDS, імена ролей IAM, імена стеків CloudFormation та будь-які інші поля, значення яких займає глобальний простір імен у хмарного провайдера, — мають додавати {{ .metadata.release_name }} та/або {{ .context.instance_id }} до згенерованого імені, щоб уникнути колізій, коли той самий Recipe виконується в кількох Releases або екземплярах компонентів. Канонічним шаблоном є bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" із прикладу B.
Дисципліна застосовується скрізь, де ім’я обмежене єдиним глобальним простором імен. Імена бакетів AWS S3 мають спільний глобальний простір імен для всіх облікових записів у регіоні; два Releases того самого Aggregate (prod-billing і staging-billing) не можуть обидва розгорнути бакети з іменем customer-data — друге розгортання завершується помилкою під час виконання через відмову з боку AWS. Додавання release_name розрізняє Release; додавання context.instance_id розрізняє кожен екземпляр компонента; додавання обох розрізняє кожен компонент у кожному Release.
Що компілятор перевіряє, а що ні. Компілятор не перевіряє виходи valuesMapping: на наявність полів з іменами хмарних ресурсів без цих інтерполяцій. Дисципліну підтримують автори Recipe (які знають, які поля іменують глобально унікальні ресурси для цільового провайдера) та рецензенти (які виявляють шаблони з неіменованими ресурсами під час рев’ю PR). Плагін-лінтер міг би позначати Recipes, чиї виходи valuesMapping: посилаються на поля з іменами хмарних ресурсів без інтерполяції release_name / instance_id; сокет лінтера постачається й запускається через aggrega lint (див. plugins/plugin-contract.md «Placement criterion: the linter socket vs the governance verdict roles»), і жодне з правил лінтера публікації цього не перевіряє.
Ця дисципліна — один із кількох суспільних договорів, що тримаються на домовленості, — дисципліна авторства, яку автори засвоюють із документації, а не через примус компілятора. Повний перелік домовленостей та архітектурне обґрунтування класифікації кожного договору див. у vocabulary/social-contracts.md.
Шаблонізація поля source.
Поле source сутності Recipe саме є поверхнею шаблонізації. Обидві форми source приймають шаблони Go: форма універсального рядка
source: "{{ optional .infra `module_path` \"./src\" }}"і форма структурованого об’єкта (кожне рядкове підполе обчислюється як шаблон; нерядкові підполя передаються без змін). Те, що може читати шаблон джерела, залежить від того, чи називає джерело віддалений артефакт. Координата віддаленого джерела — version, chart, ref і module_subdir структурованого блоку, що називає реєстр, репозиторій чартів або git-репозиторій, — обчислюється тоді, коли aggrega pull розв’язує артефакт, щоб зафіксувати його, лише відносно .values, .infra і .locals, із власними допоміжними функціями Aggrega (optional, capitalizedWords та index) і без жодної функції Sprig. .context на цій поверхні немає, тож те, який артефакт фіксується для компонента, визначають значення та infra, які він отримує, і ніколи — ім’я його екземпляра. Записи locals:, що там обчислюються, — це ті, які читають ці поля, і ті, які, своєю чергою, читає такий запис: запис, який не читає жодне поле джерела, не обчислюється під час розв’язання джерела, тож локальне значення, потрібне лише рендерингу, — те, що викликає функцію Sprig або читає .context.instance_id, — не впливає на фіксацію й обчислюється, коли рендериться вузол. Якщо поле читає .locals так, що не називає жодного конкретного запису, як-от {{ index .locals "version" }}, обчислюються всі записи. Джерело, що називає шлях у робочому просторі, як наведене вище, не розв’язується для фіксації: його шаблон обчислюється під час рендерингу вузла відносно того самого самодостатнього контексту, що й locals сутності Recipe, — .context.instance_id, .values, .infra і .locals, увесь розв’язаний блок вузла, — тож він допускає і відхиляє ті самі кореневі посилання, що й запис locals:, з однією відмінністю на його користь: він може читати будь-який запис, оголошений у блоці, а не лише записи над ним. Віддалена координата так само може читати будь-який запис, оголошений у блоці. .provides немає в жодному з цих контекстів, і шаблон джерела, що звертається до provides власного вузла, зупиняє збірку й називає хибне посилання. Це незмінна властивість поверхні, а не прогалина, що чекає на подальшу роботу: локальні значення вузла розв’язуються раніше за його provides, щоб provides: міг читати .locals, а шаблон джерела читає ті самі розв’язані локальні значення замість того, щоб звертатися вперед до provides. Посилання на .context.inject і .context.uses заборонені з тих самих міркувань самодостатності: URI джерела має розв’язатися до того, як заповниться канал топології, і до того, як будь-що далі завантажить тіло чарту, модуля чи артефакту, на яке вказує URI. Повні правила доступності та обґрунтування заборонених посилань наведено в рядку №5 матриці розгортання шаблонів. Канонічне застосування — перевизначення infra.source_version, яке надає сутність Component і яке передається в поле версії джерела, — див. entities/component «Стовп infra», — тож каталогу не потрібно повторно публікувати сутність Recipe за кожного сумісного підвищення версії вище за течією.
Перелік схем поля source. Поле source: приймає в схемі кілька варіантів форми. Підтримка кожного варіанта під час виконання залежить від провайдера; таблиця нижче документує, що робить кожна форма.
| Форма | Приклад | Статус |
|---|---|---|
| Простий відносний шлях файлової системи | source: "./charts/postgres" | available — кожен наявний провайдер (helm, helm-chart, compose, terraform, cloudformation) приймає рядок простого шляху файлової системи. |
| Простий абсолютний шлях файлової системи | source: "/abs/path/to/chart" | accepted but blocked — схема його приймає, а кожна команда, що читає Recipe, відхиляє: абсолютний шлях називає місце на машині, де його написано, а не вміст у власному каталозі Recipe, тож він не переноситиметься разом із Recipe. Перемістіть чарт у каталог Recipe і вкажіть його відносно цього каталогу; див. Шляхи до вмісту залишаються у власному каталозі Recipe. |
| Порожній рядок | source: "" | accepted but blocked — схема приймає порожній рядок, але кожна команда, що завантажує сутність Recipe, відхиляє його під час читання сутності Recipe, бо порожній рядок не називає жодного режиму. Відмова називає неоднозначність разом із двома виходами з неї: пропустіть поле для режиму без source або вкажіть справжній шлях чи URI для режиму з source. aggrega validate <recipe-file> повідомляє про це для сутності Recipe, а aggrega pull, aggrega build і aggrega validate --release — для сутності Release, що досягає цієї сутності Recipe. Див. errors/fatal-halts.md «Recipe source: is an empty string» (Recipe source: є порожнім рядком). |
Структурований об’єкт, чий url: містить транспортну схему | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — вбудований source-resolver читає форму {kind, url, version, chart, ref, module_subdir} (схема в url: визначає вид — oci:// → OCI-чарт, https://….tgz → архів чарта, корінь репозиторію https:// разом із chart: → чарт із репозиторію — або вид можна вказати через kind:), завантажує та закріплює артефакт під час aggrega pull, а збірка видобуває його з кешу. Як альтернатива підтримується локальне вендорування чарта, але воно не обов’язкове. Схема приймає відкритий структурований об’єкт. Див. providers/helm.md «Набір ключів source:». |
Структурований об’єкт, чий url: називає шлях у файловій системі | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — url: без транспортної схеми називає шлях, тому нічого не завантажується й не закріплюється; збірка читає вміст із диска. Відносний url: прив’язується до каталогу, що містить recipe.yaml, який його оголошує, а той, що виходить за межі цього каталогу, — зокрема абсолютний, — відхиляється: так само, як і в двох рядках вище для простих шляхів, і форма, у якій його записано, цього не змінює. Лише url: визначає, звідки читається вміст; решта полів обирають, що було б завантажено, і все одно доходять до шаблонів Recipe як .source.*. |
OCI URI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — цільовий дизайн для розповсюдження каталогів. Сучасний трирівневий резолвер (файли, які Release називає за шляхом, каталоги робочого простору, віддалений OCI-реєстр) описано в architecture/13-catalog-and-registry.md; резолвер рівня сутностей споживає OCI URI через цей каскад, але OCI-форма поля source: окремого Recipe наразі не підключена в провайдерах. |
Інші схеми URL (https://, git+https:// тощо) | (для ілюстрації) | planned — задокументовано як задум у дорожній карті підключуваних джерел архітектури; підтримки провайдерами наразі немає. |
Як прив’язується шлях у source:.
Прив’язка застосовується лише до шляхів у файловій системі й ні до чого іншого, і вона діє незалежно від того, яка з двох форм містить шлях. Відносний шлях прив’язується до каталогу, що містить recipe.yaml, який його оголошує, а шлях, що виходить за межі цього каталогу, — зокрема абсолютний, — відхиляється, як пояснено в розділі Шляхи до вмісту залишаються в межах власного каталогу Recipe. Посилання з транспортною схемою — oci://, https://, http://, git://, ssh://, git+ssh:// або будь-яке посилання, що закінчується на .git, — називає те, що слід завантажити, а не шлях, тому передається точно так, як ви його записали, і ніколи не з’єднується з каталогом.
У структурованій формі шляхом є поле url:, і читається воно так само: відносний url: прив’язується до каталогу, що містить recipe.yaml, той, що виходить за межі цього каталогу, відхиляється, а той, що має транспортну схему, завантажується. Усі інші поля структурованого source: передаються без змін, зокрема визначені провайдером.
source:, записаний як шаблон, прив’язується за значенням, яке створює шаблон, а не за текстом самого шаблону. Шаблон нічого не називає, доки його не обчислено, тому описане вище правило застосовується до його результату: результат, що є відносним шляхом, прив’язується до каталогу, що містить recipe.yaml, той, що виходить за межі цього каталогу, — зокрема абсолютний шлях, — зупиняє збірку, а той, що має транспортну схему, передається далі й завантажується. Отже, шаблон може створювати будь-яку з форм із наведеного вище переліку, і кожна обробляється точно так, як таке саме значення, записане буквально; різниця лише в тому, коли шлях можна оцінити: для шаблону — коли збірка його обчислює, а не коли читається Recipe.
Шаблон, що нічого не створює, — з порожнім результатом, — залишає Recipe без джерела, тобто в режимі без джерела. Це відрізняється від того, щоб самостійно записати source: "", що не називає жодного режиму й відхиляється; див. рядок переліку вище.
Цей перелік — канонічний довідник щодо того, що автори можуть указати в source:; його мітки — ті, які визначає 10-status.md.
Шляхи до вмісту залишаються у власному каталозі сутності Recipe
Вміст сутності Recipe розміщується у власному каталозі цієї сутності Recipe, бо кожен файл, який містить її публікація, береться звідти. Кожен шлях, який Recipe вказує для вмісту, що його вона містить, — її source:, чи то простий шлях, чи url: структурованої форми, і кожен файл, який її записи valuesMapping:, workload: і artifacts: імпортують через $import:, — читається відносно каталогу, що містить recipe.yaml, і має залишатися всередині нього. Ці шляхи також визначають, що містить публікація: файли, які вони називають, переносяться разом із сутністю Recipe, а нічого іншого з її каталогу не переноситься (див. aggrega push). Шлях, що виходить за межі каталогу, вказує на файл, який не перенесеться разом із сутністю Recipe, тож цього файлу не буде в того, хто її використовує, а закріплення, записане для нього, засвідчувало б байти, які той не може отримати.
Є дві форми шляху, що виходять за межі каталогу, і обидві відхиляються:
- шлях, що піднімається вище за каталог, наприклад
../shared/charts/app; - абсолютний шлях, наприклад
/opt/charts/app, який називає місце на машині, де його було написано.
Шлях, що піднімається вгору й повертається всередину, — це звичайний шлях усередині каталогу: ./charts/../values.tmpl називає values.tmpl поруч із сутністю Recipe. Оцінюється те, куди веде шлях, виміряний від каталогу сутності Recipe без виходу з нього, — тож вихід назовні, який на зворотному шляху знову називає цей каталог, наприклад ../1.0.0/values.tmpl, написаний у каталозі з назвою 1.0.0, теж відхиляється. Власна назва каталогу не переноситься: опубліковану сутність Recipe читають із каталогу, який називає кеш споживача, і там ця назва нічого не знаходить.
Де шлях відхиляється. Кожна команда, що читає сутність Recipe, відхиляє такий шлях під час читання, ще до того, як щось буде завантажено, відрендерено чи опубліковано: aggrega validate — для каталогу або для власного файлу сутності Recipe, aggrega pull, aggrega build, aggrega pin і aggrega push. source:, записаний як шаблон, нічого не називає, доки збірка його не обчислить, тож шаблон, що створює шлях за межами каталогу, відхиляє збірка в момент, коли значення з’являється. Зупинка — A path names content outside the entity’s own directory (Шлях називає вміст за межами власного каталогу сутності), і вона називає шлях, який ви написали.
Що робити натомість. Покладіть файл у каталог сутності Recipe або в підкаталог під ним і вкажіть його відносно сутності Recipe: ./charts/app, ./extras/netpol.yaml. Чарт, який використовують кілька сутностей Recipes, копіюється в каталог кожної сутності Recipe, оскільки кожна Recipe публікується окремо; тіло мапінгу, робочого навантаження чи артефакту, спільне для кількох сутностей Recipes, належить до MappingLibrary, WorkloadLibrary або ArtifactLibrary, на які кожна Recipe посилається за ідентичністю.
Чому Release відрізняється. Release вказує на інші сутності — свою Aggregate, свій Manifest, сутність Release, яку вона розширює, — і ніколи не публікується, тож ніщо з прочитаного нею нікуди не переноситься. Ці посилання та файл, який імпортують її parameters:, читаються так, як їх написано, і саме це дає змогу спільно використовувати одну Aggregate у варіантах сутності Release у підкаталогах. Див. entities/release.md.
Те саме обмеження діє для сутності FeatureRecipe і для кожної схеми, яку імпортує Component або Feature.
Поле workload: — синтезований тип вхідних даних
Recipe.spec.workload: оголошує тіло Workload, яке компілятор синтезує в нативні ресурси провайдера. Це один із трьох типів вхідних даних, які може оголосити Recipe, поряд із source: (рендеринг із джерела) та artifacts: (допоміжні маніфести). Для кожного провайдера має бути присутній принаймні один із трьох; сервіс, який збірка не надає, оголошує workload: з form: reference.
Поле приймає три режими написання — вбудований блоковий скаляр, файловий $import: або бібліотечний $import:. Компілятор обирає режим за формою вмісту поля; анотація $mode: не потрібна.
Режим 1: вбудований (рядковий скаляр шаблону Go). Значення — це блоковий скаляр YAML, результат якого розбирається як aggrega.ai/v1beta1 Workload:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Поля Workload розташовані в корені документа — обгортки spec: немає, — а containers: і ports: кожного контейнера є мапами з ключами-іменами, а не послідовностями, і порядок, заданий автором, зберігається. Провайдер перетворює цю форму на власну нативну, тож запис мапи контейнерів з’являється у відрендереному виводі helm як елемент containers[], названий за його ключем; авторська форма — це мапа, а не відрендерений список.
Режим 2: файловий $import:. Значення — це мапа з єдиним ключем $import:, що вказує на локальний файл шаблону Go:
spec: workload: $import: ./workload/web-server.yaml.tmplРозв’язання шляхів відповідає valuesMapping:: відносний шлях прив’язується до каталогу, що містить recipe.yaml, який його оголошує, а не до каталогу, з якого запущено збирання, і має залишатися всередині цього каталогу. Імпортоване тіло — це шаблон Go, що обчислюється в контексті рендерингу сутності Recipe, так само як і вбудоване тіло.
Режим 3: бібліотечний $import:. Значення — це мапа з єдиним ключем $import:, що містить посилання за ідентичністю на голе ім’я запису WorkloadLibrary:
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceСаме фрагмент #/workloads/ обирає запис Workload, і саме він відрізняє це посилання від форми #/mappings/, яку використовує valuesMapping:, — та адресує запис MappingLibrary і не називає тіло Workload. Посилання не містить хоста реєстру, розв’язана версія береться з lockfile окремої сутності Release, необов’язкову нижню межу мінімальної версії :<version> можна задати як <Library>:<version>#/workloads/<Entry>, а запис, тіло якого саме є $import: у корені поля, розв’язується рекурсивно. Імпортоване тіло — це шаблон Go, що обчислюється в контексті рендерингу сутності Recipe, яка його використовує, тож .values, .infra і .features потрапляють у нього так само, як і у вбудоване тіло. Див. entities/workloadlibrary, щоб дізнатися про бібліотечну сутність і повну граматику посилань.
Цільовий провайдер має підтримувати синтез (каталог стандартної бібліотеки за домовленістю оголошує workloadSchema для таких провайдерів); вибір провайдера, який не може виконувати синтез, відхиляється під час рендерингу вузла з діагностикою можливостей провайдера — вона залежить від можливостей провайдера, а не від наявності workloadSchema. Повну граматику Workload, наскрізні поля у формі K8s і поведінку перетворення для кожного провайдера див. у entities/workload.md. Ширшу модель трьох типів вхідних даних і асемблер, що об’єднує синтез із виводом, відрендереним із джерела, та артефактами, див. у architecture/16-recipe-input-composition.md.
Передавання власних значень компонента у власний образ розробника. Згідно з домовленістю каталогу стандартної бібліотеки, від сутності Recipe, що запускає образ, який збирає розробник, очікується, що вона передаватиме все, що розв’язали блоки inject: розробника, з .context.inject; вона також може передавати власні значення компонента під назвами, які обирає сама. Там, де сутність Component оголошує spec.inject, назви вибирає власний блок розробника, а .context.self_inject повідомляє сутності Recipe те одне власне значення, яке читає шаблон кожного запису, — values.<key> для запису, що читає рівно одне власне значення і нічого більше. Домовленість каталогу стандартної бібліотеки полягає в тому, щоб розглядати назви, які сутність Recipe дає цим значенням, як типові, а не як контракт, який має читати код розробника, і передавати значення під його типовою назвою лише тоді, коли жоден запис на нього не відображається; корпоративний каталог може обрати інакше. Контракт контексту шаблонів наводить точні правила цієї мапи та повний приклад шаблону.
Поле artifacts: — допоміжні маніфести
Recipe.spec.artifacts: — це мапа «ім’я запису → тіло артефакту», записи якої створюють додаткові файли маніфестів поруч із первинним вихідним результатом сутності Recipe, отриманим із джерела або синтезованим. Це один із трьох видів вхідних даних (із джерела / синтезовані / артефакти): сутність Recipe може оголосити лише artifacts: або разом із workload: та/або source:.
Значення кожного запису має один із трьох режимів, що визначаються формою вмісту, паралельно до workload:: вбудований вміст, файловий $import: або бібліотечний $import:. Компілятор обирає режим за формою вмісту значення; анотація $mode: не потрібна. В усіх трьох режимах ключ мапи називає те, що створює запис: для двох однофайлових режимів це ім’я вихідного файлу, а для режиму пакета — каталог, у який вкладаються файли пакета. Оскільки ключ називає вихідний результат, він обмежений тим, чим може бути ім’я одного файлу: на початку літера або цифра, далі літери, цифри, крапки, дефіси та підкреслення. Крапки зберігають розширення, яке ключ за домовленістю містить, — main.tf, template.yaml, serviceaccount.yaml, — тоді як алфавіт не допускає /, через який ключ називав би шлях, а не файл, і не допускає початкової ., тож ключ ніколи не може бути сегментом батьківського каталогу. Ключ поза цим алфавітом не проходить перевірку оболонки під час завантаження робочого простору, у aggrega validate та в діагностиці редактора.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportРежим 1: вбудований (скаляр-рядок шаблону Go). Значення — блоковий скаляр, а ключ мапи — ім’я вихідного файлу, використане як написано: перший запис вище створює extra-configmap.yaml.
Режим 2: файловий $import:. Значення — мапа з єдиним ключем $import:, що вказує на локальний файл шаблону Go, і ключ мапи — це ім’я вихідного файлу, точно як у режимі 1. Імпортований файл надає вміст, але не ім’я. Другий запис вище має ключ network-policy.yaml і створює network-policy.yaml, хоча імпортований файл називається network-policy.tmpl. Отже, автор, якому потрібне певне ім’я вихідного файлу, записує його як ключ, а два записи, що імпортують різні файли з однаковим ім’ям — ./extras/shared.yaml і ./overrides/shared.yaml, — є двома окремими вихідними результатами. Розв’язання шляхів таке саме, як для valuesMapping: і workload:: відносний шлях прив’язується до каталогу з recipe.yaml, що його оголошує, а не до каталогу, з якого запущено збірку, і має залишатися в межах цього каталогу.
Режим 3: бібліотечний $import:. Значення — мапа з єдиним ключем $import:, що містить посилання на ідентичність за простим ім’ям на пакет сутності ArtifactLibrary, <Library>#/artifacts/<name>. Пакет — це набір файлів, що імпортуються як одне ціле, тож один запис розгортається в один вихідний результат на кожен файл пакета, кожен вкладений під ключ мапи як <key>/<filename>: ключ називає місце використання і є каталогом, у який потрапляють ці файли, а не ім’ям будь-якого з них. Третій запис вище має ключ operator-support; якщо PlatformArtifacts#/artifacts/OperatorSupport оголошує crd.yaml і rbac.yaml, цей єдиний запис створює operator-support/crd.yaml і operator-support/rbac.yaml. Посилання не містить хоста реєстру — форма з хостом oci://… відхиляється, — розв’язана версія береться з lock-файлу кожної сутності Release, а необов’язкову нижню межу версії :<version> можна задати як <Library>:<version>#/artifacts/<name>. Див. entities/artifactlibrary щодо сутності бібліотеки та повної граматики посилань.
Файловий $import: закріплюється поруч із сутністю Recipe. aggrega pin записує дайджест байтів кожного імпортованого файлу в entity.lock у каталозі сутності Recipe з ключем, що дорівнює ключу мапи запису, а aggrega build знову обчислює дайджест файлу і зупиняється з [CATALOG_ERROR E0026], коли він більше не збігається, — або спершу з E0130, якщо lock-файл сутності Release, записаний до зміни, фіксує сутність Recipe за її вмістом, — тож файл, змінений після закріплення, ніколи не рендериться неперевіреним. Якщо зміна була навмисною, виконайте aggrega pin для сутності Recipe, щоб записати новий дайджест; інакше відновіть файл. Вбудований запис є частиною файлу сутності Recipe, а бібліотечний запис закріплюється версією бібліотеки, яку фіксує lock-файл, тож жоден із них не має власного закріплення. aggrega pull описує цей файл.
Шаблон кожного запису артефакту обчислюється з тим самим контекстом шаблону, що й valuesMapping:, незалежно від режиму, який надав його тіло. Два вихідні результати з однаковим ім’ям файлу зупиняють збірку під час рендерингу вузла. Два записи однієї мапи artifacts: не можуть назвати один вихідний результат: ключ мапи унікальний у межах одного документа й задає одне ім’я файлу, тож вихідний результат однофайлового запису — це його ключ, а файли запису-пакета лежать у каталозі, названому його ключем; перший сегмент кожного шляху, який створює запис, — це ключ, що його породив, тож різні ключі лишаються різними вихідними іменами, хоч як називаються імпортовані файли. Зупинка охоплює одне ім’я файлу, яке надають два різні види вхідних даних — шаблон чарта й запис артефакту, що обидва створюють servicemonitor.yaml, — і повідомляється щодо цієї сутності Recipe з діагностикою, що називає кожне джерело внеску.
Сценарії використання. artifacts: — місце для допоміжних ресурсів, яких не створює первинний чарт або модуль: NetworkPolicy для робочого навантаження, HPA у парі з Deployment, допоміжний ConfigMap, прив’язаний до instance_id. Наскрізні допоміжні ресурси, що застосовуються до багатьох компонентів (наприклад, sidecar резервного копіювання, приєднаний до кожного сховища даних), належать до генерації ресурсів сутності FeatureRecipe, а не до artifacts: окремої сутності Recipe; див. entities/featurerecipe.md щодо поверхні розширення FeatureRecipe.
Блок boundary: — файли для спільного виводу межі
Більшості сутностей Recipes це ніколи не знадобиться. Усе інше, що пише Recipe, належить її власному компоненту: провайдер розміщує це під власною позицією цього компонента у виводі межі. Деякі файли натомість належать межі загалом — це файл, який ціль читає один раз для всього, що розгортає межа. Типовий випадок — конфігурація провайдера Terraform: документація Terraform радить не розміщувати блоки provider у модулі, який викликає інша конфігурація, а модуль, що містить власний такий блок, не можна викликати з depends_on, count або for_each. spec.boundary.artifacts — це місце, де Recipe пише такий файл.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }Блок — це artifacts: на другому рівні. artifacts — його єдиний член, і він має точно таку саму форму, як власне поле artifacts: сутності Recipe: ті самі три режими — вбудований вміст, файловий $import:, бібліотечний $import:, файли якого вкладаються під ключ запису як <key>/<filename>, — те саме правило «ключ — ім’я файлу» і той самий алфавіт для ключа, а також той самий контекст шаблону, тож запис читає .values, .infra, .locals та решту точно так само, як запис artifacts:. Він потребує щонайменше одного запису, а будь-який інший член під boundary: відхиляється під час читання Recipe. FeatureRecipe не має такого блоку.
Де записується файл. Один раз, у каталозі, що містить зібраний вивід межі, поряд із файлами, які туди записує власне збирання провайдера, — для terraform поряд із кореневою конфігурацією aggrega.modules.tf, а не всередині модуля компонента. Провайдер не отримує жодного з цих файлів: компілятор обчислює їх і записує сам і нічого не проставляє у файл, щоб указати, з якого компонента він походить, бо файл належить кожному компоненту, що його оголосив. Запис, шаблон якого рендериться в порожнечу, не записує жодного файлу.
Як зустрічаються кілька учасників. Кожен запис обчислюється для кожного компонента, який Recipe рендерить у межі, а файли, оголошені всіма учасниками межі, об’єднуються за іменем. Одне ім’я, обчислене в ті самі байти — двома компонентами, прив’язаними до однієї Recipe, або двома Recipes, що однаково конфігурують один провайдер, — це один файл. Одне ім’я, обчислене в різні байти, зупиняє збирання з указанням файлу та кожного учасника, бо жоден окремий файл не є тим, що написали всі вони; так само й ім’я, яке записує власне збирання провайдера, як-от aggrega.modules.tf. Обидва випадки — це колізія зібраного виводу. Дві Recipes, що конфігурують один провайдер під двома різними іменами файлів, не об’єднуються — записується кожен файл, — і тоді про дубльовану конфігурацію повідомляє ціль, тож Recipes, які мають спільно використовувати конфігурацію провайдера, спільно використовують і ім’я її файлу, за домовленістю — назване на честь провайдера, який він конфігурує.
Які провайдери це приймають. Чи має якесь значення файл, розміщений поряд із зібраним виводом межі, — це властивість цілі провайдера, тому це частина власного оголошення провайдера. Recipe, що оголошує блок, провайдер якої його не приймає, відхиляється ще до будь-якого рендерингу, незалежно від того, у що рендеряться її записи; див. The provider does not support boundary artifacts (Провайдер не підтримує артефакти межі). Таблиця можливостей наводить заявку кожного провайдера.
| Provider | boundary.artifacts: |
|---|---|
terraform | Приймається. Кожен файл записується поряд із кореневою конфігурацією межі, яку Terraform читає разом з усіма іншими файлами конфігурації в цьому каталозі. |
helm, compose, helm-chart, cloudformation | Відхиляється ще до будь-якого рендерингу. |
Файловий $import: тут закріплюється так само, як файл, що його імпортує запис artifacts:. Блокування сутності записує його дайджест у той самий список artifactDigests, під boundary/<key>, а не лише під ключем, тож записи кожного блоку, написані під одним ключем, закріплюються окремо. Крок закріплення записує його, pull без закріплення зупиняється там, де закріплення відсутнє або більше не збігається, а збирання відхиляє файл, відредагований після закріплення, точно так само, як відхиляє файл artifacts:.
Поле outputLabels: — мітки, оголошені автором, на згенерованому виводі
Recipe.spec.outputLabels: — це мапа «ключ мітки → значення», яку provider проставляє на кожен об’єкт, що його створює згенерований вивід сутності Recipe. Це чесне місце для риси реалізації — властивості того, як конкретний Recipe реалізує компонент, на відміну від того, чим компонент є. Візьмімо сховище, з яким реалізація зберігає дані, нижче записане ілюстративним ключем example.io/storage-backing: Helm-Recipe, що монтує PersistentVolumeClaim, і Compose-Recipe, що монтує іменований том, реалізують той самий компонент різними механізмами, тож вони мають різні outputLabels, і подальші інструменти (розподіл витрат, політики, інвентаризація) можуть розрізнити їх на згенерованих ресурсах. Ключ ілюстративний — example.io/ є прикладом простору імен, а каталог сам обирає ключі, які читають його інструменти.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformВихідні мітки йдуть тією самою колією, що й фіксовані мітки походження збірки: їх зливають із набором міток, який проставляє кожна поверхня виводу, тож вони потрапляють усюди, куди потрапляє походження. Відрізняється власник: ключі походження належать компілятору, а outputLabels належать авторові Recipe.
Власну мітку ідентичності компонента тут не вписують — це домовленість каталогу, а не правило, яке примусово застосовує компілятор. Ключі, що кажуть, чим компонент є, а не як його реалізує один Recipe, — його когнітивна категорія, операційний тип, мітки можливостей для кожної ролі, хто експлуатує базовий ресурс, клас ліцензування того, що він обгортає, — оголошуються в metadata.labels сутності Component; осі див. у розділі «The Semantic Label Taxonomy» сторінки entities/component. Recipe переносить один із цих ключів на свій згенерований вивід, називаючи ключ у outputComponentLabels: нижче, а не вписуючи тут ключ і значення. Причина в тому, що літеральний запис — це друга копія значення, яке компонент уже має, а друга копія може розійтися з першою: автор Recipe може вписати одну позицію на вузлі, чий Component оголошує іншу, і повідомити подальшому читачеві те, чого граф не каже. Перенесений запис копіює за посиланням, тож не має другої копії, яка могла б розійтися. Ядро приймає будь-який варіант, який ви напишете, окрім правила зарезервованих просторів імен нижче; домовленості дотримуються автори каталогів.
Зарезервовані простори імен. Простори імен aggrega.ai/ і app.kubernetes.io/ зарезервовано для нативного походження платформи. Recipe, що оголошує ключ outputLabels під будь-яким із цих префіксів, відхиляється під час завантаження з чіткою помилкою каталогу, яка називає проблемний ключ. Будь-який інший ключ приймається. Інакше ядро не контролює ключ чи значення — за ключ або значення, неприпустимі для поверхні міток цільового рушія, відповідає автор, і їх відхиляє подальше середовище виконання; поза правилом зарезервованих просторів імен компілятор не втручається.
Відображення для кожного provider. Кожен provider переносить мітки на власну поверхню виводу:
- helm, синтез workload — і в
metadata.labelsоб’єкта, і вmetadata.labelsшаблону pod, там само, де синтез розміщує походження. - helm, source-render і artifacts — у
metadata.labelsоб’єкта. - compose — у мапі
labels:кожного сервісу. - terraform — як теги окремих ресурсів у структурно адресованих тілах артефактів
.tf.json, за можливості: блок ресурсу, що вже оголошує мапуtags(AWS/azurerm) абоlabels(Google), отримує вихідні мітки в ній, оголошений автором ключ ніколи не перезаписується, а ресурс без такого атрибута лишається недоторканим (атрибут ніколи не вигадується). Тіла нативного HCL (main.tf,*.tf) і вендорені модулі виводяться дослівно й не містять доданих тегів. Походження Terraform і далі передається в супровідному файлі коментарів, окремо від колії тегів.
Вихідні мітки — це лише мітки; окремої поверхні вихідних анотацій немає. outputLabels оголошує автор Recipe (шар реалізації, створений ops), а не Aggregate — воно описує реалізацію, а не ідентичність розробника в абстрактному графі.
Поле outputComponentLabels: — просування власних міток компонента
Recipe.spec.outputComponentLabels: — це список ключів міток, а не пар ключ-значення. Для кожного названого ключа провайдер проставляє цей ключ на відрендерений вивід зі значенням, яке цей ключ має в екземплярі компонента, що рендериться. Там, де outputLabels задає значення, outputComponentLabels вказує, звідки це значення слід прочитати.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingЯкщо metadata.labels сутності Component оголошують component.aggrega.ai/hosting: managed, кожен об’єкт, який ця сутність Recipe рендерить для цього компонента, має component.aggrega.ai/hosting: managed. Прив’яжіть ту саму сутність Recipe до компонента, що оголошує self-hosted, і об’єкти цього компонента натомість матимуть self-hosted — одна сутність Recipe, один названий ключ, власне значення для кожного компонента.
Просування відбувається за посиланням, і саме в цьому суть. Значення читається з компонента щоразу під час рендерингу виводу, тож воно не може розійтися з ідентичністю, з якої походить: немає другої копії, яку треба синхронізувати, коли мітка компонента змінюється. Літеральний запис outputLabels, що повторює мітку компонента, і є такою другою копією, і обидві розходяться, щойно змінюється будь-яка з них. Тому використовуйте outputLabels, коли значення є властивістю того, як ця сутність Recipe реалізує компонент, а outputComponentLabels — коли значення вже існує в компоненті і відрендерений вивід теж має його містити.
Просунутий ключ потрапляє точно на ту саму поверхню, що й літеральний: описане вище відображення для кожного провайдера застосовується без змін, і жоден провайдер не відрізняє просунутий ключ від записаного на місці.
Зарезервовані простори імен. Простори імен aggrega.ai/ і app.kubernetes.io/ зарезервовано для вбудованих у платформу міток походження, і просунутий ключ із будь-яким із цих префіксів відхиляється під час завантаження з помилкою каталогу, що називає ключ і поле, в якому він з’являється. Перевіряється саме префікс: ключ на кшталт component.aggrega.ai/hosting належить до власного простору імен, а не до зарезервованого кореня, і його можна просувати.
Ключ належить або до одного блоку, або до іншого. Оголошення того самого ключа і в outputLabels, і в outputComponentLabels відхиляється під час завантаження, тож кожен проставлений ключ має єдине джерело — або літеральне значення, записане в сутності Recipe, або власну мітку компонента, але ніколи обидва.
Просунутий ключ, якого компонент не оголошує, нічого не проставляє. Збирання продовжується й видає попередження, що називає вузол, сутність Recipe і відсутній ключ. Це зроблено навмисно: сутність Recipe, прив’язана до компонентів із різними наборами міток, однаково рендериться, а розбіжність повідомляється, а не зупиняє збирання.
Компоненти з однією позицією — домовленість, а не правило. Просування переносить будь-яке значення, яке оголошує компонент, і компілятор це значення не інтерпретує. Тому компонент, чия мітка ідентичності містить заповнювач на позначення «буває по-різному», просуває цей заповнювач на кожен об’єкт, відрендерений для нього. Там, де компонент справді має більше ніж одну позицію, домовленість каталогу стандартної бібліотеки полягає в тому, щоб кожна сутність Recipe вказувала позицію власної реалізації через ключ outputLabels, яким володіє ця сутність Recipe, а не через ключ ідентичності компонента, який та сама домовленість натомість спрямовує через outputComponentLabels:, — або не проставляла нічого. Ці два ключі відповідають на різні запитання, і жоден не замінює іншого: ключ ідентичності каже, чим є компонент у кожній реалізації, а ключ, яким володіє сутність Recipe, каже, що робить ця конкретна реалізація. Це домовленість каталогу, яку підтримують його автори, а не обмеження, яке забезпечує компілятор.
Блок locals:
Recipe.spec.locals: — це приватний операційний стан (Private Ops State): мапа іменованих рядків шаблонів Go, відрендерений результат яких надає мапу .locals.* пізнішим шаблонам Recipe. Це робочий простір, щоб один раз обчислити фізичні реалії (цільові контейнери, шляхи JSON, похідні імена хостів) і повторно використовувати їх у provides:, source:, valuesMapping:, workload:, artifacts:, assertions: та корисних навантаженнях pipeline[].with без повторного обчислення. Відрендерений результат кожного запису зберігається без початкових і кінцевих пробільних символів.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: ніколи не відкривається викликачам: downstream-компоненти, що споживають цей Recipe через uses:, бачать лише provides:. Власні шаблони provides:, source:, valuesMapping:, workload:, artifacts:, assertions: і pipeline[].with цього Recipe бачать розв’язану мапу .locals.*. Значення окремих ключів можуть бути звичайними рядками або шаблонами Go; компілятор розв’язує весь блок у преамбулі locals, до provides: цього вузла, тож кожен пізніший шаблон бачить стабільні розв’язані значення.
Кожен запис обчислюється в самодостатньому локальному контексті вузла: .context.instance_id, .values, .infra і вже розв’язані записи цього ж блоку. Локальна змінна не може читати .provides: цієї складової немає на цій поверхні, і запис, що звертається до неї, зупиняє збірку. Не може вона читати й .context.rendered_name — ім’я, яке provider, наприклад helm, дає ресурсам, що рендерить для вузла, тож локальна змінна, що називає один із цих ресурсів, містить лише частину після цього імені, як secret_target_db_password вище, а шаблон, що записує повне ім’я, з’єднує обидві частини.
Авторський порядок має значення
Записи розв’язуються в порядку написання, і запис може читати сусідній запис, визначений вище, отримуючи його розв’язане значення:
spec: locals: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveЛанцюжки працюють лише донизу. Коли один запис читає інший, порядок записів вирішує, чи вдасться збірка: перемістіть db_identifier нижче secret_target — і збірка зупиниться. Компілятор ніколи не сортує й не переставляє блок, щоб розв’язати посилання, тож записаний порядок і є контрактом: перестановка блоку locals: — це зміна поведінки, а не косметична.
Дві зупинки розрізняють дві помилки, яких може припуститися автор, бо виправляються вони по-різному:
- Посилання на запис, який блок визначає пізніше, зупиняє збірку з вказівкою на помилку порядку; виправлення — перемістити визначення вище за його читача.
- Посилання на ключ, який блок взагалі не оголошує, зупиняє збірку з назвою ключа; виправлення — виправити написання.
Перевірка відстежує псевдонім блоку. Ключ, до якого звертаються через крапку, яку перепризначає тіло with .locals, або через змінну, прив’язану до .locals, перевіряється точно так само, як пряме написання: {{ with .locals }}{{ .nope }}{{ end }} і {{ $l := .locals }}{{ $l.nope }} обидва зупиняють збірку з назвою .locals.nope, так само як {{ .locals.nope }}, і так само {{ (.locals).nope }} та {{ ($.locals).nope }}, бо дужки дають сам блок і нічого більше. Одне написання уникає перевірки: ключ, до якого звертаються через виклик, результат якого текст шаблону не може назвати, — {{ index .locals "nope" }} або {{ (default dict .locals).nope }}, — бо те, що повертає такий виклик, визначається під час виконання шаблону, а не написаним. Відсутній ключ, прочитаний як поле з результату такого виклику, не зупиняє збірку й рендерить буквальний текст <no value>, а не порожнечу. Відсутній ключ, до якого звертаються через index, зупиняє збірку з назвою ключа, бо index зупиняє її на кожній поверхні шаблонів, коли мапа, яку він читає, не містить запитаного ключа, — це інше повідомлення, ніж у цієї перевірки, описане в errors/fatal-halts.md під «A template indexes a map with a key the map does not hold (Шаблон індексує мапу ключем, якого мапа не містить)». Тому index лишається способом звернутися до ключа, ім’я якого саме обчислюється, наприклад {{ index .locals (printf "secret_target_%s" .values.slot) }}, а обчислене ім’я, якого блок не оголошує, все одно повідомляється за ключем.
provides: читає .locals й отримує розв’язані значення, бо locals вузла розв’язуються перед його provides. Шаблон provides:, що називає ключ, не оголошений у блоці locals, зупиняє збирання. Це означає, що значення, потрібне і записові provides:, і артефакту, задається один раз, у locals:, і читається з обох місць.
Публічний відповідник API описано нижче: див. provides: блок. Поверхня FeatureRecipe дотримується тих самих правил — див. entities/featurerecipe.md, розділ «Блок locals:».
Блок provides:
Recipe.spec.provides: — це публічний API для розробників: мапа «ім’я → рядок шаблону Go», що оголошує значення, які цей Recipe надає в канали .context.inject і .context.uses низхідних викликачів. Компілятор обчислює шаблони provides: на етапі обчислення provides (самодостатньо, у будь-якому порядку); ключі inject викликачів розв’язуються щодо цих значень на етапі гідратації inject.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"Шаблон кожного запису обчислюється на самодостатній поверхні обчислення provides — .context.instance_id, .context.rendered_name, якщо провайдер вузла його повідомляє, .values, .infra, розв’язані .locals вузла та статичний текст. Простору імен, у який розміщено вузол, на ній немає, тож опублікований хост його не містить: споживач в іншому просторі імен уточнює його на своєму боці. .locals на ній є, бо locals вузла розв’язуються в преамбулі того самого етапу, перед його provides; шаблон provides, що називає ключ, не оголошений у блоці locals, зупиняє збірку. Відокремлення обчислення provides від гідратації inject є несучим: provides: сутності Recipe не може посилатися на стан жодного викликача, бо викликачі ще не розв’язані, коли виконується обчислення provides, — provides: самодостатній згідно з архітектурним інваріантом. Далі викликачі читають ці значення через .context.uses.<alias>.provides.<provided-name> у власних шаблонах — надані імена вкладаються під provides на ребрі, поряд з іншими полями ребра. Викликач, що оголошує на ребрі список дозволених inject:, натомість отримує ті самі значення через свій канал .context.inject.
Ключі provides: є частиною контрактної поверхні сутності Recipe. Перейменування чи вилучення ключа — несумісна зміна для кожного викликача, що покладається на старе ім’я; версія інтерфейсу implements: має відображати еволюцію контракту. Семантику каскадного розв’язання, контракт каналу inject і робочі приклади з маршрутизацією між просторами імен і регіонами див. у architecture/06-data-taxonomy-and-composition.md §3 і templates/expansion-matrix.md.
Читання опублікованих значень вкладення
Recipe читає Features, прикріплені до її компонента, за шляхом .features.<instance-name>, а Features облікових даних — за шляхом .features.<slot>. Обидва мають однакову форму вкладення — .type, .values, .infra, .provides, — тож вкладення читається однаково, хоч у якій мапі воно міститься; відрізняється між ними лише те, що вкладення створює.
.provides — це опублікований вихід вкладення, розв’язаний із прив’язаної до нього FeatureRecipe. Це відповідник блоку provides: вище, видимий зі сторони споживача: якщо Recipe публікує значення для своїх викликачів, то вкладення публікує їх для свого компонента-хоста.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Читання опублікованого значення замість його повторного обчислення з тих самих вхідних даних values/infra — це різниця між одним визначенням імені та двома, які можуть розійтися. Повну форму поле за полем, разом із правилами доступності, наведено в templates/template-context-contract.md.
Вкладення, записане на одному з з’єднань компонента — облікові дані, які компонент пред’являє одній цілі, — читається в тій самій формі під цим з’єднанням, за шляхом .context.uses.<alias>.features.<slot>, і ніколи не потрапляє до .features. Recipe, що звертається до кількох цілей, читає власні облікові дані кожної цілі під псевдонімом цієї цілі, а цикл по .features, що відбирає вкладення за типом, знаходить лише власні вкладення компонента:
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Див. Вкладення з’єднання, щоб дізнатися про форму та порядок, у якому шаблон перебирає з’єднання.
Поле pipeline:
Recipe.spec.pipeline: — це послідовний масив кроків конвеєра Wasm, які виконуються після рендерингу над набором відрендерених документів, і кожен повертає патчі RFC 6902 та побічні ефекти. Кожен запис оголошує id (ідентифікатор кроку: літери, цифри та підкреслення), plugin (сутність Plugin, яку виконує крок, обмежену її типом плагіна, — pipeline-step/<name>, за потреби з версією; просте посилання на .wasm або артефакт відхиляється), function (експорт плагіна, який слід викликати), необов’язкове тіло шаблону Go with:, що надає корисне навантаження плагіна, і необов’язковий шаблон Go when:, який визначає, чи виконується крок: хибний результат пропускає крок як прохідний, і набір документів лишається незмінним. Умову when:, її незалежність від optional: і правило істинності повністю описано в entities/featurerecipe.md, розділ «Умовні кроки — when:»:
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"Компілятор виконує кроки pipeline: базової сутності Recipe в оголошеному порядку так само, як виконує pipeline: сутності FeatureRecipe: він запускає названий Wasm plugin кожного кроку над відрендереним виводом, застосовує повернуті операції JSON Patch до адресованих документів і видає побічні ефекти кроку. Поле FeatureRecipe pipeline: має ту саму форму схеми й те саме виконання — див. entities/featurerecipe.md, розділ «Authoring Contract», і Стан мови щодо стану виконання кожної поверхні.
Механіка поля відтворює семантику FeatureRecipe: послідовне обчислення в оголошеному порядку, операції JSON Patch, застосовані до відрендерених документів, побічні ефекти, що видаються поряд із ними, і помилки, що повідомляються з походженням, яке вказує на крок-порушник. Крок, умова when: якого рендериться як хибна, пропускається як наскрізний, залишаючи набір документів незмінним для наступного кроку.
Блок assertions:
Recipe.spec.assertions: — це необов’язкова мапа іменованих правил, що виражають інваріанти реалізації Recipe — міжполеві правила, які виконуються для конкретного чарту чи модуля, що його використовує Recipe як джерело. Кожен ключ — це ідентифікатор правила, який з’являється в повідомленні про помилку; кожне значення — тіло шаблону Go. На відміну від тверджень Component (які виражають інваріанти рівня контракту незалежно від того, яка Recipe прив’язується), твердження Recipe є властивостями конкретної обраної реалізації.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}Наведене вище правило стосується лише чарту Bitnami 20.x; воно не застосовується, якщо прив’язується інша Recipe для MariaDB. Правила рівня Component із контракту й далі застосовуються паралельно й обчислюються на ранішій фазі конвеєра.
Твердження Recipe обчислюються після прив’язки Recipe і до рендерингу, коли locals і provides кожного вузла вже визначено. Контекст шаблону містить .provides, .locals і .recipe.source сутності Recipe на додачу до полів екземпляра сутності (.values, .infra, .uses, .features). .uses і .features тут мають вужчу форму поверхні тверджень, а не форму шаблону Recipe: запис з’єднання містить його ціль і псевдонім, labels цілі, власні values з’єднання та прикріплення, записані на ньому в features, але нічого з того, що публікує ціль; а запис прикріплення — власного прикріплення компонента чи прикріплення з’єднання — містить його type, resolved_version і values, але ні його infra, ні його provides: на момент виконання твердження FeatureRecipe прикріплення ще не визначила свої provides. Тому звернення до .features.<name>.provides зупиняє збірку, а читання з урахуванням наявності повертає своє резервне значення. Повну граматику написання, розподіл відповідальності між правилами рівня контракту й рівня реалізації та розібрані приклади див. у templates/assertions-block.md.
Поле omits: — вилучення відрендерених документів із джерела
Більшості сутностей Recipes це ніколи не знадобиться. Поле призначене для джерела, яке ви берете як є — найчастіше це chart, завантажений із реєстру, — і яке рендерить документ, що його ваша сутність Release не повинна постачати: наприклад, Secret, який chart генерує заново під час кожного рендерингу, через що дві збірки відрізняються, а після застосування він перезаписує Secret, наданий оператором. Завантажений chart ви не редагуєте, і жодне правило ігнорування до нього не дістає, тож omits: — це спосіб, яким сутність Recipe вилучає такий документ зі збірки. Завантажений compose-файл — той самий випадок: він може містити service, volume або config, яких у сутності Release не має бути, а накладання valuesMapping: може змінити такий елемент, але ніколи не видалити його. Так само із завантаженим шаблоном CloudFormation, який може оголошувати ресурс, що його сутність Release не повинна створювати: valuesMapping: може заповнити оголошені в ньому параметри, але ніколи не видалить жодного з його ресурсів.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringЩо охоплює поле. Лише те, що рендерить source:. workload: і записи artifacts: ніколи не фільтруються: їх ви пишете в сутності Recipe, тож документ, який вам там не потрібен, ви просто не пишете. Ключ вимагає source:; документ, що порушує це правило, відхиляється під час читання із зазначенням правила.
Запис. Кожен запис визначає, що вилучити, трьома полями, а четверте вирішує, чи застосовується запис. Те, що називають перші три, — це власна лексика провайдера для того, що рендерить його джерело; для кожного провайдера її наведено в таблиці нижче:
kind— вид того, що рендерить джерело: для chart — вид відрендереного документа:Secret,ConfigMap,Deployment; для compose-файлу —service,volumeабоconfig; для шаблону CloudFormation —Typeресурсу:AWS::S3::Bucket. Він не пов’язаний ізkind:, який містить структурованийsource:і який визначає спосіб завантаження джерела.name— його ім’я:metadata.nameдокумента; ключ одиниці compose уservices:,volumes:абоconfigs:; логічний ID ресурсу CloudFormation, тобто його ключ уResources.namespace(необов’язково) — простір імен, у якому перебуває документ, для провайдера, вивід якого має простори імен. Без нього запис визначає вид та ім’я в будь-якому просторі імен;namespace, що рендериться в порожнє значення, вважається відсутнім.when(необов’язково) — чи застосовується запис до цієї збірки. Воно обчислюється першим і читається за тим самим правилом, що йwhen:кроку pipeline: хибний результат відкидає запис, тож інші його поля не обчислюються, і він не передається провайдеру й не перевіряється, тоді як відсутнє або порожнєwhen:зберігає його.
kind і name обов’язкові, а запис із будь-яким іншим полем відхиляється під час читання сутності Recipe.
Кожне значення є шаблоном, що обчислюється в тому самому контексті, що й valuesMapping:. Цей контекст містить .context.rendered_name — ім’я, яке провайдер дає ресурсам вузла і за яким chart зазвичай їх називає, тож запис може назвати документ точно так, як це зробить chart. Шаблон, який не вдалося відрендерити, зупиняє збірку так само, як невдалий шаблон valuesMapping:.
Кожен запис, що застосовується, мусить щось вилучити. Провайдер повідомляє, скільки одиниць вилучив кожен запис, а запис, який нічого не вилучив, зупиняє збірку із зазначенням запису; див. An omits entry left out nothing the source rendered (Запис omits не вилучив нічого з того, що відрендерило джерело). Звичайна причина — оновлення джерела, яке перейменовує або видаляє документ, і саме ця зупинка не дає перейменованому документу непомітно потрапити у ваш вивід. Щоб вилучати документ лише іноді, зазначте це через when:, а не покладайтеся на відсутність документа.
Джерело все одно рендериться повністю. Фільтрується лише його вивід: кожен шаблон chart усе одно виконується, тож шаблон, що завершується помилкою, однаково зупиняє збірку, а вилучений документ спершу рендериться, а потім відкидається. Після відкидання він не потрапляє ні в що, що збірка робить далі: ні в жоден згенерований файл, ні в порівняння імен з іменами інших компонентів, ні в жоден факт про рендеринг, який читає сутність Feature, ні в те, що передається кроку pipeline.
Сутність Release впливає на ключ через infra і parameters. Ключ належить сутності Recipe, тож сутність Release не може його записати. Проте вона може визначати, що робить запис: шаблони запису читають infra, який заповнює сутність Release, а parameters, які вона надає, потрапляють у .values сутності Recipe там, де сутність Aggregate їх туди спрямовує. Тож сутність Release вмикає або вимикає запис через when:, як це робить другий запис вище, або визначає, що він називає.
За те, що ви вилучаєте, відповідаєте ви. Ніщо у збірці не знає, для чого призначений документ. Вилучення документа, від якого решта chart залежить під час виконання, — Secret, який монтує Deployment, ServiceAccount, від імені якого працює pod, — дає вивід, що чисто збирається, а потім збоїть під час застосування, якщо цей документ не надає щось інше, застосоване поруч. Для compose-файлу та шаблону CloudFormation збірка таки перевіряє це, бо кожен із них сам указує свої посилання: якщо те, що залишилося, досі називає вилучену одиницю — service, що називає вилучений service, ресурс або output, що називає вилучений ресурс, — збірка зупиняється, як описано в таблиці нижче.
Які провайдери це підтримують. Вилучити документ може лише провайдер, бо лише провайдер знає, що рендерить його джерело, тож те, чи підтримує провайдер цей ключ, є частиною власного оголошення провайдера. Сутність Recipe, що оголошує omits:, провайдер якої цього не підтримує, відхиляється ще до будь-якого рендерингу, незалежно від того, у що рендеряться when: її записів; див. The provider does not support omits (Провайдер не підтримує omits).
| Provider | omits: |
|---|---|
helm | Підтримується. Запис називає документ, який рендерить chart — із шаблону або з його каталогу crds/, — за власними kind, metadata.name документа і, якщо запис його вказує, простором імен, у якому перебуває документ. Див. helm → Режим із джерелом. |
compose | Підтримується. Запис називає service, volume або config compose-файлу з джерела за його ключем у services:, volumes: або configs:, зіставленим після злиття valuesMapping: із файлом, і не вказує простору імен: запис, що називає інший вид або простір імен, зупиняє збірку під час рендерингу компонента. Файл, у якому те, що залишилося, досі називає вилучену одиницю — через depends_on, links, volumes_from, мережевий режим або режим простору імен service:, extends, контекст збірки чи запис volumes: або configs:, — зупиняє збірку із зазначенням кожного посилання. Див. compose → Режим із джерелом. |
cloudformation | Підтримується. Запис називає ресурс шаблону з джерела за його Type і логічним ID у кожному шаблоні джерела-каталогу та не вказує простору імен: запис, що його містить, зупиняє збірку під час рендерингу компонента. Шаблон, у якому те, що залишилося, досі називає вилучений ресурс — через Ref, Fn::GetAtt, DependsOn або змінну Fn::Sub, — зупиняє збірку із зазначенням кожного посилання. Див. cloudformation → Вилучення ресурсів із шаблону з джерела. |
helm-chart, terraform | Відхиляється: провайдер передає своє джерело далі, щоб його було відрендерено під час розгортання, тож під час збірки немає документа, який можна вилучити. Для локального chart або модуля натомість файл із нього вилучає рядок у .aggregaignore поруч із сутністю Recipe. |
Той самий ключ задається в сутності FeatureRecipe; див. entities/featurerecipe.md.
Робочий приклад — вилучений згенерований Secret завантаженого chart, зупинка через недетермінованість, на яку той самий chart натрапляє без запису, і зупинка на записі, що нічого не збігається, усе з реальної збірки, — див. у ai-gateway-own-webhook-certificate.