Домовленості щодо іменування
У цьому розділі описано правила іменування та регістру, що застосовуються до авторського вмісту Aggrega: шаблон для імен екземплярів, які пише користувач, дисципліну регістру для імен полів у DSL, регістр, який платформа використовує для ідентифікаторів, що їх визначає вона, а не ви, і синтаксис коментарів на авторській поверхні YAML.
Імена екземплярів
Імена екземплярів, які пише користувач, — ключі, що їх розробник пише для компонентів, фіч, агрегатів, підсистем, меж, а також сокетів і псевдонімів uses, — усі відповідають одному шаблону: ^[a-zA-Z0-9_-]+$. Допустимі як kebab-case (pii-filter, my-agent), так і snake_case (openai_key, db_credentials); команди можуть обрати ту домовленість, якій надають перевагу.
Дозволені символи: літери й цифри (a-z, A-Z, 0-9), дефіси (-) і символи підкреслення (_). Інші символи не дозволені.
Приклади:
components: web-server: # kebab-case finance_worker: # snake_case
features: pii-filter: # kebab-case audit_logger: # snake_case openai_key: # snake_case — natural for a credential attachment db-password: # kebab-case — also valid| Шаблон | Область застосування | Приклади |
|---|---|---|
^[a-zA-Z0-9_-]+$ | Усі імена екземплярів, які пише користувач | web-server, openai_key, pii-filter |
Шаблон перевіряється під час розв’язання за допомогою patternProperties у JSON Schema.
Чого коштує ім’я компонента і чому під деякими цілями великі літери коштують більше
Наведений вище шаблон визначає, що ви можете написати. Чого ім’я коштує — окреме питання, і відповідь залежить від цілі, на яку розгортається компонент, — тож це варто знати до того, як ви оберете ім’я, а не тоді, коли збірка його відхилить.
Ім’я компонента стає ідентичністю, якою позначається кожен ресурс, що його компонент породжує, і кожна ціль виводить із цієї ідентичності власні імена: інсталятор чартів виводить ім’я релізу, оркестратор контейнерів — імена сервісів. Ціль, чий алфавіт вужчий за шаблон, не може містити символу, якого вона не допускає, а Aggrega не замінюватиме непомітно такий символ на схожий — два імена, які автор може розрізнити, не повинні стати одним ім’ям у кластері. Тому символ, якого ціль не допускає, натомість записується як escape-послідовність, а escape-послідовність довша за символ, який вона замінює.
Практичний наслідок: велика літера нічого не коштує під одними цілями і дорого коштує під іншими.
- Під ціллю, чиї імена допускають великі літери, — наприклад, файлом compose для оркестрації контейнерів —
PaymentsAPIпередається точно так, як ви його написали, і коштує одинадцять символів. - Під ціллю, чиї імена допускають лише малі літери, — ім’я релізу інсталятора чартів — кожна велика літера екранується, і ім’я лише з шести великих літер уже перевищує те, що ця ціль приймає.
Є й другий ефект, і він гостріший: escape-послідовність починається з дефіса. Тому ціль, яка вимагає, щоб ім’я починалося з малої літери або цифри, відхилить ім’я, чий перший символ вона не допускає, хоч яким коротким був би решта імені, — жодне скорочення цього не виправить.
Рекомендації випливають із цих двох ефектів. Надавайте перевагу малим літерам і цифрам із дефісами між словами і починайте ім’я з малої літери. payments-api передається без змін кожною ціллю, для якої Aggrega постачає провайдер. payments_api передається файлом compose, але не ціллю helm, чиї імена ресурсів не допускають підкреслення: сервіси, робочі навантаження й реліз, які вона називає за компонентом, записуються як payments-zuapi. PaymentsAPI там коштує ще більше. Recipe, що публікує адресу такого ресурсу, зчитує власне написання цілі, а не передбачає його, — див. templates/rendered-resource-names.md.
Цифру на початку дозволено писати, і під файлом compose вона нічого не коштує, але ціль helm її відхиляє. Ім’я Service у Kubernetes має починатися з літери, а сервіси, які породжує чарт або синтезоване робоче навантаження, називаються за компонентом, тож компонент з ім’ям 1cache зупиняє збірку helm — відмова називає компонент і повідомляє, що ім’я Service має починатися з літери, — замість того щоб рендерити сервіси, які кластер відхилив би.
Ніщо з цього не є правилом, яке компілятор застосовує з власної ініціативи, — він не містить правил іменування жодної цілі й не вигадує обмежень. Провайдер кожної цілі відповідає за власні імена, тож ім’я відхиляється лише тоді, коли ціль, на яку компонент фактично розгортається, повідомляє, що не може його використати, і відмова містить власну причину цієї цілі та вказує на ключ spec.components, який ви написали. Ім’я, що прийнятне під однією ціллю і відхиляється під іншою, — це очікувана поведінка, а не непослідовність.
Імена, які складає сама Aggrega, — наприклад, ідентичність фічі, прикріпленої на межі, — обробляються навпаки: їх скорочують, щоб вони вмістилися в ціль, а не відхиляють, бо вони збираються з частин, написаних у кількох місцях, і жоден окремий автор не бачить, якої довжини вони досягають. Відхиляється лише ім’я, яке написали ви.
Крапка як зарезервований роздільник шляху
Символ крапки (.) заборонено в усіх іменах екземплярів, які пише користувач. Крапка має структурне призначення: це роздільник шляху, який генерує компілятор для посилань на компоненти між агрегатами.
Коли коренева сутність Aggregate імпортує підагрегат з іменем data-layer, що містить компонент з іменем main-db, компілятор будує сплощений абсолютний ідентифікатор data-layer.main-db, з’єднуючи крапкою ім’я екземпляра агрегату та ім’я екземпляра компонента. Цей шлях із крапкою з’являється в:
- Цілях
usesрозробника:target: data-layer.public_db— посилання на експортований компонент із вкладеного агрегату. - Власній діагностиці збірки: зупинка або попередження щодо цього компонента називає його шляхом із крапкою, тож ім’я, яке ви читаєте, — це те, яке можна шукати у ваших документах.
Роздільник не потрапляє в ім’я
Шлях із крапкою — це адреса всередині ваших документів, і це не ім’я, яке прийме ціль розгортання. Ім’я Kubernetes Service взагалі не допускає крапки; гірше того, крапка в адресі кластера відокремлює сервіс від простору імен, у якому він живе, тож ім’я з крапкою, передане споживачеві як хост, розв’язалося б в інший сервіс замість того, щоб спричинити помилку.
Тому роздільник виписується з кожного імені та мітки, які збірка виводить з ідентичності компонента, і саме виписується, а не замінюється: data-layer.main-db стає data-layer-zdmain-db. Заміна його символом, який ціль приймає, дозволила б двом різним компонентам отримати одне ім’я — data-layer.main-db і компонент, який хтось записав як data-layer-main-db, — а ім’я, до якого приходять два компоненти, не ідентифікує жодного.
На що це поширюється, а на що ні:
- Це поширюється на імена та мітки, виведені з ідентичності, —
metadata.nameресурсу, який синтезує Aggrega, міткиaggrega.ai/component-idіapp.kubernetes.io/name, селектори, що їм відповідають, імена згенерованих файлів,{{ .context.instance_id }}та ім’я, яке провайдер виводить для себе, наприклад ім’я релізу helm. Вони змінюються разом, тож адреса, яку сутність Recipe складає з ключа, що називає ресурс, —.context.instance_id, де ціль називає його за ідентичністю,.context.rendered_name, де ціль повідомляє власне ім’я, — і далі називає ресурс, який генерує збірка. - Це не поширюється на ім’я, яке написали ви. Ім’я компонента без роздільника повертається байт у байт, тож лише компонент, який додає імпортована сутність Aggregate, записано у виводі інакше, ніж у документі.
- Це не поширюється на імена всередині чарта чи фрагмента, які надав автор. Вони належать тому, хто їх написав, і ім’я, перенесене зі стороннього чарта, — ім’я користувацького ресурсу виду
<plural>.<group>, де крапка допустима, — генерується точно так, як його записав цей чарт.
🔴 Останній пункт має наслідок для того, що має публікувати сутність Recipe, і на цій сторінці в цьому найлегше помилитися. Власні шаблони наданого чарта називають свої ресурси за ідентичністю, яку їм передає платформа, — ім’ям релізу, записаним власним алфавітом цієї платформи, а не наведеним вище, — і ціль helm називає синтезовані нею робочі навантаження за тим самим ім’ям релізу. Тому для виводу, відрендереного з наданого вами джерела, і для робочого навантаження, синтезованого під такою ціллю, {{ .context.instance_id }} не є ім’ям цих ресурсів, і адреса, опублікована з нього, нічого не називає щоразу, коли два алфавіти відрізняються. Ключ, що містить ім’я платформи, і те, які провайдери його повідомляють, описано в templates/rendered-resource-names.md.
Виписування роздільника коштує символів, і обмеженому імені їх може забракнути. Роздільник замінюється короткою екрануючою послідовністю, а не одним символом, тож кваліфікована ідентичність у записаному вигляді трохи довша, ніж у ваших документах. Це важить лише там, де ім’я, яким вона стає, обмежене: ціль, що рендерить компонент, вказує, якої довжини значення мітки вона прийме, і якщо записана ідентичність перевищила б це, збірка зупиняється, а не генерує значення, яке ціль відхилила б. Зупинка вказує довжину, у яку має вміститися сама ідентичність, — довжину до виписування, тож ім’я, вибране в її межах, спрацює з першого разу, — а виправлення полягає у скороченні авторських частин: імені, яке імпортувальний документ дає підагрегату, або власного імені компонента в ньому.
Роздільник — звичайна причина, з якої ім’я записується довшим, ніж читається, але не єдина. Дві форми, яких авторське ім’я може законно набувати, також не можна перенести як є, бо їх збереження зробило б екранування неоднозначним: ім’я, що закінчується дефісом, та ім’я, у якому за дефісом одразу йде z. Кожну з них виписують так само, з тією ж ціною. Будь-яке інше авторське ім’я повертається байт у байт, тож ім’я з літер, цифр, підкреслень і дефісів між словами нічого з цього не зачіпає.
Ім’я сокета у власному блоці uses компонента або збігається з ключем у usesSchema сутності каталогу — оголошеним сокетом, — або називає власний ad hoc-сокет розробника, який збирається навіть на сутності, що взагалі не оголошує usesSchema; ім’я, що відрізняється від оголошеного сокета одним редагуванням, спричиняє попередження з обома написаннями. Поребровий uses сутності Release, як і відповідне налаштування приєднання Feature, може називати лише сокет, оголошений сутністю, а будь-яке інше ім’я завершується помилкою валідації unknown-uses-socket.
Регістр полів
DSL розділяє YAML для розробників (який пишуть люди) і внутрішні контракти компілятора (які споживають шаблони та інструменти):
- YAML для розробників (camelCase): багатослівні назви полів у схемах Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest і Plugin використовують camelCase. Приклади:
exportedComponents,syncWave,subDirectory,featuresSchema,usesSchema,valuesMapping,injectMapping,executionScope,appliesTo,appliesToAnyOf,conflictsWith. Відповідає домовленостям Kubernetes API. - Внутрішні контракти (snake_case): багатослівні назви полів у схемі IR Graph і схемі Template Context використовують snake_case. Приклади, з якими стикаються автори сутностей Recipe:
instance_id(у.context.instance_id— ідентичність сутності Recipe),inject_raw(у.inject_raw, стовп верхнього рівня поряд із.inject, а не ключ у.context— незмінений контракт ін’єкції),attachment_name(у контексті приєднуваної сутності FeatureRecipe — визначає слот, який заповнює приєднання, або ім’я, під яким його було приєднано). Відповідає домовленостям JSON API та узгоджується з генерацією JSON-тегів структур у Go. - Однослівні поля: нижній регістр незалежно від контексту. Приклади:
values,infra,inject,provides,locals,features,labels,annotations,boundaries,components,subsystems,pipeline,source.
Розробники не стикаються з snake_case у своєму YAML, а автори шаблонів не стикаються з camelCase у своїх шаблонах Go. Доповнення схем дотримуються цих домовленостей.
Три регістри, що перетинаються в одному виразі
Під час написання сутності Recipe в одному виразі зазвичай перетинаються всі три домовленості щодо регістру: поле DSL, визначене схемою, використовує camelCase, ім’я екземпляра, написане користувачем, — kebab-case або snake_case, а посилання на контекст шаблону — snake_case. Автори, які сприймають ці перетини як окремі домовленості, легко читають отриманий YAML; автори, які намагаються звести регістри до однієї домовленості, плутаються на межах.
Канонічний розібраний приклад: шаблон valuesMapping: сутності Recipe, що посилається на відрендерений екземпляр Component через контекст шаблону.
# Recipe authored against a Component the developer instantiated as "web-server"# (kebab-case instance name) in their Aggregate.spec: valuesMapping: | # camelCase — schema-defined DSL field name: "{{ .context.instance_id }}" # snake_case — template context # internal contract image: "{{ .values.image }}" # snake_case — template context # internal contractТри регістри, один вираз:
valuesMapping— camelCase. Назва поля DSL, яку схема визначає для шаблону зіставлення сутності Recipe. Camel, бо YAML мови для розробників дотримується домовленостей Kubernetes API.web-server(згадується опосередковано через відрендерений компонент) — kebab-case. Ім’я екземпляра, написане користувачем в Aggregate; розробник обрав форму з дефісом. Так само могло б бутиweb_server(snake_case); обидва варіанти допустимі за шаблоном імені екземпляра.instance_id,image— snake_case. Назви полів у контексті шаблону (.context.instance_id,.values.image). Snake, бо IR Graph і контекст шаблону дотримуються домовленостей JSON-API та узгоджуються з генерацією JSON-тегів структур у Go.
Три регістри не взаємозамінні. Автор сутності Recipe, який пише {{ .context.instanceId }} (camelCase), зупиняє збірку: .context оголошує свої ключі, а instanceId не є одним із них, тож посилання відхиляється ще до рендерингу, а діагностика перелічує ключі, які .context визначає, — див. errors/fatal-halts.md «Template references a root the render context does not define (Шаблон посилається на корінь, який контекст рендерингу не визначає)». Розробник, який пише web.server (з крапкою), отримує відхилення за шаблоном імені екземпляра, бо крапку зарезервовано як роздільник шляху. Мета цієї дисципліни: тримати в голові три домовленості під час читання чи написання; покладатися на межі (де саме ви перебуваєте в YAML чи шаблоні), щоб знати, який регістр застосовується.
Ідентифікатори, визначені платформою
Усе викладене вище стосується імен на поверхні авторингу — імені екземпляра, яке ви обираєте, поля схеми, яке мова визначає для заповнення, ключа контексту шаблону, який ви читаєте. Ще два регістри стосуються ідентифікаторів, які визначає сама платформа, а ви лише читаєте або вводите. Вони відокремлені, бо виконують різні завдання, і саме завдання визначає форму.
Описовий регістр: kebab-case, без винятків. Ідентифікатор тут словами описує те, що він називає, тож його можна прочитати й діяти відповідно, нічого не шукаючи. До нього належать прапорець CLI, ідентифікатор правила лінтингу публікації, код класу діагностики та код, під яким зареєстровано умову зупинки.
--no-unsupported-field-warnings # a CLI flag you typecategory-matches-directory # a lint rule id, printed in `aggrega lint` outputunsupported-field # a diagnostic class codeartifact-provenance-skipped # anotherparameter-contract-violation # the code a halting condition is registered underЯкщо клас діагностики має прапорець приглушення, код і прапорець складаються з тих самих слів у тому самому порядку — unsupported-field приглушується прапорцем --no-unsupported-field-warnings, — тож клас, за яким ви зіставляли, підказує потрібний прапорець, і нічого не треба перекладати. Код класу — це стабільне ім’я, за яким інструменти розпізнають знахідку, не розбираючи текст її повідомлення; формулювання повідомлення може покращуватися, код не змінюється.
Регістр коротких кодів: літера E і чотири цифри. Умова зупинки має також короткий код — E0007, — і це єдиний визначений платформою ідентифікатор, що не є kebab-case. Причина — позиція: він стоїть на початку кожної діагностики зупинки, поруч із категорією, перед файлом і рядком, які ви збираєтеся прочитати.
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edgeОписовий код там розмістити не можна. Найдовший із них сам заповнив би вузький термінал ще до розташування, яке вказує, куди дивитися. Тому на початку стоїть ідентифікатор, обраний за шириною, і цей компроміс свідомий: чотири цифри нічого не кажуть про умову, тому кожен короткий код опубліковано поруч з умовою, яку він називає, і текстом, який ця умова виводить, у довіднику сигнальних помилок. Наводьте короткий код у звіті, вводьте його в пошук і з’ясовуйте його значення там.
Обидва регістри називають ті самі умови з двох боків, і жоден не замінює іншого. Зіставляйте описовий код, коли пишете інструмент, що реагує на умову; наводьте короткий код, коли говорите про умову з людиною.
Те, що kebab-case з’являється і тут, і в іменах екземплярів, — не колізія. Шаблон імені екземпляра стосується того, що вам дозволено писати: там допустимі і kebab-case, і snake_case, і команди обирають одне з них. Цей регістр стосується того, що пише сама платформа, де обирати нічого: ви ніколи не обираєте написання ідентифікатора правила лінтингу, а платформа ніколи не обирає написання імені вашого компонента.
Регістр полів він не змінює. Авторські поля схеми залишаються в camelCase, а ключі контексту шаблону — у snake_case. Жоден з ідентифікаторів цього регістру не є полем на жодній із цих поверхонь — це короткі стабільні імена прапорця, правила або класу знахідки, — тож те, що код діагностики записано в kebab-case, нічого не каже про написання поля схеми.
Дисципліна суфіксів у назвах шляхів у документі
Частина полів мови містить значення шляхів у документі — рядки, що вказують на позицію всередині іншого документа (розділ томів відрендереного Workload, запис featuresSchema сутності Component, рівень mappings сутності Manifest). Значення відповідають синтаксису RFC 6901 JSON Pointer — токенам, розділеним скісними рисками, що визначають шлях у цільовому документі.
RFC 6901 — базова граматика шляхів для кожної поверхні шляхів у документі в Aggrega. Контракт Wasm плагінів споживає документи JSON Patch за RFC 6902, шляхи в яких є вказівниками RFC 6901 (згідно з plugins/plugin-contract.md, вивід JSONPatch ролі label-transform); перелік рядків формату в граматиці URI називає RFC 6901 поряд із синтаксисом шаблонів Go та допоміжними функціями Sprig (згідно з vocabulary/uri-grammar.md, «Перелік рядків формату»); експорти .locals кожного Recipe використовують RFC 6901, щоб вказувати на позиції в синтезованому Workload, які плагіни Wasm Injector отримують у конвеєрі плагінів через корисне навантаження with свого кроку. Одна граматика, кілька поверхонь-споживачів.
Дисципліна суфіксів у назвах розрізняє дві сторони створення цих значень шляхів через навмисний поділ суфіксів, узгоджений із ширшим розділом про регістр полів вище:
- Поля схеми, що містять RFC 6901 JSON Pointers, використовують суфікс camelCase
*Path. Ці поля є частиною YAML-схеми для розробників, тому дотримуються домовленості camelCase. Жодна схема сутності не оголошує такого поля; шляхи в документі, які пише автор, — це ключі експорту.locals, описані нижче. - Ключі експорту
.locals, що містять RFC 6901 JSON Pointers, використовують суфікс snake_case*_path. Ці ключі є частиною внутрішньої поверхні експорту сутності Recipe — їх читають наступні шаблони самого Recipe, а також конвеєр Wasm плагінів через корисне навантаженняpipeline[].with, що посилається на.locals, — тому вони дотримуються домовленості snake_case. Приклади:volumes_path—.locals.volumes_path: "/spec/template/spec/volumes"відкриває позицію масиву томів синтезованого Workload.containers_path—.locals.containers_path: "/spec/template/spec/containers"відкриває позицію масиву контейнерів.resource_path—.locals.resource_path: "/resource/aws_s3_bucket/main"відкриває нативний для Terraform шлях ресурсу.root_path—.locals.root_path: "/data"відкриває кореневий шлях, який споживає конвеєр рендерера.
Дві домовленості щодо суфіксів відображають дворівневу домовленість розділу про регістр полів: поля, визначені схемою, використовують camelCase; ідентифікатори, створені користувачем або приватні для Recipe, використовують snake_case (або kebab-case). Дисципліна суфіксів *Path / *_path робить граматичну природу шляху у значенні видимою на рівні ідентифікатора — читач, бачачи будь-який із суфіксів, знає, що значення відповідає синтаксису RFC 6901, без потреби перевіряти саме значення.
Розібраний приклад: Wasm Injector, що споживає експорти *_path сутності Recipe.
# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumesspec: locals: primary_compute: "worker-container" containers_path: "/spec/template/spec/containers" volumes_path: "/spec/template/spec/volumes"# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe# above realizes. Its templates read `.locals`: an attachment sees the host# Recipe's resolved locals merged with the attachment's own block.spec: pipeline: - id: workload_injector plugin: pipeline-step/k8s-workload-injector:2.0.0 function: inject_secret with: | target_container: "{{ .locals.primary_compute }}" containers_path: "{{ .locals.containers_path }}" volumes_path: "{{ .locals.volumes_path }}"Ключі *_path — це приватні експорти Recipe; значення containers_path / volumes_path — рядки RFC 6901 JSON Pointer. Плагін Injector споживає ці рядки, щоб позиціонувати свій вивід JSONPatch відносно AST відрендереного Workload. Прикріплення отримує їх зі свого власного стовпа .locals — поля .context.uses[].locals немає, тож споживач не може читати locals своєї цілі через ребро uses; через ребро переходить provides цілі.
Ширший перелік рядків формату (синтаксис шаблонів Go, функції Sprig, JSON Pointer поряд із регулярними виразами SemVer і граматикою селекторів міток) див. у vocabulary/uri-grammar.md, «Перелік рядків формату». Поверхню контракту Wasm плагінів, що споживає патчі RFC 6902, адресовані вказівниками RFC 6901, див. у plugins/plugin-contract.md.
Синтаксис коментарів
Символи коментарів залежать від навколишньої мови:
- Контекст YAML (типова поверхня авторингу для кожної сутності Aggrega): використовуйте
# - Контекст шаблонів Go (усередині блокових скалярів
valuesMapping:у Recipe, блокових скалярівinjectMapping:у FeatureRecipe, записів зіставлення в MappingLibrary, тілassertions:у блоках перевірок): використовуйте{{/* ... */}}для коментарів шаблону, які рушій шаблонів розпізнає та вилучає під час рендерингу, або#для коментарів рівня YAML поза тілом шаблону.
Компактні схеми в schema:, usesSchema:, featuresSchema: і parameters: повністю є YAML; анотація description: для кожного поля — це задокументована поверхня для вбудованого документування полів (port: { type: integer, description: "TCP listen port" }).