MariaDB + Adminer — робочий приклад із двома цільовими платформами
Цей приклад компілює невеликий реальний стек — базу даних MariaDB з вебінтерфейсом Adminer перед нею — з одного написаного розробником Aggregate для двох платформ:
- Docker Compose для локальної розробки та
- Kubernetes для локального кластера (kind / minikube / k3d), відрендерений трьома способами.
Обидві керуються одним і тим самим Aggregate. Змінюються лише Release, його Manifest і шар сутностей Recipe, завантажений під час збирання. Кожен файл тут компілюється за допомогою CLI aggrega, що постачається, а згенерований результат працює: запустіть стек, відкрийте Adminer у браузері й увійдіть до робочої бази даних.
aggregate.yamlнаписано один раз
На ноутбуці
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlУ кластері Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildМаніфести Kubernetes
Кожну платформу збирають із її власних сутностей Release і Manifest. Сутність Aggregate, яка описує ваш застосунок, залишається тією самою.
Що демонструє приклад
- Одна поверхня авторства, багато цілей. Єдиний
aggregate.yamlє джерелом істини про те, що являє собою стек. Кожна ціль — це тонкий шар каталогу, який визначає, як його реалізувати. - String Pipe. Adminer оголошує використання
databasesдля MariaDB; значенняprovides.hostсутності Recipe бази даних передається в змінну середовищаADMINER_DEFAULT_SERVERAdminer. Компілятор маршрутизує рядок, не інтерпретуючи його, тож збірка compose підставляє ім’я сервісу compose, а збірка Kubernetes — DNS-ім’я Service, з одного й того самого ребра. - Синтез робочих навантажень. Recipes для compose і для самодостатнього Kubernetes
оголошують
Workload, агностичний щодо можливостей; провайдер синтезує сервісdocker-compose.yamlабо ті об’єкти Kubernetes, яких вимагаєformсутності Workload:DeploymentіServiceдля веб-інтерфейсу без стану, а для бази даних ізform: stateful—StatefulSet, шаблон запиту тому якого для кожної репліки містить каталог даних, поряд із HeadlessService, що ним керує, іClusterIPService, до якого звертаються споживачі. - Підсистема облікових даних. Паролі бази даних приєднуються в розділі
features:компонента — кожен якFeatureз міткоюfeature.aggrega.ai/kind: secret, окремо відvaluesзастосунку. ПолеfeaturesSchemaсутності Component оголошує два види слотів, і приклад використовує обидва: слот «чорна скринька», значення якого FeatureRecipe постачає внутрішньо, і прозорий слот, значення якого розробник постачає явно блокомinject:у приєднанні. - Віддалені джерела чартів. Керована ціль Kubernetes отримує upstream-чарт
Bitnami MariaDB за посиланням OCI.
aggrega pullфіксує чарт у lock-файлі та завантажує його в кеш з адресацією за вмістом;aggrega buildрендерить з цього кешу, тож під час блокування і під час збірки визначається той самий чарт. Версія чарта береться зinfra.source_versionоператора, якщо Release її фіксує, а інакше — зі значення, створеного розробником (значення, що потрапляє у визначення джерела). Lock-файли для кожного релізу фіксують ідентичності та дайджести сутностей: після перейменування сутностей каталогу або зміни їхнього вмісту оновіть застарілий локальний lock-файл командоюaggrega pull --release release-<variant>.yaml. Кожен варіант релізу визначається відносно власного сусіднього каталогу, який.aggrega-config.yamlвказує для нього вworkspace.releases, тож--catalogне потрібен ні в терміналі, ні в редакторі, ні через асистента. - Походження як анотації. Кожен відрендерений об’єкт Kubernetes має
анотацію
aggrega.ai/recipe-uri, що фіксує Recipe, який його створив, — саме анотацію, а не мітку, бо значення URI містить символи, неприпустимі у значенні мітки Kubernetes. - Композиція чартів (на відміну від синтезу). Той самий Aggregate може створити
придатний для поширення чарт Helm замість відрендерених маніфестів. Провайдер
helm-chartкомпонує парасольковий чарт: локальний підчарт кожного компонента копіюється дослівно (його конструкції Helm{{ }}лишаються незмінними), аvalues.yamlпарасолькового чарта маршрутизує зіставлені значення кожного компонента, зокрема переданий хост бази даних, під псевдонімом цього компонента. - Вибір Provider за типом компонента. Recipe, що рендерить кожен компонент, — це та, з якою Manifest цілі зіставляє тип цього компонента; її взято з того шару каталогу, який завантажує збірка.
Створення і використання — змішаний робочий простір
Цей приклад працює з обома кінцями каталогу одночасно: деякі сутності він створює локально, а інші використовує зі стандартної бібліотеки Aggrega. Сутність Component бази даних MariaDB, її сутності Features для облікових даних і Recipes для кожної цілі створено з нуля в локальних каталогах catalog-*/ — одна сутність Aggregate рендерить цю локально створену базу даних для чотирьох цілей. Вебінтерфейс Adminer, натомість, використовується: компонент web безпосередньо посилається на постачену сутність Component core/devtool/adminer, і кожна ціль створює лише локальну сутність Recipe, яка її реалізує. Тож той самий робочий простір показує створення сутностей на боці бази даних поруч із використанням каталогу на боці інтерфейсу. Сутності, які ви тут створюєте, належать до того самого типу, що й сутності стандартної бібліотеки: сутність Component бази даних, сутності Features для облікових даних, сутності Recipes провайдерів.
Приклад catalog-only розташований на кінці чистого використання тієї самої навчальної програми: він збирає саме цей стек — базу даних MariaDB з інтерфейсом Adminer — через посилання на сутності стандартної бібліотеки, не створюючи жодної власної. Прочитайте частину цього прикладу про базу даних, щоб дізнатися, як сутності каталогу створюються; прочитайте приклади використання, щоб дізнатися, як цілий стек використовується з постаченого каталогу.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example mariadb-adminerПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd mariadb-adminerЗбирання
Кожна ціль — це одна сутність Release, яку збирають по одній за запуск; pull записує lockfile, який читає збірка. Спершу Docker Compose — розділ кожної цілі нижче наводить власні команди:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlЗ ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `mariadb-adminer`, викличте один раз інструмент `scaffold`, задавши для `example` значення `mariadb-adminer`, без `dir`: він запише приклад у нову теку `mariadb-adminer`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `mariadb-adminer`, для `release` — `release-compose.yaml`, для `auto_pull` — true і для `write` — true. Скажіть, які файли записала збірка; вони розташовані в `mariadb-adminer/dist/`.Структура
mariadb-adminer/├── aggregate.yaml # Developer intent — shared by every target│├── manifest-compose.yaml # Ops mapping, Docker Compose target├── release-compose.yaml # Operator release, Docker Compose target├── catalog-compose/ # Recipe layer: compose│├── manifest-helm-synth.yaml # Ops mapping, self-contained Kubernetes target├── release-helm-synth.yaml # Operator release, self-contained Kubernetes target├── catalog-helm-synth/ # Recipe layer: helm (Workload synthesis)│├── manifest-helm-bitnami.yaml # Ops mapping, managed-chart Kubernetes target├── release-helm-bitnami.yaml # Operator release, managed-chart Kubernetes target├── catalog-helm-bitnami/ # Recipe layer: helm (upstream Bitnami chart)│├── manifest-helm-chart.yaml # Ops mapping, composed-Helm-chart target├── release-helm-chart.yaml # Operator release, composed-Helm-chart target└── catalog-helm-chart/ # Recipe layer: helm-chart (umbrella composition)Кожен каталог catalog-* містить локально створені визначення сутностей Component і Feature для MariaDB, а також Recipes для однієї цієї цілі. Сутності Component для Adminer серед них немає — вона розв’язується зі стандартної бібліотеки. Збірка завантажує один шар catalog-* поверх цієї стандартної бібліотеки, а Manifest цілі зіставляє кожен тип компонента з сутністю Recipe у цьому шарі.
Сутність Release, її aggregate: і її manifest: лежать поруч у цьому
каталозі; каталог, з яким збирається кожна сутність Release, указано для неї у
.aggrega-config.yaml.
Спільна сутність Aggregate
spec: components: db: type: core/datastore/mariadb values: database: appdb user: appuser charset: utf8mb4 collation: utf8mb4_general_ci chart_version: "25.0.8" # the managed-chart target's chart, absent an operator pin features: root_password: # black-box slot: the FeatureRecipe delivers it type: core/secret-value values: { key: MARIADB_ROOT_PASSWORD, origin: dev-root-pw-change-me } user_password: # transparent slot: the developer delivers it type: core/secret-provided values: { origin: dev-app-pw-change-me } inject: env: [{ in: MARIADB_PASSWORD, from: value }]
web: type: core/devtool/adminer values: design: pepa-linha-dark uses: databases: db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: hostweb оголошує використання databases для db. Блок inject прив’язує provides.host з Recipe бази даних до змінної середовища
ADMINER_DEFAULT_SERVER у контейнері Adminer. Жодна частина Aggregate не називає провайдера;
цей вибір повністю міститься в шарі каталогу, який завантажує збірка.
Примітка щодо облікових даних
Образу MariaDB для запуску потрібен пароль root, а користувачеві застосунку потрібен власний. Обидва приєднано в опорі features: компонента бази даних — окремо від values застосунку — як Features з міткою feature.aggrega.ai/kind: secret. featuresSchema сутності Component core/datastore/mariadb оголошує слот для кожного з них, і приклад задіює обидві моделі доставки:
root_password— це слот типу чорна скринька (inject: []): FeatureRecipe доставляє значення в канал компонента. Розробник не визначає — і не може визначати — як саме.user_password— це прозорий слот (inject: [env, file]): облікові дані розкривають своє значення, і розробник зіставляє його зі змінною середовища за допомогою блокуinject:у приєднанні.
Значення тут є вбудованими літералами, тож стек запускається однією командою — це підходить для локальної розробки та демонстрацій. Для спільних або робочих середовищ ті самі приєднання отримують свої значення зі сховища секретів: каталог цільової платформи завантажує FeatureRecipe, що їх отримує, а Aggregate не змінюється.
Ціль 1 — Docker Compose
Спершу pull, потім збирання — pull записує release-compose.lock, який читає збирання:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlРезультат: dist/app/compose/docker-compose.yaml — два сервіси в одній мережі.
db запускає mariadb:11.4 з базою даних, користувачем, кодуванням і впровадженими
паролями; web запускає adminer:4, публікує порт 8080, залежить від db і
містить ADMINER_DEFAULT_SERVER: db (ім’я сервісу compose, яке згенерував
Recipe бази даних).
Запустіть його:
docker compose -f dist/app/compose/docker-compose.yaml up -dВідкрийте http://localhost:8080 і увійдіть:
| Поле | Значення |
|---|---|
| Система | MySQL / MariaDB |
| Сервер | db (уже заповнено) |
| Ім’я користувача | appuser |
| Пароль | dev-app-pw-change-me |
| База даних | appdb |
(або root / dev-root-pw-change-me). Щоб видалити все, виконайте
docker compose -f dist/app/compose/docker-compose.yaml down -v.
Ціль 2 — Kubernetes (самодостатня)
Ця ціль генерує звичайні маніфести Kubernetes безпосередньо з Workload,
без зовнішнього чарту — одна офлайн-збірка.
Workload бази даних оголошує form: stateful, тож він синтезує
StatefulSet, каталог даних якого — шаблон заявки на том для кожної репліки, а не
Deployment, що спільно використовує одну заявку. З цією формою йдуть два супутники:
том оголошується як persistentTemplate, а Headless Service надає
стабільну DNS-ідентичність для кожного пода, яку StatefulSet називає своїм керівним
сервісом. Adminer не зберігає стану, тож його Workload залишає form за замовчуванням
і лишається Deployment — збереження даних є властивістю сутності Workload, а не
окремим компонентом.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlВихідні файли в dist/app/helm/:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080Зверніть увагу на ADMINER_DEFAULT_SERVER: db-default — для Kubernetes сутність Recipe бази даних
видає DNS-ім’я Service усередині кластера, тож те саме ребро сутності Aggregate розв’язується
в маршрутизовану адресу на цій цілі.
Застосуйте й відкрийте:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Відкрийте http://localhost:8080 і увійдіть із сервером db-default, іменем користувача
appuser, паролем dev-app-pw-change-me, базою даних appdb. Видаліть усе командою
kubectl delete -f dist/app/helm/.
Ціль 3 — Kubernetes (керований чарт Bitnami)
Третій шар реалізує той самий Component core/datastore/mariadb
на основі upstream-чарту Bitnami MariaDB Helm, замість того щоб синтезувати
маніфести. Recipe отримує чарт за посиланням OCI і відображає
значення сутності Component на схему значень чарту:
spec: capability: helm implements: core/datastore/mariadb source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` .values.chart_version }}" # operator pin, else the value valuesMapping: | auth: database: "{{ .values.database }}" rootPassword: "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" username: "{{ .values.user }}" password: "{{ .context.inject.env.MARIADB_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" primary: persistence: size: "{{ .infra.storage.size }}" # … resources, read replicas, metrics mapped from infra …source.version у Recipe надає перевагу infra.source_version оператора і
в разі його відсутності використовує .values.chart_version, задане розробником. Фіксація версії чарту — це питання інфраструктури, тож фіксація оператора перемагає скрізь, де її задає
Release; цей Release навмисно її не задає, тому ключ .values — це
версія, яка фактично визначається, і саме в цьому суть цілі, адже
значення розробника, що доходить до визначення джерела, можна побачити у згенерованому
результаті лише за відсутності операційної фіксації. Зафіксуйте source_version для компонента db
у release-helm-bitnami.yaml, і згенерована мітка helm.sh/chart
натомість відповідатиме цій версії.
optional читає фіксацію за назвою, а не як шлях через крапку, і саме це дозволяє
відсутній фіксації перейти до значення розробника, а не визначитися як порожня
версія, — див. optional
щодо семантики перевірки наявності.
Збирання цієї цілі відбувається у два кроки: aggrega pull визначає чарт,
фіксує його в release-helm-bitnami.lock і завантажує в адресований за вмістом
кеш збирання (єдиний онлайн-крок); потім aggrega build генерує результат із кешу,
тож під час блокування і під час збирання визначається ідентичний чарт. Впроваджені облікові дані
потрапляють у значення auth чарту, а чарт генерує Kubernetes
Secret, який читає база даних. Adminer генерується тим самим синтезованим Recipe,
що й у цілі 2, і звертається до основного Service чарту (db-mariadb). Дві
самодостатні цілі вище — це спосіб запустити стек від початку до кінця
без жодних залежностей.
Ціль 4 — Kubernetes (скомпонований Helm-чарт)
Четвертий шар реалізує ті самі компоненти для провайдера helm-chart, який компонує розповсюджуваний парасольковий Helm-чарт замість рендерингу маніфестів (ціль 2) чи рендерингу upstream-чарту (ціль 3). Кожен Recipe бере за джерело невеликий локальний чарт:
spec: capability: helm-chart implements: core/datastore/mariadb source: ./charts/mariadb # copied as the sub-chart, bar its own name valuesMapping: | { "database": "{{ .values.database }}", "rootPassword": "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}", "serviceName": "{{ .context.instance_id }}-mariadb" }Зберіть його:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlРезультат у dist/app/helm-chart/:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── db/ # the local ./charts/mariadb; its Chart.yaml name is `db`│ ├── Chart.yaml│ ├── values.yaml│ └── templates/│ ├── deployment.yaml│ ├── service.yaml│ ├── pvc.yaml│ └── netpol.yaml # injected artifact (see below)└── web/ # the local ./charts/adminer; its Chart.yaml name is `web` [… omitted: web's own Chart.yaml, values.yaml, and a templates/ holding deployment.yaml and service.yaml — Adminer keeps no state, so it has no pvc.yaml, and the injected netpol.yaml is db's alone]Встановіть його (підчарти вендоровано в charts/, тож попередньо виконувати
helm dependency build не потрібно):
helm install mariadb-adminer dist/app/helm-chart/Файл values.yaml парасолькового чарту вже містить розв’язані значення кожного компонента, тож
база даних запускається зі своїми обліковими даними, а Adminer під’єднано до сервісу MariaDB — те саме з’єднання, яке виражають інші цілі, тепер постачене як чарт,
який можна встановити або вендорувати.
Діють два окремі режими роздільників, і вони не перетинаються:
- Підчарти-джерела копіюються, за винятком власної назви. Файли в
./charts/mariadbі./charts/adminerвключаються до парасолькового чарту без змін — їхні директиви Helm{{ }}компілятор не зачіпає, і вони розв’язуються під часhelm install. Завдання компонувальника тут — лише збирання, а не шаблонізація. Єдине поле, яке він задає, —nameу кожному розміщеномуChart.yaml, яке стає ідентичністю екземпляра компонента (db,web), щоб два компоненти, що вендорують чарти з однаковою назвою, залишалися розрізнюваними; див.providers/helm-chart.md. - Артефакти
$import:мають подвійні роздільники. Recipe може додавати додаткові файли шаблонів черезartifacts: { name: { $import: ... } }. Ці файли — і лише вони — попередньо рендеряться компілятором із роздільниками[[ ]], перш ніж потрапити на місце, тоді як їхні{{ }}зберігаються для Helm. Артефактnetpol.yaml— з ключемnetpol.yaml, імпортований з./extras/mariadb-netpol.yaml, оскільки ключ задає назву створюваного файлу, а імпорт — його вміст, — показує цю суміш:[[ .context.instance_id ]](заповнюється під час збирання) і{{ .Release.Namespace }}(залишається для встановлення).
String Pipe виражено в термінах чарту: використання MariaDB у databases Adminer
розв’язує provides.host з Recipe бази даних у values.yaml парасолькового чарту
під псевдонімом web (adminerDefaultServer: db-mariadb), який підчарт Adminer
читає як {{ .Values.adminerDefaultServer }}. Те саме значення задає назву
сервісу підчарту MariaDB, тож з’єднання узгоджено розв’язується під час встановлення. Результат — чарт для helm install або вендорування, а не набір застосованих маніфестів.
Як вибирається ціль
Recipe вибирається за типом компонента: Manifest кожної цілі зіставляє кожен тип із сутністю Recipe у шарі каталогу, який завантажує її Release, тож manifest-compose.yaml прив’язує core/datastore/mariadb до Recipe для compose, а manifest-helm-synth.yaml — до Recipe для Kubernetes. Тип, який Manifest не зіставляє, зупиняє збірку з назвами сутностей Recipes, що його реалізують, навіть якщо завантажений шар містить лише одну. Провайдер, який рендерить вузол, — це spec.capability того Recipe, що був прив’язаний. Змінити ціль означає змінити сутність Release разом з її Manifest і каталогом, який для неї вказує .aggrega-config.yaml, — сутність Aggregate ніколи не змінюється.