Pulumi Databricks-resursprovider

Artikel
05/03/2024

Kommentar

Den här artikeln beskriver Pulumi, som varken tillhandahålls eller stöds av Databricks. Information om hur du kontaktar leverantören finns i Pulumi Support.

Den här artikeln visar hur du använder Python och Pulumi, en IaC-plattform (infrastruktur som kod) från tredje part som gör att du kan skapa, distribuera och hantera Azure Databricks-resurser med hjälp av välbekanta programmeringsspråk, verktyg och tekniska metoder. Även om den här artikeln visar hur du använder Python och Pulumi Databricks-resursprovidern har Pulumi stöd för andra språk utöver Python för Azure Databricks, inklusive TypeScript, JavaScript, Go och C#.

Pulumi Databricks-resursprovidern baseras på Databricks Terraform-providern. Mer information finns i Terraform Cloud.

Krav

Ett Pulumi-konto. Registrera dig för Pulumi om du inte redan har ett Pulumi-konto. Pulumi är gratis för enskilda användare och erbjuder en kostnadsfri nivå för team.
Python 3.6 eller senare. Om du vill kontrollera om du har Python installerat kör du kommandot python --version från terminalen eller med PowerShell. Installera Python om du inte redan har installerat det.

Kommentar

Vissa installationer av Python kan kräva att du använder python3 i stället för python. I så fall ersätter du pythonpython3 i den här artikeln.
Url:en för Azure Databricks per arbetsyta, till exempel https://adb-1234567890123456.7.azuredatabricks.net.
Åtkomstautentiseringsuppgifter för Azure Databricks. Pulumi Databricks-projekt stöder följande Azure Databricks-autentiseringstyper:
- Personlig åtkomsttokenautentisering i Azure Databricks (databricks:authType pat)
- Azure-hanterad identitetsautentisering (databricks:authType azure-msi)
- Microsoft Entra ID-tjänstens huvudnamnsautentisering (databricks:authType azure-client-secret)
- Azure CLI-autentisering (databricks:authType azure-cli)

