Документация Grafana Документация GlaberGraph Upgrade Grafana Обновление до v13.0

Upgrade to Grafana v13.0

Technical notes

Обновления, связанные с React 19

В рамках перехода на React 19 в Grafana 13 внесите следующие обновления, чтобы убедиться, что ваши плагины работают корректно и у вас не возникает сбоев во время обновления до Grafana 13.

Следуйте этой последовательности для достижения наилучших результатов:

Обновите Grafana до последней версии исправлений для той версии, которую вы используете

Чтобы убедиться, что изменения, необходимые для обновления до React 19, присутствуют в вашей версии Grafana, обновитесь до последней доступной минорной версии для вашего экземпляра Grafana. Доступные версии можно проверить на странице загрузки.

Обновите все свои плагины

Обновите все установленные плагины и проверьте, что они по-прежнему работают корректно. Используя последнюю версию плагина, вы обеспечиваете поддержку React 19.

Обновитесь до Grafana 13

Наконец, вы можете продолжить обновление до Grafana 13.

Устаревшие конечные точки /api теперь объявлены устаревшими

Grafana переносит существующие API на новую модель /apis — уровень API в стиле Kubernetes, который следует стандартизированной структуре API наряду с согласованной версионностью API. Подробнее см. в документации Новая структура API в Grafana.

Устаревшие API пока не отключаются. Удаление устаревших API запланировано на будущий крупный выпуск, и о любых критических изменениях будет объявлено заранее, чтобы избежать сбоев.

Для получения дополнительной информации и рекомендаций по миграции обратитесь к разделу Переход на новые API.

Устаревшие API источников данных отключены

API источников данных, которые ссылаются на источники данных по числовому id, объявлены устаревшими с Grafana 9. В Grafana 13 они отключены по умолчанию.

Вы затронуты, если

Вы используете конечные точки API источников данных, которые ссылаются на источники данных по числовому id, а не по uid.

Миграция

Обновите свои вызовы API, чтобы ссылаться на источники данных по uid вместо числового id. Чтобы временно повторно включить устаревшие API, включите флаг функции datasourceLegacyIdApi. И устаревшие API, и флаг функции будут удалены в будущем выпуске.

Поддержка плагина Image Renderer удалена

В Grafana 13 поддержка плагина Image Renderer удалена.

Вы затронуты, если

Вы запускаете Image Renderer как плагин Grafana. После обновления плагин больше не будет работать для рендеринга снимков экрана или запланированных отчётов.

Миграция

Разверните рендерер изображений как отдельный сервис вместе с Grafana. Инструкции по настройке см. в разделе Настройка рендеринга изображений.

Аутентификация Image Renderer по умолчанию изменена на JWT

Ранее Image Renderer аутентифицировался в Grafana с помощью непрозрачных токенов, хранящихся в базе данных, при создании снимков экрана и PDF. Grafana v13.0 включает флаг функции renderAuthJWT по умолчанию, который переключает аутентификацию на JSON Web Tokens (JWT) без сохранения состояния, не зависящие от базы данных.

Требуемые действия

После обновления до Grafana v13.0, если вы используете Image Renderer, вы должны задать в конфигурационном файле Grafana значение [rendering]renderer_token, отличное от пустого или значения по умолчанию (-), и настроить Image Renderer с тем же значением токена. Перезапустите ваш экземпляр Grafana, чтобы изменения вступили в силу.

Для получения дополнительной информации обратитесь к документации по настройке безопасности Image Renderer.

Возврат к прежнему поведению

После обновления до Grafana v13.0, чтобы вернуться к аутентификации с помощью непрозрачных токенов, отключите флаг функции в конфигурационном файле Grafana:

ini Copy

[feature_toggles]
renderAuthJWT = false

Перезапустите ваш экземпляр Grafana, чтобы изменения вступили в силу.

Единое хранилище для папок и панелей мониторинга

Grafana v13.0 автоматически переносит папки и панели мониторинга из устаревшей SQL-базы данных в единое хранилище при запуске. Миграция выполняется один раз и отслеживается в таблице unifiedstorage_migration_log.

После завершения миграции следующие устаревшие таблицы объявляются устаревшими:

• dashboard
• dashboard_acl
• dashboard_provisioning
• dashboard_version
• dashboard_tag
• library_element_connection
• folder

Эти таблицы будут удалены в будущем выпуске.

Если вы понизите версию Grafana до более ранней после миграции, старая версия будет читать устаревшие таблицы и не будет отражать изменения, внесённые в едином хранилище. Чтобы выполнить откат, восстановите данные из резервной копии базы данных, которую вы сделали перед обновлением.

