Справочник по языку
«Что» и «как использовать» в Aggrega. Синтаксис, вызов CLI, каталог ошибок, разобранные примеры.
При первом знакомстве читайте главы ниже по порядку. Справочные подкаталоги перечислены под своими главами — переходите к ним напрямую, когда ищете конкретную сущность, ключевое слово, провайдер, команду CLI или ошибку.
Прежде чем читать главы по порядку, ознакомьтесь с разделом Состояние языка, чтобы узнать текущую степень готовности: какие возможности языка доступны уже сегодня, какие принимаются, но пока не обрабатываются компилятором, и какие запланированы на будущие итерации. Раздел Совместимость определяет, что выпуск обещает в отношении схем, командной строки, инструментов ассистента, кодов ошибок и наборов для разработки плагинов.
Модель уровней сущностей
Виды сущностей для авторинга в Aggrega организованы в три уровня, отражающих последовательность освоения (см. ниже). Рядом с ними стоит принадлежащая платформе сущность Workload, которая не является самостоятельным видом для авторинга: это форма, которую принимают синтезированные входные данные сущности Recipe, выражающая форму вычислений через словарь form: (stateless, stateful, daemon, scheduled, task, reference). Деление на уровни — это механизм документации и знакомства с языком, а не ограничение времени выполнения: каждый вид сущностей — полноправный элемент языка; компилятор обрабатывает их единообразно; Aggrega с открытым исходным кодом поддерживает все уровни без лицензирования и без ограничения функциональности. Отметки уровней означают «продвинутое; пропустите, если не нужно» для навигации, а не для возможностей.
| Уровень | Виды сущностей | Когда осваивать |
|---|---|---|
| Уровень 1 — минимально достаточный набор | Aggregate, Component, Recipe, Manifest, Release | День 1 — основатели-одиночки и небольшие команды выпускают работающее ПО, используя только уровень 1. Ментальная модель: «У меня есть приложение; я хочу его развернуть; вот как это сделать». |
| Уровень 2 — разделение ролей | Feature, FeatureRecipe, Plugin | День 30 — небольшие команды, в которых роли разделяются (разработчик + Ops + иногда безопасность). Уровень 2 появляется через сущности Plugins для рендеринга провайдеров (Ops выбирают между Helm, helm-chart, Compose, Terraform и CloudFormation), сущности Features (безопасность управляет учётными данными отдельно от конфигурации приложения) и сущности FeatureRecipes (настройка в момент привязки для каждого провайдера). |
| Уровень 3 — повторное использование между сущностями Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | День 365 — зрелые каталоги, в которых общие формы повторяются во многих сущностях. Порог неформален: когда форма (например, PodResources) встречается в 5+ сущностях Components и согласование обновлений становится обременительным, запись в SchemaLibrary себя оправдывает. |
Каждый шаг освоения добровольный. Основателя-одиночку никогда не заставляют разбираться с уровнем 3; корпоративный каталог имеет полный доступ к уровню 3 по мере необходимости. Уровень 1 полон для сценария основателя-одиночки: разработчик может выпускать работающие приложения, используя только сущности уровня 1. Это важное свойство дизайна: уровень 1 — не «подмножество, которое компилируется», а «подмножество, с которым выпускают ПО».
Набор уровня 1 из пяти сущностей требует начальных затрат: Aggregate + Component + Recipe + Manifest + Release — это больше формальностей, чем «положи YAML-файл и получи работающий сервис». Эти затраты — цена разделения авторинга на четыре домена (намерение разработчика / каталог платформы / эксплуатация платформы / маршрутизация), которое отличает Aggrega от чистого Helm или чистого Terraform. Учебные руководства уровня 1 явно разбирают настройку из пяти сущностей.
Внутри уровня 3 механизм spec.templates / $instantiate: (параметрические вспомогательные шаблоны в SchemaLibrary) описан как ещё более продвинутая подфункция. Большинство осваивающих уровень 3 поначалу не прибегают к spec.templates; порог — «когда в вашей библиотеке 6+ схем с общей параметризованной структурой».
Порядок чтения
- Как пользоваться этим справочником
- Соглашения об именовании
- Обзор справочника сущностей
- Уровень 1: aggregate, component, recipe, manifest, release
- Уровень 2: feature, featurerecipe, plugin
- Уровень 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Сквозные: workload (вид компилятора, принадлежащий платформе и используемый внутри
workload:сущности Recipe)
- Обзор словаря
- Справочник словаря: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Обзор шаблонов
- Справочник шаблонов: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Обзор сущностей Providers
- Справочник по сущностям Providers: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Обзор CLI
- Справочник CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import и файл ответов импорта, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Обзор ошибок
- Справочник ошибок: fatal-halts, warnings, sentinels, error-translation
- Обзор примеров
- Справочник примеров: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; запускаемые рабочие пространства: Запускаемые примеры
Справочник по разработке Plugin
Интерфейс плагинов Wasm располагается рядом с последовательностью глав, а не внутри неё: автор плагина читает его независимо от пути написания сущностей. Страница сущности plugin описывает интерфейс написания каталога; страницы ниже описывают сокеты, полезные нагрузки и рабочий процесс автора.
- plugin-contract — сокеты, к которым подключается плагин, их место в конвейере и формы входных и выходных данных каждого сокета.
- plugin-developer-guide — сквозной рабочий процесс автора:
describe(), заявления о возможностях, ограничения среды выполнения, жизненный цикл publish/pull/build, подписание, версионирование. - policy-socket — подробно о сокете управления: его четыре роли, уровни серьёзности вердиктов, канал входных данных оператора и написание политики для любого из движков, поставляемых в составе компилятора.
- governance-attachment-facts — факты по каждому подключению, которые политика управления считывает из графа сборки, включая три единицы маркировки чувствительности и причину, по которой отсутствие маркировки не является разрешением.
- when-to-use-a-pipeline-step — выбор между шагом конвейера и шаблонной FeatureRecipe.
- embedded-plugins — плагины, поставляемые в составе исполняемого файла компилятора.
- tagging-plugins — два встроенных плагина управления, которые записывают метки без политики,
governance/label-injectorиgovernance/selector-tagger: их настройки и то, что записывает каждый из них. - core-importers — десять импортёров компилятора, от Langflow, Flowise и n8n до Compose, MCP и фреймворков агентов: что каждый из них читает и какие черновики составляет, их настройки и их публикация с каждым выпуском компилятора.
- authoring-a-provider-walkthrough — пошаговый разбор создания гостевого модуля провайдера: от пустого каталога до сборки, записывающей файлы, которые отрендерил провайдер.
- writing-a-governance-plugin — написание собственного плагина управления на основе каркаса адаптера из набора для плагинов: одно правило, ручной запуск экспорта каждой роли, сущность
Pluginв каталоге рабочего пространства и сборка, которую плагин отклоняет. - compatibility — как версионируются наборы для разработки плагинов: что могут изменить патч-выпуск и минорный выпуск набора и что позволяет уже собранному плагину продолжать загружаться.