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 クラウド」を参照してください。

要件

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

注

Python のインストールによっては、 pythonの代わりに python3 を使用する必要がある場合があります。その場合は、この記事全体で python3 python に置き換えてください。
Databricks ワークスペースインスタンスの URL( https://1234567890123456.7.gcp.databricks.comなど)。
Databricks のアクセス資格情報。 Pulumi Databricks プロジェクトでは、次の Databricks 認証の種類がサポートされています。
- Databricks personal アクセストークン認証 (databricks:authType pat)
GitHub の Pulumi Databricks リポジトリの「構成」を参照してください。

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

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

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

ターミナルまたはPowerShellから、空のディレクトリを作成し、次のように切り替えます。
mkdir pulumi-demo cd pulumi-demo
md pulumi-demo cd pulumi-demo
オペレーティングシステムに応じて、次のコマンドを実行してPulumiをインストールします。
Unix または Linux に Pulumi をインストールするには、 curl を使用します。
curl -fsSL https://get.pulumi.com | sh
自作を使用してmacOSにプルミをインストールします。
brew install pulumi/tap/pulumi
Chocolatey パッケージマネージャーを使用して昇格されたアクセス許可を持つ PowerShell を使用して、Windows に Pulumi をインストールします。
choco install pulumi
代替の Pulumi インストールオプションについては、Pulumi ドキュメントの「ダウンロードとインストール」を参照してください。
次のコマンドを実行して、基本的な Python Pulumi プロジェクトを作成します。
```
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 スタックの初期デプロイを実行します。
```
pulumi up
```
この更新を実行するように求められたら、上方向キーを押して [はい ] に移動し、 Enter キーを押します。
表示される [ライブを表示 ] リンクをコピーして Web ブラウザーのアドレスバーに貼り付けると、オンラインで Pulumi アカウントに移動します。 pulumi-demo プロジェクトの dev スタックのアクティビティの詳細が表示されます。スタックにはまだリソースがないため、現在見るものはあまりありません。これらのリソースは次のステップで作成します。

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

このステップでは、Pulumi Databricks リソースプロバイダーを使用して、既存の 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 は、 __main__.py ファイルと同じディレクトリに Pulumi.dev.yaml という名前のファイルを作成し、この YAML ファイルに次のコードを追加します。
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
構成値を使用すると、コードのモジュール化と再利用性が向上します。これで、他のユーザーが __main__.py ファイルを再利用し、 __main__.py ファイルの内容を変更せずに resource_prefix 変数に別の値を定義できます。
node-typeという名前の構成値を定義し、次のコマンドを実行して、次のハードコーディングされた値に設定します。Pulumi は、この構成値を使用して、ジョブが実行されるクラスターのタイプを判別します。
```
pulumi config set node-type "n1-standard-4"
```
Pulumi.dev.yaml ファイルの内容は次のようになります。
```
config:
  pulumi-demo:node-type: n1-standard-4
  pulumi-demo:resource-prefix: pulumi-demo
```
Pulumi が Databricks ワークスペースで認証できるようにするには、関連するコマンドを実行して Databricks 固有の構成値を定義します。たとえば、Databricks 個人用アクセストークン認証の場合は、次のコマンドを実行します。これらのコマンドでは、次のようになります。
- <workspace-instance-url> をワークスペースインスタンスの URL(https://1234567890123456.7.gcp.databricks.comなど) に置き換えます。
- <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: n1-standard-4
  pulumi-demo:resource_prefix: pulumi-demo
```
別の Databricks 認証の種類を使用するには、「要件」を参照してください。 GitHub の Pulumi Databricks リポジトリの「構成」も参照してください。

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

このステップでは、Pulumi Python プロジェクトテンプレートの実行の一環として、Pulumi がプロジェクトに提供する Python 仮想環境をアクティブ化します。この仮想環境は、正しいバージョンの Python、Pulumi、および Pulumi Databricks リソースプロバイダーを一緒に使用していることを確認するのに役立ちます。 venv、virtualenv、 pipenv など、いくつかの Python 仮想環境フレームワークが利用可能です。この記事と Pulumi Python プロジェクトテンプレートでは、 venvを使用します。 venv はすでに Python に含まれています。詳細については、「仮想環境の作成」を参照してください。

オペレーティングシステムとシェルタイプに応じて、 pulumi-demo ディレクトリから次のコマンドを実行して、Python仮想環境をアクティブ化します。

プラットホーム	シェル	仮想環境をアクティブにするコマンド
Unix, Linux, macOS	バッシュ/ZSH	`source venv/bin/activate`
	魚	`source venv/bin/activate.fish`
	csh/tcsh	`source venv/bin/activate.csh`
	PowerShell Core	`venv/bin/Activate.ps1`
Windows	うん.exe	`venv\Scripts\activate.bat`
	PowerShell	`venv\Scripts\Activate.ps1`

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

pip のインストールによっては、 pipの代わりに pip3 を使用する必要がある場合があります。その場合は、この記事全体で pip3 pip に置き換えてください。
Pulumi が作成するリソースをプレビューするには、次のコマンドを実行します。
```
pulumi preview
```
エラーが報告された場合は、それらを修正してからコマンドを再実行します。

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

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

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

ジョブがワークスペースで実行されるノートブックを表示するには、表示される [ノートブック URL ] リンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ワークスペースでノートブックを実行するジョブを表示するには、表示される [ ジョブ URL ] リンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ジョブを実行するには、ジョブページの [ 今すぐ実行 ] ボタンをクリックします。
ジョブの実行が完了したら、ジョブの実行結果を表示するには、ジョブページの [完了した実行 (過去 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 までの数字ではなく、指定された DataFrame の内容を印刷するように指示されます。

注

data で始まり ''').decode("UTF-8") で終わるコード行が、コードエディターの端に揃っていることを確認します。そうしないと、Pulumi はノートブックに追加の空白を挿入し、新しい Python コードの実行が失敗する可能性があります。
必要に応じて、次のコマンドを実行して、Pulumi が変更するリソースをプレビューします。
```
pulumi preview
```
エラーが報告された場合は、それらを修正してからコマンドを再実行します。

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

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

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

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

テスティング

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

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

次のinfra.pyという名前のサンプルファイルは、この記事のmain.pyファイルで宣言されたノートブックとジョブの実装をモック化します。この例の単体テストでは、小説、ジョブの名前、およびジョブ実行が成功した場合の E メール受信者の 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 リソース プロバイダー

要件