Pulumi Databricks リソースプロバイダー

重要

このドキュメントは廃止されており、更新されない可能性があります。

注記

この記事では、サードパーティによって開発されたPulumiについて説明します。プロバイダーに問い合わせるには、 Pulumi サポートを参照してください。

この記事では、使い慣れたプログラミング言語、ツール、エンジニアリング手法を使用して Databricks リソースを作成、配置、管理できるサードパーティのInfrastructure-as-Code (IaC) プラットフォームである Python と Pulumi を使用する方法について説明します。この記事では Python と Pulumi Databricks リソースプロバイダーの使用方法について説明しますが、 Pulumi は Python for Databricks に加えて、TypeScript、JavaScript、Go、C# などの他の言語をサポートしています。

Pulumi Databricks リソースプロバイダーは、 Databricks Terraform プロバイダーに基づいています。詳細については、「 Terraform Cloud」を参照してください。

必要条件

Pulumi アカウント。 Pulumi アカウントをまだお持ちでない場合は、Pulumi にサインアップしてください。Pulumi は個人向けで、チーム向けは無料枠を提供しています。
Python 3.6 以降。 Pythonがインストールされているかどうかを確認するには、ターミナルから、またはPowerShellを使用してコマンド python --version を実行します。 Pythonをまだインストールしていない場合は、インストールします。

注記

Python の一部のインストールでは、 pythonの代わりに python3 を使用する必要がある場合があります。その場合は、この記事全体でpython3を python に置き換えてください。

