Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Как кодbreadcrumb arrow Наблюдаемость как кодbreadcrumb arrow Синхронизация Gitbreadcrumb arrow Key concepts

Ключевые концепции Git Sync

Note

Функциональность Git Sync постоянно развивается. Свяжитесь с Grafana для получения поддержки или чтобы сообщить о любых проблемах, с которыми вы столкнётесь, и помочь нам улучшить эту функцию.

Ключевые компоненты Git Sync

Прежде чем начать использовать Git Sync, разберитесь, как связаны ключевые компоненты Git Sync:

Экземпляр Grafana

Экземпляр Grafana — это работающий сервер Grafana. Несколько экземпляров могут:

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

Репозиторий Git

Репозиторий Git — это внешнее хранилище, с которым вы хотите синхронизировать ваш экземпляр Grafana. Вы можете организовать свой репозиторий Git несколькими способами:

  • Одна ветка, несколько путей: используйте разные каталоги для разных целей. Например, dev/, prod/ или team-a/.
  • Несколько веток: используйте разные ветки для разных сред или команд. Например, main, develop или team-a.
  • Несколько репозиториев: используйте отдельные репозитории для разных команд или сред.

Гибкая конфигурация репозиториев Git Sync

Репозитории Git Sync поддерживают различные комбинации URL репозитория, ветки и пути:

  • Разные репозитории Git: каждая среда или команда может использовать собственный репозиторий.
    • Экземпляр A: repository: your-org/grafana-prod.
    • Экземпляр B: repository: your-org/grafana-dev.
  • Разные ветки: используйте отдельные ветки внутри одного репозитория.
    • Экземпляр A: repository: your-org/grafana-manifests, branch: main.
    • Экземпляр B: repository: your-org/grafana-manifests, branch: develop.
  • Разные пути: используйте разные пути каталогов внутри одного репозитория.
    • Экземпляр A: repository: your-org/grafana-manifests, branch: main, path: production/.
    • Экземпляр B: repository: your-org/grafana-manifests, branch: main, path: development/.
  • Любая комбинация: комбинируйте по своему усмотрению в зависимости от требований вашего рабочего процесса.

Ресурс репозитория Git Sync

Ресурс репозитория — это объект конфигурации Grafana, который определяет связь между группой репозиториев и вашим экземпляром Grafana через Git Sync.

  • С каким репозиторием Git синхронизировать ваш экземпляр Grafana.
  • Какую ветку использовать.
  • Какой путь каталога синхронизировать.
  • Поведение синхронизации и рабочие процессы.

Каждый ресурс репозитория создаёт двунаправленную синхронизацию между экземпляром Grafana и конкретным местом в Git.

Ресурс подключения Git Sync

Подключение — это настройка аутентификации между Grafana и внешним провайдером Git, необходимая, когда вы не используете персональный токен доступа (Personal Access Token) или статический токен для аутентификации. Используйте его для авторизации доступа к вашим внешним репозиториям и для генерации или обновления учётных данных для Git Sync. Одно подключение можно переиспользовать для нескольких репозиториев.

Например, если вы используете GitHub App для аутентификации, подключение представляет установку приложения. Grafana использует это подключение для аутентификации в GitHub, создания токенов доступа и авторизации доступа к репозиториям от вашего имени.

Ресурс подключения включает:

  • Конфигурацию внешнего провайдера: механизм аутентификации, который Grafana использует для связи с провайдером Git (например, GitHub App).
  • Авторизацию или установку у провайдера: авторизованную сущность, позволяющую Grafana запрашивать токены у провайдера.
  • Область доступа к репозиториям: набор репозиториев, к которым подключению (а значит, и Grafana) разрешён доступ у провайдера Git.

Как ведёт себя Git Sync?

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

  1. Grafana отслеживает указанное место в Git (репозиторий, ветку и путь).
  2. Grafana создаёт папку в разделе Dashboards (обычно с именем репозитория).
  3. Grafana создаёт дашборды из JSON-файлов дашбордов в Git внутри этой папки.
  4. Grafana фиксирует изменения дашбордов, сделанные в интерфейсе, обратно в Git.
  5. Grafana подтягивает изменения дашбордов, сделанные в Git, и обновляет дашборды в интерфейсе.
  6. Синхронизация происходит через регулярные интервалы (настраиваемые) или мгновенно, если вы используете вебхуки.

