Документация Grafana Документация GlaberGraph Как код Наблюдаемость как код Синхронизация Git Add non-provisioned resources

Добавление невыделенных ресурсов из Grafana

С существующими невыделенными ресурсами можно сделать две разные вещи, и ведут они себя по-разному:

• Выборочное копирование отдельных дашбордов: добавление копии выбранного дашборда в выделенную папку. Grafana создаёт новый дашборд с новым UID; оригинал остаётся нетронутым, и существующие ссылки продолжают указывать на него. Это самый простой вариант, и он не требует ничего удалять.
• Миграция существующих дашбордов: перемещение существующих дашбордов под управление Git Sync с сохранением их UID, чтобы существующие ссылки и обращения продолжали работать. Этот вариант требует дополнительной осторожности, поскольку он перенимает ресурс на месте и требует удаления исходного ресурса.

Выборочное копирование отдельных дашбордов

Используйте эти методы, чтобы добавить копию одного или нескольких дашбордов в выделенную папку. Каждая копия создаётся с новым UID, поэтому исходные дашборды остаются точно такими же, и ничего удалять не нужно. Существующие ссылки продолжают указывать на исходные дашборды, а не на копии.

• Добавление дашборда через Import dashboards
• Копирование существующего дашборда из интерфейса Grafana

Добавление дашборда через Import dashboards

Вы можете импортировать дашборды непосредственно в свои выделенные папки Git Sync, используя интерфейс Grafana или HTTP API.

Чтобы открыть инструмент Import dashboard из интерфейса Git Sync:

1. Перейдите на вкладку Dashboards вашего подключения.
2. В правом верхнем углу нажмите New.
3. Выберите Import dashboard, и вы будете перенаправлены в мастер.
4. Загрузите или вставьте JSON дашборда.
5. Заполните соответствующие поля, включая ветку и папку репозитория, и нажмите Import.
6. Откройте pull request, следуйте своему обычному рабочему процессу и выполните слияние. Учтите, что импортированный дашборд может появиться лишь через несколько минут.

Учитывайте следующее:

• Импорт обычного JSON дашборда создаёт новый дашборд с новым UID. Чтобы вместо этого сохранить исходный UID (для миграции), укажите UID в мастере или импортируйте файл ресурса, в котором уже задан metadata.name. См. раздел Миграция существующих дашбордов.
• UID глобально уникальны в пределах организации. Два репозитория с дашбордами, имеющими одинаковый UID, будут конфликтовать.
• Два дашборда могут иметь одинаковый заголовок, если они находятся по разным путям в репозитории. Если файл с таким же именем уже существует по целевому пути, импорт останавливается до того, как что-либо перезапишется.

Дополнительную информацию см. в разделе Импорт дашбордов документации Data Visualization.

Копирование существующего дашборда из интерфейса Grafana

Вы также можете сохранить копию дашборда непосредственно из интерфейса Grafana в свою выделенную папку. Это создаёт новый дашборд с новым UID и оставляет оригинал на месте.

Для этого выполните следующие шаги:

1. Убедитесь, что дашборд находится в режиме Editable.
2. Выберите Save или Save as в правом верхнем углу.
3. В меню:
   • Target folder: выберите выделенную папку в интерфейсе Grafana, в которую хотите сохранить дашборд.
   • Branch: введите имя ветки выделенного репозитория, в которой хотите работать, или создайте новую ветку. Прямая фиксация в main не поддерживается.
   • Folder: введите папку в вашем синхронизированном репозитории, если она есть.
   • Заполните остальные поля соответствующим образом.
4. Нажмите Save.
5. В вашем синхронизированном репозитории GitHub выполните слияние ветки с дашбордом, который хотите синхронизировать.

Миграция существующих дашбордов в Git Sync

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

Миграция состоит из следующих шагов:

1. Прежде чем начать: создайте резервную копию экземпляра и разберитесь, чем управляет Git Sync.
2. Шаг 1: Экспорт ресурсов в ваш репозиторий: экспортируйте с сохранением UID и зафиксируйте изменения.
3. Шаг 2: Удаление исходных дашбордов: обязательно, чтобы Git Sync мог перенять каждый дашборд по UID.
4. Шаг 3: Проверка миграции: убедитесь, что ресурсы синхронизированы, прежде чем двигаться дальше.

