Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Обратно несовместимые измененияbreadcrumb arrow Обратно несовместимые изменения в Grafana v10.0

Обратно несовместимые изменения в Grafana v10.0

Ниже перечислены обратно несовместимые изменения, о которых следует знать при обновлении до Grafana v10.0.

Для наших целей обратно несовместимым изменением является любое изменение, требующее от пользователей или операторов каких-либо действий. К ним относятся:

  • Изменения в одной части системы, которые могут привести к сбою других компонентов
  • Признание функции устаревшей или её удаление
  • Изменения в API, которые могут нарушить работу автоматизации
  • Изменения, затрагивающие некоторые плагины или функции Grafana
  • Миграции, которые невозможно откатить

Для каждого изменения приведённая информация:

  • Помогает определить, затронуты ли вы
  • Описывает изменение или соответствующую предысторию
  • Подсказывает, как смягчить последствия изменения или выполнить миграцию
  • Предоставляет дополнительные материалы для изучения

О ключевых нововведениях и устаревших функциях см. Что нового в v10.0. Конкретные шаги, которые мы рекомендуем при обновлении до v10.0, описаны в нашем руководстве по обновлению.

Общие обратно несовместимые изменения

Angular устарел и по умолчанию отключён для новых стеков Grafana Cloud

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

Вы создаёте новый стек Grafana Cloud и намерены использовать любые плагины панелей или источников данных, написанные с использованием JavaScript-фреймворка Angular.js. См. список плагинов Angular.

Предыстория

AngularJS — это старый фронтенд-фреймворк, активная разработка которого прекратилась много лет назад. Из-за этого он представляет собой риск для безопасности. AngularJS также требует unsafe-eval в настройках CSP (Content Security Policy), что дополнительно снижает уровень безопасности выполнения javascript в браузере.

Поддержка плагинов Angular в Grafana устарела, то есть будет удалена в будущем релизе. По-прежнему существуют некоторые плагины сообщества и приватные плагины, созданные с использованием Angular. Начиная с v9.0 в Grafana есть серверный параметр конфигурации под названием angular_support_enabled, который управляет доступностью поддержки плагинов Angular.

Изменение в Grafana v10

Angular по умолчанию отключён для всех новых стеков Grafana Cloud. Существующие стеки в Grafana Cloud, локальные экземпляры Grafana Enterprise и экземпляры Grafana OSS не будут затронуты автоматически.

Как смягчить

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

Если вы разработчик, поддерживающий плагин, использующий Angular, мы рекомендуем вам отрефакторить или переписать его фронтенд на React.js. Команда Grafana готова помочь и предоставить инструменты и рекомендации; связаться с нами можно в Slack или на нашем Форуме.

Дополнительные материалы

Устаревшая система оповещений Grafana устарела и больше не принимает внутренние или внешние вклады

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

Вы используете устаревшую систему оповещений Grafana и запрашивали для неё новые функции или изменения.

Описание

Устаревшая система оповещений Grafana (оповещения на дашбордах) устарела начиная с Grafana v9.0 в пользу новой, улучшенной системы Grafana Alerting. В Grafana v10 кодовая база устаревшей системы оповещений—которая зависит от Angular—по-прежнему доступна, но мы больше не будем вносить в неё вклад и принимать для неё внешние вклады. Мы продолжим работу над путём миграции с устаревшей системы оповещений на Grafana Alerting для оставшихся пользователей, которым нужна миграция.

Путь миграции

Новая система Grafana Alerting была представлена в Grafana 8 и является надмножеством устаревшей системы оповещений. Узнайте, как мигрировать ваши оповещения, в документации по обновлению оповещений.

Ключи API мигрируют в сервисные аккаунты

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

Вы используете ключи API Grafana и ещё не мигрировали на сервисные аккаунты

Описание

В Grafana v8.5 мы представили сервисные аккаунты, которые являются надмножеством ключей API и поддерживают ротацию токенов и управление доступом на основе ролей (RBAC). Они были переведены в статус общей доступности (GA) в v9.1, и с тех пор есть возможность вручную мигрировать ключи API в сервисные аккаунты через UI и API. При обновлении до Grafana v10 Grafana автоматически мигрирует все ключи API в сервисные аккаунты и скроет экран ключей API, который находился в разделе Admin.

