Fournisseur de ressources Pulumi Databricks

Important

Cette documentation a été supprimée et peut ne pas être mise à jour.

Remarque

Cet article traite de Pulumi, qui est développé par un tiers. Pour contacter le fournisseur, consultez la page Support Pulumi.

Cet article vous montre comment utiliser Python et Pulumi, une plateforme d’infrastructure en tant que code (IaC) tierce qui vous permet de créer, déployer et gérer des ressources Azure Databricks à l’aide de langages de programmation familiers, d’outils et de pratiques d’ingénierie. Bien que cet article vous montre comment utiliser Python et le fournisseur de ressources Pulumi Databricks , Pulumi prend en charge d’autres langages en plus de Python pour Azure Databricks, notamment TypeScript, JavaScript, Go et C#.

Le fournisseur de ressources Pulumi Databricks est basé sur le fournisseur Databricks Terraform . Pour plus d’informations, consultez Terraform Cloud.

Exigences

Les étapes suivantes montrent comment créer un projet Pulumi Databricks avec Python. Pour un didacticiel sous l'angle du fournisseur de cloud avant tout, consultez la section Commencer avec Azure dans la documentation Pulumi. Pour obtenir un didacticiel du point de vue du langage de programmation, consultez Python , Node.js (JavaScript, TypeScript), Goet .NET (C#, VB, F#) dans la documentation Pulumi.

Étape 1 : Créer un projet Pulumi

Dans cette étape, sur votre ordinateur de développement local, vous configurez la structure de répertoires nécessaire pour un projet Pulumi. Vous créez ensuite votre projet Pulumi dans cette structure de répertoires.

  1. À partir de votre terminal ou avec PowerShell, créez un répertoire vide, puis basculez vers celui-ci, par exemple :

    Unix, Linux et macOS

    mkdir pulumi-demo
cd pulumi-demo

    Fenêtres

    md pulumi-demo
cd pulumi-demo

  2. Installez Pulumi en exécutant la commande suivante, en fonction de votre système d’exploitation :

    Unix, Linux

    Installez Pulumi sur Unix ou Linux à l’aide de curl:

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

    MacOS

    Installez Pulumi sur macOS à l’aide de Homebrew:

    brew install pulumi/tap/pulumi

    Fenêtres

    Installez Pulumi sur Windows à l’aide de PowerShell avec des autorisations élevées via le gestionnaire de package Chocolatey :

    choco install pulumi

    Pour obtenir d’autres options d’installation de Pulumi, consultez Télécharger et installer dans la documentation Pulumi.

  3. Créez un projet Python Pulumi de base en exécutant la commande suivante :

    pulumi new python

    Conseil

    Vous pouvez également créer un projet Pulumi à partir de votre compte Pulumi en ligne (Projects > Créer un projet). Toutefois, il n’existe aucun modèle de projet pour Azure Databricks.

  4. Si vous y êtes invité, appuyez sur votre touche Entrée, puis utilisez votre navigateur web pour vous connecter à votre compte Pulumi en ligne, si ce n'est pas déjà fait. Une fois connecté, revenez à votre terminal ou à PowerShell.

  5. Lorsque vous êtes invité à entrer un nom de projet , acceptez le nom de projet par défaut de pulumi-demo en appuyant sur Entrée.

  6. Lorsque vous y êtes invité, pour unedescription de projet, entrezA demo Python Pulumi Databricks project et appuyez sur Entrée.

  7. lorsque vous êtes invité, pour un nom de pile, acceptez le nom de la pile par défaut en dev appuyant sur Entrée. Pulumi crée les fichiers et sous-répertoires suivants dans votre répertoire pulumi-demo :

    • Pulumi.yaml, qui est une liste de paramètres pour votre projet Pulumi.
    • __main__.py, qui contient le code Python que vous écrivez pour votre projet Pulumi.
    • requirements.txt, qui est une liste de packages de code Python pris en charge que Pulumi installe pour votre projet.
    • .gitignore, qui est une liste de fichiers et de répertoires que Git ignore si vous souhaitez envoyer (push) ce projet dans un dépôt Git distant.
    • Le sous-répertoire venv contient le code d’environnement virtuel Python que Pulumi utilise pour votre projet.

  8. Effectuez un déploiement initial de la pile dev de votre projet en exécutant la commande suivante :

    pulumi up

  9. Lorsque vous êtes invité à effectuer cette mise à jour, appuyez sur la flèche vers le haut pour accéder à oui, puis appuyez sur Entrée.

  10. Copiez le lien Afficher en direct qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web, ce qui vous amène à votre compte Pulumi en ligne. Les détails de l'activité de la pile dev de votre projet pulumi-demo apparaissent. Il n’y a pas beaucoup à voir pour le moment, car il n’y a pas encore de ressources dans votre pile. Vous créez ces ressources à l’étape suivante.

