Poskytovatel prostředků Pulumi Databricks

  • Článek

Poznámka:

Tento článek se zabývá Pulumi, který není poskytován ani podporován Databricks. Pokud chcete kontaktovat poskytovatele, přejděte na podporu Pulumi.

V tomto článku se dozvíte, jak používat platformu Python a Pulumi třetí strany, infrastrukturu jako kód (IaC), která umožňuje vytvářet, nasazovat a spravovat prostředky Azure Databricks pomocí známých programovacích jazyků, nástrojů a technických postupů. I když tento článek ukazuje, jak používat Python a poskytovatele prostředků Pulumi Databricks, podporuje Pulumi kromě Pythonu pro Azure Databricks i další jazyky, včetně TypeScriptu, JavaScriptu, Go a C#.

Poskytovatel prostředků Pulumi Databricks je založený na poskytovateli Databricks Terraform. Další informace najdete v tématu Terraform Cloud.

Požadavky

  • Účet Pulumi. Zaregistrujte se k Pulumi, pokud ještě nemáte účet Pulumi. Pulumi je zdarma pro jednotlivce a nabízí bezplatnou úroveň pro týmy.

  • Python 3.6 nebo vyšší Pokud chcete zkontrolovat, jestli máte nainstalovaný Python, spusťte příkaz python --version z terminálu nebo pomocí PowerShellu. Nainstalujte Python, pokud ho ještě nemáte nainstalovaný.

    Poznámka:

    Některé instalace Pythonu můžou vyžadovat, abyste místo nich používali python3 python. Pokud ano, nahraďte python python3 ho v celém tomto článku.

  • Adresa URL azure Databricks pro jednotlivé pracovní prostory, například https://adb-1234567890123456.7.azuredatabricks.net.

  • Přihlašovací údaje pro přístup k Azure Databricks Projekty Pulumi Databricks podporují následující typy ověřování Azure Databricks:

    • Ověřování osobního přístupového tokenu Azure Databricks (databricks:authType pat)
    • Ověřování spravovaných identit Azure (databricks:authType azure-msi)
    • Ověřování instančního objektu MS Entra (databricks:authType azure-client-secret)
    • Ověřování Azure CLI (databricks:authType azure-cli)

