Databricks Terraform プロバイダー

HashiCorp Terraform は、複数のクラウド プロバイダーにわたって安全で予測可能なクラウド インフラストラクチャを作成するためによく使用されるオープン ソース ツールです。 Databricks Terraform プロバイダーを使用すると、柔軟で強力なツールを使用して、Azure Databricks ワークスペースと関連するクラウド インフラストラクチャを管理できます。 Databricks Terraform プロバイダーの目標は、すべての Databricks REST API をサポートし、データ プラットフォームのデプロイと管理における最も複雑な側面の自動化に対応することです。 Databricks のお客様は、Databricks Terraform プロバイダーを使用して、クラスターとジョブのデプロイと管理、データ アクセスの構成を行います。 Azure プロバイダーを使用して、Azure Databricks ワークスペースをプロビジョニングします。

作業の開始

このセクションでは、Terraform と Databricks Terraform プロバイダーをローカル開発マシンで使用するための要件をインストールして構成します。 その後、Terraform 認証を構成します。 このセクションの後、この記事では、既存の Azure Databricks ワークスペースで、Azure Databricks ノートブック、クラスター、およびクラスターでノートブックを実行するジョブをプロビジョニングするためのサンプル構成について説明します。

要件

1. Terraform CLI が必要です。 詳細については、Terraform Web サイトの Terraform のダウンロードに関する記事を参照してください。

2. Terraform プロジェクトが必要です。 ターミナルで空のディレクトリを作成し、それに切り替えます。 (Terraform 構成ファイルの各個別のセットは、Terraform プロジェクトと呼ばれる独自のディレクトリに存在する必要があります)。例: mkdir terraform_demo && cd terraform_demo。

   mkdir terraform_demo && cd terraform_demo
   

   Terraform プロジェクトの 1 つ以上の構成ファイルに、プロジェクトの Terraform 構成を含めます。 構成ファイルの構文の詳細については、Terraform Web サイトの Terraform 言語のドキュメントを参照してください 。

3. Terraform プロジェクトに Databricks Terraform プロバイダーの依存関係を追加する必要があります。 Terraform プロジェクトの構成ファイルのいずれかに以下を追加します。

   terraform {
     required_providers {
       databricks = {
         source = "databricks/databricks"
       }
     }
   }
   

4. Terraform プロジェクトの認証を構成する必要があります。 Databricks Terraform プロバイダーのドキュメントの「認証」を参照してください。

サンプル構成

このセクションは、既存の Azure Databricks ワークスペースで、Azure Databricks ノートブック、クラスター、およびクラスターでノートブックを実行するジョブをプロビジョニングするためのサンプル構成について説明します。 前のセクションで説明したように、 要件を既に設定しているだけでなく、Terraform プロジェクトを作成し、Terraform 認証を使用してプロジェクトを構成済みであることを前提としています。

1. Terraform プロジェクトに me.tf というファイルを作成し、次のコードを追加します。 このファイルは、次の現在のユーザー (ユーザー) に関する情報を取得します。

   # Retrieve information about the current user.
   data "databricks_current_user" "me" {}
   

2. 別の notebook.tf という名前のファイルを作成し、次のコードを追加します。 このファイルはノートブックを表します。

   variable "notebook_subdirectory" {
     description = "A name for the subdirectory to store the notebook."
     type        = string
     default     = "Terraform"
   }
   
   variable "notebook_filename" {
     description = "The notebook's filename."
     type        = string
   }
   
   variable "notebook_language" {
     description = "The language of the notebook."
     type        = string
   }
   
   resource "databricks_notebook" "this" {
     path     = "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
     language = var.notebook_language
     source   = "./${var.notebook_filename}"
   }
   
   output "notebook_url" {
    value = databricks_notebook.this.url
   }
   

3. 別の notebook.auto.tfvars という名前のファイルを作成し、次のコードを追加します。 このファイルは、ノートブックのプロパティを指定します。

   notebook_subdirectory = "Terraform"
   notebook_filename     = "notebook-getting-started.py"
   notebook_language     = "PYTHON"
   

4. 別の notebook-getting-started.py という名前のファイルを作成し、次のコードを追加します。 このファイルはノートブックのコンテンツを表します。

   display(spark.range(10))
   