Étape 2 : Créer des ressources Databricks

Dans cette étape, vous utilisez le fournisseur de ressources Pulumi Databricks pour créer, dans votre espace de travail Azure Databricks existant, un notebook et un travail pour exécuter ce notebook.

  1. Dans le fichier __main.py__ généré par Pulumi, utilisez votre éditeur de texte préféré ou votre environnement de développement intégré (IDE) pour entrer le code suivant. Ce code déclare les ressources Pulumi Databricks Notebook et Job ainsi que leurs paramètres :

    """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. Définissez une valeur de configuration nommée resource-prefixet définissez-la sur la valeur codée en dur de pulumi-demo, en exécutant la commande suivante. Pulumi utilise cette valeur de configuration pour nommer le bloc-notes et le travail :

    pulumi config set resource-prefix "pulumi-demo"

    Pulumi crée un fichier nommé Pulumi.dev.yaml dans le même répertoire que le fichier __main__.py et ajoute le code suivant à ce fichier YAML :

    config:
  pulumi-demo:resource_prefix: pulumi-demo

    L’utilisation de valeurs de configuration permet à votre code d’être plus modulaire et réutilisable. Maintenant, quelqu’un d’autre peut réutiliser votre fichier __main__.py et définir une valeur différente pour la variable resource_prefix sans modifier le contenu du fichier __main__.py.

  3. Définissez une valeur de configuration nommée node-typeet définissez-la sur la valeur codée en dur suivante en exécutant la commande suivante. Pulumi utilise cette valeur de configuration pour déterminer le type de cluster sur lequel le travail s’exécute.

    pulumi config set node-type "Standard_D3_v2"

    Le contenu du fichier Pulumi.dev.yaml ressemble maintenant à ceci :

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

  4. Pour permettre à Pulumi de s’authentifier auprès de votre espace de travail Azure Databricks, définissez des valeurs de configuration spécifiques à Azure Databricks en exécutant les commandes associées. Par exemple, pour l’authentification par jeton d’accès personnel Azure Databricks, exécutez les commandes suivantes. Dans ces commandes :

    • Remplacez <workspace-instance-url> par votre URL de par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net.

    • Remplacez <access-token> par la valeur de votre jeton d’accès. Veillez à spécifier l’option --secret. Cela indique à Pulumi de chiffrer votre jeton d’accès en tant que meilleure pratique de sécurité.

      Remarque

      Par défaut, Pulumi utilise une clé de chiffrement par pile gérée par le service Pulumi et un sel par valeur pour chiffrer les valeurs. Pour utiliser un autre fournisseur de chiffrement, consultez Configuration du chiffrement des secrets dans la documentation Pulumi.

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

    Le contenu du fichier Pulumi.dev.yaml ressemble maintenant à ceci :

    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

    Pour utiliser un autre type d’authentification Azure Databricks, consultez les Exigences. Consultez également configuration dans le référentiel Pulumi Databricks dans GitHub.

Étape 3 : Déployer les ressources

Dans cette étape, vous activez un environnement virtuel Python fourni par Pulumi pour votre projet dans le cadre de l’exécution du modèle de projet Python Pulumi. Cet environnement virtuel vous permet de vous assurer que vous utilisez ensemble la version correcte de Python, Pulumi et le fournisseur de ressources Pulumi Databricks. Il existe plusieurs frameworks d’environnement virtuel Python, tels que venv, virtualenvet pipenv. Cet article et le modèle de projet Pulumi Python utilisent venv. venv est déjà inclus avec Python. Pour plus d’informations, consultez Création d’environnements virtuels.

  1. Activez l’environnement virtuel Python en exécutant la commande suivante à partir de votre répertoire pulumi-demo, en fonction de votre système d’exploitation et du type d’interpréteur de commandes :

    Plateforme Coquille Commande pour activer l’environnement virtuel
    Unix, Linux, macOS bash/zsh source venv/bin/activate
    poisson source venv/bin/activate.fish
    csh/tcsh source venv/bin/activate.csh
    PowerShell Core venv/bin/Activate.ps1
    Fenêtres cmd.exe venv\Scripts\activate.bat
    PowerShell venv\Scripts\Activate.ps1

  2. Installez le fournisseur de ressources Pulumi Databricks à partir de l'index des paquets Python (PyPI) dans votre environnement virtuel en exécutant la commande suivante :

    pip install pulumi-databricks

    Remarque

    Certaines installations de pip peuvent nécessiter l’utilisation de pip3 au lieu de pip. Dans ce cas, remplacez pip pour pip3 tout au long de cet article.

  3. Affichez un aperçu des ressources créées par Pulumi en exécutant la commande suivante :

    pulumi preview

    S’il existe des erreurs signalées, corrigez-les, puis réexécutez la commande.

    Pour afficher un rapport détaillé dans votre compte Pulumi en ligne de ce que Pulumi fera, copiez le lien Afficher en direct qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.

  4. Créez et déployez les ressources sur votre espace de travail Azure Databricks en exécutant la commande suivante :

    pulumi up

  5. Lorsque vous êtes invité à effectuer cette mise à jour, appuyez sur la flèche vers le haut pour accéder à oui, puis appuyez sur Entrée. S’il existe des erreurs signalées, corrigez-les, puis réexécutez la commande.

  6. Pour afficher un rapport détaillé dans votre compte Pulumi en ligne de ce que Pulumi a fait, copiez le lien Afficher en direct qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.

Étape 4 : Interagir avec les ressources

Dans cette étape, vous exécutez le travail dans votre espace de travail Azure Databricks, qui exécute le notebook spécifié.

  1. Pour afficher le bloc-notes que le travail exécutera dans votre espace de travail, copiez le lien URL du bloc-notes qui s’affiche et collez-le dans la barre d’adresses de votre navigateur web.
  2. Pour afficher le travail qui exécute le bloc-notes dans votre espace de travail, copiez le lien URL du travail qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.
  3. Pour exécuter la tâche, cliquez sur le bouton Exécuter maintenant sur la page de la tâche.
  4. Une fois le travail terminé, pour afficher les résultats de l’exécution du travail, dans la liste Exécutions terminées (60 derniers jours) sur la page de travail, cliquez sur l’entrée d’heure la plus récente dans la colonne Heure de début . Le volet Sortie affiche le résultat de l’exécution du code du bloc-notes, qui imprime les nombres 1 à 10.

(Facultatif) Étape 5 : Apporter des modifications à une ressource

Dans cette étape facultative, vous modifiez le code du bloc-notes, redéployez le bloc-notes modifié, puis utilisez le travail pour réexécuter le bloc-notes modifié.

Si vous ne souhaitez pas apporter de modifications au bloc-notes, passez à l’étape 6 : Nettoyez.

  1. De retour dans le fichier __main.py__, modifiez cette ligne de code :

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

    Pour cela, puis enregistrez le fichier :

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

    Cette modification indique au bloc-notes d’imprimer le contenu du DataFrame spécifié au lieu des nombres 1 à 10.

    Remarque

    Assurez-vous que les lignes de code commençant par data et se terminant par ''').decode("UTF-8") sont alignées avec le bord de votre éditeur de code. Dans le cas contraire, Pulumi insère un espace blanc supplémentaire dans le notebook qui peut entraîner l’échec de l’exécution du nouveau code Python.

  2. Si vous le souhaitez, affichez un aperçu de la ressource que Pulumi va modifier en exécutant la commande suivante :

    pulumi preview

    S’il existe des erreurs signalées, corrigez-les, puis réexécutez la commande.

    Pour afficher un rapport détaillé dans votre compte Pulumi en ligne de ce que Pulumi fera, copiez le lien Afficher en direct qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.

  3. Déployez la modification des ressources sur votre espace de travail Azure Databricks en exécutant la commande suivante :

    pulumi up

  4. Lorsque vous êtes invité à effectuer cette mise à jour, appuyez sur la flèche vers le haut pour accéder à oui, puis appuyez sur Entrée. S’il existe des erreurs signalées, corrigez-les, puis réexécutez la commande.

  5. Pour afficher un rapport détaillé dans votre compte Pulumi en ligne de ce que Pulumi a fait, copiez le lien Afficher en direct qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.

  6. Pour afficher le bloc-notes modifié dans votre espace de travail, copiez le lien URL du bloc-notes qui s’affiche et collez-le dans la barre d’adresse de votre navigateur web.

  7. Pour réexécuter le travail avec le bloc-notes modifié, copiez le lien URL du travail qui s’affiche et collez-le dans la barre d’adresses de votre navigateur web. Cliquez ensuite sur le bouton Exécuter maintenant sur la page de travail.

  8. Une fois le travail terminé, pour afficher les résultats de l’exécution du travail, dans la liste Exécutions terminées (60 derniers jours) sur la page de travail, cliquez sur l’entrée d’heure la plus récente dans la colonne Heure de début . Le volet Sortie affiche le résultat de l’exécution du code du bloc-notes, qui imprime le contenu du DataFrame spécifié.

Étape 6 : Nettoyer

Dans cette étape, vous demandez à Pulumi de supprimer le bloc-notes et le travail de votre espace de travail Azure Databricks, ainsi que de supprimer le projet pulumi-demo et sa pile de dev de votre compte Pulumi en ligne.

  1. Supprimez les ressources de votre espace de travail Azure Databricks en exécutant la commande suivante :

    pulumi destroy

  2. Lorsque vous êtes invité à effectuer cette suppression, appuyez sur la flèche vers le haut pour accéder à oui, puis appuyez sur Entrée.

  3. Supprimez le projet pulumi pulumi-demo et sa pile de dev de votre compte Pulumi en ligne en exécutant la commande suivante :

    pulumi stack rm dev

  4. Lorsque vous êtes invité à effectuer cette suppression, tapez dev, puis appuyez sur Entrée.

  5. Pour désactiver l’environnement virtuel venv Python, exécutez la commande suivante :

    deactivate

Test

Vous pouvez tester votre projet Pulumi avant de le déployer. Consultez Programmes de test Pulumi dans la documentation Pulumi.

Pour les tests unitaires de projets Pulumi basés sur Python, vous pouvez écrire et exécuter des tests unitaires à l’aide du test unitaire du framework de test Python, ainsi que l’espace de noms pulumi.runtime du package Pulumi . Pour exécuter des tests sur des ressources simulées, vous remplacez les appels à Pulumi (et à Azure Databricks) par des simulations. Consultez Programmes de test unitaire Pulumi dans la documentation Pulumi.

L'exemple de fichier suivant infra.py simule une implémentation du carnet de notes et de la tâche déclarés dans le fichier main.py de cet article. Les tests unitaires de cet exemple vérifient si le contenu encodé en Base64 du notebook, le nom de la tâche et le destinataire de l'e-mail pour les exécutions réussies de la tâche renvoient tous les valeurs attendues. Par conséquent, seules ces propriétés associées sont simulées ici avec des exemples de valeurs. En outre, les valeurs de propriété de ressource requises doivent toujours être fournies, même si vous ne prévoyez pas de les utiliser dans vos tests unitaires. Dans cet exemple, ces valeurs requises sont définies sur des valeurs de my-mock- aléatoires et ces valeurs ne sont pas testées.

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

L’exemple de fichier suivant test_main.py teste si les propriétés associées retournent leurs valeurs attendues.

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

Pour exécuter ces tests et afficher leurs résultats de test, exécutez la commande suivante à partir du répertoire racine du projet Pulumi :

python -m unittest

Pour plus d’informations sur d’autres types de tests que vous pouvez exécuter, consultez les articles suivants dans la documentation Pulumi :

Autres ressources

  • Last updated on