Provider di risorse Pulumi Databricks

Nota

Questo articolo illustra Pulumi, che non è fornito né supportato da Databricks. Per contattare il provider, vedere Supporto di Pulumi.

Questo articolo illustra come usare Python e Pulumi, una piattaforma IaC (Infrastructure as Code) di terze parti che consente di creare, distribuire e gestire risorse di Azure Databricks usando linguaggi di programmazione, strumenti e procedure di progettazione familiari. Anche se questo articolo illustra come usare Python e il provider di risorse Pulumi Databricks, Pulumi supporta altri linguaggi oltre a Python per Azure Databricks, tra cui TypeScript, JavaScript, Go e C#.

Il provider di risorse Pulumi Databricks si basa sul provider Databricks Terraform. Per altre informazioni, vedere Terraform Cloud.

Requisiti

• Un account Pulumi. Iscriversi a Pulumi, se non si ha già un account Pulumi. Pulumi è gratuito per i singoli utenti e offre un livello gratuito per i team.

• Python 3.6 o versione successiva. Per verificare se Python è installato, eseguire il comando python --version dal terminale o con PowerShell. Installare Python, se non è già installato.

  Nota

  Alcune installazioni di Python possono richiedere l'uso python3 invece di python. In tal caso, sostituire python per python3 tutto questo articolo.

• URL di Azure Databricks per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net.

• Credenziali di accesso di Azure Databricks. I progetti Pulumi Databricks supportano i tipi di autenticazione di Azure Databricks seguenti:

  • Autenticazione del token di accesso personale di Azure Databricks (databricks:authType pat)
  • Autenticazione delle identità gestite di Azure (databricks:authType azure-msi)
  • Autenticazione dell'entità servizio MS Entra (databricks:authType azure-client-secret)
  • Autenticazione dell'interfaccia della riga di comando di Azure (databricks:authType azure-cli)

