Compartir a través de

Proveedor de recursos Pulumi de Databricks

  • Artículo

Nota:

En este artículo se describe Pulumi, desarrollado por un tercero. Para ponerse en contacto con el proveedor, consulte Soporte técnico de Pulumi.

En este artículo se muestra cómo usar Python y Pulumi, una plataforma de infraestructura como código (IaC) de terceros que le permite crear, implementar y administrar recursos de Azure Databricks mediante lenguajes de programación, herramientas y prácticas de ingeniería conocidos. Aunque en este artículo se muestra cómo usar Python y el proveedor de recursos Pulumi Databricks, Pulumi admite otros lenguajes además de Python para Azure Databricks, incluidos TypeScript, JavaScript, Go y C#.

El proveedor de recursos Pulumi Databricks se basa en el proveedor de Databricks Terraform. Para más información, consulte Terraform Cloud.

Requisitos

En los pasos siguientes se muestra cómo crear un proyecto de Pulumi Databricks con Python. Para ver un tutorial desde una perspectiva puramente basada en el proveedor de nube, consulte Introducción a Azure en la documentación de Pulumi. Para ver un tutorial desde una perspectiva de lenguaje de programación primero, consulte Python, Node.js (JavaScript, TypeScript),Go y .NET (C#, VB, F#) en la documentación de Pulumi.

Paso 1: Creación de un proyecto de Pulumi

En este paso, en la máquina de desarrollo local, configuró la estructura de directorios necesaria para un proyecto de Pulumi. A continuación, cree el proyecto de Pulumi dentro de esta estructura de directorios.

  1. Desde el terminal o con PowerShell, cree un directorio vacío y, a continuación, cambie a él, por ejemplo:

    Unix, Linux y macOS

    mkdir pulumi-demo
cd pulumi-demo

    Windows

    md pulumi-demo
cd pulumi-demo

  2. Instale Pulumi mediante la ejecución del siguiente comando, según el sistema operativo:

    Unix, linux

    Instale Pulumi en Unix o Linux mediante curl:

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

    MacOS

    Instale Pulumi en macOS mediante Homebrew:

    brew install pulumi/tap/pulumi

    Windows

    Instale Pulumi en Windows mediante PowerShell con permisos elevados a través del administrador de paquetes Chocolatey:

    choco install pulumi

    Para ver opciones alternativas de instalación de Pulumi, consulte Descargar e instalar en la documentación de Pulumi.

  3. Para crear un proyecto básico de Python de Pulumi, ejecute el siguiente comando:

    pulumi new python

    Sugerencia

    También puede crear un proyecto de Pulumi desde su cuenta de Pulumi en línea (Proyectos > Crear proyecto). Sin embargo, no hay ninguna plantilla de proyecto para Azure Databricks.

  4. Si se le solicita, presione la tecla Entrar y use el explorador web para iniciar sesión en su cuenta de Pulumi en línea, si aún no ha iniciado sesión. Después de iniciar sesión, vuelva al terminal o a PowerShell.

  5. Cuando se le solicite un nombre de proyecto, acepte el nombre de proyecto predeterminado de pulumi-demo pulsando Entrar.

  6. Cuando se le solicite una descripción del proyecto, escriba A demo Python Pulumi Databricks project y presione Entrar.

  7. Cuando se le solicite un nombre de pila, acepte el nombre de pila predeterminado de dev pulsando Entrar. Pulumi crea los siguientes archivos y subdirectorios en el directorio pulumi-demo:

    • Pulumi.yaml, que es una lista de opciones de configuración para el proyecto de Pulumi.
    • __main__.py, que contiene el código de Python que se escribe para el proyecto de Pulumi.
    • requirements.txt, que es una lista de los paquetes de código de Python compatibles que Pulumi instala para el proyecto.
    • .gitignore, que es una lista de archivos y directorios que Git omite si desea insertar este proyecto en un repositorio de Git remoto.
    • El subdirectorio venv contiene el código de entorno virtual de Python compatible que Pulumi usa para el proyecto.

  8. Realice una implementación inicial de la pila del proyecto dev ejecutando el siguiente comando:

    pulumi up

  9. Cuando se le solicite que realice esta actualización, presione la tecla de flecha arriba para ir a Sí y, a continuación, presione Entrar.

  10. Copie el vínculo Ver en directo que aparece y péguelo en la barra de direcciones del explorador web, que le llevará a su cuenta en línea de Pulumi. Aparecen los detalles de la actividad de la pila dev para el proyecto pulumi-demo. No hay mucho que ver ahora, porque todavía no hay ningún recurso en la pila. Estos recursos se crean en el paso siguiente.

Paso 2: Crear recursos Databricks

En este paso, usará el proveedor de recursos Pulumi Databricks para crear, en el área de trabajo de Azure Databricks existente, un cuaderno y un trabajo para ejecutar ese cuaderno.

  1. En el archivo __main.py__ que Pulumi generó, utilice su editor de texto preferido o entorno de desarrollo integrado (IDE) para introducir el siguiente código. Este código declara los recursos de Cuaderno y Trabajo de Pulumi Databricks y su configuración:

    """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. Defina un valor de configuración llamado resource-prefix, y ajústelo al valor codificado de pulumi-demo, ejecutando el siguiente comando. Pulumi usa este valor de configuración para asignar un nombre al cuaderno y al trabajo:

    pulumi config set resource-prefix "pulumi-demo"

    Pulumi crea un archivo llamado Pulumi.dev.yaml en el mismo directorio que el archivo __main__.py y agrega el siguiente código a este archivo YAML:

    config:
  pulumi-demo:resource_prefix: pulumi-demo

    El uso de valores de configuración permite que el código sea más modular y reutilizable. Ahora otra persona puede reutilizar el archivo __main__.py y definir un valor diferente para la variable resource_prefix sin cambiar el contenido del archivo __main__.py.

  3. Defina un valor de configuración llamado node-type, y ajústelo al siguiente valor codificado, ejecutando el siguiente comando. Pulumi usa este valor de configuración para determinar el tipo de clúster en el que se ejecuta el trabajo.

    pulumi config set node-type "Standard_D3_v2"

    El contenido del archivo Pulumi.dev.yaml tiene ahora este aspecto:

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

  4. Para permitir que Pulumi se autentique con el área de trabajo de Azure Databricks, defina valores de configuración específicos de Azure Databricks mediante la ejecución de los comandos relacionados. Por ejemplo, para la autenticación de token de acceso personal de Azure Databricks, ejecute los siguientes comandos. En estos comandos:

    • Reemplace <workspace-instance-url> por la dirección URL por área de trabajo; por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net.

    • Reemplace <access-token> con el valor del token de acceso. Asegúrese de especificar la opción --secret. Esto indica a Pulumi que cifre el token de acceso como procedimiento recomendado de seguridad.

      Nota:

      De forma predeterminada, Pulumi usa una clave de cifrado por pila administrada por el servicio Pulumi y una sal por valor para cifrar los valores. Para usar un proveedor de cifrado alternativo, consulte Configuración de cifrado de secretos en la documentación de Pulumi.

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

    El contenido del archivo Pulumi.dev.yaml tiene ahora este aspecto:

    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

    Para usar otro tipo de autenticación de Azure Databricks, consulte Requisitos. Consulte también Configuración en el repositorio de Pulumi Databricks en GitHub.

Paso 3: Implementar los recursos

En este paso, activará un entorno virtual de Python que Pulumi proporciona para el proyecto como parte de la ejecución de la plantilla de proyecto de Python de Pulumi. Este entorno virtual ayuda a garantizar que usa la versión correcta de Python, Pulumi y el proveedor de recursos de Pulumi Databricks juntos. Hay varios marcos de entorno virtual de Python disponibles, como venv, virtualenv y pipenv. En este artículo y la plantilla de proyecto de Python de Pulumi se usa venv. venv ya está incluido en Python. Para más información, consulte Creación de entornos virtuales.

  1. Active el entorno virtual de Python ejecutando el siguiente comando desde el directorio pulumi-demo, dependiendo de su sistema operativo y tipo de shell:

    Plataforma Shell Comando para activar el entorno virtual
    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
    Windows cmd.exe venv\Scripts\activate.bat
    PowerShell venv\Scripts\Activate.ps1

  2. Instale el proveedor de recursos Pulumi Databricks desde el Python Package Index (PyPI) en su entorno virtual ejecutando el siguiente comando:

    pip install pulumi-databricks

    Nota:

    Algunas instalaciones de pip pueden requerir el uso de pip3 en lugar de pip. Si es así, sustituya pip por pip3 en todo este artículo.

  3. Obtenga una vista previa de los recursos que Pulumi creará ejecutando el siguiente comando:

    pulumi preview

    Si se notifican errores, corrijalos y vuelva a ejecutar el comando.

    Para ver un informe detallado en su cuenta de Pulumi en línea de lo que hará Pulumi, copie el vínculo Ver en directo que aparece y péguelo en la barra de direcciones del explorador web.

  4. Cree e implemente los recursos en el área de trabajo de Azure Databricks mediante la ejecución del siguiente comando:

    pulumi up

  5. Cuando se le solicite que realice esta actualización, presione la tecla de flecha arriba para ir a Sí y, a continuación, presione Entrar. Si se notifican errores, corrijalos y vuelva a ejecutar el comando.

  6. Para ver un informe detallado en su cuenta de Pulumi en línea de lo que hizo Pulumi, copie el vínculo Ver en directo que aparece y péguelo en la barra de direcciones del explorador web.

Paso 4: Interacción con los recursos

En este paso, ejecutará el trabajo en el área de trabajo de Azure Databricks, que ejecuta el cuaderno especificado.

  1. Para ver el cuaderno que ejecutará el trabajo en el área de trabajo, copie el vínculo URL del cuaderno que aparece y péguelo en la barra de direcciones del explorador web.
  2. Para ver el trabajo que ejecuta el cuaderno en el área de trabajo, copie el enlace URL del trabajo que aparece y péguelo en la barra de direcciones del explorador web.
  3. Para ejecutar el trabajo, haga clic en el botón Ejecutar ahora en la página del trabajo.
  4. Una vez que el trabajo termine de ejecutarse, para ver los resultados de la ejecución del trabajo, en la lista Ejecuciones completadas (últimos 60 días) de la página del trabajo, haga clic en la entrada de hora más reciente en la columna Hora de inicio. El panel Salida muestra el resultado de ejecutar el código del cuaderno, que imprime los números del 1 al 10.

(Opcional) Paso 5: Realizar cambios en un recurso

En este paso opcional, cambiará el código del cuaderno, volverá a implementar el cuaderno cambiado y, a continuación, usará el trabajo para volver a ejecutar el cuaderno cambiado.

Si no desea realizar ningún cambio en el cuaderno, vaya al Paso 6: Limpieza.

  1. De vuelta en el archivo __main.py__, cambie esta línea de código:

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

    Para ello, guarde el archivo:

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

    Este cambio indica al cuaderno que imprima el contenido del DataFrame especificado en lugar de los números 1 a 10.

    Nota:

    Asegúrese de que las líneas de código que comienzan por data y que terminan con ''').decode("UTF-8") están alineadas con el borde del editor de código. De lo contrario, Pulumi insertará espacios en blanco adicionales en el cuaderno que pueden provocar que el nuevo código de Python no se ejecute.

  2. Opcionalmente, ejecute el comando siguiente para obtener una vista previa del recurso que Pulumi cambiará:

    pulumi preview

    Si se notifican errores, corrijalos y vuelva a ejecutar el comando.

    Para ver un informe detallado en su cuenta de Pulumi en línea de lo que hará Pulumi, copie el vínculo Ver en directo que aparece y péguelo en la barra de direcciones del explorador web.

  3. Implemente el cambio de recursos en el área de trabajo de Azure Databricks ejecutando el siguiente comando:

    pulumi up

  4. Cuando se le solicite que realice esta actualización, presione la tecla de flecha arriba para ir a Sí y, a continuación, presione Entrar. Si se notifican errores, corrijalos y vuelva a ejecutar el comando.

  5. Para ver un informe detallado en su cuenta de Pulumi en línea de lo que hizo Pulumi, copie el vínculo Ver en directo que aparece y péguelo en la barra de direcciones del explorador web.

  6. Para ver el cuaderno modificado en el área de trabajo, copie el vínculo URL del cuaderno que aparece y péguelo en la barra de direcciones del explorador web.

  7. Para volver a ejecutar el trabajo con el cuaderno modificado, copie el vínculo URL del trabajo que aparece y péguelo en la barra de direcciones del explorador web. A continuación, haga clic en el botón Ejecutar ahora de la página del trabajo.

  8. Una vez que el trabajo termine de ejecutarse, para ver los resultados de la ejecución del trabajo, en la lista Ejecuciones completadas (últimos 60 días) de la página del trabajo, haga clic en la entrada de hora más reciente en la columna Hora de inicio. El panel Salida muestra el resultado de ejecutar el código del cuaderno, que imprime el contenido del Dataframe especificado.

Script 6: Limpieza

En este paso, le indica a Pulumi que elimine el cuaderno y el trabajo del área de trabajo de Azure Databricks, así como que elimine el proyecto pulumi-demo y su pila dev de la cuenta de Pulumi en línea.

  1. Elimine los recursos del área de trabajo de Azure Databricks ejecutando el siguiente comando:

    pulumi destroy

  2. Cuando se le solicite que realice esta eliminación, pulse la tecla de flecha arriba para desplazarse a Sí y, a continuación, pulse Entrar.

  3. Elimine el proyecto Pulumi pulumi-demo y su pila dev de la cuenta Pulumi en línea ejecutando el siguiente comando:

    pulumi stack rm dev

  4. Cuando se le solicite que realice esta eliminación, escriba dev y pulse Entrar.

  5. Para desactivar el entorno virtual de Python venv, ejecute el siguiente comando:

    deactivate

Prueba

Puede probar el proyecto Pulumi antes de implementarlo. Consulte Probar programas Pulumi en la documentación de Pulumi.

Para las pruebas unitarias de proyectos Pulumi basados en Python, puede escribir y ejecutar pruebas unitarias utilizando el marco de pruebas de Python unittest junto con el espacio de nombres pulumi.runtime del paquete Pulumi. Para ejecutar pruebas con recursos simulados, reemplace las llamadas a Pulumi (y a Azure Databricks) por simulación. Consulte Programas Pulumi de pruebas unitarias en la documentación de Pulumi.

El siguiente archivo de ejemplo denominado infra.py simula una implementación del cuaderno y el trabajo declarados en el archivo main.py de este artículo. Las pruebas unitarias de este ejemplo comprueban si el contenido codificado en Base64 del cuaderno, el nombre del trabajo y el destinatario del correo electrónico para un trabajo correcto ejecuta todos los valores esperados devueltos. Por lo tanto, solo las propiedades relacionadas se simulan aquí con valores de ejemplo. Además, siempre se deben proporcionar los valores de propiedad de recursos necesarios, incluso si no tiene previsto usarlos en las pruebas unitarias. En este ejemplo, estos valores necesarios se establecen en valores de my-mock- aleatorios y esos valores no se prueban.

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

El siguiente archivo de ejemplo test_main.py comprueba si las propiedades relacionadas devuelven sus valores esperados.

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

Para ejecutar estas pruebas y mostrar sus resultados, ejecute el siguiente comando desde el directorio raíz del proyecto Pulumi:

python -m unittest

Para obtener información sobre otros tipos de pruebas que puede ejecutar, consulte los siguientes artículos en la documentación de Pulumi:

Más recursos