Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

MariaDB + Adminer — робочий приклад із двома цільовими платформами

Цей приклад компілює невеликий реальний стек — базу даних MariaDB з вебінтерфейсом Adminer перед нею — з одного написаного розробником Aggregate для двох платформ:

  • Docker Compose для локальної розробки та
  • Kubernetes для локального кластера (kind / minikube / k3d), відрендерений трьома способами.

Обидві керуються одним і тим самим Aggregate. Змінюються лише Release, його Manifest і шар сутностей Recipe, завантажений під час збирання. Кожен файл тут компілюється за допомогою CLI aggrega, що постачається, а згенерований результат працює: запустіть стек, відкрийте Adminer у браузері й увійдіть до робочої бази даних.

aggregate.yaml

написано один раз

На ноутбуці

release-compose.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

У кластері Kubernetes

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Маніфести Kubernetes

Кожну платформу збирають із її власних сутностей Release і Manifest. Сутність Aggregate, яка описує ваш застосунок, залишається тією самою.

Що демонструє приклад

  • Одна поверхня авторства, багато цілей. Єдиний aggregate.yaml є джерелом істини про те, що являє собою стек. Кожна ціль — це тонкий шар каталогу, який визначає, як його реалізувати.
  • String Pipe. Adminer оголошує використання databases для MariaDB; значення provides.host сутності Recipe бази даних передається в змінну середовища ADMINER_DEFAULT_SERVER Adminer. Компілятор маршрутизує рядок, не інтерпретуючи його, тож збірка compose підставляє ім’я сервісу compose, а збірка Kubernetes — DNS-ім’я Service, з одного й того самого ребра.
  • Синтез робочих навантажень. Recipes для compose і для самодостатнього Kubernetes оголошують Workload, агностичний щодо можливостей; провайдер синтезує сервіс docker-compose.yaml або ті об’єкти Kubernetes, яких вимагає form сутності Workload: Deployment і Service для веб-інтерфейсу без стану, а для бази даних із form: stateful — StatefulSet, шаблон запиту тому якого для кожної репліки містить каталог даних, поряд із Headless Service, що ним керує, і ClusterIP Service, до якого звертаються споживачі.
  • Підсистема облікових даних. Паролі бази даних приєднуються в розділі 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 — через посилання на сутності стандартної бібліотеки, не створюючи жодної власної. Прочитайте частину цього прикладу про базу даних, щоб дізнатися, як сутності каталогу створюються; прочитайте приклади використання, щоб дізнатися, як цілий стек використовується з постаченого каталогу.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example mariadb-adminer

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd mariadb-adminer

Збирання

Кожна ціль — це одна сутність Release, яку збирають по одній за запуск; pull записує lockfile, який читає збірка. Спершу Docker Compose — розділ кожної цілі нижче наводить власні команди:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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: host

web оголошує використання 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, який читає збирання:

Terminal window
aggrega pull --release release-compose.yaml
aggrega 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 бази даних).

Запустіть його:

Terminal window
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, а не окремим компонентом.

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Вихідні файли в dist/app/helm/:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

Зверніть увагу на ADMINER_DEFAULT_SERVER: db-default — для Kubernetes сутність Recipe бази даних видає DNS-ім’я Service усередині кластера, тож те саме ребро сутності Aggregate розв’язується в маршрутизовану адресу на цій цілі.

Застосуйте й відкрийте:

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl 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" }

Зберіть його:

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega build --release release-helm-chart.yaml

Результат у dist/app/helm-chart/:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── 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 не потрібно):

Terminal window
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 ніколи не змінюється.