Поставщик ресурсов Pulumi Databricks

Статья
07/09/2024

Примечание.

В этой статье описывается решение Pulumi, которое не предоставляется и не поддерживается Databricks. Чтобы связаться с поставщиком, обратитесь в службу поддержки Pulumi.

В этой статье показано, как использовать Python и Pulumi, стороннюю платформу IaC (инфраструктура как код), которая позволяет создавать, развертывать ресурсы Azure Databricks и управлять ими с помощью знакомых языков программирования, инструментов и технических методик. Хотя в этой статье описано, как использовать Python и поставщик ресурсов Pulumi Databricks, Pulumi поддерживает другие языки в дополнение к Python для Azure Databricks, включая TypeScript, JavaScript, Go и C#.

В основе поставщика ресурсов Pulumi Databricks лежит поставщик Databricks Terraform. Дополнительные сведения см. в разделе Terraform Cloud.

Требования

Учетная запись Pulumi. Зарегистрируйтесь в Pulumi, если у вас еще нет учетной записи Pulumi. Платформа Pulumi предоставляется бесплатно для частных лиц и предлагает бесплатный уровень для команд.
Python 3.6 или более поздней версии. Чтобы проверить, установлен ли Python, выполните команду python --version в терминале или в среде PowerShell. Установите Python, если он еще не установлен.

Примечание.

Для некоторых установок Python может потребоваться использовать python3 вместо python. В этом случае замените python на python3 во всей статье.
Например, URL-адресhttps://adb-1234567890123456.7.azuredatabricks.net azure Databricks для каждой рабочей области.
Учетные данные доступа к Azure Databricks. Проекты Pulumi Databricks поддерживают следующие типы проверки подлинности Azure Databricks:
- Проверка подлинности маркера личного доступа Azure Databricks (databricks:authType pat)
- Проверка подлинности управляемых удостоверений Azure (databricks:authType azure-msi)
- Проверка подлинности субъекта-службы MS Entra (databricks:authType azure-client-secret)
- Проверка подлинности Azure CLI (databricks:authType azure-cli)