Вы можете найти выделенные дашборды, организованные в папки, в разделе Dashboards.

Цели синхронизации

С Git Sync вы можете размещать синхронизированные ресурсы в Grafana двумя способами:

  • Синхронизация с папкой: Grafana создаёт папку с именем репозитория и помещает все синхронизированные ресурсы внутрь неё. Подкаталоги в репозитории становятся подпапками внутри этой папки. Это поведение по умолчанию.
  • Синхронизация без папки: Grafana размещает синхронизированные ресурсы на верхнем уровне, не создавая обёрточную папку. Файлы в корне пути репозитория становятся ресурсами верхнего уровня, а подкаталоги — папками верхнего уровня.

Используйте синхронизацию с папкой, чтобы держать ресурсы каждого репозитория сгруппированными в выделенной папке. Используйте синхронизацию без папки, когда вы хотите, чтобы выделенные ресурсы отображались в верхней части представления Dashboards, а не были вложены в папку репозитория.

Оба режима могут сосуществовать друг с другом и с ресурсами, не управляемыми Git Sync.

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

Репозиторий grafana-manifests синхронизируется из пути grafana/:

your-org/grafana-manifests/
└── grafana/
    ├── cpu-metrics.json
    └── team-platform/
        ├── _folder.json
        └── memory-usage.json

Файл _folder.json хранит стабильный UID и отображаемое имя папки team-platform, поэтому папка сохраняет свою идентичность и права, если вы переместите или переименуете её в репозитории. Подробности см. в разделе Файл метаданных папки Git Sync.

На экземпляре также есть содержимое, не управляемое Git Sync: созданная вручную папка Ops и Ad-hoc dashboard.

При синхронизации с папкой папка репозитория оборачивает синхронизированные ресурсы, наряду с невыделенным содержимым:

Dashboards
├── 📁 grafana-manifests/      ← managed by Git Sync
│   ├── CPU Metrics Dashboard
│   └── 📁 team-platform/
│       └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

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

Dashboards
├── CPU Metrics Dashboard      ← managed by Git Sync
├── 📁 team-platform/          ← managed by Git Sync
│   └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

Синхронизация без папки управляет только теми ресурсами, которые она выделяет. Невыделенные папка Ops и Ad-hoc dashboard остаются нетронутыми.

Несколько репозиториев без папок

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

Dashboards
├── CPU Metrics Dashboard      ← managed by grafana-manifests
├── 📁 team-platform/          ← managed by grafana-manifests
│   └── Memory Usage Dashboard
├── Billing Overview           ← managed by finance-dashboards
├── 📁 invoices/               ← managed by finance-dashboards
│   └── Monthly Invoices
└── Ad-hoc dashboard           ← not managed by Git Sync

Состояния Git Sync

Ваш экземпляр Grafana может находиться в одном из следующих состояний Git Sync:

  • Не выделен: ни один из ресурсов экземпляра не управляется Git Sync.
  • Частично выделен: некоторые ресурсы контролируются Git Sync.
  • Полностью выделен: все поддерживаемые типы ресурсов управляются Git Sync. Неподдерживаемые ресурсы не управляются.

Пример: связь между репозиторием, веткой и путём

Вот пример, показывающий, как концепции репозитория, ветки и пути работают вместе:

Конфигурация:

  • Репозиторий: your-org/grafana-manifests
  • Ветка: main
  • Путь: team-platform/grafana/

В Git (в ветке main):

your-org/grafana-manifests/
├── .git/
├── README.md
├── team-platform/
│   └── grafana/
│       ├── cpu-metrics.json       ← Synced
│       ├── memory-usage.json      ← Synced
│       └── disk-io.json           ← Synced
├── team-data/
│   └── grafana/
│       └── pipeline-stats.json    ← Not synced (different path)
└── other-files.txt                ← Not synced (outside path)

В представлении Dashboards в Grafana:

Dashboards
└── 📁 grafana-manifests/
    ├── CPU Metrics Dashboard
    ├── Memory Usage Dashboard
    └── Disk I/O Dashboard

Ключевые выводы:

  • Grafana синхронизирует только файлы внутри указанного пути (team-platform/grafana/).
  • Grafana игнорирует файлы в других путях или в корне репозитория.
  • Имя папки в Grafana берётся из имени репозитория.
  • Заголовки дашбордов берутся из содержимого JSON-файла, а не из имени файла.