Aller au contenu principal
Dernière mise à jour le

Fournisseur de ressources Pulumi Databricks

important

Cette documentation a été retirée et pourrait ne pas être mise à jour.

remarque

Cet article couvre Pulumi, qui est développé par un tiers. Pour contacter le fournisseur, consultez l’assistance Pulumi.

Cet article vous montre comment utiliser Python et Pulumi, une plateforme tierce d'infrastructure as code (IaC) qui vous permet de créer, déployer et gérer des Ressources Databricks en utilisant des langages de programmation, des outils et des pratiques de Data Engineering familiers. 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 Databricks, notamment TypeScript, JavaScript, Go et C#.

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

Exigences​

  • Un compte Pulumi. Inscrivez-vous à Pulumi si vous n’avez pas encore de compte Pulumi. Pulumi est gratuit pour les particuliers et propose une offre gratuite pour les équipes.

  • Python 3.6 ou version supérieure. Pour vérifier si vous avez Python d'installé, exécutez la commande python --version depuis votre terminal ou avec PowerShell. Installez Python, si vous ne l'avez pas déjà installé.

remarque

Certaines installations de Python peuvent vous obliger à utiliser python3 au lieu de python. Si c'est le cas, remplacez python par python3 tout au long de cet article.

Voici les étapes à suivre pour créer un projet Pulumi Databricks avec Python. Pour un didacticiel axé uniquement sur le fournisseur de cloud, consultez Démarrer avec AWS dans la documentation Pulumi. Pour un tutoriel axé sur le langage de programmation, consultez Python, Node.js (JavaScript, TypeScript), Go et .NET (C#, VB, F#) dans la documentation Pulumi.

Étape 1 : créez un projet Pulumi​

Dans cette étape, sur votre machine de développement locale, vous configurez la structure de répertoire nécessaire pour un projet Pulumi. Vous créez ensuite votre projet Pulumi au sein de cette structure de répertoire.

  1. Depuis votre terminal ou avec PowerShell, créez un répertoire vide, puis accédez-y, par exemple :
Bash
mkdir pulumi-demo
cd pulumi-demo
  1. Installez Pulumi en exécutant la commande suivante, en fonction de votre système d'exploitation :

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

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

Pour d'autres options d'installation de Pulumi, consultez Download et installez dans la documentation Pulumi.

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

    Bash
    pulumi new python
astuce

Vous pouvez également créer un projet Pulumi à partir de votre compte Pulumi en ligne ( Projets > Créer un projet ). Cependant, il n'existe pas de Template de projet pour Databricks.

  1. Si vous y êtes invité, appuyez sur la touche **Entrée**, puis utilisez votre navigateur web pour vous connecter à votre compte Pulumi en ligne, si vous n'êtes pas déjà connecté. Après vous être connecté, retournez à votre terminal ou PowerShell.

  2. Lorsque vous êtes invité à saisir un nom de projet , acceptez le nom de projet default de pulumi-demo en appuyant sur Entrée .

  3. Lorsque vous êtes invité à saisir une **description du projet**, saisissez A demo Python Pulumi Databricks project et appuyez sur **Entrée**.

  4. Lorsque vous êtes invité à saisir un nom de pile , acceptez le nom de pile default de dev en appuyant sur Entrée . Pulumi crée les fichiers et le sous-répertoire 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 pousser ce projet vers un repository Git distant.
    • Le sous-répertoire venv contient le code de support de l'environnement virtuel Python que Pulumi utilise pour votre projet.

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

    Bash
    pulumi up

  6. Lorsque vous y êtes invité pour effectuer cette mise à jour, appuyez sur la touche fléchée vers le haut pour naviguer jusqu'à **oui**, puis appuyez sur **Entrée**.

  7. Copiez le View Live Link qui apparaît, puis collez-le dans la barre d’adresse de votre navigateur Web, qui vous mène à votre compte Pulumi en ligne. Les détails de l'activité de la pile dev pour votre projet pulumi-demo s'affichent. Il n'y a pas grand-chose à 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 workspace Databricks existant, un notebook et un job pour exécuter ce notebook.

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

    Python
    """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-prefix, et 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 notebook et le job :

    Bash
    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 :

    YAML
    config:
      pulumi-demo:resource_prefix: pulumi-demo

    L'utilisation de valeurs de configuration permet à votre code d'être plus modulaire et réutilisable. Désormais, une autre personne 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. Veuillez définir une valeur de configuration nommée node-type et 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 job s'exécute.

    Bash
    pulumi config set node-type "i3.xlarge"

    Le contenu du fichier Pulumi.dev.yaml se présente désormais comme suit :

    YAML
    config:
      pulumi-demo:node-type: i3.xlarge
      pulumi-demo:resource-prefix: pulumi-demo

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

    • Remplacez <workspace-instance-url> par votre URL de l'instance Workspace, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com.

    • Remplacez <access-token> par la valeur de votre jeton d'accès. Veillez à spécifier l'option --secret. Ceci indique à Pulumi d'encrypter votre jeton d'accès comme bonne pratique de sécurité.

remarque

By default, 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 fournisseur de chiffrement alternatif, consultez Configuration du chiffrement des secrets dans la documentation Pulumi.

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

Le contenu du fichier Pulumi.dev.yaml se présente désormais comme suit :

YAML
config:
  databricks:host: <your-workspace-instance-url>
  databricks:token:
    secure: <an-encrypted-version-of-your-access-token>
  pulumi-demo:node-type: i3.xlarge
  pulumi-demo:resource_prefix: pulumi-demo

Pour utiliser un autre type d'authentification Databricks, consultez les Exigences. Consultez également Configuration dans le repository Pulumi Databricks sur GitHub.

Étape 3 : Déployez les Ressources​

À cette étape, vous activez un environnement virtuel Python que Pulumi fournit pour votre projet dans le cadre de l'exécution du Template de projet Pulumi Python. Cet environnement virtuel permet de s'assurer que vous utilisez ensemble la bonne version de Python, Pulumi et le fournisseur de ressources Pulumi Databricks. Plusieurs frameworks d'environnement virtuel Python sont disponibles, tels que venv, virtualenv et pipenv. Cet article et le Template de projet Pulumi Python utilisent venv. venv est déjà inclus avec Python. Pour plus d'information, 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 de Shell :

    Plateforme

    Shell

    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

    Windows

    cmd.exe

    venv\Scripts\activate.bat

    PowerShell

    venv\Scripts\Activate.ps1

    Plateforme

    Shell

    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

    Windows

    cmd.exe

    venv\Scripts\activate.bat

    PowerShell

    venv\Scripts\Activate.ps1

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

    Bash
    pip install pulumi-databricks
remarque

Certaines installations de pip peuvent vous demander d'utiliser pip3 au lieu de pip. Si tel est le cas, substituez pip à pip3 dans l'ensemble de cet article.

  1. Prévisualisez les Ressources que Pulumi créera en exécutant la commande suivante :

    Bash
    pulumi preview

    S'il y a des erreurs signalées, corrigez-les et exécutez à nouveau la commande.

    Pour consulter un rapport détaillé en ligne dans votre compte Pulumi sur ce que Pulumi fera, copiez le View Live Link qui apparaît et collez-le dans la barre d'adresse de votre navigateur web.

  2. Créez et déployez les ressources dans votre Workspace Databricks en exécutant la commande suivante :

    Bash
    pulumi up

  3. Lorsque vous êtes invité à effectuer cette mise à jour, appuyez sur votre touche flèche haut pour accéder à oui , puis appuyez sur Entrée . S'il y a des erreurs signalées, corrigez-les, puis exécutez à nouveau la commande.

  4. Pour afficher un rapport détaillé de ce que Pulumi a fait dans votre compte Pulumi en ligne, copiez le View Live Link qui apparaît 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 Job dans votre Workspace Databricks, qui exécute le Notebook spécifié.

  1. Pour consulter le Notebook que le Job exécutera dans votre Workspace, copiez le Notebook URL Link qui apparaît et collez-le dans la barre d’adresse de votre navigateur web.
  2. Pour afficher le Job qui exécute le Notebook dans votre Workspace, copiez le URL du Job Link qui apparaît et collez-le dans la barre d'adresse de votre navigateur web.
  3. Pour exécuter le job, cliquez sur le bouton Exécuter maintenant sur la page du job.
  4. Une fois le Job terminé, pour afficher les résultats de l'exécution du Job, dans la liste **Exécutions terminées (60 derniers jours)** de la page du Job, cliquez sur l'entrée de temps la plus récente dans la colonne **Heure de start**. Le volet **Output** affiche le résultat de l'exécution du code du Notebook, qui imprime les nombres de 1 à 10.

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

Dans cette étape facultative, vous modifiez le code du Notebook, redéployez le Notebook modifié, puis utilisez le Job pour réexécuter le Notebook modifié.

Si vous ne souhaitez pas apporter de modifications au Notebook, passez à l'Étape 6 : nettoyage.

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

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

    À cela, puis enregistrez le fichier :

    Python
      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 demande au notebook d’imprimer le contenu du DataFrame spécifié au lieu des nombres de 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. Sinon, Pulumi insérera des espaces supplémentaires dans le notebook, ce qui pourrait faire échouer l'exécution du nouveau code Python.

  1. Facultativement, prévisualisez la ressource que Pulumi modifiera en exécutant la commande suivante :

    Bash
    pulumi preview

    S'il y a des erreurs signalées, corrigez-les et exécutez à nouveau la commande.

    Pour consulter un rapport détaillé en ligne dans votre compte Pulumi sur ce que Pulumi fera, copiez le View Live Link qui apparaît et collez-le dans la barre d'adresse de votre navigateur web.

  2. Déployez la modification de ressource vers votre workspace Databricks en exécutant la commande suivante :

    Bash
    pulumi up

  3. Lorsque vous êtes invité à effectuer cette mise à jour, appuyez sur votre touche flèche haut pour accéder à oui , puis appuyez sur Entrée . S'il y a des erreurs signalées, corrigez-les, puis exécutez à nouveau la commande.

  4. Pour afficher un rapport détaillé de ce que Pulumi a fait dans votre compte Pulumi en ligne, copiez le View Live Link qui apparaît et collez-le dans la barre d'adresse de votre navigateur web.

  5. Pour afficher le Notebook modifié dans votre Workspace, copiez le Link URL du Notebook qui apparaît et collez-le dans la barre d'adresse de votre navigateur web.

  6. Pour relancer le Job avec le Notebook modifié, copiez le **Job URL** Link qui apparaît et collez-le dans la barre d'adresse de votre navigateur web. Cliquez ensuite sur le bouton **Exécuter maintenant** de la page Job.

  7. Une fois le Job terminé, pour afficher les résultats de l'exécution du Job, dans la liste **Exécutions terminées (60 derniers jours)** de la page du Job, cliquez sur l'entrée de temps la plus récente dans la colonne **Heure de start**. Le volet Sortie affiche le résultat de l'exécution du code du Notebook, qui imprime le contenu du DataFrame spécifié.

Étape 6 : Nettoyer​

Dans cette étape, vous indiquez à Pulumi de supprimer le notebook et le job de votre workspace Databricks ainsi que de supprimer le projet pulumi-demo et sa pile dev de votre compte Pulumi en ligne.

  1. Supprimez les Ressources de votre Workspace Databricks en exécutant la commande suivante :

    Bash
    pulumi destroy

  2. Lorsque vous êtes invité à effectuer cette suppression, appuyez sur la touche flèche haut pour naviguer jusqu'à oui , puis appuyez sur Entrée .

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

    Bash
    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 Python venv, exécutez la commande suivante :

    Bash
    deactivate

Test​

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

Pour les tests unitaires des projets Pulumi basés sur Python, vous pouvez écrire et exécuter des tests unitaires à l’aide du framework de test Python unittest ainsi que de 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 à Databricks) par des mocks. Consultez Tests unitaires des programmes Pulumi dans la documentation Pulumi.

Le fichier d'exemple suivant nommé infra.py simule une implémentation du notebook et du job déclarée 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 du Job et le destinataire de l'e-mail pour les exécutions de Job réussies retournent tous les valeurs attendues. Par conséquent, seules ces propriétés connexes sont simulées ici avec des valeurs d'exemple. De plus, 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 my-mock- aléatoires, et ces valeurs ne sont pas testées.

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

Le fichier d'exemple suivant test_main.py vérifie si les propriétés associées renvoient leurs valeurs attendues.

Python
# 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, exécutez la commande suivante à partir du répertoire racine du projet Pulumi :

Python
python -m unittest

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

Autres ressources​

Sur cette page