Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Grafana — один Aggregate, две целевые платформы, необязательные учётные данные администратора

Этот пример компилирует один сервер дашбордов и визуализации Grafana из одного созданного разработчиком Aggregate в две реализации:

  • Docker Compose для локальной разработки и
  • синтезированный helm Recipe, запускающий официальный upstream-образ grafana/grafana непосредственно в Kubernetes (без внешнего чарта).

Синтезированный helm Recipe — это путь для Kubernetes: он зависит только от тега официального образа, а не от стороннего чарта, и набор отрисованных ресурсов в точности соответствует тому, что объявляет рабочая нагрузка.

Один и тот же aggregate.yaml управляет обоими вариантами. Для каждой реализации меняется только слой Recipe, выбранный в Manifest. Ещё две сущности Aggregates показывают тот же сервер с подключёнными необязательными учётными данными пароля администратора: aggregate-auth.yaml для пути Compose (учётные данные inject-value, передаваемые как переменная окружения) и aggregate-helm-synth-auth.yaml для пути синтезированного helm (ссылочные учётные данные, материализуемые как Kubernetes Secret).

Упакованный сервер Grafana распространяется под лицензией AGPL-3.0.

Файлы

ФайлРоль
aggregate.yamlНамерение разработчика: один компонент dashboards типа core/observability/grafana, без учётных данных — учётная запись администратора использует детерминированный пароль для разработки из Recipe.
aggregate-auth.yamlТот же сервер с учётными данными пароля администратора, подключёнными к необязательному слоту admin_password компонента (путь Compose).
aggregate-helm-synth-auth.yamlТот же сервер со ссылочными учётными данными, подключёнными для пути синтезированного helm, — значение материализуется как Kubernetes Secret, на который ссылается Deployment.
manifest-compose.yamlСопоставляет тип Grafana с Compose Recipe (compose/grafana), а учётные данные — с dotenv-secret.
manifest-helm-synth.yamlСопоставляет тип Grafana с синтезированным helm Recipe (helm/grafana), а учётные данные — с k8s-secret-from-parameter.
release-compose.yaml / release-helm-synth.yamlЗаписи оператора для двух реализаций, без подключённых учётных данных.
release-compose-auth.yaml / release-helm-synth-auth.yamlЗаписи оператора, включающие аутентификацию.

Что демонстрирует пример

  • Одна поверхность описания, много целевых платформ. Единственный Aggregate — источник истины о том, что представляет собой стек. Каждый Manifest описывает, как его реализовать.
  • Сервер с постоянным томом. Grafana хранит своё состояние — пользователей, сохранённые дашборды, настройки — на диске, поэтому компонент объявляет том данных, размер которого задаётся из infra.storage. В Kubernetes синтезированный helm Recipe отрисовывает Deployment с PersistentVolumeClaim, смонтированным в /var/lib/grafana; в Compose сервис монтирует именованный том по тому же пути.
  • Синтез рабочей нагрузки (Kubernetes). Синтезированный helm Recipe объявляет Workload — Deployment и ClusterIP Service, запускающие официальный образ grafana/grafana, — который helm-провайдер преобразует в манифесты Kubernetes без внешнего чарта. Набор отрисованных ресурсов в точности соответствует тому, что объявляет Workload. Поскольку и Compose Recipe, и синтезированный helm Recipe носят имя grafana, сущности Manifests ссылаются на них с указанием провайдера: compose/grafana и helm/grafana.
  • Детерминированный пароль администратора. Учётная запись администратора Grafana присутствует всегда. Этот компонент передаёт пароль через необязательный слот учётных данных admin_password: если учётные данные не подключены (базовый Aggregate), Recipe задаёт детерминированный пароль для разработки, поэтому результат отрисовки побайтно совпадает между запусками; если учётные данные подключены, внедрённое значение становится паролем администратора. В Compose оно передаётся как переменная окружения GF_SECURITY_ADMIN_PASSWORD; в Kubernetes путь синтезированного helm материализует его как Secret, на который Deployment ссылается через env secretKeyRef, поэтому открытый текст никогда не появляется в манифесте Deployment.

Что здесь не моделируется

Grafana развёртывается автономно. Подключение источника метрик или логов — например, сервера Prometheus — к Grafana в качестве подготовленного источника данных не моделируется: компонент не объявляет сокета uses.

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

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

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

Terminal window
aggrega scaffold --example grafana-dashboards

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd grafana-dashboards

Сборка

В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:

Terminal window
# Local development (Docker Compose), development admin password
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), development admin password
aggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabled
aggrega build --release release-compose-auth.yaml --auto-pull
aggrega build --release release-helm-synth-auth.yaml --auto-pull

Отрендеренные артефакты помещаются в dist/.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `grafana-dashboards`, вызовите инструмент `scaffold` один раз, задав `example` равным `grafana-dashboards` и не указывая `dir`: он запишет пример в новую папку `grafana-dashboards`. Затем вызовите инструмент `build` один раз для каждой сущности Release в следующем порядке — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml`, `release-helm-synth-auth.yaml` — каждый раз задавая `workspace_root` равным `grafana-dashboards`, `release` равным этому файлу, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала каждая сборка; они находятся в `grafana-dashboards/dist/`.

Примечание о передаче учётных данных

На пути Compose учётные данные — это секрет inject-value (aggregate-auth.yaml): его значение передаётся по каналу окружения компонента и становится переменной окружения сервиса GF_SECURITY_ADMIN_PASSWORD.

Путь синтезированного helm использует ссылочные учётные данные (aggregate-helm-synth-auth.yaml): значение материализуется как Kubernetes Secret, а Deployment ссылается на него через env secretKeyRef, привязанный к GF_SECURITY_ADMIN_PASSWORD. Поэтому пароль в открытом виде никогда не появляется в манифесте Deployment — только в Secret.

Значение origin в сущностях Aggregates с аутентификацией — заглушка для разработки; для любого реального развёртывания задайте настоящее значение через свой источник учётных данных.

Запуск (Compose)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

Откройте http://localhost:3000 — веб-интерфейс Grafana — и войдите как admin с паролем для разработки. Для остановки выполните docker compose -f dist/app/compose/docker-compose.yaml down.