Pulumi Databricks 資源提供者

文章
07/09/2024

注意

本文涵蓋 Pulumi，這是 Databricks 既未提供也不支援。若要連絡提供者，請參閱 Pulumi 支援。

本文說明如何使用 Python 和 Pulumi，這是第三方基礎結構即程式代碼（IaC）平臺，可讓您使用熟悉的程式設計語言、工具和工程實務來建立、部署及管理 Azure Databricks 資源。雖然本文說明如何使用 Python 和 Pulumi Databricks 資源提供者，但 Pulumi 除了適用於 Azure Databricks 的 Python 之外，還支援其他語言，包括 TypeScript、JavaScript、Go 和 C#。

Pulumi Databricks 資源提供者是以 Databricks Terraform 提供者為基礎。如需詳細資訊，請參閱 Terraform Cloud。

需求

Pulumi 帳戶。如果您還沒有 Pulumi 帳戶，請註冊 Pulumi。 Pulumi 適用於個人，並提供小組的免費層。
Python 3.6 或更高版本。若要檢查您是否已安裝 Python，請從終端機或使用 PowerShell 執行命令 python --version 。如果您尚未安裝 Python，請安裝 Python。

注意

某些 Python 安裝可能會要求您使用 python3 ，而不是 python。若是如此，請取代pythonpython3本文的。
您的 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
Azure Databricks 存取認證。 Pulumi Databricks 項目支援下列 Azure Databricks 驗證類型：
- Azure Databricks 個人存取令牌驗證（databricks:authType pat）
- Azure 受控識別驗證（databricks:authType azure-msi）
- MS Entra 服務主體驗證（databricks:authType azure-client-secret）
- Azure CLI 驗證（databricks:authType azure-cli）

下列步驟示範如何使用 Python 建立 Pulumi Databricks 專案。如需純雲端提供者優先觀點的教學課程，請參閱 Pulumi 檔中的開始使用 Azure 。如需程式設計語言優先觀點的教學課程，請參閱 Pulumi 檔中的 Python、Node.js（JavaScript、TypeScript）、Go 和 .NET （C#、VB、F#）。

步驟 1：建立 Pulumi 專案

在此步驟中，在本機開發計算機上，您已為 Pulumi 項目設定必要的目錄結構。接著，您會在此目錄結構內建立 Pulumi 專案。

從終端機或使用 PowerShell 建立空的目錄，然後切換至它，例如：

Unix、Linux 和macOS
```
mkdir pulumi-demo
cd pulumi-demo
```
Windows
```
md pulumi-demo
cd pulumi-demo
```
視您的作業系統而定，執行下列命令來安裝 Pulumi：

Unix、Linux

使用 curl 在 Unix 或 Linux 上安裝 Pulumi：
```
curl -fsSL https://get.pulumi.com | sh
```
MacOS

使用 Homebrew 在 macOS 上安裝 Pulumi：
```
brew install pulumi/tap/pulumi
```
Windows

透過 Chocolatey 套件管理員，使用具有更高許可權的 PowerShell 在 Windows 上安裝 Pulumi：
```
choco install pulumi
```
如需替代的 Pulumi 安裝選項，請參閱 Pulumi 檔中的下載和安裝。
執行下列命令來建立基本的 Python Pulumi 專案：
```
pulumi new python
```
提示

您也可以從 Pulumi 帳戶在線建立 Pulumi 專案（專案 > 建立專案）。不過，Azure Databricks 沒有項目範本。
如果出現提示，請按 Enter 鍵，然後使用網頁瀏覽器在在線登入 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 鍵。
複製出現的 [檢視即時] 連結，並將其貼到網頁瀏覽器的網址列中，這會將您帶您上線至 Pulumi 帳戶。 dev專案的堆疊活動詳細數據pulumi-demo隨即出現。現在看不到太多，因為您的堆疊中還沒有任何資源。您會在下一個步驟中建立這些資源。

步驟 2：建立 Databricks 資源

在此步驟中，您會使用 Pulumi Databricks 資源提供者，在現有的 Azure Databricks 工作區、筆記本和作業中建立以執行該筆記本。