5. 別の cluster.tf という名前のファイルを作成し、次のコードを追加します。 このファイルはクラスターを表します。

   variable "cluster_name" {
     description = "A name for the cluster."
     type        = string
     default     = "My Cluster"
   }
   
   variable "cluster_autotermination_minutes" {
     description = "How many minutes before automatically terminating due to inactivity."
     type        = number
     default     = 60
   }
   
   variable "cluster_num_workers" {
     description = "The number of workers."
     type        = number
     default     = 1
   }
   
   # Create the cluster with the "smallest" amount
   # of resources allowed.
   data "databricks_node_type" "smallest" {
     local_disk = true
   }
   
   # Use the latest Databricks Runtime
   # Long Term Support (LTS) version.
   data "databricks_spark_version" "latest_lts" {
     long_term_support = true
   }
   
   resource "databricks_cluster" "this" {
     cluster_name            = var.cluster_name
     node_type_id            = data.databricks_node_type.smallest.id
     spark_version           = data.databricks_spark_version.latest_lts.id
     autotermination_minutes = var.cluster_autotermination_minutes
     num_workers             = var.cluster_num_workers
   }
   
   output "cluster_url" {
    value = databricks_cluster.this.url
   }
   

6. 別の cluster.auto.tfvars という名前のファイルを作成し、次のコードを追加します。 このファイルは、クラスターのプロパティを指定します。

   cluster_name                    = "My Cluster"
   cluster_autotermination_minutes = 60
   cluster_num_workers             = 1
   

7. 別の job.tf という名前のファイルを作成し、次のコードを追加します。 このファイルは、クラスターでノートブックを実行するジョブを表します。

   variable "job_name" {
     description = "A name for the job."
     type        = string
     default     = "My Job"
   }
   
   variable "task_key" {
     description = "A name for the task."
     type        = string
     default     = "my_task"
   }
   
   resource "databricks_job" "this" {
     name = var.job_name
     task {
       task_key = var.task_key
       existing_cluster_id = databricks_cluster.this.cluster_id
       notebook_task {
         notebook_path = databricks_notebook.this.path
       }
     }
     email_notifications {
       on_success = [ data.databricks_current_user.me.user_name ]
       on_failure = [ data.databricks_current_user.me.user_name ]
     }
   }
   
   output "job_url" {
     value = databricks_job.this.url
   }
   

8. 別の job.auto.tfvars という名前のファイルを作成し、次のコードを追加します。 このファイルは、ジョブのプロパティを指定します。

   job_name = "My Job"
   task_key = "my_task"
   

9. terraform planを実行します。 エラーがある場合は、修正してからコマンドを再実行します。

10. terraform applyを実行します。

11. ノートブック、クラスターおよびジョブが作成されたことを確認します。terraform apply コマンドの出力で、notebook_url、cluster_url、および job_url の URL を見つけ、それらの URL に移動します。

12. ジョブを次のように実行します。[ジョブ] ページで、[今すぐ実行] をクリックします。 ジョブが完了したら、メールの受信トレイを確認します。

13. このサンプルが完了したら、terraform destroy を実行して、Azure Databricks ワークスペースからノートブック、クラスターおよびジョブを削除します。

    Note

    terraform plan、terraform apply、terraform destroy コマンドの詳細については、Terraform ドキュメントの Terraform CLI ドキュメントを参照してください。

14. ノートブック、クラスターおよびジョブが削除されたことを確認します。ノートブック、クラスターおよびジョブのページを更新して、リソースが見つからないことを示す各メッセージを表示します。

テスト

Terraform 構成をデプロイの前または後にテストします。 リソースをデプロイする前に、単体テストに似たテストを実行できます。 また、リソースのデプロイ後に、統合テストに似たテストを実行することもできます。 Terraform ドキュメントのテストのページを参照してください。

このプロセスに従って、この記事のサンプル構成に対する統合テストに似たテストを実行します。

1. cluster.tftest.hcl という名前のファイルを作成し、次のコードを追加します。 このファイルは、デプロイされたクラスターに予期されるクラスター名が付けられているかどうかをテストします。

   # Filename: cluster.tftest.hcl
   
   run "cluster_name_test" {
     command = apply
   
     assert {
       condition     = databricks_cluster.this.cluster_name == var.cluster_name
       error_message = "Cluster name did not match expected name"
     }
   }
   

2. job.tftest.hcl という名前のファイルを作成し、次のコードを追加します。 このファイルは、デプロイされたジョブに予期されるジョブ名が付けられているかどうかをテストします。

   run "job_name_test" {
     command = apply
   
     assert {
       condition     = databricks_job.this.name == var.job_name
       error_message = "Job name did not match expected name"
     }
   }
   

3. notebook.tftest.hcl という名前のファイルを作成し、次のコードを追加します。 このファイルは、デプロイされたノートブックに予期されるワークスペース パスがあるかどうかをテストします。

   run "notebook_path_test" {
     command = apply
   
     assert {
       condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
       error_message = "Notebook path did not match expected path"
     }
   }
   

4. terraform test を実行します。 Terraform は、各リソースを Azure Databricks ワークスペースにデプロイして関連する各テストを実行し、そのテスト結果を報告してから、デプロイされたリソースを破棄します。

