Proveedor de recursos de Pulumi Databricks

Importante

Esta documentación se ha retirado y es posible que no se actualice.

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, como TypeScript, JavaScript, Go y C#.

El proveedor de recursos Pulumi Databricks se basa en el proveedor de Databricks Terraform. Para obtener 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 en la nube, consulte Introducción a Azure en la documentación de Pulumi. Para ver un tutorial desde una perspectiva de primer lenguaje de programación, consulte Python, Node.js (JavaScript, TypeScript),Go y .NET (C#, VB, F#) en la documentación de Pulumi.

Paso 1: Crear un proyecto de Pulumi

En este paso, en tu máquina de desarrollo local configuras la estructura de directorios necesaria para un proyecto de Pulumi. A continuación, creará el proyecto 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 ejecutando el siguiente comando, en función del 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 obtener opciones alternativas de instalación de Pulumi, consulte Descargar e instalar en la documentación de Pulumi.

  3. Cree un proyecto básico de Python Pulumi mediante la ejecución del comando siguiente:

    pulumi new python

    Sugerencia

    También puede crear un proyecto 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, a continuación, 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 PowerShell.

  5. Cuando se le solicite un nombre de proyecto, acepte el nombre predeterminado del pulumi-demo proyecto presionando 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 presionando Entrar. Pulumi crea los siguientes archivos y subdirectorios en el pulumi-demo directorio:

    • Pulumi.yaml, que es una lista de configuraciones para el proyecto Pulumi.
    • __main__.py, que contiene el código en Python que escribes para tu 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 venv subdirectorio contiene el código de entorno virtual de Python compatible que Pulumi usa para el proyecto.

  8. Para realizar una implementación inicial de la pila de tu proyecto dev, ejecute el siguiente comando:

    pulumi up

  9. Cuando se le pida 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 lleva a su cuenta de Pulumi en línea. Los detalles de actividad de la pila de tu dev proyecto aparecen. No hay mucho que ver en este momento, dado que aún no hay recursos en tu pila. Cree estos recursos en el paso siguiente.

Paso 2: Creación de recursos de 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 __main.py__ archivo generado por Pulumi, use el editor de texto preferido o el entorno de desarrollo integrado (IDE) para escribir el código siguiente. Este código declara los recursos Pulumi Databricks Cuaderno y Trabajo 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 denominado resource-prefixy establézcalo en el valor codificado de forma rígida 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 denominado Pulumi.dev.yaml en el mismo directorio que el __main__.py archivo y agrega el código siguiente 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 __main__.py archivo y definir un valor diferente para la resource_prefix variable sin cambiar el contenido del __main__.py archivo.

  3. Defina un valor de configuración denominado node-typey establézcalo en el siguiente valor codificado de forma rígida mediante la ejecución del 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 Pulumi.dev.yaml archivo ahora tiene 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> por el valor del token de acceso. Asegúrese de especificar la --secret opción . Esto indica a Pulumi que cifre el token de acceso como procedimiento recomendado de seguridad.

      Nota:

      De forma predeterminada, Pulumi utiliza una clave de cifrado por cada pila gestionada por el servicio de Pulumi, y una sal por cada valor, para cifrar los valores. Para usar un proveedor de cifrado alternativo, consulte Configuración del 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 Pulumi.dev.yaml archivo ahora tiene 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 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 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 pulumi de Python se usa venv. venv ya está incluido con Python. Para más información, consulte Creación de entornos virtuales.

  1. Active el entorno virtual de Python mediante la ejecución del siguiente comando desde el pulumi-demo directorio, según el sistema operativo y el tipo de shell:

    Plataforma Cáscara Comando para activar el entorno virtual
    Unix, Linux, macOS bash/zsh source venv/bin/activate
    pescado 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. Ejecute el comando siguiente para instalar el proveedor de recursos pulumi Databricks desde el índice de paquetes de Python (PyPI) en el entorno virtual:

    pip install pulumi-databricks

    Nota:

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

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

    pulumi preview

    Si se notifica algún error, 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 live 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 comando siguiente:

    pulumi up

  5. Cuando se le pida que realice esta actualización, presione la tecla de flecha arriba para ir a Sí y, a continuación, presione Entrar. Si se notifica algún error, 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 live que aparece y péguelo en la barra de direcciones del explorador web.

Paso 4: Interactuar 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 vínculo Dirección 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 modificado y, a continuación, usará el trabajo para volver a ejecutar el cuaderno modificado.

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

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

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

    A continuación, 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 del 1 al 10 especificados.

    Nota:

    Asegúrese de que las líneas de código que comienzan por data y 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 siguiente comando para obtener una vista previa del recurso que Pulumi cambiará:

    pulumi preview

    Si se notifica algún error, 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 live que aparece y péguelo en la barra de direcciones del explorador web.

  3. Implemente el cambio de recurso en el área de trabajo de Azure Databricks mediante la ejecución del comando siguiente:

    pulumi up

  4. Cuando se le pida que realice esta actualización, presione la tecla de flecha arriba para ir a Sí y, a continuación, presione Entrar. Si se notifica algún error, 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 live que aparece y péguelo en la barra de direcciones del explorador web.

  6. Para ver el cuaderno cambiado 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 Dirección 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 en 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.

Paso 6: Limpiar

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

  1. Para quitar los recursos del área de trabajo de Azure Databricks, ejecute el siguiente comando:

    pulumi destroy

  2. Cuando se le pida que realice esta eliminación, presione la tecla de flecha arriba para ir a sí y, a continuación, presione Entrar.

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

    pulumi stack rm dev

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

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

    deactivate

Ensayo

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

Para realizar pruebas unitarias de proyectos pulumi basados en Python, puede escribir y ejecutar pruebas unitarias mediante 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 de 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 de main.py este artículo. Las pruebas unitarias de este ejemplo verifican si el contenido codificado en Base64 del cuaderno, el nombre del trabajo y el destinatario del correo electrónico para ejecuciones exitosas del trabajo devuelven todos los valores esperados. 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 aleatorios my-mock- 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' ]
  )
)

En el siguiente archivo test_main.py de ejemplo se 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 de pruebas, 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

  • Last updated on