在 Pulumi 產生的檔案中 __main.py__ ，使用您慣用的文字編輯器或整合開發環境（IDE）來輸入下列程式代碼。此程式代碼會宣告 Pulumi Databricks Notebook 和作業資源及其設定：

"""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 會在與檔案相同的目錄中建立名為 Pulumi.dev.yaml 的 __main__.py 檔案，並將下列程式代碼新增至此 YAML 檔案：
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
使用組態值可讓您的程式代碼更模組化且可重複使用。現在，其他人可以重複使用您的 __main__.py 檔案，併為變數定義不同的值 resource_prefix ，而不需要變更檔案的內容 __main__.py 。
執行下列命令，定義名為 node-type的組態值，並將其設定為下列硬式編碼值。 Pulumi 會使用此組態值來判斷作業執行的叢集類型。
```
pulumi config set node-type "Standard_D3_v2"
```
檔案的內容 Pulumi.dev.yaml 現在看起來像這樣：
```
config:
  pulumi-demo:node-type: Standard_D3_v2
  pulumi-demo:resource-prefix: pulumi-demo
```
若要讓 Pulumi 向 Azure Databricks 工作區進行驗證，請執行相關的命令來定義 Azure Databricks 特定組態值。例如，針對 Azure Databricks 個人存取令牌驗證，請執行下列命令。在下列命令中：
- 以您的個別工作區 URL 取代 <workspace-instance-url> ，例如 https://adb-1234567890123456.7.azuredatabricks.net。
- 將取代 <access-token> 為您的存取權杖值。請務必指定 --secret 選項。這會指示 Pulumi 將您的存取令牌加密為安全性最佳做法。
  
  注意
  
  根據預設，Pulumi 會使用 Pulumi 服務所管理的個別堆疊加密密鑰，以及個別值 salt 來加密值。若要使用替代加密提供者，請參閱 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: Standard_D3_v2
  pulumi-demo:resource_prefix: pulumi-demo
```
若要使用不同的 Azure Databricks 驗證類型，請參閱需求。另請參閱 GitHub 中 Pulumi Databricks 存放庫中的組態。

步驟 3：部署資源

在此步驟中，您會啟動 Pulumi 為專案提供的 Python 虛擬環境，作為執行 Pulumi Python 專案範本的一部分。此虛擬環境可協助確保您同時使用正確的 Python 版本 Pulumi 和 Pulumi Databricks 資源提供者。有數個可用的 Python 虛擬環境架構，例如 venv、virtualenv 和 pipenv。本文和 Pulumi Python 專案範本使用 venv。 venv 已隨附於 Python 中。如需詳細資訊，請參閱建立虛擬環境。

視您的作業系統和殼層類型而定，從目錄 pulumi-demo 執行下列命令來啟用 Python 虛擬環境：

平台	Shell	啟動虛擬環境的命令
Unix、Linux、macOS	bash/zsh	`source venv/bin/activate`
	fish	`source venv/bin/activate.fish`
	csh/tcsh	`source venv/bin/activate.csh`
	PowerShell Core	`venv/bin/Activate.ps1`
Windows	cmd.exe	`venv\Scripts\activate.bat`
	PowerShell	`venv\Scripts\Activate.ps1`

執行下列命令，將 Pulumi Databricks 資源提供者從 Python 套件索引（PyPI）安裝到您的虛擬環境：
```
pip install pulumi-databricks
```
注意

的某些安裝 pip 可能會要求您使用 pip3 ，而不是 pip。若是如此，請取代pippip3本文的。
執行下列命令來預覽 Pulumi 將建立的資源：
```
pulumi preview
```
如果報告了任何錯誤，請修正錯誤，然後再次執行命令。

若要在 Pulumi 帳戶在線檢視 Pulumi 將執行哪些動作的詳細報告，請複製 出現的 [檢視即時 ] 連結，並將其貼到網頁瀏覽器的網址列中。
執行下列命令，以建立資源並將其部署至 Azure Databricks 工作區：
```
pulumi up
```
當系統提示您執行此更新時，請按向上鍵以流覽至 [是 ]，然後按 Enter 鍵。如果報告了任何錯誤，請修正錯誤，然後再次執行命令。
若要在 Pulumi 帳戶在線檢視 Pulumi 所做的詳細報告，請複製 出現的 [檢視即時 ] 連結，並將其貼到網頁瀏覽器的網址列中。

步驟 4：與資源互動

在此步驟中，您會在 Azure Databricks 工作區中執行作業，以執行指定的筆記本。

若要檢視作業將在工作區中執行的筆記本，請複製 顯示的 Notebook URL 連結，並將其貼到網頁瀏覽器的網址列中。
若要檢視在工作區中執行筆記本的工作，請複製 出現的作業 URL 連結，並將其貼到網頁瀏覽器的網址列中。
若要執行作業，請按下作業頁面上的 [ 立即執行] 按鈕。
作業完成執行之後，若要檢視作業執行的結果，請在作業頁面上的 [已完成執行]（過去 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")
```
這項變更會指示筆記本列印指定之 DataFrame 的內容，而不是數位 1 到 10。

注意

請確定以 data 開頭和結尾 ''').decode("UTF-8") 的程式代碼行會對齊程式碼編輯器的邊緣。否則，Pulumi 會將額外的空格符插入筆記本中，這可能會造成新的 Python 程式代碼無法執行。
或者，執行下列命令來預覽 Pulumi 將變更的資源：
```
pulumi preview
```
如果報告了任何錯誤，請修正錯誤，然後再次執行命令。

若要在 Pulumi 帳戶在線檢視 Pulumi 將執行哪些動作的詳細報告，請複製 出現的 [檢視即時 ] 連結，並將其貼到網頁瀏覽器的網址列中。
執行下列命令，將資源變更部署至 Azure Databricks 工作區：
```
pulumi up
```
當系統提示您執行此更新時，請按向上鍵以流覽至 [是 ]，然後按 Enter 鍵。如果報告了任何錯誤，請修正錯誤，然後再次執行命令。
若要在 Pulumi 帳戶在線檢視 Pulumi 所做的詳細報告，請複製 出現的 [檢視即時 ] 連結，並將其貼到網頁瀏覽器的網址列中。
若要在工作區中檢視已變更的筆記本，請複製 出現的 Notebook URL 連結，並將其貼到網頁瀏覽器的網址列中。
若要使用已變更的筆記本重新執行作業，請複製 出現的作業 URL 連結，並將其貼到網頁瀏覽器的網址列中。然後按下作業頁面上的 [ 立即執行] 按鈕。
作業完成執行之後，若要檢視作業執行的結果，請在作業頁面上的 [已完成執行]（過去 60 天）清單中，按兩下 [開始時間] 資料行中的最近時間專案。 [ 輸出 ] 窗格會顯示執行筆記本程式代碼的結果，其會列印指定之 DataFrame 的內容。

步驟 6：清除

在此步驟中，您會指示 Pulumi 從 Azure Databricks 工作區移除筆記本和作業，以及從您的 Pulumi 帳戶在線移除 pulumi-demo 專案及其 dev 堆疊。

執行下列命令，從 Azure Databricks 工作區移除資源：
```
pulumi destroy
```
當系統提示您執行此移除時，請按向上鍵以流覽至 [是 ]，然後按 Enter 鍵。
執行下列命令，從 Pulumi 帳戶在線移除 Pulumi pulumi-demo 專案及其 dev 堆疊：
```
pulumi stack rm dev
```
當系統提示您執行此移除時，輸入 dev ，然後按 Enter。
若要停用 venv Python 虛擬環境，請執行下列命令：
```
deactivate
```

測試

部署 Pulumi 專案之前，您可以先測試 Pulumi 專案。請參閱 Pulumi 檔中的測試 Pulumi 程式。

針對以 Python 為基礎的 Pulumi 專案的單元測試，您可以使用 Python 測試架構單元測試以及 Pulumi 套件的 pulumi.runtime 命名空間來撰寫和執行單元測試。若要對模擬資源執行測試，您可以使用模擬取代 Pulumi 的呼叫（以及 Azure Databricks）。請參閱 Pulumi 檔中的 Pulumi 程式單元測試。

下列名為 infra.py 的範例檔案會模擬本文檔案中宣告的筆記本和作業實作 main.py 。此範例中的單元測試會檢查筆記本的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 資源提供者

需求

步驟 1：建立 Pulumi 專案

Unix、Linux 和macOS

Windows

Unix、Linux

MacOS