Ниже показано, как создать проект Pulumi Databricks с помощью Python. Руководство с точки зрения поставщика облачных служб см. в разделе Приступая к работе с Azure в документации по Pulumi. Руководство с точки зрения языка программирования см. в разделах Python, Node.js (JavaScript, TypeScript), Go и .NET (C#, VB, F#) в документации по Pulumi.

Шаг 1. Создание проекта Pulumi

На этом шаге вы настроите необходимую структуру каталогов для проекта Pulumi на локальном компьютере разработки. Затем вы создадите проект Pulumi в этой структуре каталогов.

В терминале или с помощью PowerShell создайте пустой каталог, а затем перейдите в него, например, выполнив следующие команды:

Unix, Linux и macOS
```
mkdir pulumi-demo
cd pulumi-demo
```
Windows
```
md pulumi-demo
cd pulumi-demo
```
Установите Pulumi, выполнив следующую команду в зависимости от операционной системы:

Unix, Linux

Установите Pulumi в Unix или Linux с помощью curl:
```
curl -fsSL https://get.pulumi.com | sh
```
MacOS

Установите Pulumi в macOS с помощью Homebrew:
```
brew install pulumi/tap/pulumi
```
Windows

Установите Pulumi в Windows с помощью PowerShell с повышенными привилегиями, используя диспетчер пакетов Chocolatey:
```
choco install pulumi
```
Альтернативные варианты установки Pulumi см. в разделе Скачивание и установка в документации по Pulumi.
Создайте простой проект Python Pulumi, выполнив следующую команду:
```
pulumi new python
```
Совет

Вы также можете создать проект Pulumi из учетной записи Pulumi в Интернете (Проекты > Создать проект). Однако шаблон проекта для Azure Databricks для этой учетной записи отсутствует.
При появлении запроса нажмите клавишу ВВОД, а затем войдите в свою учетную запись Pulumi в Интернете в браузере, если вы еще этого не сделали. После входа в систему вернитесь в терминал или PowerShell.
При появлении запроса на ввод имени проекта примите имя проекта по умолчанию pulumi-demo, нажав клавишу ВВОД.
При появлении запроса на ввод описания проекта введите A demo Python Pulumi Databricks project и нажмите клавишу ВВОД.
При появлении запроса на ввод имени стека примите имя стека по умолчанию dev, нажав клавишу ВВОД. Pulumi создает следующие файлы и подкаталог в каталоге pulumi-demo:
- Файл Pulumi.yaml, содержащий список параметров для проекта Pulumi.
- Файл __main__.py, содержащий код Python для проекта Pulumi.
- Файл requirements.txt, содержащий список поддерживаемых пакетов кода Python, устанавливаемых Pulumi для вашего проекта.
- Файл .gitignore, содержащий список файлов и каталогов, которые Git игнорирует, если вы хотите отправить этот проект в удаленный репозиторий Git.
- Подкаталог venv содержит вспомогательный код виртуальной среды Python, которую Pulumi использует для вашего проекта.
Выполните начальное развертывание стека проекта dev, выполнив следующую команду:
```
pulumi up
```
При появлении запроса на обновление нажмите клавишу "стрелка вверх", чтобы перейти к варианту да, а затем нажмите клавишу ВВОД.
Скопируйте отображаемую ссылку Просмотреть и вставьте ее в адресную строку веб-браузера. При переходе по этой ссылке будет открыта учетная запись Pulumi в Интернете. Будут показаны сведения об активности стека dev для вашего проекта pulumi-demo. Пока ничего особенного не происходит, потому что в вашем стеке еще нет ресурсов. Эти ресурсы будут созданы на следующем шаге.

Шаг 2. Создание ресурсов Databricks

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

Откройте созданный Pulumi файл __main.py__ в подходящем текстовом редакторе или в интегрированной среде разработки (IDE) и введите следующий код. Этот код объявляет в Pulumi Databricks ресурсы Записная книжка и Задание, а также их параметры:

"""A Python Pulumi program"""

import pulumi
from pulumi_databricks import *
from base64 import b64encode

# Get the authenticated user's workspace home directory path and email address.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/getcurrentuser
user_home_path     = get_current_user().home
user_email_address = get_current_user().user_name

# Define the name prefix to prepend to the resource names that are created
# for the Notebook and Job resources. To do this, you can use a Pulumi
# configuration value instead of hard-coding the name prefix in this file.
#
# To set a Pulumi configuration value, run the following command, which sets
# a "resource-prefix" configuration value to "pulumi-demo" in the
# associated "Pulumi.<stack-name>.yaml" configuration file:
#
# pulumi config set resource-prefix "pulumi-demo"
#
# For more information about defining and retrieving hard-coded values, see
# https://www.pulumi.com/docs/intro/concepts/config
config = pulumi.config.Config()
resource_prefix = config.require('resource-prefix')

# Define cluster resource settings.
node_type = config.require('node-type')

# Create a Notebook resource.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/notebook
# This example adds a single cell to the notebook, which is constructed from
# a single base64-encoded string. In practice, you would replace this:
#
# language       = "PYTHON",
# content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
#
# With this:
#
# source         = "path/to/local/my-notebook.py"
#
# To provide more notebook content easier and faster. Also, the notebook's language
# is automatically detected. If you specify a notebook path, be sure that it does
# not end in .ipynb, as Pulumi relies on the workspace import API, which doesn't
# rely on any specific extensions such as .ipynb in the notebook path.
notebook = Notebook(
  resource_name  = f"{resource_prefix}-notebook",
  path           = f"{user_home_path}/Pulumi/{resource_prefix}-notebook.py",
  language       = 'PYTHON',
  content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
)

# Export the URL of the Notebook, so that you can easily browse to it later.
# See https://www.pulumi.com/docs/intro/concepts/stack/#outputs
pulumi.export('Notebook URL', notebook.url)

# Create a Job resource.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/job
# This job uses the most recent Databricks Runtime long-term support (LTS)
# runtime programmatic version ID at the time this article was first published,
# which is 14.3.x-scala2.12. You can replace this with a later version.
job = Job(
  resource_name = f"{resource_prefix}-job",
  name = f"{resource_prefix}-job",
  tasks = [
    JobTaskArgs(
      task_key = f"{resource_prefix}-task",
      new_cluster   = JobNewClusterArgs(
        num_workers   = 1,
        spark_version = "14.3.x-scala2.12",
        node_type_id  = node_type
      ),
      notebook_task = JobNotebookTaskArgs(
        notebook_path = f"{user_home_path}/Pulumi/{resource_prefix}-notebook.py"
      )
    )
  ],
  email_notifications = JobEmailNotificationsArgs(
    on_successes = [ user_email_address ],
    on_failures  = [ user_email_address ]
  )
)

# Export the URL of the Job, so that you can easily browse to it later.
# See https://www.pulumi.com/docs/intro/concepts/stack/#outputs
pulumi.export('Job URL', job.url)

Определите параметр конфигурации с именем resource-prefix и присвойте ему жестко закодированное значение pulumi-demo, выполнив следующую команду. Pulumi использует этот параметр конфигурации для присвоения имени записной книжке и заданию:
```
pulumi config set resource-prefix "pulumi-demo"
```
Pulumi создает файл с именем Pulumi.dev.yaml в том же каталоге, в котором находится файл __main__.py, и добавляет следующий код в этот файл YAML:
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
Использование параметров конфигурации позволяет сделать код более модульным и использовать его повторно. Теперь другой пользователь может повторно использовать ваш файл __main__.py и определить другое значение переменной resource_prefix, не изменяя содержимое файла __main__.py.
Определите параметр конфигурации с именем node-type и присвойте ему следующее жестко закодированное значение, выполнив следующую команду. Pulumi использует этот параметр конфигурации для определения типа кластера, в котором выполняется задание.
```
pulumi config set node-type "Standard_D3_v2"
```
Содержимое файла Pulumi.dev.yaml теперь выглядит следующим образом:
```
config:
  pulumi-demo:node-type: Standard_D3_v2
  pulumi-demo:resource-prefix: pulumi-demo
```
Чтобы включить проверку подлинности Pulumi в рабочей области Azure Databricks, определите определенные значения конфигурации Azure Databricks, выполнив связанные команды. Например, для проверки подлинности маркера личного доступа Azure Databricks выполните следующие команды. В этих командах:
- Замените <workspace-instance-url> URL-адрес рабочей области, напримерhttps://adb-1234567890123456.7.azuredatabricks.net.
- Замените <access-token> на значение маркера доступа. Не забудьте указать параметр --secret. Этот параметр означает, что Pulumi должен зашифровать маркер доступа в соответствии с рекомендацией по обеспечению безопасности.
  
  Примечание.
  
  По умолчанию Pulumi шифрует значения, используя ключи шифрования для каждого стека, управляемые службой Pulumi, и соль для каждого значения. Если вы хотите использовать альтернативного поставщика шифрования, обратитесь к разделу Настройка шифрования секретов в документации по Pulumi.
```
pulumi config set databricks:host "<workspace-instance-url>"
pulumi config set databricks:token "<access-token>" --secret
```
Содержимое файла Pulumi.dev.yaml теперь выглядит следующим образом:
```
config:
  databricks:host: <your-workspace-instance-url>
  databricks:token:
    secure: <an-encrypted-version-of-your-access-token>
  pulumi-demo:node-type: Standard_D3_v2
  pulumi-demo:resource_prefix: pulumi-demo
```
Сведения об использовании другого типа проверки подлинности Azure Databricks см. в разделе "Требования". См. также раздел "Конфигурация" в репозитории Pulumi Databricks в GitHub.

Шаг 3. Развертывание ресурсов

На этом шаге вы активируете виртуальную среду Python, которую Pulumi предоставляет для проекта в рамках запуска шаблона проекта Python Pulumi. Эта виртуальная среда обеспечивает использование правильной версии Python, Pulumi и поставщика ресурсов Pulumi Databricks. Существует несколько платформ виртуальных сред Python, это такие платформы как venv, virtualenv и pipenv. В этой статье и в этом шаблоне проекта Pulumi Python используется venv. venv уже входит в состав Python. Дополнительные сведения см. в разделе Создание виртуальных сред.

Активируйте виртуальную среду Python, выполнив следующую команду в каталоге pulumi-demo в зависимости от типа операционной системы и оболочки:

Платформа	Shell	Команда для активации виртуальной среды
Unix, Linux, macOS	bash/zsh	`source venv/bin/activate`
	fish	`source venv/bin/activate.fish`
	csh/tcsh	`source venv/bin/activate.csh`
	PowerShell Core	`venv/bin/Activate.ps1`
Windows	cmd.exe	`venv\Scripts\activate.bat`
	PowerShell	`venv\Scripts\Activate.ps1`

Установите поставщик ресурсов Pulumi Databricks из списка пакетов Python (PyPI) в виртуальной среде, выполнив следующую команду:
```
pip install pulumi-databricks
```
Примечание.

Для некоторых установок pip может потребоваться использовать pip3 вместо pip. В этом случае замените pip на pip3 во всей статье.
Просмотрите ресурсы, созданные Pulumi, выполнив следующую команду:
```
pulumi preview
```
При наличии ошибок исправьте их, а затем снова выполните команду.

Чтобы просмотреть подробный отчет о действиях Pulumi, в учетной записи Pulumi в Интернете, скопируйте отображаемую ссылку Просмотреть и вставьте ее в адресную строку веб-браузера.
Создайте и разверните ресурсы в рабочей области Azure Databricks, выполнив следующую команду:
```
pulumi up
```
При появлении запроса на обновление нажмите клавишу "стрелка вверх", чтобы перейти к варианту да, а затем нажмите клавишу ВВОД. При наличии ошибок исправьте их, а затем снова выполните команду.
Чтобы просмотреть подробный отчет о действиях Pulumi, в учетной записи Pulumi в Интернете, скопируйте отображаемую ссылку Просмотреть и вставьте ее в адресную строку веб-браузера.

Шаг 4. Взаимодействие с ресурсами

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

Чтобы просмотреть записную книжку, которую задание запустит в рабочей области, скопируйте ссылку URL-адрес записной книжки и вставьте ее в адресную строку веб-браузера.
Чтобы просмотреть задание, которое запускает записную книжку в рабочей области, скопируйте ссылку URL-адрес задания и вставьте ее в адресную строку веб-браузера.
Чтобы запустить задание, нажмите кнопку Запустить на странице задания.
Чтобы просмотреть результаты выполнения задания после завершения задания, в списке Завершенные запуски (за последние 60 дней) на странице задания щелкните последнюю запись по времени в столбце Время начала. На панели Выходные данные появится результат выполнения кода записной книжки. Этот код выводит числа от 1 до 10.

(Необязательно) Шаг 5. Внесение изменений в ресурс

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

Если вы не хотите вносить изменения в записную книжку, перейдите к Шагу 6. Очистка.

Вернитесь в файл __main.py__ и измените следующую строку кода:
```
content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
```
Укажите следующее содержимое вместо этой строки, а затем сохраните файл:
```
  content_base64 = b64encode(b'''
data = [
         { "Category": 'A', "ID": 1, "Value": 121.44 },
         { "Category": 'B', "ID": 2, "Value": 300.01 },
         { "Category": 'C', "ID": 3, "Value": 10.99 },
         { "Category": 'E', "ID": 4, "Value": 33.87}
       ]

df = spark.createDataFrame(data)

display(df)
''').decode("UTF-8")
```
Это изменение предписывает записной книжке распечатать содержимое указанного кадра данных вместо чисел от 1 до 10.

Примечание.

Убедитесь, что строки кода начинаются data и заканчиваются ''').decode("UTF-8") краем редактора кода. В противном случае Pulumi вставляет дополнительное пространство пробелов в записную книжку, которая может привести к сбою запуска нового кода Python.
При необходимости просмотрите ресурс, который будет изменен Pulumi, выполнив следующую команду:
```
pulumi preview
```
При наличии ошибок исправьте их, а затем снова выполните команду.

Чтобы просмотреть подробный отчет о действиях Pulumi, в учетной записи Pulumi в Интернете, скопируйте отображаемую ссылку Просмотреть и вставьте ее в адресную строку веб-браузера.
Разверните изменение ресурса в рабочей области Azure Databricks, выполнив следующую команду:
```
pulumi up
```
При появлении запроса на обновление нажмите клавишу "стрелка вверх", чтобы перейти к варианту да, а затем нажмите клавишу ВВОД. При наличии ошибок исправьте их, а затем снова выполните команду.
Чтобы просмотреть подробный отчет о действиях Pulumi, в учетной записи Pulumi в Интернете, скопируйте отображаемую ссылку Просмотреть и вставьте ее в адресную строку веб-браузера.
Чтобы просмотреть измененную записную книжку в рабочей области, скопируйте ссылку URL-адрес записной книжки и вставьте ее в адресную строку веб-браузера.
Чтобы перезапустить задание с измененной записной книжкой, скопируйте ссылку URL-адрес задания и вставьте ее в адресную строку веб-браузера. Затем нажмите кнопку Запустить на странице задания.
Чтобы просмотреть результаты выполнения задания после завершения задания, в списке Завершенные запуски (за последние 60 дней) на странице задания щелкните последнюю запись по времени в столбце Время начала. На панели Выходные данные отображается результат выполнения кода записной книжки. Этот код выводит содержимое указанного кадра данных.

Шаг 6. Очистка

На этом шаге вы указываете Pulumi удалить записную книжку и задание из рабочей области Azure Databricks, а также удалить проект pulumi-demo и его стек dev из учетной записи Pulumi в Интернете.

Удалите ресурсы из рабочей области Azure Databricks, выполнив следующую команду:
```
pulumi destroy
```
При появлении запроса на удаление нажмите клавишу "стрелка вверх", чтобы перейти к варианту да, а затем нажмите клавишу ВВОД.
Удалите проект Pulumi pulumi-demo и его стек dev из учетной записи Pulumi в Интернете, выполнив следующую команду:
```
pulumi stack rm dev
```
При появлении запроса на удаление введите dev и нажмите клавишу ВВОД.
Чтобы отключить виртуальную среду Python venv, выполните следующую команду:
```
deactivate
```

Тестирование

Перед развертыванием проекта Pulumi вы можете протестировать проект Pulumi. См. статью "Тестирование программ Pulumi" в документации по Pulumi.

Для модульного тестирования проектов Pulumi на основе Python можно создавать и запускать модульные тесты с помощью модульного теста Python вместе с пространством имен pulumi.runtime пакета Pulumi.runtime. Чтобы выполнить тесты для имитированных ресурсов, замените вызовы Pulumi (и Azure Databricks) макетами. Ознакомьтесь с программами Модульного тестирования Pulumi в документации по Pulumi.

Следующий пример файла с именем макетирует infra.py реализацию записной книжки и задания, объявленных в файле этой статьи main.py . Модульные тесты в этом примере проверяют, выполняется ли содержимое записной книжки в кодировке Base64, имя задания и получатель электронной почты для успешного задания выполняет все ожидаемые значения. Таким образом, только эти связанные свойства смеются здесь с примерами значений. Кроме того, обязательные значения свойств ресурсов всегда должны быть предоставлены, даже если вы не планируете использовать их в модульных тестах. В этом примере эти обязательные значения задаются случайными my-mock- значениями, и эти значения не проверяются.

# infra.py

from pulumi_databricks import (
  Notebook,
  Job,
  JobEmailNotificationsArgs
)

notebook = Notebook(
  resource_name  = 'my-mock-notebook-resource-name',
  path           = 'my-mock-notebook-path',
  content_base64 = 'ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp'
)

job = Job(
  resource_name = 'my-mock-job-resource-name',
  name          = 'pulumi-demo-job',
  email_notifications = JobEmailNotificationsArgs(
    on_successes = [ 'someone@example.com' ]
  )
)

В следующем примере файла test_main.py проверяется, возвращают ли связанные свойства ожидаемые значения.

# test_main.py

import pulumi
from pulumi_databricks import *
import unittest
import infra

# Set up mocking.
class MyMocks(pulumi.runtime.Mocks):
  def new_resource(self, type_, name, inputs, provider, id_):
    return [name + '_id', inputs]

  def call(self, token, args, provider):
    return {}

pulumi.runtime.set_mocks(MyMocks())

class TestNotebookAndJob(unittest.TestCase):
  @pulumi.runtime.test
  def test_notebook(self):
    def check_notebook_content_base64(args):
      content_base64 = args
      # Does the notebook's Base64-encoded content match the expected value?
      self.assertIn('ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp', content_base64)

    # Pass the mocked notebook's content_base64 property value to the test.
    return pulumi.Output.all(infra.notebook.content_base64).apply(check_notebook_content_base64)

  @pulumi.runtime.test
  def test_job(self):
    def check_job_name_and_email_onsuccesses(args):
      name, email_notifications = args
      # Does the job's name match the expected value?
      self.assertIn('pulumi-demo-job', name)
      # Does the email address for successful job runs match the expected value?
      self.assertIn('someone@example.com', email_notifications['on_successes'])

    # Pass into the test the mocked job's property values for the job's name
    # and the job's email address for successful runs.
    return pulumi.Output.all(
      infra.job.name,
      infra.job.email_notifications
    ).apply(check_job_name_and_email_onsuccesses)

Чтобы выполнить эти тесты и отобразить результаты теста, выполните следующую команду из корневого каталога проекта Pulumi:

python -m unittest

Сведения о других типах тестов, которые можно запустить, см. в следующих статьях документации по Pulumi:

Поделиться через

Поставщик ресурсов Pulumi Databricks

Требования

Шаг 1. Создание проекта Pulumi

Unix, Linux и macOS

Windows

Unix, Linux

MacOS