Перейти к содержимому
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 объявляет использование MariaDB типа databases; значение provides.host из Recipe базы данных передаётся в переменную окружения Adminer ADMINER_DEFAULT_SERVER. Компилятор передаёт строку, не интерпретируя её, поэтому из одного и того же ребра сборка для 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 получает исходный чарт 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 — путём ссылок на сущности стандартной библиотеки, не создавая ни одной собственной. Изучите сторону базы данных в этом примере, чтобы узнать, как создаются сущности каталога; изучите примеры потребления, чтобы узнать, как целый стек используется из поставляемого каталога.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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-* содержит локально созданные определения сущностей 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: 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-имя сервиса, поэтому то же ребро сущности 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 на основе вышестоящего 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" }

Сборка:

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 никогда не меняется.