Databricks ワークスペースインスタンスの URL ( https://dbc-a1b2345c-d6e7.cloud.databricks.com.
Databricks アクセス資格情報。 Pulumi Databricks プロジェクトでは、次の Databricks 認証の種類がサポートされています。
- Databricksの個人アクセス VPN で認証する (レガシー) ( databricks:authType pat )
- OAuth を使用して Databricks へのユーザーアクセスを承認する (databricks:authType databricks-cli)

注記

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。「Databricks で管理されるパスワードのサポート終了」を参照してください。

次の手順は、Python を使用して Pulumi Databricks プロジェクトを作成する方法を示しています。純粋なクラウドプロバイダーファーストの視点からのチュートリアルについては、Pulumi ドキュメントの「 AWS の使用開始」を参照してください。プログラミング言語優先の視点からのチュートリアルについては、Pulumi のドキュメントの「Python、Node.js (JavaScript、TypeScript)、Go、.NET (C#、VB、F#)」を参照してください。

ステップ 1: Pulumi プロジェクトを作成する

この手順では、ローカルの開発マシンで、Pulumi プロジェクトに必要なディレクトリ構造を設定します。次に、このディレクトリ構造内に Pulumi プロジェクトを作成します。

ターミナルまたは PowerShell から、空のディレクトリを作成し、次の例のようにそのディレクトリに切り替えます。

Unix, Linux, and macOS
Windows

Bash
mkdir pulumi-demo
cd pulumi-demo

PowerShell
md pulumi-demo
cd pulumi-demo

Pulumi をインストールするには、オペレーティングシステムに応じて次のコマンドを実行します。

Unix, Linux
MacOS
Windows

curl を使用して Unix または Linux に Pulumi をインストールします。

Bash
curl -fsSL https://get.pulumi.com | sh

Homebrewを使用してmacOSにPulumiをインストールします。

Bash
brew install pulumi/tap/pulumi

Windows に Pulumi をインストールするには、 PowerShell を使用して Chocolatey パッケージマネージャーから昇格されたアクセス許可を使用します。

PowerShell
choco install pulumi

別の Pulumi インストールオプションについては、Pulumi のドキュメントの「ダウンロードとインストール」を参照してください。

次のコマンドを実行して、基本的な Python Pulumi プロジェクトを作成します。
Bash
```
pulumi new python
```

ヒント

また、オンラインで Pulumi アカウントから Pulumi プロジェクトを作成することもできます ( [プロジェクト] > [プロジェクトの作成 ])。ただし、Databricks のプロジェクトテンプレートはありません。

プロンプトが表示されたら、 Enter キーを押してから、Webブラウザを使用してPulumiアカウントにオンラインでサインインします(まだサインインしていない場合)。サインインしたら、ターミナルまたは PowerShell に戻ります。
プロジェクト名 の入力を求められたら、 Enter キーを押してデフォルトのプロジェクト名である pulumi-demo を受け入れます。
プロジェクトの説明 を求められたら、「A demo Python Pulumi Databricks project」と入力して Enter キーを押します。
スタック名 の入力を求められたら、 Enter キーを押してデフォルトのスタック名である dev を受け入れます。Pulumi は、 pulumi-demo ディレクトリに次のファイルとサブディレクトリを作成します。
- Pulumi.yamlこれは、Pulumi プロジェクトの設定のリストです。
- __main__.pyここには、Pulumi プロジェクト用に記述した Python コードが含まれています。
- requirements.txtこれは、Pulumi がプロジェクトにインストールするサポート Python コードパッケージの一覧です。
- .gitignoreこれは、このプロジェクトをリモート Git リポジトリにプッシュする場合に Git が無視するファイルとディレクトリの一覧です。
- venv サブディレクトリには、Pulumi がプロジェクトに使用するサポートする Python 仮想環境コードが含まれています。
プロジェクトの dev スタックの初期デプロイを実行するには、次のコマンドを実行します。
Bash
```
pulumi up
```
この更新を実行するように求められたら、上矢印キーを押して [はい ] に移動し、 Enter キーを押します。
表示される View Live リンクをコピーして、Webブラウザのアドレスバーに貼り付けると、オンラインでPulumiアカウントに移動します。 pulumi-demoプロジェクトのdevスタックのアクティビティの詳細が表示されます。スタックにはまだリソースがないため、今は見るべきものはあまりありません。これらのリソースは、次の手順で作成します。

ステップ 2: Databricks リソースを作成する

この手順では、Pulumi Databricks リソースプロバイダーを使用して、既存の Databricks ワークスペースにノートブックとそのノートブックを実行するジョブを作成します。

Pulumi が生成した __main.py__ ファイルに、任意のテキストエディターまたは統合開発環境 (IDE) を使用して次のコードを入力します。次のコードは、Pulumi Databricks ノートブックとジョブリソースとその設定を宣言します。

Python
"""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 は、この構成値を使用して、ノートブックとジョブに名前を付けます。
Bash
```
pulumi config set resource-prefix "pulumi-demo"
```
Pulumi は、__main__.py ファイルと同じディレクトリに Pulumi.dev.yaml という名前のファイルを作成し、この YAML ファイルに次のコードを追加します。
YAML
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
構成値を使用すると、コードのモジュール化と再利用性を高めることができます。これで、他のユーザーが __main__.py ファイルを再利用し、__main__.py ファイルの内容を変更せずに resource_prefix 変数に別の値を定義できるようになります。
node-typeという名前の設定値を定義し、次のコマンドを実行して、次のハードコードされた値に設定します。Pulumi は、この構成値を使用して、ジョブが実行されるクラスターのタイプを判別します。
Bash
```
pulumi config set node-type "i3.xlarge"
```
Pulumi.dev.yamlファイルの内容は、次のようになります。
YAML
```
config:
  pulumi-demo:node-type: i3.xlarge
  pulumi-demo:resource-prefix: pulumi-demo
```
Pulumi が Databricks ワークスペースで認証できるようにするには、関連するコマンドを実行して Databricks 固有の構成値を定義します。たとえば、Databricks 個人用アクセストークン認証の場合は、次のコマンドを実行します。これらのコマンドでは、次のようになります。
- <workspace-instance-url> をワークスペースインスタンスの URL に置き換えます (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com)。
- <access-token> をアクセストークンの値に置き換えます。必ず --secret オプションを指定してください。これにより、Pulumi はセキュリティのベストプラクティスとしてアクセストークンを暗号化するように指示されます。

注記

デフォルトでは、Pulumi は Pulumi サービスによって管理されるスタックごとの暗号化キーと値ごとのソルトを使用して値を暗号化します。別の暗号化プロバイダーを使用するには、Pulumi ドキュメントの「シークレット暗号化の設定」を参照してください。

Bash
pulumi config set databricks:host "<workspace-instance-url>"
pulumi config set databricks:token "<access-token>" --secret

Pulumi.dev.yamlファイルの内容は、次のようになります。

YAML
config:
  databricks:host: <your-workspace-instance-url>
  databricks:token:
    secure: <an-encrypted-version-of-your-access-token>
  pulumi-demo:node-type: i3.xlarge
  pulumi-demo:resource_prefix: pulumi-demo

別の Databricks 認証の種類を使用するには、要件を参照してください。 GitHub の Pulumi Databricks リポジトリの構成も参照してください。

ステップ 3: リソースをデプロイする

このステップでは、Pulumi Python プロジェクトテンプレートの実行の一部として、Pulumi がプロジェクトに提供する Python 仮想環境をアクティブ化します。この仮想環境は、正しいバージョンの 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`
	魚	`source venv/bin/activate.fish`
	CSH/TCSHの	`source venv/bin/activate.csh`
	PowerShell コア	`venv/bin/Activate.ps1`
Windows	cmd.exe	`venv\Scripts\activate.bat`
	PowerShell	`venv\Scripts\Activate.ps1`

次のコマンドを実行して、 Python パッケージインデックス (PyPI) から仮想環境にPulumi Databricks リソースプロバイダーをインストールします。
Bash
```
pip install pulumi-databricks
```

注記

pip のインストールによっては、pipの代わりに pip3 を使用する必要がある場合があります。その場合は、この記事全体でpip3を pip に置き換えてください。

Pulumi が作成するリソースをプレビューするには、次のコマンドを実行します。
Bash
```
pulumi preview
```
エラーが報告された場合は、エラーを修正してから、コマンドを再度実行してください。

PulumiアカウントでPulumiが何をするかについての詳細なレポートをオンラインで表示するには、表示される View Live リンクをコピーして、Webブラウザのアドレスバーに貼り付けます。
次のコマンドを実行して、リソースを作成し、Databricks ワークスペースにデプロイします。
Bash
```
pulumi up
```
この更新を実行するように求められたら、上矢印キーを押して [はい ] に移動し、 Enter キーを押します。エラーが報告された場合は、エラーを修正してから、コマンドを再度実行してください。
Pulumi アカウントで Pulumi の行動に関する詳細なレポートをオンラインで表示するには、表示される View Live リンクをコピーして、Web ブラウザーのアドレスバーに貼り付けます。

ステップ 4: リソースを操作する

この手順では、 Databricks ワークスペースでジョブを実行し、指定したノートブックを実行します。

ジョブが実行するノートブックをワークスペースで表示するには、表示される ノートブック URL リンクをコピーして、Web ブラウザーのアドレスバーに貼り付けます。
ノートブックを実行するジョブをワークスペースで表示するには、表示される ジョブ URL リンクをコピーして、Web ブラウザーのアドレスバーに貼り付けます。
ジョブを実行するには、ジョブページの [今すぐ実行 ] ボタンをクリックします。
ジョブの実行が終了したら、ジョブの実行結果を表示するには、ジョブページの [完了した実行 (過去 60 日間)] リストで、[ 開始時刻 ] 列の最新の時刻エントリをクリックします。 [出力 ] ウィンドウには、ノートブックのコードを実行した結果が表示され、1 から 10 までの数値が出力されます。

(オプション)ステップ 5: リソースに変更を加える

このオプションのステップでは、ノートブックのコードを変更し、変更したノートブックを再デプロイしてから、ジョブを使用して変更したノートブックを再実行します。

ノートブックに変更を加えない場合は、「ステップ 6: クリーンアップ」に進んでください。

__main.py__ ファイルに戻り、次のコード行を変更します。

Python
content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")

これに、ファイルを保存します。

Python
  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 が変更するリソースをプレビューするには、次のコマンドを実行します。
Bash
```
pulumi preview
```
エラーが報告された場合は、エラーを修正してから、コマンドを再度実行してください。

PulumiアカウントでPulumiが何をするかについての詳細なレポートをオンラインで表示するには、表示される View Live リンクをコピーして、Webブラウザのアドレスバーに貼り付けます。
次のコマンドを実行して、リソースの変更を Databricks ワークスペースにデプロイします。
Bash
```
pulumi up
```
この更新を実行するように求められたら、上矢印キーを押して [はい ] に移動し、 Enter キーを押します。エラーが報告された場合は、エラーを修正してから、コマンドを再度実行してください。
Pulumi アカウントで Pulumi の行動に関する詳細なレポートをオンラインで表示するには、表示される View Live リンクをコピーして、Web ブラウザーのアドレスバーに貼り付けます。
ワークスペースで変更されたノートブックを表示するには、表示される ノートブック URL リンクをコピーして、Web ブラウザーのアドレスバーに貼り付けます。
変更したノートブックでジョブを再実行するには、表示される ジョブURL リンクをコピーして、Webブラウザーのアドレスバーに貼り付けます。次に、ジョブページの「 今すぐ実行 」ボタンをクリックします。
ジョブの実行が終了したら、ジョブの実行結果を表示するには、ジョブページの [完了した実行 (過去 60 日間)] リストで、[ 開始時刻 ] 列の最新の時刻エントリをクリックします。 [出力 ] ウィンドウには、ノートブックのコードを実行した結果が表示され、指定した DataFrame の内容が出力されます。

ステップ 6: クリーンアップ

この手順では、ノートブックとジョブを Databricks ワークスペースから削除し、 pulumi-demo プロジェクトとその dev スタックを Pulumi アカウントからオンラインで削除するように Pulumi に指示します。

次のコマンドを実行して、Databricks ワークスペースからリソースを削除します。
Bash
```
pulumi destroy
```
この削除を実行するように求められたら、上矢印キーを押して [はい ] に移動し、 Enter キーを押します。
次のコマンドを実行して、Pulumi pulumi-demo プロジェクトとその dev スタックを Pulumi アカウントからオンラインで削除します。
Bash
```
pulumi stack rm dev
```
この削除を実行するように求められたら、「 dev 」と入力して Enter キーを押します。
venv Python 仮想環境を非アクティブ化するには、次のコマンドを実行します。
Bash
```
deactivate
```

テスティング

Pulumi プロジェクトは、デプロイする前にテストできます。 Pulumi ドキュメントの Pulumi プログラムのテストを参照してください。

Python ベースの Pulumi プロジェクトの単体テストでは、Python テストフレームワークの unittest と Pulumi パッケージの pulumi.runtime 名前空間を使用して、単体テストを記述して実行できます。シミュレートされたリソースに対してテストを実行するには、Pulumi (および Databricks) の呼び出しをモックに置き換えます。Pulumi ドキュメントの「Pulumi プログラムのユニットテスト」を参照してください。

次の infra.py という名前のサンプルファイルは、この記事の main.py ファイルで宣言されたノートブックとジョブの実装をモックしています。この例のユニットテストでは、ノートブックの Base64 でエンコードされたコンテンツ、ジョブの名前、および成功したジョブ実行の Eメール受信者がすべて期待値を返すかどうかを確認します。そのため、ここでは、関連するプロパティのみが例の値でモックされます。また、必要なリソースプロパティ値は、単体テストで使用する予定がない場合でも、常に指定する必要があります。この例では、これらの必須値はランダムな my-mock- 値に設定され、それらの値はテストされません。

Python
# 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 、関連するプロパティが期待値を返すかどうかをテストします。

Python
# 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
python -m unittest

実行できる他の種類のテストに関する情報については、Pulumi ドキュメントの次の記事を参照してください。

必要条件​

ステップ 1: Pulumi プロジェクトを作成する​

ステップ 2: Databricks リソースを作成する​

ステップ 3: リソースをデプロイする​

ステップ 4: リソースを操作する​

(オプション)ステップ 5: リソースに変更を加える​

ステップ 6: クリーンアップ​

テスティング​

その他のリソース​