Terraform CDK Databricks プロバイダー

[アーティクル]
05/01/2024

注意

この記事では、Databricks で提供もサポートもされていない Cloud Development Kit for Terraform (CDKTF) について説明します。プロバイダーに連絡するには、Terraform コミュニティをご覧ください。

この記事では、Python を Terraform CDK Databricks プロバイダーおよび Cloud Development Kit for Terraform (CDKTF) と共に使用する方法について説明します。 CDKTF は、使い慣れたプログラミング言語、ツール、エンジニアリングプラクティスを使用して Azure Databricks リソースを作成、デプロイ、管理できる、サードパーティによるコードとしてのインフラストラクチャ (IaC) プラットフォームです。この記事では Python の使用方法について説明しますが、CDKTF では TypeScript、Java、C#、Go などの他の言語もサポートされています。

Terraform CDK Databricks プロバイダーは、Databricks Terraform プロバイダーに基づいています。詳細については、Terraform Cloud のページを参照してください。 CDKTF は AWS クラウド開発キット (AWS CDK) に基づいています。

必要条件

この記事では既存のワークスペースにリソースをデプロイするので、Azure Databricks ワークスペースが必要です。

ローカル開発マシンには、次のものをインストールしておく必要があります。

Terraform、バージョン 1.1 以降。 Terraform がインストールされているかどうかを確認し、インストールされているバージョンを確認するには、ターミナルまたは PowerShell でコマンド terraform -v を実行します。 Terraform をまだインストールしていない場合はインストールします。
```
terraform -v
```
Node.js、バージョン 16.13 以降、および npm。 Node.js と npm がインストールされているかどうかを確認し、インストールされているバージョンを確認するには、コマンド node -v と npm -v を実行します。最新バージョンの Node.js には npm が既に含まれています。 Node.js をまだインストールしておらず、npm を既にインストールしている場合は、ノードバージョンマネージャー (nvm) を使用して Node.js と npm をインストールします。
```
node -v
npm -v
```
CDKTF CLI。 CDKTF CLI がインストールされているかどうかを確認し、インストールされているバージョンを確認するには、コマンド cdktf --version を実行します。 CDKTF CLI がまだインストールされていない場合は、npm を使用してインストールします。
```
cdktf --version
```
ヒント

Homebrew を使用して macOS に CDKTF CLI をインストールすることもできます。「Install CDKTF (CDKTF のインストール)」を参照してください。
Python バージョン 3.7 以降と pipenv バージョン 2021.5.29 以降。 Python と pipenv がインストールされているかどうかを確認し、インストールされているバージョンを確認するには、コマンド python --version と pipenv --version を実行します。 Python をインストールし、pipenv をインストールします (まだインストールされていない場合)。
```
python --version
pipenv --version
```
使用したいサポートされている認証の種類用に構成された Azure Databricks 認証。 Databricks Terraform プロバイダーのドキュメントの「認証」を参照してください。

手順 1: CDKTF プロジェクトの作成

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

CDKTF プロジェクト用の空のディレクトリを作成し、それに切り替えます。ターミナルまたは PowerShell で次のコマンドを実行します。

Unix、Linux、macOS
```
mkdir cdktf-demo
cd cdktf-demo
```
Windows
```
md cdktf-demo
cd cdktf-demo
```
次のコマンドを実行して CDKTF プロジェクトを作成します。
```
cdktf init --template=python --local
```
プロジェクト名の入力を求められたら、Enter キーを押して既定のプロジェクト名である cdktf-demo をそのまま使用します。
プロジェクトの説明の入力を求められたら、Enter キーを押して既定のプロジェクトの説明をそのまま使用します。
"Do you want to start from an existing Terraform project" (既存の Terraform プロジェクトから開始しますか) というメッセージが表示されたら、「N」と入力し、Enter キーを押します。
"Do you want to send crash reports to the CDKTF team" (クラッシュレポートを CDKTF チームに送信しますか) というメッセージが表示されたら、「n」と入力し、Enter キーを押します。

CDKTF で次のファイルとサブディレクトリが cdktf-demo ディレクトリに作成されます。

.gitignore は、このプロジェクトをリモート Git リポジトリにプッシュする場合に Git で無視されるファイルとディレクトリの一覧です。
cdktf.json には、CDKTF プロジェクトの構成設定が含まれます。構成設定の詳細については、「Configuration File (構成ファイル)」を参照してください。
help には、CDKTF プロジェクトを操作するために次に実行できる手順に関する情報が含まれます。
main-test.py には、CDKTF プロジェクト用に記述できるサポート単体テストが含まれます。単体テストの詳細については、「Unit Tests (単体テスト)」を参照してください。
main.py には、CDKTF プロジェクト用に記述する Python コードが含まれます。
Pipfile と Pipfile.lock は、CDKTF プロジェクトのコードの依存関係を管理するものです。