Прежде чем начать

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

Git Sync создаёт собственные папки, когда синхронизируется с вашим существующим репозиторием. Он выводит UID каждой папки из её пути в репозитории, поэтому создаваемые им папки — это новые папки, не зависящие от ваших существующих, даже если у них одинаковое имя. Как следствие:

• Вам не нужно удалять исходные папки, чтобы мигрировать находящиеся в них дашборды.
• Не удаляйте папку, содержащую алерты или панели-библиотеки. Git Sync ими не управляет, и удаление папки удалит их безвозвратно.

Чтобы мигрировать безопасно, учитывайте следующее:

• Сначала создайте резервную копию экземпляра. Экспортируйте или сделайте снимок ваших дашбордов, папок, правил алертинга и панелей-библиотек, прежде чем что-либо удалять. Удалённые ресурсы невозможно восстановить из интерфейса Grafana.
• Мигрируйте папку за папкой. Начните с одной папки, полностью завершите её миграцию и проверьте результат, прежде чем переходить к следующей. Это ограничивает последствия, если что-то пойдёт не так, и позволяет привыкнуть к процессу.
• Сохраните исходные папки и отделите их. После миграции у вас останется исходная папка (с алертами и панелями-библиотеками) рядом с новой папкой Git Sync с таким же именем. Чтобы избежать путаницы, переименуйте исходные папки или переместите их в одну папку верхнего уровня Alerts & Library Panels. Это сохраняет неподдерживаемые ресурсы нетронутыми и чётко отделёнными от выделенных дашбордов. Если вместо этого вам нужно, чтобы ссылки на исходные папки продолжали работать, см. раздел Сохранение ссылок на исходные папки.

Шаг 1: Экспорт ресурсов в ваш репозиторий

Экспортируйте дашборды, которые хотите мигрировать, так, чтобы каждый файл сохранял исходный UID дашборда (metadata.name), затем зафиксируйте файлы в вашем репозитории Git. Вы можете использовать любой из следующих способов:

• Экспорт с помощью Grafana CLI
• Экспорт в виде JSON-файла ресурса

Экспорт с помощью Grafana CLI

Вы можете экспортировать существующие дашборды из терминала или из агентных инструментов программирования с помощью CLI gcx. С gcx вы можете загрузить ресурсы, которые хотите синхронизировать, из Grafana, а затем зафиксировать и отправить эти файлы в ваш выделенный репозиторий Git. После этого Git Sync обнаружит коммит и синхронизируется с Grafana.

Чтобы экспортировать дашборды с помощью gcx, выполните следующие шаги:

1. Настройте контекст gcx так, чтобы он указывал на ваш экземпляр, как описано в разделе Defining contexts.

2. Извлеките ресурсы, которые хотите синхронизировать, из экземпляра в ваш локальный репозиторий:

   Copy

   gcx resources pull dashboards --path <REPO_PATH>

3. Зафиксируйте и отправьте ресурсы в ваш репозиторий Git:

   Copy

   git add <DASHBOARDS_PATH>
   git commit -m "Add dashboards from Grafana"
   git push

   Где:

   • <GIT_REPO>: путь к репозиторию, синхронизированному с Git Sync
   • <DASHBOARDS_PATH>: путь, по которому находятся дашборды, которые вы хотите экспортировать. Путь к дашбордам должен находиться внутри репозитория

После того как вы зафиксируете ресурсы, перейдите к Шагу 2.

Экспорт в виде JSON-файла ресурса

Чтобы экспортировать дашборд в виде JSON-файла ресурса, вам нужно:

1. Экспортировать дашборд как JSON.
2. Преобразовать его в формат Custom Resource Definition (CRD), требуемый Grafana App Platform.
3. Зафиксировать преобразованный файл в вашем репозитории Git.

После того как вы зафиксируете файл, перейдите к Шагу 2.

