Terraform CDK Databricks プロバイダー

注

この記事では、Databricks によって提供もサポートもされていない Terraform 用クラウド開発キット (CDKTF) について説明します。 プロバイダーに連絡するには、 Terraformコミュニティを参照してください。

この記事では 、Python TerraformCDKDatabricks プロバイダー と クラウド開発キット forTerraform (CDKTF) とともに を使用する方法について説明します。CDKTF は、使い慣れたプログラミング言語、ツール、エンジニアリング手法を使用して Databricks リソースを作成、デプロイ、管理できるサードパーティの Infrastructure as Code (IaC) プラットフォームです。 この記事では Python の使用方法を説明しますが、CDKTF では TypeScript、Java、C#、Go などの追加言語もサポートされています。

Terraform CDK Databricks プロバイダーは、 Databricks Terraform プロバイダーに基づいています。 詳細については、「 Terraform クラウド」を参照してください。 CDKTF は AWS Cloud Development Kit (AWS CDK) に基づいています。

要件

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

ローカル開発コンピューターには、次のものがインストールされている必要があります。

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

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

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

    mkdir cdktf-demo
cd cdktf-demo

    md cdktf-demo
cd cdktf-demo

  2. 次のコマンドを実行して、CDKTF プロジェクトを作成します。

    cdktf init --template=python --local

  3. プロジェクト名の入力を求めるプロンプトが出されたら、Enter キーを押してデフォルトのプロジェクト名 cdktf-demo を受け入れ ます。

  4. プロジェクトの説明の入力を求めるプロンプトが出されたら、Enter キーを押してデフォルトのプロジェクトの説明を受け入れ ます。

  5. [ 既存の Terraform プロジェクトから開始しますか] というプロンプトが表示されたら、 N と入力して Enter キーを押します。

  6. [ クラッシュ レポートを CDKTF チームに送信しますか] というメッセージが表示されたら、 n と入力して Enter キーを押します。

CDKTF は、 cdktf-demo ディレクトリに次のファイルとサブディレクトリを作成します。

  • .gitignoreこれは、このプロジェクトをリモート Git リポジトリにプッシュする場合に Git が無視するファイルとディレクトリのリストです。

  • cdktf.jsonCDKTF プロジェクトの構成設定が含まれています。 構成設定の詳細については、「 構成ファイル 」を参照してください。

  • helpCDKTF プロジェクトで作業するために実行できる次のステップに関する情報が含まれています。

  • main-test.pyCDKTF プロジェクト用に記述できるサポート単体テストが含まれています。 単体 テストの詳細については、「単体テスト 」を参照してください。

  • main.pyこれには、CDKTF プロジェクト用に記述した Python コードが含まれています。

  • Pipfile および Pipfile.lockは、CDKTF プロジェクトのコードの依存関係を管理します。

ステップ 2: リソースを定義する

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

  1. プロジェクトの依存関係をインストールします。 pipenvを使用して、CDKTF プロジェクトにTerraform CDK Databricks プロバイダーをインストールし、Databricks リソースを生成します。 これを行うには、以下を実行します。

    pipenv install cdktf-cdktf-provider-databricks

  2. main.py ファイルの内容を次のコードで置き換えます。このコードは、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()

  3. 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    = "n1-standard-4"

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

このステップでは、CDKTF CLI を使用して、既存の Databricks ワークスペースに、定義されたノートブックとそのノートブックを実行するジョブをデプロイします。

  1. CDKTF プロジェクトに相当する Terraform コードを生成します。 これを行うには、 cdktf synth コマンドを実行します。

    cdktf synth

  2. 変更を加える前に、保留中のリソースの変更を確認できます。 以下を実行します。

    cdktf diff

  3. cdktf deploy コマンドを実行して、ノートブックとジョブをデプロイします。

    cdktf deploy

  4. 承認を求めるメッセージが表示されたら、 Enter キーを押します。Terraform によってノートブックとジョブが作成され、ワークスペースにデプロイされます。

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

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

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

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

  3. ジョブを実行するには、ジョブ ページの [ 今すぐ実行 ] ボタンをクリックします。

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

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

ノートブックに変更を加えない場合は、「 ステップ 6: クリーンアップ」に進みます。

  1. 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")
)

    注

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

  2. CDKTF プロジェクトに相当する Terraform コードを再生成します。 これを行うには、次のコマンドを実行します。

    cdktf synth

  3. 変更を加える前に、保留中のリソースの変更を確認できます。 以下を実行します。

    cdktf diff

  4. cdktf deploy コマンドを実行して、ノートブックの変更をデプロイします。

    cdktf deploy

  5. 承認を求めるメッセージが表示されたら、 Enter キーを押します。Terraform によってノートブックの内容が変更されます。

  6. ジョブがワークスペースで実行される変更されたノートブックを表示するには、前に開いたノートブックを更新するか、 cdk deploy コマンドの出力に表示される [ノートブックの URL] リンクをコピーして、Web ブラウザーのアドレス バーに貼り付けます。

  7. ワークスペースで変更されたノートブックを実行するジョブを表示するには、前に開いたジョブを更新するか、 cdk deploy コマンドの出力に表示される [ジョブ URL] リンクをコピーして、Web ブラウザーのアドレス バーに貼り付けます。

  8. ジョブを実行するには、ジョブ ページの [ 今すぐ実行 ] ボタンをクリックします。

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

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

  1. ワークスペースからリソースを削除するには、 cdktf destroy コマンドを実行します。

    cdktf destroy

  2. 承認を求めるメッセージが表示されたら、 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"
      }
    )