Это «обратно несовместимое» изменение, потому что если пользователи привыкли видеть ключи API и работать с ними, они больше не увидят эту страницу в навигации и им нужно будет перейти на страницу Service accounts. Однако ваши существующие токены API останутся полностью работоспособными и будут мигрированы в сервисные аккаунты, поэтому никакая автоматизация не сломается. Если вы откатитесь к предыдущей версии Grafana, ваши ключи API останутся нетронутыми.

Конечные точки HTTP API Grafana для создания и управления ключами API остаются работоспособными, но мы рекомендуем вам начать использовать HTTP API сервисных аккаунтов для создания и управления машинной аутентификацией.

Путь миграции

При обновлении до Grafana v10 вам не нужно предпринимать никаких действий; ваши ключи API будут автоматически мигрированы. Чтобы протестировать или выполнить миграцию с ключей API на сервисные аккаунты до обновления до Grafana v10, следуйте нашей документации по миграции.

Дополнительные материалы

Экспериментальная функция «dashboard previews» удалена

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

У вас включён переключатель функции dashboardPreviews.

Описание

Мы удаляем экспериментальную функцию предпросмотра дашбордов из-за проблем с правами пользователей и производительностью, которые не позволили продолжить её разработку. Предпросмотр дашбордов находился за переключателем функции начиная с Grafana v9.0.

Путь миграции

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

Дополнительные материалы

RBAC включён по умолчанию в Grafana Enterprise и не может быть отключён

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

Вы активно отключали RBAC в конфигурации Grafana.

Описание

Начиная с Grafana 9 RBAC включён по умолчанию. Возможность отключить RBAC была введена как аварийный механизм и использовалась лишь в редких случаях. В Grafana v10 мы удалили параметр конфигурации для отключения RBAC. Это обеспечивает согласованную работу Grafana в разных функциях и снижает риск возникновения проблем с устаревшим управлением доступом Grafana. Кроме того, управление доступом для некоторых функций Grafana v10 работает только с RBAC, поэтому его отключение больше не является вариантом.

Путь миграции

Никаких действий не требуется—миграция выполняется автоматически. Текущие роли, разрешения, сопоставление SSO и другие функции авторизации пользователей продолжат работать как прежде.

Имена пользователей теперь по умолчанию нечувствительны к регистру

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