手順 2: リソースを定義する

この手順では、Terraform CDK Databricks プロバイダーを使用して、ノートブックとそのノートブックを実行するジョブを定義します。

プロジェクトの依存関係をインストールします。pipenv を使用して、Terraform CDK Databricks プロバイダーを CDKTF プロジェクトにインストールして、Azure Databricks リソースを生成します。そのためには、次のように実行します。
```
pipenv install cdktf-cdktf-provider-databricks
```

main.py ファイルの内容を次のコードに置き換えます。このコードは、Azure Databricks ワークスペースで CDKTF を認証し、ノートブックを、そのノートブックを実行するジョブと共に生成します。このコードの構文ドキュメントを表示するには、Python の Terraform CDK Databricks プロバイダーコンストラクトリファレンスを参照してください。

#!/usr/bin/env python
from constructs import Construct
from cdktf import (
  App, TerraformStack, TerraformOutput
)
from cdktf_cdktf_provider_databricks import (
  data_databricks_current_user,
  job, notebook, provider
)
import vars
from base64 import b64encode

class MyStack(TerraformStack):
  def __init__(self, scope: Construct, ns: str):
    super().__init__(scope, ns)

    provider.DatabricksProvider(
      scope = self,
      id    = "databricksAuth"
    )

    current_user = data_databricks_current_user.DataDatabricksCurrentUser(
      scope     = self,
      id_       = "currentUser"
    )

    # Define the notebook.
    my_notebook = notebook.Notebook(
      scope          = self,
      id_            = "notebook",
      path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
      language       = "PYTHON",
      content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
    )

    # Define the job to run the notebook.
    my_job = job.Job(
      scope = self,
      id_ = "job",
      name = f"{vars.resource_prefix}-job",
      task = [ 
        job.JobTask(
          task_key = f"{vars.resource_prefix}-task",
          new_cluster = job.JobTaskNewCluster(
            num_workers   = vars.num_workers,
            spark_version = vars.spark_version,
            node_type_id  = vars.node_type_id
          ),
          notebook_task = job.JobTaskNotebookTask(
            notebook_path = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py"
          ),
          email_notifications = job.JobTaskEmailNotifications(
            on_success = [ current_user.user_name ],
            on_failure = [ current_user.user_name ]
          )
        )
      ]
    )

    # Output the notebook and job URLs.
    TerraformOutput(
      scope = self,
      id    = "Notebook URL",
      value = my_notebook.url
    )

    TerraformOutput(
      scope = self,
      id    = "Job URL",
      value = my_job.url
    )

app = App()
MyStack(app, "cdktf-demo")
app.synth()

main.py と同じディレクトリに、vars.py という名前のファイルを作成します。次の値を独自の値に置き換えて、リソースプレフィックスとクラスター設定 (ワーカーの数、Spark ランタイムバージョン文字列、ノードの種類など) を指定します。
```
#!/usr/bin/env python
resource_prefix = "cdktf-demo"
num_workers     = 1
spark_version   = "14.3.x-scala2.12"
node_type_id    = "Standard_D3_v2"
```

手順 3: リソースをデプロイする

この手順では、CDKTF CLI を使用して、既存の Azure Databricks ワークスペースに、定義済みのノートブック、およびそのノートブックを実行するジョブをデプロイします。

CDKTF プロジェクトと同等の Terraform コードを生成します。これを行うには、cdktf synth コマンドを実行します。
```
cdktf synth
```
変更を行う前に、保留中のリソースの変更を確認できます。次のコマンドレットを実行します。
```
cdktf diff
```
cdktf deploy コマンドを実行して、ノートブックとジョブをデプロイします。
```
cdktf deploy
```
承認するかどうかを確認するメッセージが表示されたら、Enter キーを押します。 Terraform により、ノートブックとジョブが作成されて、ワークスペースにデプロイされます。

手順 4: リソースを操作する

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

ワークスペースでジョブによって実行されるノートブックを表示するには、cdk deploy コマンドの出力に表示される [Notebook URL] (ノートブック URL) のリンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ワークスペースでノートブックを実行するジョブを表示するには、cdk deploy コマンドの出力に表示される [ジョブ URL] のリンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ジョブを実行するには、ジョブページの [今すぐ実行] ボタンをクリックします。

