Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Соглашения об именовании

В этой главе описаны правила именования и регистра, применяемые к содержимому, которое вы пишете для 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 не будет незаметно заменять такой символ на похожий: два имени, которые автор может различить, не должны превращаться в одно имя в кластере. Поэтому недопустимый для платформы символ записывается в виде экранирующей последовательности, а она длиннее заменяемого символа.

Практическое следствие: в одних целевых платформах заглавная буква ничего не стоит, в других обходится дорого.

  • В целевой платформе, имена которой допускают заглавные буквы, — например, в compose-файле оркестрации контейнеров — PaymentsAPI передаётся ровно так, как вы его написали, и занимает одиннадцать символов.
  • В целевой платформе, имена которой допускают только строчные буквы, — например, в имени релиза установщика чартов — каждая заглавная буква экранируется, и имя из одних лишь шести заглавных букв уже превышает допустимую для этой платформы длину.

Есть и второй эффект, более серьёзный: экранирующая последовательность начинается с дефиса. Поэтому целевая платформа, требующая, чтобы имя начиналось со строчной буквы или цифры, отвергнет имя, первый символ которого для неё недопустим, какой бы короткой ни была остальная часть, — никакое сокращение этого не исправит.

Рекомендации следуют из этих двух эффектов. Используйте строчные буквы и цифры, разделяя слова дефисами, и начинайте имя со строчной буквы. payments-api передаётся без изменений всеми целевыми платформами, для которых Aggrega поставляет провайдер. payments_api передаётся compose-файлом, но не целевой платформой helm, имена ресурсов которой не допускают подчёркивания: сервисы, рабочие нагрузки и релиз, названные по компоненту, записываются как payments-zuapi. PaymentsAPI там обходится ещё дороже. Сущность Recipe, публикующая адрес такого ресурса, считывает собственное написание целевой платформы, а не предугадывает его, — см. templates/rendered-resource-names.md.

Начальная цифра допустима при написании и ничего не стоит в compose-файле, но целевая платформа helm её отвергает. Имя сервиса Kubernetes должно начинаться с буквы, а сервисы, создаваемые чартом или синтезированной рабочей нагрузкой, называются по компоненту, поэтому компонент с именем 1cache останавливает сборку helm — в сообщении об отказе называется компонент и указывается, что имя сервиса должно начинаться с буквы, — вместо того чтобы отрисовать сервисы, которые кластер отверг бы.

Ничто из этого не является правилом, которое компилятор применяет по собственной инициативе: он не хранит правил именования ни одной целевой платформы и не придумывает ограничений. Провайдер каждой целевой платформы отвечает за её собственные имена, поэтому имя отвергается только тогда, когда платформа, на которую компонент действительно развёртывается, сообщает, что не может его использовать, и отказ содержит собственную причину этой платформы и указывает на написанный вами ключ spec.components. Имя, допустимое в одной целевой платформе и отвергаемое в другой, — ожидаемое поведение, а не несогласованность.

С именами, которые составляет сама Aggrega, — например, с идентификатором функции, присоединённой на границе, — поступают наоборот: их сокращают под целевую платформу, а не отвергают, поскольку они собираются из частей, написанных в разных местах, и ни один автор не видит, какой длины они достигают. Отвергается только имя, написанное вами.

Точка как зарезервированный разделитель пути

Символ точки (.) запрещён во всех пользовательских именах экземпляров. Точка выполняет структурную роль разделителя пути, генерируемого компилятором, для ссылок на компоненты из других агрегатов.

Когда корневая сущность Aggregate импортирует вложенный агрегат с именем data-layer, содержащий компонент с именем main-db, компилятор строит плоский абсолютный ID 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 type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-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, ничего не говорит о написании поля схемы.

Дисциплина суффиксов в именах путей внутри документа

Ряд полей в языке содержит значения-пути внутри документа — строки, указывающие на позицию внутри другого документа (раздел volumes отрендеренной сущности Workload, запись featuresSchema сущности Component, уровень mappings сущности Manifest). Значения следуют синтаксису RFC 6901 JSON Pointer — токены, разделённые косой чертой, которые задают путь по целевому документу.

RFC 6901 — базовая грамматика путей для всех поверхностей путей внутри документа в Aggrega. Контракт плагинов Wasm принимает документы JSON Patch по RFC 6902, пути в которых являются указателями RFC 6901 (см. вывод JSONPatch роли label-transform в plugins/plugin-contract.md); перечень форматных строк грамматики URI называет RFC 6901 наряду с синтаксисом шаблонов Go и хелперами Sprig (см. раздел «Format-string inventory» в vocabulary/uri-grammar.md); экспорты .locals каждой сущности Recipe используют RFC 6901, чтобы указывать на позиции в синтезированной сущности Workload, которые плагины Wasm Injector получают в конвейере плагинов через полезную нагрузку with своего шага. Одна грамматика, несколько потребляющих поверхностей.

Дисциплина суффиксов в именах различает две авторские стороны этих значений-путей с помощью намеренного разделения суффиксов, согласованного с более общим разделом о регистре полей выше:

  • Поля схемы, содержащие JSON Pointer по RFC 6901, используют суффикс camelCase *Path. Эти поля входят в YAML-схему, с которой работает разработчик, поэтому следуют соглашению camelCase. Ни одна схема сущности не объявляет такого поля; пути внутри документа, которые пишет автор, — это ключи экспорта .locals, описанные ниже.
  • Ключи экспорта .locals, содержащие JSON Pointer по RFC 6901, используют суффикс snake_case *_path. Эти ключи входят во внутреннюю поверхность экспорта сущности Recipe — их читают последующие шаблоны самой сущности Recipe, а также конвейер плагинов Wasm через полезную нагрузку pipeline[].with, ссылающуюся на .locals, — поэтому они следуют соглашению snake_case. Примеры:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" открывает позицию массива volumes синтезированной сущности Workload.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" открывает позицию массива 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 consumes
spec:
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 — строки JSON Pointer по RFC 6901. Плагин Injector использует эти строки, чтобы позиционировать свой вывод JSONPatch относительно AST отрендеренной сущности Workload. Подключение получает их на собственной опоре .locals — поля .context.uses[].locals нет, поэтому потребитель не может прочитать locals своей цели через ребро uses; через ребро передаётся provides цели.

Более полный перечень форматных строк (синтаксис шаблонов Go, функции Sprig, JSON Pointer наряду с регулярным выражением SemVer и грамматикой селекторов меток) см. в разделе «Format-string inventory» в 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" }).