Настройка, дерево дашбордов

Назначение файла

Этот документ описывает, как устроена директория config/grafana/deployment/docker/, за что отвечают её подпапки и файлы, а также содержит пошаговую инструкцию по запуску сервиса Grafana в составе системы мониторинга.

1. Дерево каталогов

config/
└─ grafana/
   └─ deployment/
      └─ docker/
         ├─ .env_example         # пример переменных окружения
         ├─ docker-compose.yml   # основной compose-файл сервиса Grafana
         ├─ dashboards/          # JSON-файлы дашбордов, сгруппированные по доменам
         │  ├─ asu_ppk/
         │  ├─ asu_ppk_api/
         │  ├─ asu_ppk_external_service/
         │  ├─ express/
         │  ├─ infrastructure/
         │  ├─ monitoring_system/
         │  ├─ mobipass/
         │  └─ sla/
         └─ provisioning/        # автоконфигурация Grafana
            ├─ datasources/      # источники данных (VictoriaMetrics / VictoriaLogs)
            │  └─ datasource.yml
            └─ dashboards/
               ├─ folders.yml    # описание папок в Grafana (id + название)
               └─ dashboard.yml  # провайдеры, указывающие где искать JSON-дашборды

1.1 `dashboards/`

Содержит готовые JSON-файлы дашбордов. Подкаталог = папка (folder) в Grafana. Добавили новый бизнес-домен ➜ создайте одноимённую папку и положите туда все файлы дашбордов.

1.2 `provisioning/datasources/`

Файлы .yml, описывающие источники данных. При старте контейнера Grafana автоматически создаёт/обновляет все указанные data-sources.

1.3 `provisioning/dashboards/`

folders.yml — регистрирует папки (folder) в Grafana. Нужно, если появляется новая группа дашбордов.
dashboard.yml — провайдеры, связывающие папку в Grafana с путём на диске (/var/lib/grafana/dashboards/<folder>).

2. Переменные окружения

Все переменные задаются в файле .env (создайте из .env_example).

Переменная	Назначение
`GRAFANA_IMG_VERSION`	тег Docker-образа Grafana
`GRAFANA_HOST` / `GRAFANA_PORT`	доменное имя и порт сервиса (используются Traefik-роутером)
`INSTALL_PLUGINS`	список плагинов через `,` (пример: `grafana-clock-panel`)
`ALLOW_PLUGINS`	`true`, чтобы позволить подписи сторонних плагинов
`ADMIN_USER` / `ADMIN_PASSWORD`	базовая учётка администратора (если не используется OAuth)
`KEYCLOAK_*`	параметры OIDC-авторизации через Keycloak

⚠️ Значения, содержащие пробелы или спецсимволы, экранируйте кавычками.

3. Запуск Grafana

Перейдите в каталог config/grafana/deployment/docker.
Скопируйте пример переменных и заполните: bash cp .env_example .env # отредактируйте .env любым редактором
Убедитесь, что внешняя сеть monitoring_net уже создана (её поднимает общая docker-compose системы мониторинга). При необходимости: bash docker network create monitoring_net
Запустите контейнер: bash docker compose up -d
Перейдите по адресу https://<GRAFANA_HOST> (или http://localhost:3000, если открыли порт). Авторизуйтесь через Keycloak либо базовую учётку.

Контейнер перезапускается автоматически (restart: always). Любое изменение файлов в dashboards/ или provisioning/ достаточно сохранить — Grafana подхватит новые ресурсы через ~10 секунд.

4. Работа с дашбордами

Дашборды редактируем в UI Grafana ➜ Save as JSON ➜ кладём в нужную папку.
Название файла = латиница+snake_case, например asuppk_api_servers.json.
После добавления нового дашборда НЕ нужно пересобирать контейнер.
Если нужна новая папка в Grafana:
Добавьте запись в provisioning/dashboards/folders.yml c уникальным id.
Добавьте блок-провайдер в dashboard.yml.
Создайте директорию в dashboards/.

Подробный процесс описан в grafana_create_dash.md.

5. Обновление и резервное копирование

# Проверка доступных новых версий образа
docker pull grafana/grafana:${GRAFANA_IMG_VERSION}

# Резервная копия данных Grafana (папка grafanadata)
docker run --rm -v grafanadata:/data -v $(pwd):/backup alpine \
  tar czf /backup/grafana_backup_$(date +%F).tgz -C /data .

6. Быстрый чек-лист для админа

[ ] .env заполнен и закоммичен? (секреты храните в CI Vault!)
[ ] Плагины перечислены в INSTALL_PLUGINS?
[ ] Все dashboard-файлы лежат в корректных каталогах?
[ ] Добавлены источники данных в datasource.yml?
[ ] Сервис запущен docker compose up -d и доступен по URL?

❤️ Если заметили неточность — правьте файл и создавайте Pull Request.