GitOps для Apache Superset

В современном data-стеке «дрейф дашбордов» — ситуация, когда метрики в BI постепенно расходятся с источником правды — это постоянная угроза. В распределённых командах, которые работают в разных часовых поясах, ручные правки в UI Apache Superset быстро приводят к несогласованным метрикам, сломанным графикам и отсутствию аудита изменений.

Чтобы с этим справиться, мы построили GitOps-процесс для Superset. Относясь к датасетам как к коду, мы получили единый источник правды, автоматические quality gates и прозрачную сертификацию, которые удерживают продакшн-дашборды в надёжном состоянии.

1. Философия: Git как источник авторитета

Переход на GitOps был мотивирован пятью ключевыми требованиями:

• Единый источник правды — GitHub-репозиторий является авторитетным источником для всех продакшн-датасетов.
• Версионирование и audit trail — любое изменение колонки, метрики или SQL фиксируется через Pull Request.
• Автоматические quality gates — ни один «ломающий» SQL или некорректный Jinja не должен попасть в прод.
• Видимая сертификация — бейдж в UI Superset ведёт прямо на последний успешный запуск GitHub Actions.
• Блокировка UI — после сертификации через Git датасет становится read-only в интерфейсе, чтобы исключить ручные правки.

2. Архитектура репозитория

Мы зеркалируем структуру датасетов Superset внутри репозитория. Каждый датасет лежит в папке, имя которой совпадает с его dataset_id.

Структура файлов

datasets/
└── 34/
    ├── dataset.json              # Основные метаданные (ID, БД, схема, таблица)
    ├── columns.json              # Физические и простые виртуальные колонки
    ├── calculated_columns.json   # Сложные виртуальные колонки с логикой
    ├── metrics.json              # Сохранённые метрики (SQL-выражения и подписи)
    └── sql.sql                   # Исходный SQL для виртуальных датасетов (с Jinja)

Пример dataset.json

{
  "dataset_id": 34,
  "description": "Core store reference table",
  "database_id": 14,
  "schema": "b2b",
  "table_name": "All_stores_summary"
}

3. Пайплайн валидации из четырёх шагов

Каждый Pull Request запускает workflow в GitHub Actions. Чтобы фидбэк приходил быстро, мы через git diff определяем и валидируем только изменённые папки датасетов.

Шаг 1 — валидация структуры

Система проверяет, что имя папки совпадает с внутренним dataset_id, и контролирует наличие обязательных файлов. Затем выполняется JSON schema validation: типы и длины полей проверяются до любого обращения к API.

Шаг 2 — перекрёстная валидация

Этот шаг гарантирует внутреннюю консистентность файлов датасета:

• Ссылаются ли выражения метрик на колонки, которые действительно существуют в columns.json?
• Совпадает ли table_name из метаданных с тем, что используется в SQL-файле?

Шаг 3 — разбор Jinja-шаблонов

Superset использует Jinja для динамической фильтрации (например, {{ current_user_id() }}), поэтому мы парсим SQL через Python-библиотеку jinja2. Это ловит синтаксические ошибки и ошибки вложенности, которые иначе упали бы уже во время рендера дашборда.

Шаг 4 — SQL-линт через SQLFluff

Мы внедрили жёсткий SQL-стайлгайд на базе SQLFluff с диалектом Postgres. Ключевые правила:

• AM08 — запрещены неявные cross join.
• ST11 — запрещены неиспользуемые join.
• AM06 — запрещены неоднозначные ссылки на колонки.
• Стандартизация — никаких SELECT * и жёсткие лимиты сложности.

4. Интеграция с UI и сертификация

Если пайплайн проходит, деплой-джоба отправляет PATCH-запрос в API Superset. Мы используем штатные поля сертификации Superset, чтобы замкнуть контур:

{
  "certification": {
    "certified_by": "GitHub Action",
    "details": "https://github.com/org/repo/actions/runs/XXXXXX"
  }
}

Что видит пользователь

В нашем кастомном форке Superset у датасета появляется бейдж сертификации. При наведении пользователь видит прямую ссылку на конкретный запуск GitHub Action, который подтвердил этот код. Сам датасет в UI становится read-only, так что любые дальнейшие изменения идут только через установленный PR-процесс.

5. Результаты и стратегия

Главные эффекты

• Доверие — стейкхолдеры могут проверить, когда и как метрика обновлялась в последний раз.
• Стабильность — −90% обращений по «сломанным дашбордам», вызванным ручными правками метаданных.
• Скорость — селективный CI выдаёт аналитикам обратную связь за секунды.

Сложности и следующие шаги

Главный вызов — адопция. Переход от GUI к Git-процессу — это культурный сдвиг для многих аналитиков. Мы разрабатываем внутренние «UI-помощники», чтобы переход к Git был максимально бесшовным.

Кому это подходит

Схема оптимальна для self-hosted Superset и дата-инжиниринговых команд, которые тонут в рутине. Мы используем кастомный форк ради блокировки UI, но около 80% этого процесса можно собрать на ванильном Superset — через REST API и стандартные поля метаданных.

Также в X

Коротко о том же процессе — тред.