(省略可能) 手順 5: リソースに変更を加える

省略可能なこの手順では、ノートブックのコードを変更し、変更したノートブックを再デプロイしてから、ジョブを使用して、変更したノートブックを再実行します。

ノートブックを変更しない場合は、「手順 6: クリーンアップする」に進んでください。

main.py ファイルで、notebook 変数宣言を以下から変更します。

my_notebook = notebook.Notebook(
  scope          = self,
  id_            = "notebook",
  path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
  language       = "PYTHON",
  content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
)

次のようにします。

my_notebook = notebook.Notebook(
  scope          = self,
  id_            = "notebook",
  path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
  language       = "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")
)

Note

次に示すように、3 重引用符 (''') の間のコード行がコードエディターの端に揃っていることを確認します。そうでないと、Terraform によってノートブックに追加の空白が挿入され、それが原因で新しい Python コードの実行が失敗する可能性があります。

CDKTF プロジェクトと同等の Terraform コードを再生成します。そのためには、次のように実行します。
```
cdktf synth
```
変更を行う前に、保留中のリソースの変更を確認できます。次のコマンドレットを実行します。
```
cdktf diff
```
cdktf deploy コマンドを実行して、ノートブックの変更をデプロイします。
```
cdktf deploy
```
承認するかどうかを確認するメッセージが表示されたら、Enter キーを押します。 Terraform により、ノートブックの内容が変更されます。
ワークスペースでジョブによって実行される変更済みのノートブックを表示するには、前に開いたノートブックを最新の情報に更新するか、cdk deploy コマンドの出力に表示される [Notebook URL] (ノートブック URL) のリンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ワークスペースで変更済みのノートブックを実行するジョブを表示するには、前に開いたジョブを最新の情報に更新するか、cdk deploy コマンドの出力に表示される [ジョブ URL] のリンクをコピーし、Web ブラウザーのアドレスバーに貼り付けます。
ジョブを実行するには、ジョブページの [今すぐ実行] ボタンをクリックします。

手順 6: クリーンアップする

この手順では、CDKTF CLI を使用して、Azure Databricks ワークスペースからノートブックとジョブを削除します。

cdktf destroy コマンドを実行して、ワークスペースからリソースを削除します。
```
cdktf destroy
```
承認するかどうかを確認するメッセージが表示されたら、Enter キーを押します。 Terraform により、リソースがワークスペースから削除されます。

テスト

CDKTF プロジェクトをデプロイする前にテストできます。 CDKTF ドキュメントの「単体テスト」を参照してください。

Python ベースの CDKTF プロジェクトの場合、Python テストフレームワーク pytest を、cdktf パッケージの Testing クラスと共に使用してテストを作成して実行できます。 test_main.py という名前の次のサンプルファイルは、この記事で上記の main.py ファイルの CDKTF コードをテストします。最初のテストでは、プロジェクトのノートブックに、ノートブックのコンテンツの予想される Base64 でエンコードされた表現が含まれるかどうかを確認します。 2 番目のテストでは、プロジェクトのジョブに予想されるジョブ名が含まれるかどうかを確認します。これらのテストを実行するには、プロジェクトのルートディレクトリから pytest コマンドを実行します。

from cdktf import App, Testing
from cdktf_cdktf_provider_databricks import job, notebook
from main import MyStack

class TestMain:
  app = App()
  stack = MyStack(app, "cdktf-demo")
  synthesized = Testing.synth(stack)

  def test_notebook_should_have_expected_base64_content(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = notebook.Notebook.TF_RESOURCE_TYPE,
      properties = {
        "content_base64": "ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp"
      }
    )

  def test_job_should_have_expected_job_name(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = job.Job.TF_RESOURCE_TYPE,
      properties = {
        "name": "cdktf-demo-job"
      }
    )

その他のリソース

TypeScript、Python、Java、C#、Go の Terraform CDK Databricks プロバイダーコンストラクトリファレンス
CDKTF アプリケーションのログ記録を有効にする

次の方法で共有

Terraform CDK Databricks プロバイダー

必要条件

手順 1: CDKTF プロジェクトの作成

Unix、Linux、macOS

Windows

手順 2: リソースを定義する

手順 3: リソースをデプロイする

手順 4: リソースを操作する

(省略可能) 手順 5: リソースに変更を加える

手順 6: クリーンアップする

テスト

その他のリソース

フィードバック

フィードバック

その他のリソース