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

Тестовые песочницы с Git Sync

Используйте ветку-песочницу, в которую пользователи могут пушить напрямую, не открывая pull request для каждого изменения. Ветка-песочница — это среда с низким порогом входа для краткосрочных проектов и экспериментов, при этом каждый дашборд остаётся под контролем версий в Git. Когда работа готова, вы переносите её в ветку main.

Песочница — это ветка в том же репозитории, синхронизированная с Grafana с включённым рабочим процессом write. В режиме write сохранение дашборда фиксируется напрямую в ветке-песочнице, поэтому процесс редактирования ощущается почти как работа в Grafana без Git Sync. Разница в том, что каждое изменение всё равно фиксируется в Git, поэтому ничего не теряется и история сохраняется.

В этом сценарии используется одна общая ветка-песочница, в которой работают все. Общая песочница использует только одно подключение Repository независимо от того, сколько пользователей в ней работает, что позволяет оставаться в рамках ограничения в 10 подключений к репозиториям на стек. Если вам нужна более строгая изоляция, можно вместо этого выделить каждому пользователю собственную ветку-песочницу. См. Индивидуальные или общие песочницы.

Когда использовать

  • Краткосрочные проекты: вам нужно временное пространство для работы, которая может попасть в production, а может и не попасть.
  • Совместные эксперименты: команда свободно экспериментирует в одном пространстве, не затрагивая общие production-дашборды.
  • Быстрая итерация: вы хотите получить низкий порог входа при редактировании, как в экземпляре без provisioning, но с безопасностью истории Git.
  • Поэтапный перенос: вы разрабатываете в песочнице, а затем переносите завершённую работу в ветку main.

Архитектура

┌────────────────────────────────────────────────────────────┐
│              GitHub Repository                             │
│   Repository: your-org/grafana-manifests                 │
│                                                            │
│   Branch: main       ← Promoted, reviewed work            │
│   └── grafana/                                             │
│       ├── dashboard-stable.json                            │
│       └── dashboard-approved.json                          │
│                                                            │
│   Branch: sandbox    ← Direct pushes, shared experiments  │
│   └── grafana/                                             │
│       ├── alice/dashboard-wip.json                         │
│       └── bob/dashboard-test.json                          │
└────────────────────────────────────────────────────────────┘
                        ↕
              Git Sync (write workflow)
                        ↕
              ┌─────────────────────────┐
              │    Grafana Instance     │
              │                         │
              │  Repository Resource:   │
              │  - branch: sandbox      │
              │  - path: grafana/       │
              │  - workflows: [write]   │
              │                         │
              │  Save = direct commit   │
              │  to sandbox             │
              └─────────────────────────┘

Структура репозитория

В Git:

your-org/grafana-manifests
├── (branch: main)
│   └── grafana/
│       ├── dashboard-stable.json
│       └── dashboard-approved.json
└── (branch: sandbox)
    └── grafana/
        ├── alice/
        │   └── dashboard-wip.json
        └── bob/
            └── dashboard-test.json

В представлении Dashboards в Grafana (синхронизировано с sandbox):

Dashboards
└── 📁 grafana-manifests/
    ├── 📁 alice/
    │   └── Work in Progress Dashboard
    └── 📁 bob/
        └── Test Dashboard
  • Папка с именем «grafana-manifests» (по имени репозитория) содержит дашборды, синхронизированные из ветки-песочницы.
  • Пользователи могут создавать внутри неё подпапки, например alice/ и bob/, чтобы разделить свою работу в общей ветке. Подпапки соответствуют подкаталогам внутри синхронизируемого пути, поэтому дополнительное подключение Repository не требуется.
  • В экземпляре отображаются только дашборды из настроенной ветки и пути.
  • Сохранение дашборда фиксируется напрямую в ветке-песочнице.

Параметры конфигурации

Настройте ресурс Repository на синхронизацию с веткой-песочницей и включите рабочий процесс write:

  • Repository: your-org/grafana-manifests
  • Branch: sandbox
  • Path: grafana/
  • Workflows: write

В ресурсе Repository это выглядит так:

YAML 
spec:
  github:
    url: 'https://github.com/your-org/grafana-manifests'
    branch: 'sandbox'
    path: grafana/
  workflows:
    - write

Note

Если вы включите только рабочий процесс write, сохранение дашборда всегда будет фиксироваться напрямую в ветке-песочнице. Чтобы также разрешить пользователям открывать pull request из Grafana, добавьте рабочий процесс branch: workflows: [write, branch]. Подробности см. в разделе Параметры конфигурации.

Как это работает

  1. Создайте ветку-песочницу в своём репозитории, например sandbox.
  2. Настройте ресурс Repository, который синхронизирует эту ветку с включённым рабочим процессом write.
  3. Пользователи создают и редактируют дашборды в Grafana, по желанию — в своей подпапке. Каждое сохранение фиксируется напрямую в ветке-песочнице.
  4. Всё ощущается примерно так же, как работа в Grafana без Git Sync, но каждое изменение фиксируется в Git.
  5. Когда работа готова, вы переносите её в ветку main. См. Перенос песочницы в main.

Индивидуальные или общие песочницы

