Приклади для запуску
Для початку Початок роботи встановлює 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.