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 объявляет использование MariaDB типа
databases; значениеprovides.hostиз Recipe базы данных передаётся в переменную окружения AdminerADMINER_DEFAULT_SERVER. Компилятор передаёт строку, не интерпретируя её, поэтому из одного и того же ребра сборка для 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 получает исходный
чарт 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 напрямую ссылается на поставляемую сущность core/devtool/adminer Component, и каждая цель создаёт лишь локальную сущность 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-* содержит локально созданные определения сущностей MariaDB Component и Feature, а также Recipes для одной соответствующей цели. Сущности Adminer Component среди них нет — она разрешается из стандартной библиотеки. Сборка загружает один слой 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-имя сервиса, поэтому то же ребро сущности 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
на основе вышестоящего Helm-чарта Bitnami MariaDB вместо синтеза
манифестов. 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) и не рендерит вышестоящий чарт (цель 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 никогда не меняется.