Запускаемые примеры
Для начала Начало работы устанавливает Aggrega и шаг за шагом проводит через два из этих примеров.
Полные рабочие пространства, которые можно форкнуть и скомпилировать с помощью CLI aggrega. Каждое из них — самодостаточный каталог (написанный разработчиком Aggregate и одна или несколько пар Release/Manifest), который собирается без какой-либо настройки сверх той, что указана на его странице. Чтобы найти пример по развёртываемому продукту или по тому, что он показывает, воспользуйтесь страницей Примеры по продуктам и возможностям, где перечислены все примеры отсюда.
Примеры бывают двух режимов — это два конца одной учебной программы:
-
Потребление — рабочее пространство ссылается на сущности каталога стандартной библиотеки и локально описывает только собственное учебное содержимое. Оно собирается без флага
--catalog:Terminal window aggrega build --release release.yamlОткуда читаются эти сущности, зависит от рабочего пространства. Каталог
catalog/в корне рабочего пространства читается независимо от того, указан ли он где-либо, поэтому рабочее пространство с собственным учебным содержимым может просто хранить его там. Рабочее пространство, содержащее.aggrega-config.yaml, также читает все каталоги, перечисленные вcatalog_dirs, и каждый из них — каталог, в котором оно хранит сущности. Перечисленные каталоги просматриваются первыми, аcatalog/— последним; побеждает первое найденное, поэтому сущность из каталога, просмотренного раньше, затеняет сущность с тем же идентификатором из более позднего. То, чего не объявляет ни один локальный каталог, — сущности стандартной библиотеки — разрешается из реестра, который конфигурация называет какdefault_registry, то есть изhub.aggrega.ai. Рабочему пространству, которое ничего не описывает локально, локальная запись не нужна, а рабочее пространство без каталогаcatalog/и без.aggrega-config.yamlразрешает всё через настроенный реестр. Пустой список вcatalog_dirsозначает, что у рабочего пространства вовсе нет локального каталога. Каждый путь вcatalog_dirsуказывает на каталог внутри рабочего пространства, поэтому копия всего рабочего пространства, перенесённая в другое место, собирается как есть.Рабочее пространство с несколькими целями, хранящее отдельный каталог для каждой цели, перечисляет директории каждой цели в
workspace.releasesс ключом по файлу сущности Release, так что каждая сущность Release собирается со своим каталогом. -
Создание — рабочее пространство строит сущности каталога (Components, Features, Recipes) с нуля в локальных каталогах
catalog-*/.mariadb-adminer— разобранный пример создания; сущности, которые он строит, того же рода, что и потребляемые в примерах потребления.
За один запуск собирайте один релиз командой aggrega build --release <release file>; страница каждого примера приводит его собственные команды. Рабочее пространство предоставляет свой каталог, как описано выше; для каталога, который рабочее пространство не называет, передайте --catalog сами, как показывают страницы, которым это нужно.
Lock-файлы генерируются, а не поставляются, поэтому в свежем клоне их нет, и первой сборке он нужен. aggrega build по умолчанию работает только на чтение: без lock-файла он останавливается и называет два возможных пути. Для первой сборки передайте --auto-pull — aggrega build --release release.yaml --auto-pull, — чтобы разрешить lock-файл во время сборки; однократный запуск aggrega pull --release <release file> заранее делает то же самое и позволяет всем последующим сборкам выполняться без флага.
В рабочей копии репозитория документации большинство рабочих пространств также содержит вспомогательный скрипт build-release.sh, через который собирают собственные проверки репозитория. Он запускает aggrega build для одного релиза, сначала выводя команду, и сообщает, какой двоичный файл aggrega использовал и откуда этот файл взят; чтобы выбрать двоичный файл, задайте AGGREGA_BIN. Копия, записанная aggrega scaffold --example, содержит вспомогательный скрипт, но без общего скрипта, который он вызывает, поэтому такую копию собирайте напрямую командой aggrega build.
Если пример здесь упоминает рабочую копию каталога стандартной библиотеки, то Импорт объясняет, где её взять.
Они дополняют концептуальные страницы, описанные в Обзоре примеров: концептуальная страница объясняет одну идею и ссылается на рабочее пространство, которое её показывает; рабочие пространства здесь — целые стеки, которые можно собрать, прочитать и адаптировать.
Там, где страница приводит результат сборки, этот блок скопирован из реального запуска, чтобы вы могли сравнить с ним свой вывод, а все пропущенные строки помечены. Чтение вывода на этих страницах описывает это соглашение и используемую пометку.
Не каждый каталог здесь — это одно рабочее пространство. Примеры быстрого старта содержат по одному рабочему пространству на шаг, а примеры импорта — по одному на этап импорта, как описано в следующем абзаце. Один каталог вовсе не содержит рабочего пространства: policy-in-ci содержит два скрипта правил, которые читают выходной каталог сборки и отклоняют его, если он нарушает правило, и шаг конвейера для каждого. Они запускаются на выводе рабочих пространств здесь и на вашем.
Каждый пример import-* — они перечислены под возможностью import в Примерах по продуктам и возможностям — хранит проект, написанный в другом формате, в том виде, в каком его получает aggrega import, в двух папках: source/ — проект, .aggrega-config.yaml, который делает его рабочим пространством, и файл ответов, из которого импорт читает значения, которые не может содержать ни один источник; и draft/ — файлы, записанные импортом, без изменений, рабочее пространство, которое собирается в записанном виде, вместе с тем, что импорт вывел в стандартный вывод (stdout.txt) и стандартный поток ошибок (import.txt). Его пошаговое руководство в разделе Импорт объясняет каждый этап. Его check.sh запускает общий для этого репозитория scripts/check-import-example.sh, который снова выполняет импорт, сравнивает то, что он записывает и выводит, с draft/, а блоки, которые цитирует руководство, — с файлами примера, после чего проверяет и собирает подготовленную сущность Release.
Порядок обучения
У каждого примера здесь есть одно место в едином порядке обучения, заданное tier и position в его заголовке: уровень за уровнем, в порядке, который задаёт список уровней, и от простого к сложному внутри каждого уровня. В порядке обучения перечисляет так каждый пример, и раздел Примеры боковой панели следует тому же порядку. Читайте уровни сверху вниз или переходите к тому, который соответствует тому, что вы делаете; чтобы вместо этого найти пример по тому, что он развёртывает или что показывает, та же страница перечисляет примеры по продукту и по возможности.
Сборка также может запускать плагины над тем, что она отрисовывает, — см. Когда прибегать к шагу конвейера.
Заголовок каждого примера
README каждого примера начинается с короткого заголовка, записанного как front matter YAML, который говорит, что представляет собой пример: его уровень, его место в порядке обучения, развёртываемые им продукты и то, что он показывает. Страница Примеры по продуктам и возможностям генерируется из этих заголовков.
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level — один из этих уровней:
start— уровень «Только каталог»: собран из сущностей каталога, и написаны только Aggregate, Manifest и Release.authoring— уровень «Создание»: создаёт Component, Feature или Recipe либо показывает, как они устроены.advanced— уровень «Продвинутый»: границы, политика управления, Features на основе аннотаций и собранные облачные стеки.
tier — часть порядка обучения, к которой относится пример, одна из этих групп, изучаемых в таком порядке:
start-here— Начните здесь: два примера, которые руководство «Начало работы» развивает шаг за шагом, а затем два стартовых примера для облака.catalog-only— Только каталог: собран из сущностей каталога, и не написано ничего, кроме сущностей Aggregate, Manifest и Release.authoring— Создание: пишет собственную сущность Component, Feature или Recipe либо показывает, как такая сущность устроена.advanced— Продвинутый: границы, политики управления, Features, управляемые аннотациями, и собранные облачные стеки, несколько из которых объединены в одной сборке.importers— Импортеры: проект, написанный в другом формате, преобразованный командойaggrega importв черновики файлов Aggrega, затем проверенный и собранный.
position — место примера внутри его группы, положительное целое число, которое не занимает ни один другой пример этой группы; группа перечисляет свои примеры от наименьшей позиции вверх, начиная с самого простого.
products перечисляет каждый Component каталога, который развёртывает пример, по имени, которое носит его запись в каталоге. Универсальный вычислительный компонент (скажем, core/compute/server) и сущность, которую пример объявляет для себя, не перечисляются, поэтому пример может не перечислять ничего.
shows перечисляет то, что демонстрирует пример; каждая запись берётся из этого списка:
multi-target— один Aggregate, собранный для двух или более целей или реализованный двумя или более способами.recipe-selection— Manifest выбирает, какой Recipe реализует компонент или какой FeatureRecipe реализует присоединение: по типу, по экземпляру или по цели.modules— Aggregate из каталога, импортированный как модуль.connections— компоненты, соединённые через сокетыuses, со значениями, передаваемыми по каждому ребру.credentials— присоединения учётных данных и то, как каждая цель их доставляет.parameters— значения, поднятые в параметры, которые заполняет Release.features— Features, присоединённые не для учётных данных, а, например, для маршрутизации, мониторинга, бюджета, кэша или маскирования.boundaries— компоненты или модули, размещённые в границах, и то, что пересекает границы между ними.policy— политика управления, которая принимает или отклоняет сборку во время сборки или по её выводу.guardrails— Release, который должен остановиться, и сообщение, с которым он останавливается.catalog-authoring— Component, Feature или Recipe, написанные для примера и хранящиеся рядом с ним или опубликованные в каталоге.cloud-infrastructure— вывод Terraform или CloudFormation для управляемых облачных сервисов.external-sources— Recipe, который загружает то, что отрисовывает: вышестоящий чарт, git-репозиторий или модуль.import— проект, написанный в другом формате, преобразованный командойaggrega importв черновики файлов Aggrega, а затем проверенный и собранный.
Пример перечисляет как минимум один продукт или одну возможность, чтобы индекс мог его разместить. Его README также содержит раздел ## Scaffold the example с aggrega scaffold --example <name> в первом блоке команд и cd <name> во втором, за которым сразу следует раздел ## Build, первый блок команд которого — это то, что aggrega scaffold --example выводит как следующий шаг для запуска после этой команды cd. scripts/gen-examples-index.sh --check, запускаемый из корня этого репозитория, проверяет каждый заголовок по этим спискам, отклоняет пример, в котором нет любого из двух разделов, а также пример, у которого нет ни исполняемого check.sh, ни build-release.sh, и подтверждает, что индекс актуален; чтобы записать индекс заново, запустите его без --check.