Рекомендации разработчика по Databricks

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

Управление исходным кодом

Управление версиями всех файлов

Декларативная автоматизация основана на идее, что если чего-то нет в системе контроля версий, значит, этого не существует. Таким образом, Databricks рекомендует управлять версиями почти каждого файла, включая:

• Все записные книжки и исходные файлы (.py, .sql)
• Файлы конфигурации пакета (databricks.yml и YAML-переопределения для конкретной среды)

Однако не зафиксируйте:

• Создание артефактов, таких как .jar или .whl файлы. Вместо этого отправьте скомпилированные двоичные файлы в тома каталога Unity во время CI. См. загрузка JAR-файла.
• Токены или учетные данные. Используйте управление секретами на уровне рабочей области, поддерживаемое диспетчером секретов облака (например, диспетчером секретов AWS или Azure Key Vault) и синхронизируйте значения в области секретов Databricks. Дополнительные сведения см. в разделе Управление секретами.
• Примеры локальных данных и файлы с PII. Используйте .gitignore, чтобы исключить их.

Один репозиторий

Databricks рекомендует использовать единый репозиторий для всего вашего кода (исходного кода и файлов конфигурации), поскольку это упрощает совместную работу, а также обмен кодом и передовыми практиками как для людей, так и для ИИ. Если у вас несколько пакетов для отдельных жизненных циклов развертывания, сохраните их в одном репозитории.

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

Стратегия ветвления на основе ствола

Чтобы минимизировать конфликты при слиянии и гарантировать, что основная ветка всегда готова к развертыванию, используйте стратегию ветвления trunk-based.

Простой рабочий процесс:

1. Разрабатывайте локально или в рабочей области, а затем развертывайте в рабочей области Databricks для тестирования изменений.
2. Создайте кратковременную ветвь функций для обновления системы управления версиями и регулярно синхронизируйте изменения локальной или рабочей области.
3. После завершения тестирования объедините фичевую ветку в основную ветвь.
4. CI/CD автоматически развертывает основную ветвь в промежуточной рабочей области, и автоматические тесты запускаются.
5. Когда промежуточные тесты и проверки проходят, CI/CD развертывает основную ветвь в рабочей области.

Эти шаги описаны на следующей схеме:

Конфигурация рабочей области

Изоляция сред рабочей области

Изолируйте среды рабочей области, чтобы свести к минимуму влияние неудачного развертывания. Рассмотрим пример.

• Небольшие команды (до 5 инженеров данных): начните с двух рабочих областей (разработка и производство) в одной облачной учетной записи.
• Растущие команды (5+ инженеров данных): перейдите на три рабочие области (разработка, тестирование и продуктивная среда). Предпродакшн-среда должна функционально соответствовать продакшну — с той же конфигурацией сборки, схемой и критически важными интеграциями, — даже если её масштаб меньше.
• Регулируемые отрасли (банковские услуги, здравоохранение, защита): физически изолируйте рабочие области и облачные учетные записи, чтобы предотвратить утечку данных. Управление изоляцией через границы каталога IAM и Unity в одной учетной записи возможно, но обеспечивает менее надежную защиту.

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

Дополнительные сведения см. в разделе "Политики сети на основе контекста".

Изоляция хранилища данных

• Используйте единое хранилище метаданных Unity Catalog и создайте отдельные каталоги для разработки, тестирования (если применимо) и продуктивной среды, повторяя структуру вашей рабочей области.
• Используйте личные схемы для отдельных разработчиков для разработки и промежуточного (непроизводственных) каталогов.
• Привяжите производственный каталог в режиме ISOLATED только к производственной рабочей области. Установка режима изоляции каталога в значение ISOLATED гарантирует, что производственные данные будут недоступны из сред разработки или тестирования, даже если идентификационные данные настроены неправильно.
• Резервируйте отдельные хранилища метаданных, учетные записи или регионы только для организаций с нормативными требованиями, требованиями к суверенитету данных или работе в нескольких регионах, которые нельзя удовлетворить с помощью изоляции на уровне каталога.

Обрабатывать метаданные таблицы и столбца как код

Рассматривайте комментарии к таблицам и столбцам как часть своего кода. Храните их в .sqlфайлах наряду с определениями пакетов декларативной автоматизации и развертывайте их с помощью задания метаданных, чтобы точные и понятные бизнес-пользователям определения были всегда доступны. Напишите комментарии, в которых простым и понятным языком описывается, что представляет собой строка, какие используются единицы измерения и какие значения являются допустимыми, вместо того чтобы просто повторять название столбца.

Настройка личных схем

Во время разработки настройте пакеты для использования личной схемы для каждого пользователя, например dev_${user_name}. Это предотвращает перезапись разработчиками таблиц друг друга в общей рабочей области.

Использование бессерверных вычислений

Использование бессерверных вычислений для упрощения управления кластерами и оптимизации затрат. См. раздел "Подключение к бессерверным вычислениям".

Рекомендации CI/CD

Декларативные пакеты автоматизации для CI/CD

Декларативные пакеты автоматизации (ранее известные как пакеты ресурсов Databricks) предлагают мощный унифицированный подход к управлению кодом, рабочими процессами и инфраструктурой в экосистеме Databricks и рекомендуется для конвейеров CI/CD.

Дополнительные сведения об использовании пакетов для рабочих процессов CI/CD см. в статье Рабочие процессы CI/CD в Databricks.

Дополнительные сведения о декларативных пакетах автоматизации см. в разделе "Что такое декларативные пакеты автоматизации?".

Используйте Terraform только для внешних ресурсов

Используйте Terraform для определения следующих ресурсов:

• Облачные и внешние ресурсы
• Административные действия, которые не должны выполняться непривилегированными пользователями, например подготовка рабочего пространства или настройка облачной сети

Используйте декларативные пакеты автоматизации для всех других ресурсов Databricks.

Управление пакетами

Создание небольших пакетов

Databricks рекомендует разрабатывать небольшие специализированные пакеты вместо одного большого пакета.

• Поместите все, что одна команда владеет в один пакет.
• Протестируйте и разверните один и тот же конвейер CI/CD, который использует один и тот же жизненный цикл и периодичность выпуска.
• Каждый пакет должен охватывать все среды для данного проекта (разработки, промежуточного хранения, рабочей среды), а не использовать отдельные пакеты для каждой среды.

Создание отдельных пакетов для:

• Различные продукты или домены, например "Аналитика выставления счетов" и "Обнаружение мошенничества"
• Разные границы владения или разрешений
• Рабочие нагрузки с совершенно разными жизненными циклами
• Сценарии, в которых требуется независимое продвижение или откат

Используйте sync.paths для синхронизации общих папок

При управлении несколькими пакетами в одном репозитории используйте sync.paths для синхронизации общих папок за пределами корневого каталога пакета. Это позволяет разным проектам совместно использовать общую папку библиотеки, например ../common, при этом сохраняя отдельные идентификаторы развертывания.

Моделирование межпакетных зависимостей в CI/CD

Если пакет B зависит от артефактов, опубликованных пакетом A, смоделируйте эту зависимость на уровне CI/CD или оркестрации, а не объединяйте оба пакета в один.

• Сделайте процесс развертывания и публикации пакета A явным предварительным условием для пакета B. Настройте конвейер так, чтобы процесс для пакета B запускался только после успешного развертывания пакета A и прохождения всех необходимых проверок.
• Передавайте идентификаторы опубликованных ресурсов или их пути далее как входные данные конвейера и немедленно завершайте с ошибкой, если ресурсы из предыдущих этапов отсутствуют. Это гарантирует, что пакет B никогда не развертывается в частично опубликованном состоянии.

Дополнительные сведения о совместном использовании пакетов см. в разделе "Общий доступ к пакетам" и файлам пакетов.

Настраиваемые шаблоны комплектов

Используйте пользовательские шаблоны Declarative Automation Bundles в качестве стандартной отправной точки для новых проектов, чтобы каждый проект наследовал одни и те же ограничения — права доступа, тегирование, политики кластера, настройки CI/CD и базовые конфигурации экземпляров — без необходимости для каждой команды решать всё с нуля.

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

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

• Название проекта или приложения
• Параметры целевой рабочей области
• Имена каталога или схемы
• Идентификаторы субъектов-служб
• Расписания и параметры уведомлений

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

Сведения о шаблонах пользовательских пакетов и их создании см. в разделе "Декларативные шаблоны проектов пакетов автоматизации".

Предусмотрите откаты и срочные исправления

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

Во время инцидента:

1. Верните или откатите затронутый пакет до последней известной хорошей версии.
2. Используйте хотфикс только для срочных исправлений с ограниченной областью применения, которые не могут ждать стандартного процесса продвижения.
3. Сливайте любое срочное исправление обратно в основную ветвь сразу после проверки, чтобы основная ветвь оставалась единым источником истины.

Общая разработка

Использование субъектов-служб или OIDC

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

• Используйте отдельные сервисные субъекты для развертывания и для выполнения. Выделенный субъект-служба развертывания для развертываний пакетов должен иметь минимальный доступ к данным. Каждая рабочая задача или конвейер должны иметь собственный сервисный субъект, от имени которого выполняется запуск и который имеет доступ только к тем данным и ресурсам, которые необходимы этой рабочей нагрузке. Это разделение гарантирует безопасность развертываний при смене или ужесточении разрешений доступа к данным и избегает изменения инфраструктуры связи с доступом к рабочим данным.
• Регулируемые отрасли: используйте федерацию удостоверений рабочих нагрузок (OIDC) для CI/CD. Это устраняет необходимость в долговечных секретах в GitHub Actions и Azure DevOps. См. статью "Включить федерацию удостоверений рабочей нагрузки" в CI/CD.

Используйте инструменты для разработчиков Databricks

Разработка в пользовательском интерфейсе рабочей области Databricks с помощью папок Git или локальной интегрированной среды разработки. Если вы используете Visual Studio Code или совместимый форк, установите официальное расширение Databricks для:

• Навыки агента, специфичные для Databricks
• Доступ к каталогу Unity и файловой системе
• Средства удаленной разработки для запуска рабочих нагрузок в вычислительной среде Databricks

Дополнительные сведения см. в разделе "Расширение Databricks" для Visual Studio Code.

Минимизация бизнес-логики в записных книжках

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

• Python: Поместите основную логику в импортируемые модули в .pysrc/ или src/py/, а затем вызывайте эти функции из ноутбуков.
• SQL: храните запросы в файлах .sql в src/ или src/sql/ и ссылайтесь на эти файлы из заданий и конвейеров вместо встраивания SQL-кода в ноутбуки.

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

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

Передавайте контекст динамически

Избегайте статических переменных для зависимостей задач. Используйте динамические ссылки на значения, такие как {{tasks.<task_key>.values.<value_key>}}, чтобы передавать контекст времени выполнения между задачами в многоэтапной задаче.

Тестирование и наблюдаемость

Реализация уровней тестирования

Используйте три уровня тестирования, которые соответствуют тому, как ваши сборки продвигаются к промышленной эксплуатации:

1. Модульные тесты: сохраняйте бизнес-логику в импортируемых src/ модулях и покрывайте её тестами с помощью pytest или аналогичного фреймворка. Запустите их для каждого pull request, чтобы при сбоях слияние блокировалось.
2. Проверка пакета: локальное выполнение bundle validate . В CI лучше использовать bundle deploy вместо непроизводственного рабочего пространства, чтобы выявить проблемы с YAML и сопоставлением ресурсов до развертывания в рабочую среду.
3. Тесты интеграции в промежуточном режиме. После развертывания в промежуточном режиме запустите сквозные задания с проверками завершения и критически важными утверждениями качества данных, такими как подсчет строк или ожидание схемы.

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

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

Рассматривайте ведение журналов как часть развертывания

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

• Единообразно выводите структурированные журналы во всех заданиях, конвейерах и задачах. Включите имя пакета, целевую среду, имя рабочей нагрузки, идентификатор выполнения и любой бизнес-идентификатор, необходимый для трассировки сбоев.
• Отслеживайте стандартный набор операционных метрик для каждой рабочей нагрузки: состояние выполнения, длительность, количество повторных попыток и индикаторы пропускной способности или свежести, где это необходимо.
• Зафиксируйте эти соглашения в общих библиотеках, переиспользуемых определениях рабочих нагрузок или шаблонах комплектов, чтобы командам не приходилось заново создавать паттерны наблюдаемости для каждого проекта.