Följande steg visar hur du skapar ett Pulumi Databricks-projekt med Python. En självstudiekurs från ett rent molnleverantörsperspektiv finns i Kom igång med Azure i Pulumi-dokumentationen. En självstudiekurs från ett programmeringsspråkperspektiv finns i stället i Python, Node.js (JavaScript, TypeScript), Go och .NET (C#, VB, F#) i Pulumi-dokumentationen.

Steg 1: Skapa ett Pulumi-projekt

I det här steget konfigurerar du den nödvändiga katalogstrukturen för ett Pulumi-projekt på den lokala utvecklingsdatorn. Sedan skapar du pulumiprojektet i den här katalogstrukturen.

Från terminalen eller med PowerShell skapar du en tom katalog och växlar sedan till den, till exempel:

Unix, linux och macos
```
mkdir pulumi-demo
cd pulumi-demo
```
Windows
```
md pulumi-demo
cd pulumi-demo
```
Installera Pulumi genom att köra följande kommando, beroende på ditt operativsystem:

Unix, linux

Installera Pulumi på Unix eller Linux med hjälp av curl:
```
curl -fsSL https://get.pulumi.com | sh
```
Macos

Installera Pulumi på macOS med homebrew:
```
brew install pulumi/tap/pulumi
```
Windows

Installera Pulumi i Windows med hjälp av PowerShell med utökade behörigheter via Chocolatey-pakethanteraren:
```
choco install pulumi
```
Alternativa installationsalternativ för Pulumi finns i Ladda ned och installera i Pulumi-dokumentationen.
Skapa ett grundläggande Python Pulumi-projekt genom att köra följande kommando:
```
pulumi new python
```
Dricks

Du kan också skapa ett Pulumi-projekt från ditt Pulumi-konto online (Projekt > skapa projekt). Det finns dock ingen projektmall för Azure Databricks.
Om du uppmanas att göra det trycker du på Retur-tangenten och använder sedan webbläsaren för att logga in på ditt Pulumi-konto online, om du inte redan är inloggad. När du har loggat in går du tillbaka till terminalen eller PowerShell.
När du uppmanas att ange ett projektnamn godkänner du standardprojektets pulumi-demo namn genom att trycka på Retur.
När du uppmanas att ange en projektbeskrivning anger A demo Python Pulumi Databricks project och trycker du på Retur.
när du uppmanas att ange ett stacknamn godkänner du standardstackens namn dev genom att trycka på Retur. Pulumi skapar följande filer och underkataloger i din pulumi-demo katalog:
- Pulumi.yaml, som är en lista över inställningar för ditt Pulumi-projekt.
- __main__.py, som innehåller Python-koden som du skriver för pulumiprojektet.
- requirements.txt, som är en lista över stöd för Python-kodpaket som Pulumi installerar för projektet.
- .gitignore, som är en lista över filer och kataloger som Git ignorerar om du vill skicka projektet till en fjärransluten Git-lagringsplats.
- Underkatalogen venv innehåller stöd för python-kod för virtuell miljö som Pulumi använder för projektet.
Utför en första distribution av projektets dev stack genom att köra följande kommando:
```
pulumi up
```
När du uppmanas att utföra den här uppdateringen trycker du på uppåtpilen för att navigera till ja och trycker sedan på Retur.
Kopiera länken Visa live som visas och klistra in den i webbläsarens adressfält, vilket tar dig till ditt Pulumi-konto online. Stackens dev aktivitetsinformation för projektet pulumi-demo visas. Det finns inte mycket att se just nu, eftersom det inte finns några resurser i din stack ännu. Du skapar dessa resurser i nästa steg.

Steg 2: Skapa Databricks-resurser

I det här steget använder du Resursprovidern Pulumi Databricks för att skapa en notebook-fil och ett jobb i din befintliga Azure Databricks-arbetsyta för att köra anteckningsboken.

I filen __main.py__ som Pulumi genererade använder du önskad textredigerare eller integrerad utvecklingsmiljö (IDE) för att ange följande kod. Den här koden deklarerar resurserna Pulumi Databricks Notebook och Job och deras inställningar:

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

Definiera ett konfigurationsvärde med namnet resource-prefixoch ange det till det hårdkodade värdet för pulumi-demogenom att köra följande kommando. Pulumi använder det här konfigurationsvärdet för att namnge anteckningsboken och jobbet:
```
pulumi config set resource-prefix "pulumi-demo"
```
Pulumi skapar en fil med namnet Pulumi.dev.yaml i samma katalog som __main__.py filen och lägger till följande kod i den här YAML-filen:
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
Med hjälp av konfigurationsvärden kan koden vara mer modulär och återanvändbar. Nu kan någon annan återanvända filen __main__.py och definiera ett annat värde för variabeln resource_prefix utan att ändra innehållet i __main__.py filen.
Definiera ett konfigurationsvärde med namnet node-typeoch ange det till följande hårdkodade värde genom att köra följande kommando. Pulumi använder det här konfigurationsvärdet för att fastställa vilken typ av kluster jobbet körs på.
```
pulumi config set node-type "Standard_D3_v2"
```
Innehållet i Pulumi.dev.yaml filen ser nu ut så här:
```
config:
  pulumi-demo:node-type: Standard_D3_v2
  pulumi-demo:resource-prefix: pulumi-demo
```
Om du vill göra det möjligt för Pulumi att autentisera med din Azure Databricks-arbetsyta definierar du Specifika konfigurationsvärden för Azure Databricks genom att köra relaterade kommandon. Kör till exempel följande kommandon för personlig åtkomsttokenautentisering i Azure Databricks. I följande kommandon:
- Ersätt <workspace-instance-url> med url:en per arbetsyta, till exempel https://adb-1234567890123456.7.azuredatabricks.net.
- Ersätt <access-token> med värdet för din åtkomsttoken. Se till att ange alternativet --secret . Detta instruerar Pulumi att kryptera din åtkomsttoken som bästa praxis för säkerhet.
  
  Kommentar
  
  Som standard använder Pulumi en krypteringsnyckel per stack som hanteras av Pulumi-tjänsten och ett salt per värde för att kryptera värden. Information om hur du använder en alternativ krypteringsprovider finns i Konfigurera kryptering av hemligheter i Pulumi-dokumentationen.
```
pulumi config set databricks:host "<workspace-instance-url>"
pulumi config set databricks:token "<access-token>" --secret
```
Innehållet i Pulumi.dev.yaml filen ser nu ut så här:
```
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
```
Information om hur du använder en annan Azure Databricks-autentiseringstyp finns i Krav. Se även Konfiguration i Pulumi Databricks-lagringsplatsen i GitHub.

Steg 3: Distribuera resurserna

I det här steget aktiverar du en virtuell Python-miljö som Pulumi tillhandahåller för projektet som en del av körningen av Projektmallen Pulumi Python. Den här virtuella miljön hjälper dig att se till att du använder rätt version av Python, Pulumi och Pulumi Databricks-resursprovidern tillsammans. Det finns flera python-ramverk för virtuell miljö, till exempel venv, virtualenv och pipenv. Den här artikeln och Projektmallen Pulumi Python använder venv. venv ingår redan i Python. Mer information finns i Skapa virtuella miljöer.

Aktivera den virtuella Python-miljön genom att köra följande kommando från din pulumi-demo katalog, beroende på operativsystem och gränssnittstyp:

Plattform	Gränssnitt	Kommando för att aktivera virtuell miljö
Unix, Linux, macOS	bash/zsh	`source venv/bin/activate`
	Fisk	`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`

Installera Pulumi Databricks-resursprovidern från Python Package Index (PyPI) i din virtuella miljö genom att köra följande kommando:
```
pip install pulumi-databricks
```
Kommentar

Vissa installationer av pip kan kräva att du använder pip3 i stället pipför . I så fall ersätter du pippip3 i den här artikeln.
Förhandsgranska de resurser som Pulumi skapar genom att köra följande kommando:
```
pulumi preview
```
Om några fel rapporteras kan du åtgärda dem och sedan köra kommandot igen.

Om du vill visa en detaljerad rapport i ditt Pulumi-konto online om vad Pulumi kommer att göra kopierar du länken Visa live som visas och klistrar in den i webbläsarens adressfält.
Skapa och distribuera resurserna till din Azure Databricks-arbetsyta genom att köra följande kommando:
```
pulumi up
```
När du uppmanas att utföra den här uppdateringen trycker du på uppåtpilen för att navigera till ja och trycker sedan på Retur. Om några fel rapporteras kan du åtgärda dem och sedan köra kommandot igen.
Om du vill visa en detaljerad rapport i ditt Pulumi-konto online om vad Pulumi gjorde kopierar du länken Visa live som visas och klistrar in den i webbläsarens adressfält.

Steg 4: Interagera med resurserna

I det här steget kör du jobbet på din Azure Databricks-arbetsyta, som kör den angivna notebook-filen.

Om du vill visa anteckningsboken som jobbet ska köras på din arbetsyta kopierar du länken notebook-URL som visas och klistrar in den i webbläsarens adressfält.
Om du vill visa jobbet som kör anteckningsboken på din arbetsyta kopierar du länken Jobb-URL som visas och klistrar in den i webbläsarens adressfält.
Om du vill köra jobbet klickar du på knappen Kör nu på jobbsidan.
När jobbet har körts klickar du på den senaste tidsposten i kolumnen Starttid i listan Slutförda körningar (senaste 60 dagarna) på jobbsidan för att visa jobbkörningens resultat. Fönstret Utdata visar resultatet av att köra anteckningsbokens kod, som skriver ut talen 1 till 10.

(Valfritt) Steg 5: Gör ändringar i en resurs

I det här valfria steget ändrar du anteckningsbokens kod, distribuerar om den ändrade anteckningsboken och använder sedan jobbet för att köra den ändrade anteckningsboken igen.

Om du inte vill göra några ändringar i anteckningsboken går du vidare till Steg 6: Rensa.

Gå tillbaka till __main.py__ filen och ändra den här kodraden:
```
content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
```
Till detta och spara sedan filen:
```
  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")
```
Den här ändringen instruerar anteckningsboken att skriva ut innehållet i den angivna DataFrame i stället för siffrorna 1 till 10.

Kommentar

Kontrollera att kodraderna som börjar med data och slutar med ''').decode("UTF-8") är justerade med kodredigerarens kant. Annars infogar Pulumi ytterligare blanksteg i notebook-filen som kan leda till att den nya Python-koden inte kan köras.
Du kan också förhandsgranska resursen som Pulumi ändrar genom att köra följande kommando:
```
pulumi preview
```
Om några fel rapporteras kan du åtgärda dem och sedan köra kommandot igen.

Om du vill visa en detaljerad rapport i ditt Pulumi-konto online om vad Pulumi kommer att göra kopierar du länken Visa live som visas och klistrar in den i webbläsarens adressfält.
Distribuera resursändringen till din Azure Databricks-arbetsyta genom att köra följande kommando:
```
pulumi up
```
När du uppmanas att utföra den här uppdateringen trycker du på uppåtpilen för att navigera till ja och trycker sedan på Retur. Om några fel rapporteras kan du åtgärda dem och sedan köra kommandot igen.
Om du vill visa en detaljerad rapport i ditt Pulumi-konto online om vad Pulumi gjorde kopierar du länken Visa live som visas och klistrar in den i webbläsarens adressfält.
Om du vill visa den ändrade anteckningsboken på din arbetsyta kopierar du länken notebook-URL som visas och klistrar in den i webbläsarens adressfält.
Om du vill köra jobbet igen med den ändrade anteckningsboken kopierar du länken Jobb-URL som visas och klistrar in den i webbläsarens adressfält. Klicka sedan på knappen Kör nu på jobbsidan.
När jobbet har körts klickar du på den senaste tidsposten i kolumnen Starttid i listan Slutförda körningar (senaste 60 dagarna) på jobbsidan för att visa jobbkörningens resultat. Fönstret Utdata visar resultatet av att köra anteckningsbokens kod, som skriver ut innehållet i den angivna DataFrame.

Steg 6: Rensa

I det här steget instruerar du Pulumi att ta bort anteckningsboken och jobbet från din Azure Databricks-arbetsyta samt ta bort pulumi-demo projektet och dess dev stack från ditt Pulumi-konto online.

Ta bort resurserna från din Azure Databricks-arbetsyta genom att köra följande kommando:
```
pulumi destroy
```
När du uppmanas att utföra den här borttagningen trycker du på uppåtpilen för att navigera till ja och trycker sedan på Retur.
Ta bort Pulumi-projektet pulumi-demo och dess dev stack från ditt Pulumi-konto online genom att köra följande kommando:
```
pulumi stack rm dev
```
När du uppmanas att utföra den här borttagningen skriver dev du och trycker sedan på Retur.
Om du vill inaktivera den venv virtuella Python-miljön kör du följande kommando:
```
deactivate
```

Testning

Du kan testa Pulumi-projektet innan du distribuerar det. Se Testa Pulumi-program i Pulumi-dokumentationen.

För enhetstestning av Python-baserade Pulumi-projekt kan du skriva och köra enhetstester med hjälp av Python-testramverkets enhetstest tillsammans med Pulumi-paketets namnområde pulumi.runtime . Om du vill köra tester mot simulerade resurser ersätter du anrop till Pulumi (och till Azure Databricks) med mocks. Se Enhetstestning av Pulumi-program i Pulumi-dokumentationen.

I följande exempelfil med namnet infra.py hånas en implementering av anteckningsboken och jobbet som deklareras i den här artikelns main.py fil. Enhetstesterna i det här exemplet kontrollerar om det Base64-kodade innehållet i anteckningsboken, jobbets namn och e-postmottagaren för ett lyckat jobb kör alla förväntade värden. Därför hånas endast de relaterade egenskaperna här med exempelvärden. Dessutom måste obligatoriska resursegenskapsvärden alltid anges, även om du inte planerar att använda dem i enhetstesterna. I det här exemplet anges dessa obligatoriska värden till slumpmässiga my-mock- värden och dessa värden testas inte.

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

I följande exempelfil test_main.py testas om de relaterade egenskaperna returnerar sina förväntade värden.

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

Kör följande kommando från Pulumi-projektets rotkatalog för att köra dessa tester och visa deras testresultat:

python -m unittest

Information om andra typer av tester som du kan köra finns i följande artiklar i Pulumi-dokumentationen:

Dela via

Pulumi Databricks-resursprovider

Krav

Steg 1: Skapa ett Pulumi-projekt

Unix, linux och macos

Windows

Unix, linux

Macos