Песочница может быть общей для всех или привязана к одному пользователю. Каждая песочница — это ветка, синхронизируемая через собственное подключение Repository, поэтому выбор ограничен лимитом в 10 подключений к репозиториям на стек. Подробности см. в разделе Ограничения по использованию и производительности.

  • Общая песочница (рекомендуется): используйте одну ветку, например sandbox, синхронизируемую через одно подключение Repository, которое используют все пользователи. При этом расходуется только одно подключение независимо от того, сколько пользователей в ней работает, поэтому такая схема масштабируется на любое число пользователей. Разделите работу пользователей с помощью подпапок (например, alice/, bob/), если хотите упорядочить её внутри общей ветки. Плата за это — меньшая изоляция, поскольку все коммитят в одну ветку. Это и есть конфигурация, описанная выше.
  • Индивидуальные песочницы: выделите каждому пользователю собственную ветку, например sandbox/alice и sandbox/bob, каждую — через отдельное подключение Repository. Это обеспечивает максимальную изоляцию, но каждая песочница расходует одно из ваших 10 подключений, поэтому песочницы на пользователя не масштабируются на большое число пользователей. Оставляйте их для небольшого числа активных пользователей или краткосрочных проектов и удаляйте ветку и её подключение по завершении работы, чтобы освободить подключение.

Оба подхода переносятся в main одинаково. См. Перенос песочницы в main.

Защита веток-песочниц

Хотя ветки-песочницы допускают прямые пуши, защитите их от деструктивных операций. Мы рекомендуем заблокировать принудительные пуши (force push) в ветках-песочницах на стороне вашего Git-провайдера.

Принудительные пуши перезаписывают историю ветки и могут незаметно отбросить коммиты, на которые опирается Git Sync. Их блокировка сохраняет историю дописываемой (append-only), поэтому Grafana и Git остаются согласованными, и вы всегда можете проследить, как дашборд пришёл к текущему состоянию.

  • GitHub: добавьте правило защиты ветки (или набор правил) для ветки-песочницы (например, sandbox или шаблон sandbox/*, если вы используете индивидуальные песочницы) и отключите Allow force pushes.
  • GitLab: сделайте ветки-песочницы защищёнными и запретите принудительный push.
  • Bitbucket: добавьте разрешение для ветки-песочницы, запрещающее перезапись истории.

Обычно pull request в ветках-песочницах остаются необязательными, чтобы пользователи могли пушить напрямую, при этом принудительные пуши всё равно блокируются.

Перенос песочницы в main

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

Вариант 1: открыть pull request из ветки-песочницы (рекомендуется)

Используйте своего Git-провайдера, чтобы открыть pull request из ветки-песочницы в main.

  1. В своём Git-провайдере откройте pull request из sandbox в main.
  2. Проверьте изменения как обычный diff Git и запросите согласования при необходимости.
  3. Выполните слияние pull request. Экземпляр, синхронизирующий main, подхватит перенесённые дашборды при следующей синхронизации.

Так сохраняется полная история ревью и аудита для всего, что попадает в main, и это рекомендуемый путь, когда main питает production.

Если вы также включите рабочий процесс branch для ресурса Repository песочницы, пользователи смогут открывать такие pull request напрямую из Grafana при сохранении, не переключаясь на Git-провайдера.

Вариант 2: выборочный перенос (cherry-pick) или слияние отдельных изменений

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

  1. Выполните cherry-pick нужных коммитов из ветки-песочницы в ветку, основанную на main, либо скопируйте конкретные файлы дашбордов.
  2. Откройте pull request в main и проверьте его.
  3. Выполните слияние, чтобы завершить перенос.

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

Вариант 3: перенос через отдельный экземпляр или путь

Когда main синхронизирован с production-экземпляром, рассматривайте песочницу как этап разработки в процессе переноса.

  1. Разрабатывайте в экземпляре песочницы (синхронизированном с веткой-песочницей в режиме write).
  2. Перенесите одобренные дашборды в main с помощью pull request (вариант 1) или скопировав файлы в путь main.
  3. Production-экземпляр, синхронизирующий main, обновится автоматически.

Это повторяет сценарий сред разработки и промышленной эксплуатации, где ветка-песочница выступает в роли этапа разработки.

Вариант 4: перенос из интерфейса Grafana

Если ветка main синхронизирована с папкой в том же экземпляре (через второе подключение Repository) или с отдельным экземпляром, пользователи могут переместить дашборд в неё прямо из Grafana, не затрагивая Git:

  • Save a copy: откройте дашборд из песочницы, выберите Save as (сохранить копию) и укажите в качестве назначения папку, связанную с веткой main. Git Sync зафиксирует копию в main.
  • Import dashboard: экспортируйте дашборд из песочницы (Export как JSON), затем воспользуйтесь Dashboards > New > Import и сохраните его в папку, связанную с веткой main. Git Sync зафиксирует его в main.

Это подходит пользователям, предпочитающим работать исключительно в интерфейсе. Учтите, что эти пути фиксируют изменения в main без pull request, поэтому используйте их только там, где main допускает прямую запись; если для main требуется ревью, предпочтите вариант 1.

После переноса можно удалить краткосрочные ветки-песочницы либо сохранить долгоживущую общую песочницу и продолжать итерации.

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

Для получения дополнительной информации обратитесь к следующим документам: