Преобразование конвейера в проект пакета

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

Учебник, использующий databricks pipelines команды для создания проекта конвейеров, а затем развертывает и запускает конвейер, см. в разделе "Разработка конвейеров с помощью декларативных пакетов автоматизации".

Обзор процесса преобразования

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

Ниже приведены действия по преобразованию существующего конвейера в пакет:

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

Требования

Перед началом работы необходимо следующее:

Шаг 1. Настройка папки для проекта пакета

У вас должен быть доступ к репозиторию Git, который настроен в Azure Databricks в качестве папки Git. Вы создадите проект пакета в этом репозитории, который будет использовать контроль исходного кода и станет доступным для других участников через Git в соответствующей рабочей области Azure Databricks. (Дополнительные сведения о папках Git см. в папках Azure Databricks Git.)

  1. Перейдите в корень клонированного репозитория Git на локальном компьютере.

  2. В соответствующем месте в иерархии папок создайте папку специально для проекта пакета. Рассмотрим пример.

    mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle

  3. Измените текущий рабочий каталог на эту новую папку. Рассмотрим пример.

    cd ~/source/my-pipelines/ingestion/events/my-bundle

  4. Инициализировать новый пакет, выполнив команду:

    databricks bundle init

    Ответьте на запросы. После завершения проекта у вас будет файл конфигурации проекта с именем databricks.yml в новой домашней папке проекта. Этот файл необходим для развертывания конвейера из командной строки. Дополнительные сведения об этом файле конфигурации см. в разделе "Декларативная конфигурация пакетов автоматизации".

Шаг 2. Создание конфигурации конвейера

В этом новом каталоге в клонированном дереве папок вашего репозитория Git выполните CLI Databricks команду bundle generate, указав идентификатор вашего конвейера, используя следующий формат <pipeline-id>:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

При выполнении generate команды он создает файл конфигурации пакета для конвейера в папке пакета resources и скачивает все указанные артефакты в папку src . ( --profile или -p флаг) является необязательным, но если у вас есть определенный профиль конфигурации Databricks (определенный в .databrickscfg файле, созданном при установке интерфейса командной строки Databricks), который вы предпочитаете использовать вместо профиля по умолчанию, укажите его в этой команде. Для получения информации о профилях конфигурации Databricks см. раздел Профили конфигурации Azure Databricks.

Подсказка

Если у вас есть существующий проект Декларативного конвейера Spark (SDP) (он содержит spark-pipeline.yml файл), можно скопировать этот проект конвейера в src папку пакета, а затем использовать databricks pipelines generate команду для создания конфигурации пакета. См. databricks pipelines generate.

Шаг 3. Просмотр файлов проекта пакета

Когда команда bundle generate завершится, она создаст две новые папки:

  • resources — это подкаталог проекта, содержащий файлы конфигурации проекта.
  • src — это папка проекта, в которой хранятся исходные файлы, такие как запросы и записные книжки.

Команда также создает некоторые дополнительные файлы:

  • *.pipeline.yml в подкаталоге resources. Этот файл содержит определенную конфигурацию и параметры для конвейера.
  • Исходные файлы, такие как SQL-запросы, в подкаталоге src, скопированные из вашего существующего конвейера.
├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Шаг 4. Привязка конвейера пакета к существующему конвейеру

Необходимо связать или привязать определение конвейера в пакете к существующему конвейеру, чтобы сохранить его в актуальном состоянии при внесении изменений. Для этого выполните команду bundle deployment bind CLI Databricks:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> — это имя конвейера. Это имя должно совпадать со значением строки с префиксом имени файла для конфигурации конвейера в новом каталоге resources. Например, если у вас есть файл конфигурации конвейера с именем ingestion_data_pipeline.pipeline.yml в папке resources, необходимо указать ingestion_data_pipeline в качестве имени конвейера.

<pipeline-ID> — это идентификатор конвейера. Он совпадает с тем, который вы скопировали в рамках требований для этих инструкций.

Шаг 5. Развертывание конвейера с помощью нового пакета

Теперь разверните пакет вашего конвейера в целевом рабочем пространстве с помощью команды Databricks CLI bundle deploy:

databricks bundle deploy --target <target-name> --profile <profile-name>

Флаг --target является обязательным и должен быть задан строкой, которая соответствует настроенной целевой рабочей области, например development или production.

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

Продвигайте в разных условиях с целями

Bundle определяет именованные среды развертывания, называемые целями в databricks.yml, каждая из которых указывает на своё рабочее пространство, каталог и значения переменных. Цели — как вы продвигаете один и тот же пайплайн через разработку, стадирование и продакшн, развертывая одинаковый исходный код в каждой последующей среде без его редактирования:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Параметр mode, заданный для каждой цели, изменяет поведение при её развертывании:

  • mode: development помечает объект как личное тестовое развертывание. Ресурсы получают [dev username] префикс, а расписания по умолчанию приостановлены, так что ваша работа не влияет на других.
  • mode: production Отключает эти стандартные настройки безопасности. В сочетании с run_as это позволяет запускать конвейер от имени сервисного субъекта, а не через личную учетную запись пользователя, поэтому его выполнение не прерывается, если кто-то уходит из команды или меняет роль. Azure Databricks рекомендует сервисный принципал для staging и production. service_principal_name принимает идентификатор приложения главного сервиса, а не его отображаемое имя. Вы можете получить ID приложения со страницы главного сервиса в настройках администратора рабочего пространства.

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

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

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Вместо того чтобы жёстко кодировать имена каталогов или пути исходного кода для каждой среды внутри кода трансформации, передайте значения от целевого кода, чтобы один и тот же исходный код работал без изменений везде. То, как вы их устанавливаете, зависит от исходного языка. Параметры конвейера применимы только к исходному коду SQL. Для исходного кода Python используйте поле pipeline configuration и читайте значения с помощью spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Для получения дополнительной информации о параметризации кода конвейера см. раздел «Использовать параметры с конвейерами».

Настройте CI/CD

Поскольку конвертированный конвейер полностью определяется как пакет (YAML плюс исходные файлы в Git), установка непрерывной интеграции и непрерывной доставки (CI/CD) для него означает запуск команд bundle из системы CI, такой как GitHub Actions или Azure DevOps. При каждом запросе на включение изменений запускается базовый набор проверок:

  1. pytest для ваших функций преобразования, пригодных для модульного тестирования. См . модульное тестирование конвейеров.
  2. databricks bundle validate --target <env> для обнаружения ошибок конфигурации.
  3. При необходимости можно использовать databricks bundle run в тестовой цели, чтобы проверить ожидания на выборочных данных.

Следующий рабочий процесс GitHub Actions развёртывается при слиянии в main, используя федерацию OpenID Connect (OIDC) вместо сохранённого токена:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Ограничите производственное развертывание за ручным одобрением (например, вторая задача, требующая одобрения GitHub Environment, или отдельный этап в Azure DevOps), чтобы человек явно одобрял каждое повышение. Производственная задача выполняется databricks bundle deploy --target prod с использованием принципа сервиса, направленного на рабочее пространство производства. Подробнее см. CI/CD на Azure Databricks.

Устранение неполадок

Проблема Solution
Ошибка "databricks.yml не найдена" при выполнении bundle generate В настоящее время bundle generate команда не создает файл конфигурации пакета (databricks.yml) автоматически. Необходимо создать файл с помощью databricks bundle init или вручную.
Существующие параметры конвейера не соответствуют значениям в конфигурации YAML созданного конвейера. Идентификатор конвейера не отображается в файле YML конфигурации пакета. Если вы заметите, что какие-либо другие настройки отсутствуют, вы можете применить их вручную.

Советы для успеха

  • Всегда используйте управление версиями. Если вы не используете папки Databricks Git, сохраните подкаталоги проекта и файлы в репозитории Git или другой управляемой версией репозитории или файловой системе.
  • Протестируйте конвейер в нерабокой среде (например, среде разработки или тестирования) перед развертыванием в рабочей среде. Легко ввести неправильное настройку случайно.

Дополнительные ресурсы

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

  • Last updated on