Если вы понизите версию, а затем снова обновитесь без восстановления резервной копии, папки или панели мониторинга, созданные или изменённые во время понижения версии, не будут перенесены автоматически. Если резервная копия недоступна, обратитесь в службу поддержки Grafana.

Развёртывания на SQLite

Если вы используете SQLite, миграция может завершиться ошибкой database is locked или database table is locked из-за конфликта блокировок. Grafana автоматически повторяет попытку, используя буфер Parquet, но если ошибки сохраняются, увеличьте migration_cache_size_kb или включите migration_parquet_buffer в разделе [unified_storage] конфигурационного файла:

Удаление команд grafana-cli и grafana-server

Команды grafana-cli и grafana-server, объявленные устаревшими с Grafana v10.0, удалены в Grafana v13.0. Обновите все скрипты, модули systemd, точки входа Docker, конвейеры CI или другую автоматизацию, чтобы использовать grafana cli и grafana server вместо них.

Изменены устаревшие конечные точки API конфигурации Alertmanager

В Grafana v13.0 удалены или ограничены несколько устаревших конечных точек API конфигурации Alertmanager:

• DELETE /api/alertmanager/grafana/config/api/v1/alerts удалена.
• POST /api/alertmanager/grafana/config/api/v1/receivers/test удалена.
• GET /api/alertmanager/grafana/config/api/v1/alerts ограничена для пользователей с правами администратора.
• GET /api/alertmanager/grafana/config/history ограничена для пользователей с правами администратора.
• POST /api/alertmanager/grafana/config/history/{id}/_activate ограничена для пользователей с правами администратора.

Вы затронуты, если

Вы вызываете любую из этих конечных точек в скриптах автоматизации, провайдерах Terraform или пользовательских инструментах.

Миграция

Перенесите работу на ресурсные API в стиле Kubernetes в разделе notifications.alerting.grafana.app/v1beta1:

Конечная точка статуса Alertmanager требует новое разрешение

Вы затронуты, если

Вы используете конечную точку GET /api/alertmanager/grafana/api/v2/status и полагаетесь на разрешение alert.notifications:read для доступа к ней.

Описание

Конечная точка GET /api/alertmanager/grafana/api/v2/status ранее требовала устаревшее разрешение alert.notifications:read. Теперь она требует отдельное разрешение alert.notifications.system-status:read. Это новое разрешение включено в роль fixed:alerting.notifications:writer, которая по умолчанию предоставляется пользователям с правами администратора.

Миграция

Если у вас есть пользовательские роли, которым нужен доступ к этой конечной точке, добавьте действие alert.notifications.system-status:read в эти роли. Пользователи с правами администратора не затронуты, так как они получают это разрешение автоматически через встроенную роль записи уведомлений об оповещениях.

Изменения в применении RBAC для пользовательских ролей

Grafana v13.0 ужесточает применение RBAC для пользовательских ролей, ролей, управляемых через Terraform, и подготовки ролей. Роли, содержащие устаревшие разрешения, могут выходить из строя при выполнении операций создания, обновления, удаления или назначения. Мы рекомендуем заранее просмотреть и обновить затронутые роли.

Вы затронуты, если

Вы управляете пользовательскими ролями RBAC через Terraform, API или подготовку, и эти роли содержат любое из следующего:

• Разрешения с областью действия по UID источника данных (datasources:uid:<uid>) в глобальной роли
• fixed:annotations.dashboard:writer или fixed:annotations.dashboard:reader
• annotations:type:dashboard
• annotations:*

Миграция

Разрешения источников данных в глобальных ролях: Если управляемый через Terraform grafana_role сочетает global = true с datasources:uid:<uid>, пересоздайте роль как неглобальную роль с новым UID. Grafana не может изменить область действия существующей роли на месте. По возможности задайте datasource_type для ресурсов разрешений источников данных.

Фиксированные роли аннотаций панелей мониторинга: Удалите fixed:annotations.dashboard:writer и fixed:annotations.dashboard:reader из своих конфигураций. Вместо этого используйте разрешения панелей мониторинга или папок (Просмотр, Редактирование, Администрирование) для управления доступом к аннотациям панелей мониторинга. Используйте annotations:type:organization для аннотаций уровня организации.

Подстановочная область annotations:*: Замените её конкретными областями: annotations:type:organization для аннотаций организации и разрешения панелей мониторинга или папок для аннотаций панелей мониторинга. Не создавайте annotations:* заново в Terraform после того, как она была удалена.

Если роль застряла, потому что Grafana отказывается обновлять или удалять её, роль может содержать устаревшее разрешение, которое необходимо удалить, прежде чем обновления через Terraform или API смогут пройти успешно. Обратитесь в службу поддержки Grafana.

Подробные примеры и устранение неполадок см. в разделе Изменения поведения RBAC в Grafana 13.