Вы запускаете Grafana с базой данных Postgres или sqlite, импортируете пользователей из разных провайдеров идентификации SSO (таких как Google и Active Directory), и пользователи, входившие из разных провайдеров, ранее создавались дважды из-за различий в регистре (например, “Myra@Grafana.com” против “myra@grafana.com”.

Предыстория

Когда кто-то регистрируется в аккаунте Grafana, он может сделать это с помощью электронной почты или логина. Эти поля были чувствительны к регистру, что могло приводить к созданию двух или более аккаунтов для одного пользователя. Кроме того, Grafana позволяет пользователям настраивать провайдера аутентификации, и этот провайдер может возвращать почту регистрации пользователя с доменным именем в верхнем регистре или с некоторой комбинацией прописных и строчных букв.

Наличие нескольких аккаунтов приводит к разделению прав пользователя, путанице в процессах регистрации и неиспользуемым «зомби»-аккаунтам в вашей базе данных. Кроме того, несколько аккаунтов могут создавать проблемы при переключении между провайдерами аутентификации. Такие несоответствия в уникальности пользователей мы называем конфликтом идентичности пользователя.

Изменение в Grafana v10

Grafana начнёт сопоставлять пользователей без учёта регистра. Конфликтующие пользователи не смогут войти.

Путь миграции

Мы создали инструмент CLI, с помощью которого пользователи могут заранее разрешить возможные конфликты. Об этом обратно несовместимом изменении уже сообщалось вместе с Grafana v9.3.

Дополнительные материалы

Интеграции Grafana OAuth больше не работают с поиском по электронной почте

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

  • Вы настроили Grafana для использования нескольких провайдеров идентификации, и у вас есть пользователи с одинаковым адресом электронной почты в нескольких провайдерах идентификации.
  • Вы настроили Grafana для использования Generic OAuth с провайдером идентификации, который не поддерживает поле уникального ID.

Предыстория

Раньше Grafana проверяла аккаунты провайдеров идентификации на основе утверждения (claim) email. У многих провайдеров идентификации поле email не является уникальным, и это могло открыть потенциальный вектор для захвата аккаунта и обхода аутентификации в определённых сценариях. Это изменение также обеспечивает защиту Grafana от уязвимости CVE-2023-3128.

Изменение в Grafana v10

Grafana не позволит затронутым пользователям войти.

Путь миграции

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

[auth]
oauth_allow_insecure_email_lookup = true

Мы настоятельно не рекомендуем этого делать, если вы используете Azure AD в качестве провайдера идентификации с многоклиентским приложением.

Дополнительные материалы

Поле «Alias» в источнике данных CloudWatch удалено

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

Вы используете поле «Alias» в источнике данных CloudWatch вместо использования динамических меток (dynamic labels).

Описание

Шаблоны Alias в редакторе запросов CloudWatch были заменены на Label (динамические метки) за переключателем функции. Начиная с Grafana v9 Label включён по умолчанию. В Grafana v10 мы удалили возможность отключить Label и полностью удалили поле Alias.

Путь миграции

Откройте и сохраните каждый дашборд, использующий поле Alias. Alias автоматически мигрирует в Label при загрузке дашборда.

Дополнительные материалы

Плагин источника данных Athena должен быть обновлён до версии >=2.9.3

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

Вы установили и используете плагин источника данных Athena.

Описание

Grafana v10.0.0 поставляется с обновлением до React 18. В свою очередь, изменения в группировке (batching) обновлений состояния в React 18 вызывают ошибку в редакторе запросов в версиях плагина Athena <=2.9.2.

Путь миграции

Обновите плагин до версии 2.9.3 или выше в консоли управления экземпляром Grafana. Это обеспечит корректную работу редактора запросов плагина.

Плагин источника данных Redshift должен быть обновлён до версии >=1.8.3

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

Вы установили и используете плагин источника данных Redshift.

Описание

Grafana v10.0.0 поставляется с обновлением до React 18. В свою очередь, изменения в группировке (batching) обновлений состояния в React 18 вызывают ошибку в редакторе запросов в версиях плагина Redshift <=1.8.3.

Путь миграции

Обновите плагин до версии 1.8.3 или выше в консоли управления экземпляром Grafana. Это обеспечит корректную работу редактора запросов плагина.

Плагин DoiT International BigQuery больше не поддерживается

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

Вы установили и используете плагин источника данных DoiT International BigQuery.

Описание

В v10.0.0 Grafana больше не поддерживает использование плагина источника данных DoiT International BigQuery, который во второй половине 2022 года был переведён в состояние «retired», а его репозиторий на GitHub был заархивирован в декабре 2022 года. Чтобы источники данных BigQuery продолжали работать, вам необходимо перейти на официальный плагин источника данных Grafana BigQuery.

Путь миграции

Для всех, кто использует Grafana v8.5+, существует возможность импортировать запросы, созданные с помощью плагина сообщества DoiT International BigQuery, просто изменив источник данных на Grafana BigQuery в селекторе источников данных в затронутой панели. Обратите внимание, что запросы будут импортированы как необработанные SQL-запросы.

Дополнительные материалы

Для разработчиков плагинов

Обновление до React 18

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

Вы разработали плагин Grafana, использующий фреймворк React JS (это касается большинства плагинов приложений, панелей и источников данных).

Описание

Grafana обновлена до React 18 и теперь использует новый API клиентского рендеринга React. Авторам плагинов следует быть особенно внимательными, поскольку из-за изменений в автоматической группировке обновлений состояния и согласованных таймингах useEffect могут возникнуть непредвиденные побочные эффекты.

Путь миграции

Как разработчик плагина: после выпуска канареечной сборки (после 9.5.0) протестируйте свой плагин на одном из docker-сборок grafana-dev здесь (вот эта, например). Из-за дополнительных оптимизаций, сделанных в React 18, для сохранения прежнего поведения могут потребоваться некоторые изменения.

Дополнительные материалы

Устаревшие функции и переменные, связанные с логами, удалены из пакетов “@grafana/data” и “@grafana/ui”

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

Вы автор плагина и используете одну из следующих функций, связанных с логами:

  • Тип интерфейса LogsParser в grafana-data

  • Следующие функции и классы, связанные с логами, в пакете grafana-ui: 1LogLabels, LogMessageAnsi, LogRows, getLogRowStyles., getLogLevel, getLogLevelFromKey, addLogLevelToSeries, LogsParsers, calculateFieldStats, calculateLogsLabelStats, calculateStats, getParser, sortInAscendingOrder, sortInDescendingOrder, sortLogsResult, sortLogRows, checkLogsError, escapeUnescapedString.

Описание

Некоторые редко используемые функции и переменные, связанные с логами, были перенесены из пакетов grafana в основную кодовую базу Grafana. Ранее эти элементы были помечены как устаревшие, и в списке изменений Grafana было опубликовано уведомление об устаревании. Авторам плагинов, которые полагались на доступность этих функций и переменных, придётся скорректировать свою кодовую базу.

Путь миграции

Если вы написали плагин источника данных или панели, убедитесь, что он не использует функции и переменные, которые были помечены как устаревшие и удалены.

Дополнительные материалы

DataFrame: используйте Array или Vector для значений полей

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

Вы автор плагина и реализовали собственную версию Vector для фреймов данных.

Описание

Работа с DataFrame была сложнее, чем должна была быть, потому что данные хранились в интерфейсе Vector, а не в простом Array. В Grafana v10 интерфейс был изменён, чтобы разработчики могли использовать простые массивы или Vector’ы.

Путь миграции

Любой код, использующий Vector, продолжит работать без проблем. Если вы реализовали собственную версию Vector, её нужно будет обновить. Самый простой подход — отрефакторить код так, чтобы он расширял MutableVector. Это будет работать как в Grafana v9, так и в v10.

Дополнительные материалы

Команды CLI grafana/toolkit удалены и перенесены в пакет create-plugin

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

Вы разрабатываете плагины с помощью команд CLI @grafana/toolkit.

Описание

Мы объявили об устаревании grafana/toolkit в v9.3 (ноябрь 2022 года), и теперь в качестве замены доступен новый инструмент под названием create-plugin. Мы призываем вас выполнить миграцию и использовать наши обновлённые инструменты. Все команды grafana/toolkit, кроме build, удалены в Grafana v10.

Вот некоторые преимущества create-plugin:

  • Более гибкий: С @grafana/create-plugin у вас больше контроля над вашими плагинами и их зависимостями, и вы можете легче настраивать инструменты под свои конкретные нужды.

  • Более быстрое время разработки: Благодаря готовой среде разработки @grafana/create-plugin может значительно сократить время разработки по сравнению с использованием @grafana/toolkit.

  • Улучшенные возможности тестирования: Тестировать плагины с @grafana/create-plugin гораздо проще благодаря рабочим процессам GitHub, которые автоматизируют запуск модульных и сквозных тестов при каждом пуше изменений в GitHub.

  • Лучшая документация: Документация по @grafana/create-plugin более полная и её легче найти, чем у @grafana/toolkit.

Путь миграции

Возможно, вы уже используете новые инструменты. Если у вас есть существующий плагин, ранее созданный с помощью @grafana/toolkit, вы можете использовать следующую команду, чтобы перенести его на новые инструменты сборки:


# Run this command from the root of your plugin

cd ./my-plugin

npx @grafana/create-plugin@latest migrate

Дополнительные материалы

Устаревшие функции

Изменение UID папки через API устарело. Эта функциональность будет удалена в будущем релизе.