Чтобы экспортировать дашборд в виде JSON-файла, он должен соответствовать следующей структуре CRD:

YAML Copy

{
  'apiVersion': 'dashboard.grafana.app/v1',
  'kind': 'Dashboard',
  'metadata': { 'name': 'dcf2lve9akj8xsd' },
  'spec': { /* Original dashboard JSON goes here */ },
}

Структура включает:

• apiVersion: указывает версию API. Поддерживаются как классическая модель JSON, так и модель v2. Дополнительную информацию см. в разделе Модель JSON дашборда.
• kind: определяет тип ресурса. Например, dashboard.
• metadata: содержит идентификатор дашборда name, который должен совпадать с исходным UID дашборда, чтобы Git Sync мог его перенять. Идентификатор можно найти в URL дашборда или в экспортированном JSON.
• spec: оборачивает исходный JSON вашего дашборда.

Шаг 2: Удаление исходных дашбордов

Поскольку экспортированные файлы сохраняют исходный UID, Git Sync не перенимает дашборд, пока в Grafana существует неуправляемый дашборд с таким же UID (metadata.name). Удалите каждый исходный дашборд, который вы мигрируете, чтобы Git Sync смог занять его UID.

Удаляя дашборд, учитывайте следующее:

• Удалённые ресурсы невозможно восстановить из интерфейса.
• История версий дашборда не переносится.
• Вам нужно заново применить пользовательские права на папки. Дополнительные сведения см. в разделе Права и контроль доступа Git Sync.

Шаг 3: Проверка миграции

1. Запустите новое извлечение, чтобы завершить синхронизацию. Дашборды пересоздаются как выделенные, с их исходными UID, поэтому существующие ссылки продолжают работать.
2. Убедитесь, что каждый дашборд появляется в выделенной папке и открывается корректно. Изменения могут появиться через несколько минут; если этого не произошло, обновите интерфейс вручную.
3. Убедитесь, что правила алертинга и панели-библиотеки в ваших исходных папках всё ещё на месте и работают.

После того как вы проверили одну папку, повторите процесс для следующей, пока миграция не будет завершена.

Сохранение ссылок на исходные папки

По умолчанию Git Sync присваивает каждой синхронизированной папке новый UID, производный от её пути в репозитории. Это означает, что ссылки и URL, указывающие на ваши исходные папки, продолжают указывать на исходные папки, а не на новые выделенные.

Если вам нужно, чтобы существующие ссылки и URL папок разрешались в выделенные папки, вы можете закрепить UID папки с помощью файла метаданных папки, чтобы Git Sync переиспользовал UID исходной папки.

Чтобы переиспользовать UID исходной папки, добавьте файл _folder.json в каталог этой папки в репозитории:

JSON Copy

{
  "apiVersion": "folder.grafana.app/v1beta1",
  "kind": "Folder",
  "metadata": { "name": "<ORIGINAL_FOLDER_UID>" },
  "spec": { "title": "<FOLDER_TITLE>" }
}

Где <ORIGINAL_FOLDER_UID> — это UID вашей существующей папки. Его можно найти в URL папки.

Поскольку этот вариант переиспользует UID исходной папки, синхронизированная папка конфликтует с вашей существующей неуправляемой папкой, и Git Sync не может занять UID, который всё ещё принадлежит неуправляемой папке, — синхронизация завершится ошибкой конфликта. Чтобы не потерять неподдерживаемые ресурсы, выполните эти шаги для каждой папки до синхронизации:

1. Создайте новую папку и переместите в неё все правила алертинга, панели-библиотеки и другие неподдерживаемые ресурсы из исходной папки.
2. Удалите исходную папку. Её дашборды должны быть уже экспортированы в репозиторий на Шаге 1.
3. Заново примените любые пользовательские права к новой выделенной папке — права на папки не переносятся. См. раздел Права и контроль доступа Git Sync.

Работа с дашбордами, управляемыми Git

После того как вы сохранили дашборд в Git, он будет синхронизироваться автоматически, и вы сможете работать с ним как с любым другим выделенным ресурсом. Дополнительную информацию см. в разделе Работа с выделенными дашбордами.