次のプロセスを使用して、この記事のサンプル構成に対する単体テストに似たテストを実行します。

• 上記の各テストの行 command = apply を command = plan に変更してから、terraform test を実行します。 Terraform によって関連する各テストが実行され、そのテスト結果が報告されますが、リソースはデプロイされません。
• Databricks Terraform プロバイダーをモックします。これにより、リソースをデプロイせずに、また認証資格情報を必要とせずに、terraform test を実行できます。 Terraform ドキュメントのモックのページを参照してください。 モック テストを実行するとき、１ つの方法として、テストに行 mock_provider "databricks" {} を追加し、行 command = apply または command = plan を削除します。次に例を示します。

# Filename: cluster.tftest.hcl

mock_provider "databricks" {}

run "cluster_mock_name_test" {
  assert {
    condition     = databricks_cluster.this.cluster_name == var.cluster_name
    error_message = "Cluster name did not match expected name"
  }
}

# Filename: job.tftest.hcl

mock_provider "databricks" {}

run "job_mock_name_test" {
  assert {
    condition     = databricks_job.this.name == var.job_name
    error_message = "Job name did not match expected name"
  }
}

# Filename: notebook.tftest.hcl

mock_provider "databricks" {}

run "notebook_mock_path_test" {
  assert {
    condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
    error_message = "Notebook path did not match expected path"
  }
}

次のステップ

1. Azure Databricks ワークスペースを作成します。
2. Azure Databricks ワークスペースのワークスペース リソースを管理します。

トラブルシューティング

エラー: プロバイダーのインストールに失敗しました

問題: バージョン管理システムに terraform.lock.hcl ファイルをチェックインせず、terraform init コマンドを実行すると、次のメッセージが表示されます。Failed to install provider。 追加の出力には、次のようなメッセージが含まれる場合があります。

Error while installing databrickslabs/databricks: v1.0.0: checksum list has no SHA-256 hash for "https://github.com/databricks/terraform-provider-databricks/releases/download/v1.0.0/terraform-provider-databricks_1.0.0_darwin_amd64.zip"

原因: Terraform 構成が古い Databricks Terraform プロバイダーを参照しています。

解決策:

1. すべての .tf ファイル内の databrickslabs/databricks を databricks/databricks で置き換えます。

   この置換を自動化するには、更新する .tf ファイルを含む親フォルダーから次の Python コマンドを実行します。

   python3 -c "$(curl -Ls https://dbricks.co/updtfns)"
   

2. 次の Terraform コマンドを実行し、ダイアログが表示されたら変更を承認します。

   terraform state replace-provider databrickslabs/databricks databricks/databricks
   

   このコマンドの詳細については、Terraform ドキュメントの「Command: state replace-provider」を参照してください。

3. 次の Terraform コマンドを実行して変更を確認します。

   terraform init
   

エラー: 使用可能なプロバイダー パッケージのクエリに失敗しました

問題: バージョン管理システムに terraform.lock.hcl ファイルをチェックインせず、terraform init コマンドを実行すると、次のメッセージが表示されます。Failed to query available provider packages。

原因: Terraform 構成が古い Databricks Terraform プロバイダーを参照しています。

解決策: 「エラー: プロバイダーのインストールに失敗しました」の解決策の指示に従ってください。

ログの有効化

Databricks Terraform プロバイダーは、TF_LOG 環境変数を DEBUG または Terraform がサポートするその他のログ レベルに設定することで有効にできるログを出力します。

既定では、ログは stderrに送信されます。 ファイルにログを送信するには、TF_LOG_PATH 環境変数をターゲット ファイル パスに設定します。

たとえば、次のコマンドを実行してデバッグ レベルでのログ記録を有効にし、terraform apply コマンドの実行中に、現在の作業ディレクトリに対して相対的な tf.log という名前のファイルにモノクロ形式でログを出力できます。

TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply -no-color

Terraform のログ記録の詳細については、「Terraform のデバッグ」を参照してください。

追加の例

• Terraform を使用して Azure Databricks ワークスペースをデプロイする

• Terraform を使用して Databricks ワークスペースを管理する

• クラスターの作成

• クラスター、ノートブック、ジョブを作成する

• Databricks SQL テーブルへのアクセスの制御

• Databricks Terraform プロバイダーを使用し、Databricks リソースを展開するための CI/CD パイプラインを実装する

• サンプル ダッシュボードを作成する

その他のリソース

• Terraform レジストリ Web サイトの Databricks プロバイダーのドキュメント
• Terraform Web サイトの Terraform のドキュメント
• GitHub の terraform-databricks-examples リポジトリ