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 網站上的下載 Terraform。

2. 您必須有 Terraform 專案。 在您的終端機中，建立空白目錄，然後切換至該目錄。 (每組單獨的 Terraform 設定檔都必須放在自己的目錄中，該目錄稱為 Terraform 專案)。例如：mkdir terraform_demo && cd terraform_demo。

   mkdir terraform_demo && cd terraform_demo
   

   在 Terraform 專案中的一或多個設定檔中包含專案的 Terraform 組態。 如需設定檔語法的相關資訊，請參閱 Terraform 網站上的 Terraform 語言文件。

3. 您必須將 Databricks Terraform 提供者的相依性新增至 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 的 HTML 檔案，並新增下列程式碼。 此檔案代表筆記本。

   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 的 HTML 檔案，並新增下列程式碼。 此檔案會指定筆記本的屬性。

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

4. 建立另一個名為 notebook-getting-started.py 的 HTML 檔案，並新增下列程式碼。 此檔案代表筆記本的內容。

   display(spark.range(10))
   

5. 建立另一個名為 cluster.tf 的 HTML 檔案，並新增下列程式碼。 此檔案代表叢集。

   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 的 HTML 檔案，並新增下列程式碼。 此檔案會指定叢集的屬性。

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

7. 建立另一個名為 job.tf 的 HTML 檔案，並新增下列程式碼。 此檔案代表在叢集上執行筆記本的工作。

   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 的 HTML 檔案，並新增下列程式碼。 此檔案會指定工作的屬性。

   job_name = "My Job"
   task_key = "my_task"
   

9. 執行 terraform plan。 如果有任何錯誤，請加以修正，然後再次執行命令。

10. 執行 terraform apply。

11. 驗證建立的筆記本、叢集和工作：在 terraform apply 命令的輸出中，尋找 notebook_url、cluster_url 和 job_url 的網址，然後移至它們。

12. 執行工作：在 [工作] 頁面上，按下 [立即執行]。 工作完成後，請檢查您的電子郵件收件匣。

13. 當您完成此範例時，請執行 terraform destroy 來從 Azure Databricks 工作區刪除筆記本、叢集和工作。

    注意

    如需 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 特定支援，請參閱 HashiCorp 討論網站上的最新 Terraform 主題。 如需 Databricks Terraform 提供者的特定問題，請參閱 databrickslabs/terraform-provider-databricks GitHub 存放庫中的問題。

錯誤：無法安裝提供者

問題：如果您未將 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 文件中的命令：狀態取代提供者。

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 資料表的存取

• 實作 CI/CD 管線，以使用 Databricks Terraform 提供者部署 Databricks 資源

• 建立樣本儀表板

其他資源

• Terraform Registry 網站上的 Databricks 提供者文件
• Terraform 網站上的 Terraform 文件
• GitHub 中的 terraform-databricks-examples 存放庫