Následující kroky ukazují, jak vytvořit projekt Pulumi Databricks pomocí Pythonu. Kurz z čistě cloudového poskytovatele– první pohled najdete v tématu Začínáme s Azure v dokumentaci k Pulumi. Kurz z první perspektivy programovacího jazyka najdete v tématu Python, Node.js (JavaScript, TypeScript), Go a .NET (C#, VB, F#) v dokumentaci k Pulumi.

Krok 1: Vytvoření projektu Pulumi

V tomto kroku na místním vývojovém počítači jste nastavili potřebnou adresářovou strukturu pro projekt Pulumi. Pak vytvoříte projekt Pulumi v rámci této adresářové struktury.

  1. V terminálu nebo pomocí PowerShellu vytvořte prázdný adresář a přepněte na něj, například:

    Unix, Linux a macOS

    mkdir pulumi-demo
cd pulumi-demo

    Windows

    md pulumi-demo
cd pulumi-demo

  2. Nainstalujte Pulumi spuštěním následujícího příkazu v závislosti na vašem operačním systému:

    Unix, Linux

    Nainstalujte Pulumi v unixu nebo Linuxu pomocí nástroje curl:

    curl -fsSL https://get.pulumi.com | sh

    MacOS

    Nainstalujte Pulumi v macOS pomocí Homebrew:

    brew install pulumi/tap/pulumi

    Windows

    Nainstalujte Pulumi ve Windows pomocí PowerShellu se zvýšenými oprávněními prostřednictvím správce balíčků Chocolatey:

    choco install pulumi

    Alternativní možnosti instalace Pulumi naleznete v části Stažení a instalace v dokumentaci Pulumi.

  3. Spuštěním následujícího příkazu vytvořte základní projekt Python Pulumi:

    pulumi new python

    Tip

    Projekt Pulumi můžete vytvořit také z online účtu Pulumi (projekty > vytvořit projekt). Pro Azure Databricks ale neexistuje žádná šablona projektu.

  4. Pokud se zobrazí výzva, stiskněte klávesu Enter a pak se pomocí webového prohlížeče přihlaste k účtu Pulumi online, pokud ještě nejste přihlášení. Po přihlášení se vraťte do terminálu nebo PowerShellu.

  5. Po zobrazení výzvy k zadání názvu projektu přijměte výchozí název pulumi-demo projektu stisknutím klávesy Enter.

  6. Po zobrazení výzvy k zadání popisu projektu zadejte A demo Python Pulumi Databricks project a stiskněte Enter.

  7. po zobrazení výzvy k zadání názvu zásobníku přijměte výchozí název zásobníku dev stisknutím klávesy Enter. Pulumi vytvoří následující soubory a podadresář ve vašem pulumi-demo adresáři:

    • Pulumi.yaml, což je seznam nastavení pro váš projekt Pulumi.
    • __main__.py, který obsahuje kód Pythonu, který píšete pro váš projekt Pulumi.
    • requirements.txt, což je seznam podpůrných balíčků kódu Pythonu, které Pulumi nainstaluje pro váš projekt.
    • .gitignore, což je seznam souborů a adresářů, které Git ignoruje, pokud chcete tento projekt odeslat do vzdáleného úložiště Git.
    • Podadresář venv obsahuje podporu kódu virtuálního prostředí Pythonu, který Pulumi používá pro váš projekt.

  8. Spuštěním následujícího příkazu proveďte počáteční nasazení zásobníku dev projektu:

    pulumi up

  9. Po zobrazení výzvy k provedení této aktualizace přejděte stisknutím klávesy se šipkou nahoru na ano a pak stiskněte Enter.

  10. Zkopírujte odkaz Zobrazit živě, který se zobrazí, a vložte ho do adresního řádku webového prohlížeče, který vás přenese do online účtu Pulumi. dev Zobrazí se podrobnosti o aktivitě zásobníku pro váš pulumi-demo projekt. V tuto chvíli není moc vidět, protože v zásobníku ještě nejsou žádné prostředky. Tyto prostředky vytvoříte v dalším kroku.

Krok 2: Vytvoření prostředků Databricks

V tomto kroku pomocí poskytovatele prostředků Pulumi Databricks vytvoříte v existujícím pracovním prostoru Azure Databricks poznámkový blok a úlohu ke spuštění tohoto poznámkového bloku.

  1. __main.py__ Do souboru, který Pulumi vygeneroval, zadejte následující kód pomocí preferovaného textového editoru nebo integrovaného vývojového prostředí (IDE). Tento kód deklaruje prostředky poznámkového bloku a úlohy Pulumi Databricks a jejich nastavení:

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

  2. Definujte hodnotu konfigurace s názvem resource-prefixa nastavte ji na pevně zakódovanou hodnotu pulumi-demo, spuštěním následujícího příkazu. Pulumi používá tuto konfigurační hodnotu k pojmenování poznámkového bloku a úlohy:

    pulumi config set resource-prefix "pulumi-demo"

    Pulumi vytvoří soubor pojmenovaný Pulumi.dev.yaml ve stejném adresáři jako __main__.py soubor a přidá do tohoto souboru YAML následující kód:

    config:
  pulumi-demo:resource_prefix: pulumi-demo

    Použití hodnot konfigurace umožňuje, aby byl kód modulární a opakovaně použitelný. Teď může váš __main__.py soubor znovu použít někdo jiný a definovat pro proměnnou jinou hodnotu resource_prefix beze změny obsahu __main__.py souboru.

  3. Definujte hodnotu konfigurace s názvem node-typea nastavte ji na následující pevně zakódovanou hodnotu spuštěním následujícího příkazu. Pulumi používá tuto konfigurační hodnotu k určení typu clusteru, na kterém se úloha spouští.

    pulumi config set node-type "Standard_D3_v2"

    Pulumi.dev.yaml Obsah souboru teď vypadá takto:

    config:
  pulumi-demo:node-type: Standard_D3_v2
  pulumi-demo:resource-prefix: pulumi-demo

  4. Pokud chcete Pulumi povolit ověřování v pracovním prostoru Azure Databricks, definujte konkrétní konfigurační hodnoty Azure Databricks spuštěním souvisejících příkazů. Například pro ověřování osobního přístupového tokenu Azure Databricks spusťte následující příkazy. V těchto příkazech:

    • Nahraďte adresou URL pro jednotlivé pracovní prostory, například https://adb-1234567890123456.7.azuredatabricks.net.<workspace-instance-url>

    • Nahraďte <access-token> hodnotou přístupového tokenu. Nezapomeňte zadat --secret možnost. To dává Pulumi pokyn k šifrování přístupového tokenu jako osvědčený postup zabezpečení.

      Poznámka:

      Ve výchozím nastavení používá Pulumi k šifrování hodnot šifrovací klíč pro jednotlivé zásobníky spravované službou Pulumi a sůl podle hodnoty. Pokud chcete použít alternativního zprostředkovatele šifrování, přečtěte si téma Konfigurace šifrování tajných kódů v dokumentaci k Pulumi.

    pulumi config set databricks:host "<workspace-instance-url>"
pulumi config set databricks:token "<access-token>" --secret

    Pulumi.dev.yaml Obsah souboru teď vypadá takto:

    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

    Pokud chcete použít jiný typ ověřování Azure Databricks, přečtěte si požadavky. Viz také Konfigurace v úložišti Pulumi Databricks na GitHubu.

Krok 3: Nasazení prostředků

V tomto kroku aktivujete virtuální prostředí Pythonu, které Pulumi pro váš projekt poskytuje jako součást spuštění šablony projektu Pulumi Python. Toto virtuální prostředí pomáhá zajistit, abyste společně používali správnou verzi Pythonu, Pulumi a poskytovatele prostředků Pulumi Databricks. K dispozici je několik architektur virtuálních prostředí Pythonu, jako je venv, virtualenv a pipenv. Tento článek a šablona projektu Pulumi Pythonu používají venv. venv je již součástí Pythonu. Další informace naleznete v tématu Vytváření virtuálních prostředí.

  1. Aktivujte virtuální prostředí Python spuštěním následujícího příkazu z adresáře pulumi-demo v závislosti na vašem operačním systému a typu prostředí:

    Platforma Prostředí Příkaz k aktivaci virtuálního prostředí
    Unix, Linux, macOS Bash/zsh source venv/bin/activate
    ryba 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

  2. Spuštěním následujícího příkazu nainstalujte poskytovatele prostředků Pulumi Databricks z indexu balíčků Pythonu (PyPI) do svého virtuálního prostředí:

    pip install pulumi-databricks

    Poznámka:

    Některé instalace pip mohou vyžadovat, abyste místo pip3 pip. Pokud ano, nahraďte pip pip3 ho v celém tomto článku.

  3. Spuštěním následujícího příkazu zobrazte náhled prostředků, které Pulumi vytvoří:

    pulumi preview

    Pokud se zobrazí nějaké chyby, opravte je a pak příkaz spusťte znovu.

    Pokud chcete zobrazit podrobnou sestavu v účtu Pulumi online s tím, co bude Pulumi dělat, zkopírujte odkaz Zobrazit živě , který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.

  4. Vytvořte a nasaďte prostředky do pracovního prostoru Azure Databricks spuštěním následujícího příkazu:

    pulumi up

  5. Po zobrazení výzvy k provedení této aktualizace přejděte stisknutím klávesy se šipkou nahoru na ano a pak stiskněte Enter. Pokud se zobrazí nějaké chyby, opravte je a pak příkaz spusťte znovu.

  6. Pokud chcete zobrazit podrobnou sestavu v účtu Pulumi online o tom, co Pulumi udělal, zkopírujte odkaz Zobrazit živě , který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.

Krok 4: Interakce s prostředky

V tomto kroku spustíte úlohu v pracovním prostoru Azure Databricks, ve kterém se spustí zadaný poznámkový blok.

  1. Pokud chcete zobrazit poznámkový blok, který bude úloha běžet ve vašem pracovním prostoru, zkopírujte odkaz URL poznámkového bloku, který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.
  2. Pokud chcete zobrazit úlohu, která spouští poznámkový blok v pracovním prostoru, zkopírujte odkaz adresa URL úlohy, který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.
  3. Pokud chcete úlohu spustit, klikněte na tlačítko Spustit hned na stránce úlohy.
  4. Jakmile se úloha dokončí, zobrazí se výsledky spuštění úlohy v seznamu Dokončená spuštění (posledních 60 dnů) na stránce úlohy, klikněte na poslední položku času ve sloupci Čas zahájení . Podokno Výstup zobrazuje výsledek spuštění kódu poznámkového bloku, který vytiskne čísla 1 až 10.

(Volitelné) Krok 5: Provedení změn prostředku

V tomto volitelném kroku změníte kód poznámkového bloku, znovu nasadíte změněný poznámkový blok a pak pomocí úlohy znovu spustíte změněný poznámkový blok.

Pokud nechcete v poznámkovém bloku provádět žádné změny, přeskočte k kroku 6: Vyčištění.

  1. Zpátky v __main.py__ souboru změňte tento řádek kódu:

    content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")

    Do tohoto souboru a pak soubor uložte:

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

    Tato změna dává poznámkovému bloku pokyn, aby místo čísel 1 až 10 vytiskl obsah zadaného datového rámce.

    Poznámka:

    Ujistěte se, že řádky kódu začínající data a končící ''').decode("UTF-8") jsou zarovnané s okrajem editoru kódu. Jinak Pulumi vloží do poznámkového bloku další prázdné znaky, které můžou způsobit selhání spuštění nového kódu Pythonu.

  2. Volitelně můžete zobrazit náhled prostředku, který bude Pulumi měnit spuštěním následujícího příkazu:

    pulumi preview

    Pokud se zobrazí nějaké chyby, opravte je a pak příkaz spusťte znovu.

    Pokud chcete zobrazit podrobnou sestavu v účtu Pulumi online s tím, co bude Pulumi dělat, zkopírujte odkaz Zobrazit živě , který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.

  3. Nasaďte změnu prostředku do pracovního prostoru Azure Databricks spuštěním následujícího příkazu:

    pulumi up

  4. Po zobrazení výzvy k provedení této aktualizace přejděte stisknutím klávesy se šipkou nahoru na ano a pak stiskněte Enter. Pokud se zobrazí nějaké chyby, opravte je a pak příkaz spusťte znovu.

  5. Pokud chcete zobrazit podrobnou sestavu v účtu Pulumi online o tom, co Pulumi udělal, zkopírujte odkaz Zobrazit živě , který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.

  6. Pokud chcete zobrazit změněný poznámkový blok v pracovním prostoru, zkopírujte odkaz URL poznámkového bloku, který se zobrazí, a vložte ho do adresního řádku webového prohlížeče.

  7. Pokud chcete úlohu znovu spustit se změněným poznámkovým blokem, zkopírujte odkaz Adresa URL úlohy, který se zobrazí, a vložte ji do adresního řádku webového prohlížeče. Potom klikněte na tlačítko Spustit hned na stránce úlohy.

  8. Jakmile se úloha dokončí, zobrazí se výsledky spuštění úlohy v seznamu Dokončená spuštění (posledních 60 dnů) na stránce úlohy, klikněte na poslední položku času ve sloupci Čas zahájení . Podokno Výstup zobrazuje výsledek spuštění kódu poznámkového bloku, který vytiskne obsah zadaného datového rámce.

Krok 6: Vyčištění

V tomto kroku Pulumi dáváte Pulumi pokyn k odebrání poznámkového bloku a úlohy z pracovního prostoru Azure Databricks a odebrání projektu a jeho dev zásobníku pulumi-demo z online účtu Pulumi.

  1. Prostředky z pracovního prostoru Azure Databricks odeberte spuštěním následujícího příkazu:

    pulumi destroy

  2. Po zobrazení výzvy k provedení tohoto odebrání přejděte stisknutím klávesy se šipkou nahoru na ano a stiskněte Enter.

  3. Spuštěním následujícího příkazu odeberte projekt Pulumi pulumi-demo a jeho dev zásobník z online účtu Pulumi:

    pulumi stack rm dev

  4. Po zobrazení výzvy k provedení tohoto odebrání zadejte dev a stiskněte Enter.

  5. Pokud chcete deaktivovat virtuální prostředí Pythonu venv , spusťte následující příkaz:

    deactivate

Testování

Před nasazením můžete svůj projekt Pulumi otestovat. Viz Testování programů Pulumi v dokumentaci Pulumi.

Pro testování jednotek projektů Pulumi založených na Pythonu můžete psát a spouštět testy jednotek pomocí unittestu testovací architektury Pythonu spolu s oborem názvů pulumi.runtime balíčku Pulumi. Pokud chcete spouštět testy na simulovaných prostředcích, nahradíte volání Pulumi (a Do Azure Databricks) napodobením. Viz programy Pulumi testování částí v dokumentaci k Pulumi.

Následující ukázkový soubor s názvem napodobení infra.py implementace poznámkového bloku a úlohy deklarované v souboru tohoto článku main.py . Testy jednotek v tomto příkladu kontrolují, jestli se na základě obsahu poznámkového bloku s kódováním Base64, názvu úlohy a příjemce e-mailu pro úspěšnou úlohu spustí všechny očekávané hodnoty. V takovém případě jsou zde napodobené pouze související vlastnosti s ukázkovými hodnotami. Také požadované hodnoty vlastností prostředků musí být vždy poskytovány, i když neplánujete jejich použití v testech jednotek. V tomto příkladu jsou tyto požadované hodnoty nastaveny na náhodné my-mock- hodnoty a tyto hodnoty nejsou testovány.

# 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' ]
  )
)

Následující příklad souboru test_main.py testuje, zda související vlastnosti vrací jejich očekávané hodnoty.

# 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)

Pokud chcete tyto testy spustit a zobrazit výsledky testů, spusťte z kořenového adresáře projektu Pulumi následující příkaz:

python -m unittest

Informace o dalších typech testů, které můžete spustit, najdete v následujících článcích v dokumentaci Pulumi:

Další materiály