I passaggi seguenti illustrano come creare un progetto Pulumi Databricks con Python. Per un'esercitazione dal punto di vista puramente del provider di servizi cloud, vedere Introduzione ad Azure nella documentazione di Pulumi. Per un'esercitazione dal punto di vista del linguaggio di programmazione, vedere invece Python, Node.js (JavaScript, TypeScript), Go e .NET (C#, VB, F#) nella documentazione di Pulumi.

Passaggio 1: Creare un progetto Pulumi

In questo passaggio, nel computer di sviluppo locale si configura la struttura di directory necessaria per un progetto Pulumi. Creare quindi il progetto Pulumi all'interno di questa struttura di directory.

1. Dal terminale o con PowerShell creare una directory vuota e quindi passare ad essa, ad esempio:

   Unix, Linux e macOS

   mkdir pulumi-demo
   cd pulumi-demo
   

   Finestre

   md pulumi-demo
   cd pulumi-demo
   

2. Installare Pulumi eseguendo il comando seguente, a seconda del sistema operativo:

   Unix, Linux

   Installare Pulumi in Unix o Linux usando curl:

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

   MacOS

   Installare Pulumi in macOS usando Homebrew:

   brew install pulumi/tap/pulumi
   

   Finestre

   Installare Pulumi in Windows usando PowerShell con autorizzazioni elevate tramite gestione pacchetti Chocolatey:

   choco install pulumi
   

   Per le opzioni di installazione alternative di Pulumi, vedere Scaricare e installare nella documentazione di Pulumi.

3. Creare un progetto Python Pulumi di base eseguendo il comando seguente:

   pulumi new python
   

   Suggerimento

   È anche possibile creare un progetto Pulumi dall'account Pulumi online (Progetti > crea progetto). Non esiste tuttavia alcun modello di progetto per Azure Databricks.

4. Se richiesto, premere INVIO e quindi usare il Web browser per accedere all'account Pulumi online, se non si è già connessi. Dopo l'accesso, tornare al terminale o a PowerShell.

5. Quando viene richiesto un nome di progetto, accettare il nome predefinito del pulumi-demo progetto premendo INVIO.

6. Quando viene richiesta una descrizione del progetto, immettere A demo Python Pulumi Databricks project e premere INVIO.

7. quando viene richiesto un nome dello stack, accettare il nome dello stack predefinito di dev premendo INVIO. Pulumi crea i file e la sottodirectory seguenti nella pulumi-demo directory:

   • Pulumi.yaml, che è un elenco di impostazioni per il progetto Pulumi.
   • __main__.py, che contiene il codice Python scritto per il progetto Pulumi.
   • requirements.txt, che è un elenco di pacchetti di codice Python di supporto installati da Pulumi per il progetto.
   • .gitignore, che è un elenco di file e directory che Git ignora se si vuole eseguire il push di questo progetto in un repository Git remoto.
   • La venv sottodirectory contiene il codice dell'ambiente virtuale Python di supporto usato da Pulumi per il progetto.

8. Eseguire una distribuzione iniziale dello stack del dev progetto eseguendo il comando seguente:

   pulumi up
   

9. Quando viene richiesto di eseguire questo aggiornamento, premere il tasto freccia su per passare a sì e quindi premere INVIO.

10. Copiare il collegamento Visualizza live visualizzato e incollarlo nella barra degli indirizzi del Web browser, che consente di accedere all'account Pulumi online. Vengono dev visualizzati i dettagli dell'attività dello stack per il pulumi-demo progetto. Non c'è molto da vedere in questo momento, perché non ci sono ancora risorse nello stack. Queste risorse vengono create nel passaggio successivo.

Passaggio 2: Creare risorse di Databricks

In questo passaggio si usa il provider di risorse Pulumi Databricks per creare, nell'area di lavoro di Azure Databricks esistente, un notebook e un processo per eseguire tale notebook.

1. __main.py__ Nel file generato da Pulumi usare l'editor di testo preferito o l'ambiente di sviluppo integrato (IDE) per immettere il codice seguente. Questo codice dichiara le risorse Notebook e job pulumi Databricks e le relative impostazioni:

   """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. Definire un valore di configurazione denominato resource-prefixe impostarlo sul valore hardcoded di pulumi-demo, eseguendo il comando seguente. Pulumi usa questo valore di configurazione per denominare il notebook e il processo:

   pulumi config set resource-prefix "pulumi-demo"
   

   Pulumi crea un file denominato Pulumi.dev.yaml nella stessa directory del __main__.py file e aggiunge il codice seguente a questo file YAML:

   config:
     pulumi-demo:resource_prefix: pulumi-demo
   

   L'uso dei valori di configurazione consente al codice di essere più modulare e riutilizzabile. Ora un altro utente può riutilizzare il __main__.py file e definire un valore diverso per la resource_prefix variabile senza modificare il contenuto del __main__.py file.

3. Definire un valore di configurazione denominato node-typee impostarlo sul valore hardcoded seguente eseguendo il comando seguente. Pulumi usa questo valore di configurazione per determinare il tipo di cluster in cui viene eseguito il processo.

   pulumi config set node-type "Standard_D3_v2"
   

   Il contenuto del Pulumi.dev.yaml file è ora simile al seguente:

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

4. Per consentire a Pulumi di eseguire l'autenticazione con l'area di lavoro di Azure Databricks, definire valori di configurazione specifici di Azure Databricks eseguendo i comandi correlati. Ad esempio, per l'autenticazione del token di accesso personale di Azure Databricks, eseguire i comandi seguenti. In questi comandi:

   • Sostituire <workspace-instance-url> con l'URL per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net.

   • Sostituire <access-token> con il valore del token di accesso. Assicurarsi di specificare l'opzione --secret . Ciò indica a Pulumi di crittografare il token di accesso come procedura consigliata per la sicurezza.

     Nota

     Per impostazione predefinita, Pulumi usa una chiave di crittografia per stack gestita dal servizio Pulumi e un salt per valore per crittografare i valori. Per usare un provider di crittografia alternativo, vedere Configurazione della crittografia dei segreti nella documentazione di Pulumi.

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

   Il contenuto del Pulumi.dev.yaml file è ora simile al seguente:

   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
   

   Per usare un tipo di autenticazione di Azure Databricks diverso, vedere Requisiti. Vedere anche Configurazione nel repository Pulumi Databricks in GitHub.

Passaggio 3: Distribuire le risorse

In questo passaggio si attiva un ambiente virtuale Python fornito da Pulumi per il progetto come parte dell'esecuzione del modello di progetto Python Pulumi. Questo ambiente virtuale consente di assicurarsi di usare insieme la versione corretta di Python, Pulumi e il provider di risorse Pulumi Databricks. Sono disponibili diversi framework di ambiente virtuale Python, ad esempio venv, virtualenv e pipenv. Questo articolo e il modello di progetto Python Pulumi usano venv. venv è già incluso in Python. Per altre informazioni, consultare Creare ambienti virtuali.

1. Attivare l'ambiente virtuale Python eseguendo il comando seguente dalla pulumi-demo directory, a seconda del sistema operativo e del tipo di shell:

   Piattaforma	Shell	Comando per attivare l'ambiente virtuale
   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
   Finestre	cmd.exe	venv\Scripts\activate.bat
   	PowerShell	venv\Scripts\Activate.ps1

2. Installare il provider di risorse Pulumi Databricks da Python Package Index (PyPI) nell'ambiente virtuale eseguendo il comando seguente:

   pip install pulumi-databricks
   

   Nota

   Alcune installazioni di pip potrebbero richiedere l'uso pip3 invece di pip. In tal caso, sostituire pip per pip3 tutto questo articolo.

3. Visualizzare in anteprima le risorse create da Pulumi eseguendo il comando seguente:

   pulumi preview
   

   Se sono presenti errori segnalati, correggerli e quindi eseguire di nuovo il comando.

   Per visualizzare un report dettagliato nell'account Pulumi online di ciò che Pulumi farà, copiare il collegamento Visualizza live visualizzato e incollarlo nella barra degli indirizzi del Web browser.

4. Creare e distribuire le risorse nell'area di lavoro di Azure Databricks eseguendo il comando seguente:

   pulumi up
   

5. Quando viene richiesto di eseguire questo aggiornamento, premere il tasto freccia su per passare a sì e quindi premere INVIO. Se sono presenti errori segnalati, correggerli e quindi eseguire di nuovo il comando.

6. Per visualizzare un report dettagliato nell'account Pulumi online di ciò che ha fatto Pulumi, copiare il collegamento Visualizza live visualizzato e incollarlo nella barra degli indirizzi del Web browser.

Passaggio 4: Interagire con le risorse

In questo passaggio si esegue il processo nell'area di lavoro di Azure Databricks, che esegue il notebook specificato.

1. Per visualizzare il notebook che il processo verrà eseguito nell'area di lavoro, copiare il collegamento URL del notebook visualizzato e incollarlo nella barra degli indirizzi del Web browser.
2. Per visualizzare il processo che esegue il notebook nell'area di lavoro, copiare il collegamento URL processo visualizzato e incollarlo nella barra degli indirizzi del Web browser.
3. Per eseguire il processo, fare clic sul pulsante Esegui ora nella pagina del processo.
4. Al termine dell'esecuzione del processo, per visualizzare i risultati dell'esecuzione del processo, nell'elenco Esecuzioni completate (ultimi 60 giorni) della pagina del processo, fare clic sulla voce relativa all’ora più recente nella colonna Ora di inizio. Il riquadro Output mostra il risultato dell'esecuzione del codice del notebook, che stampa i numeri da 1 a 10.

(Facoltativo) Passaggio 5: Apportare modifiche a una risorsa

In questo passaggio facoltativo si modifica il codice del notebook, si ridistribuisce il notebook modificato e quindi si usa il processo per eseguire nuovamente il notebook modificato.

Se non si desidera apportare modifiche al notebook, passare al passaggio 6: Pulire.

1. Tornare al __main.py__ file e modificare questa riga di codice:

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

   A questo scopo, quindi salvare il file:

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

   Questa modifica indica al notebook di stampare il contenuto del dataframe specificato anziché i numeri da 1 a 10.

   Nota

   Assicurarsi che le righe di codice che iniziano con data e che terminano con ''').decode("UTF-8") siano allineate al bordo dell'editor di codice. In caso contrario, Pulumi inserisce spazi vuoti aggiuntivi nel notebook che potrebbe causare l'esito negativo dell'esecuzione del nuovo codice Python.

2. Facoltativamente, visualizzare in anteprima la risorsa che Pulumi modificherà eseguendo il comando seguente:

   pulumi preview
   

   Se sono presenti errori segnalati, correggerli e quindi eseguire di nuovo il comando.

   Per visualizzare un report dettagliato nell'account Pulumi online di ciò che Pulumi farà, copiare il collegamento Visualizza live visualizzato e incollarlo nella barra degli indirizzi del Web browser.

3. Distribuire la modifica della risorsa nell'area di lavoro di Azure Databricks eseguendo il comando seguente:

   pulumi up
   

4. Quando viene richiesto di eseguire questo aggiornamento, premere il tasto freccia su per passare a sì e quindi premere INVIO. Se sono presenti errori segnalati, correggerli e quindi eseguire di nuovo il comando.

5. Per visualizzare un report dettagliato nell'account Pulumi online di ciò che ha fatto Pulumi, copiare il collegamento Visualizza live visualizzato e incollarlo nella barra degli indirizzi del Web browser.

6. Per visualizzare il notebook modificato nell'area di lavoro, copiare il collegamento URL del notebook visualizzato e incollarlo nella barra degli indirizzi del Web browser.

7. Per rieseguire il processo con il notebook modificato, copiare il collegamento URL processo visualizzato e incollarlo nella barra degli indirizzi del Web browser. Fare quindi clic sul pulsante Esegui ora nella pagina del processo.

8. Al termine dell'esecuzione del processo, per visualizzare i risultati dell'esecuzione del processo, nell'elenco Esecuzioni completate (ultimi 60 giorni) della pagina del processo, fare clic sulla voce relativa all’ora più recente nella colonna Ora di inizio. Il riquadro Output mostra il risultato dell'esecuzione del codice del notebook, che stampa il contenuto del dataframe specificato.

Passaggio 6: Pulire

In questo passaggio si indica a Pulumi di rimuovere il notebook e il processo dall'area di lavoro di Azure Databricks, nonché rimuovere il pulumi-demo progetto e il relativo dev stack dall'account Pulumi online.

1. Rimuovere le risorse dall'area di lavoro di Azure Databricks eseguendo il comando seguente:

   pulumi destroy
   

2. Quando viene richiesto di eseguire questa rimozione, premere il tasto freccia su per passare a sì e quindi premere INVIO.

3. Rimuovere il progetto Pulumi e il relativo dev stack dall'account Pulumi pulumi-demo online eseguendo il comando seguente:

   pulumi stack rm dev
   

4. Quando viene richiesto di eseguire questa rimozione, digitare dev e quindi premere INVIO.

5. Per disattivare l'ambiente venv virtuale Python, eseguire il comando seguente:

   deactivate
   

Test

È possibile testare il progetto Pulumi prima di distribuirlo. Vedere Test dei programmi Pulumi nella documentazione di Pulumi.

Per gli unit test dei progetti Pulumi basati su Python, è possibile scrivere ed eseguire unit test usando lo unittest del framework di test Python insieme allo spazio dei nomi pulumi.runtime del pacchetto Pulumi. Per eseguire test sulle risorse simulate, sostituire le chiamate a Pulumi (e ad Azure Databricks) con simulazioni. Vedere Unit testing programmi Pulumi nella documentazione di Pulumi.

Il file di esempio seguente denominato infra.py simula un'implementazione del notebook e del processo dichiarato nel file di main.py questo articolo. Gli unit test in questo esempio controllano se il contenuto con codifica Base64 del notebook, il nome del processo e il destinatario del messaggio di posta elettronica per il corretto processo esegue tutti i valori previsti restituiti. Di conseguenza, solo le proprietà correlate vengono fittizie qui con valori di esempio. Inoltre, è necessario specificare sempre i valori delle proprietà delle risorse necessarie, anche se non si prevede di usarli negli unit test. In questo esempio questi valori obbligatori vengono impostati su valori casuali my-mock- e tali valori non vengono testati.

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

Il file di test_main.py esempio seguente verifica se le proprietà correlate restituiscono i valori previsti.

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

Per eseguire questi test e visualizzare i risultati del test, eseguire il comando seguente dalla directory radice del progetto Pulumi:

python -m unittest

Per informazioni su altri tipi di test che è possibile eseguire, vedere gli articoli seguenti nella documentazione di Pulumi:

• Test delle proprietà per i programmi Pulumi
• Test di integrazione per i programmi Pulumi

Altre risorse

• Documentazione di Pulumi Databricks
• Repository del codice sorgente del provider di risorse Pulumi Databricks
• Documentazione di Pulumi Azure Native, documentazione di Pulumi azure classico
• Documentazione di Pulumi
• Abilitare la registrazione per Pulumi