Proveedor de Databricks de Terraform CDK

Advertencia

Azure Databricks no recomienda usar el Kit de desarrollo en la nube para Terraform (CDKTF) para administrar recursos de Databricks. HashiCorp ha anunciado el retiro del proyecto CDKTF, y el proyecto ya no recibirá soporte ni desarrollo activo.

En lugar de usar CDKTF, Azure Databricks recomienda usar el proveedor de Terraform de Databricks directamente para administrar los recursos de Databricks. El proveedor de Terraform es la solución de infraestructura como código (IaC) oficialmente compatible para Azure Databricks. Consulte el proveedor de Terraform de Databricks.

Nota:

En este artículo se describe el Kit de desarrollo en la nube para Terraform (CDKTF), desarrollado por un tercero. Para ponerse en contacto con el proveedor, consulte la comunidad de Terraform.

En este artículo se muestra cómo usar Python junto con el proveedor de Databricks de Terraform CDK y el Kit de desarrollo en la nube para Terraform (CDKTF). CDKTF es 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 TypeScript, CDKTF admite lenguajes adicionales como Java, C# y Go.

El proveedor de Databricks de Terraform CDK se basa en el proveedor de Databricks Terraform. Para más información, consulte Terraform Cloud. CDKTF se basa en el Kit de desarrollo en la nube de AWS (AWS CDK).

Requisitos

Debe tener un área de trabajo de Azure Databricks, ya que en este artículo se implementan recursos en un área de trabajo existente.

En su máquina de desarrollo local, debe tener instalado lo siguiente:

  • Terraform, versión 1.1 o posterior. Para comprobar si tiene Terraform instalado y para comprobar la versión instalada, ejecute el comando terraform -v desde el terminal o con PowerShell. Instale Terraform si aún no lo tiene instalado.

    terraform -v

  • Node.js, versión 16.13 o posterior y npm. Para comprobar si tiene Node.js y npm instalado, y para comprobar las versiones instaladas, ejecute los comandos node -v y npm -v. Las versiones posteriores de Node.js ya incluyen npm. Instale Node.js y npm mediante el Administrador de versiones de Node (nvm), si no tiene Node.js y npm ya está instalado.

    node -v
npm -v

  • La CLI de CDKTF. Para comprobar si tiene la CLI de CDKTF instalada, y para comprobar la versión instalada, ejecute el comando cdktf --version. Instale la CLI de CDKTF mediante npm, si aún no lo tiene instalado.

    cdktf --version

    Sugerencia

    También puede instalar la CLI de CDKTF en macOS con Homebrew. Consulte Instalación de CDKTF.

  • Python versión 3.7 o posterior y pipenv versión 2021.5.29 o posterior. Para comprobar si tiene Python y pipenv instalado, y para comprobar las versiones instaladas, ejecute los comandos python --version y pipenv --version. Instale Python e instale pipenv, si aún no están instalados.

    python --version
pipenv --version

  • Autenticación de Azure Databricks configurada para el tipo de autenticación admitido que desea usar. Consulte Autenticación en la documentación del proveedor de Terraform de Databricks.

Paso 1: Creación de un proyecto de CDKTF

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

  1. Cree un directorio vacío para su proyecto CDKTF y luego cambie a ese directorio. Ejecute los siguientes comandos en el terminal o con PowerShell:

    Unix, Linux y macOS

    mkdir cdktf-demo
cd cdktf-demo

    Windows

    md cdktf-demo
cd cdktf-demo

  2. Cree un proyecto de CDKTF ejecutando el siguiente comando:

    cdktf init --template=python --local

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

  4. Cuando se le solicite una descripción de proyecto, acepte la descripción de proyecto predeterminado pulsando Entrar.

  5. Si se le pide ¿Desea empezar desde un proyecto de Terraform existente?, escriba N y presione Entrar.

  6. Si se le pide ¿Desea enviar informes de bloqueo al equipo de CDKTF?, escriba n y presione Intro.

CDKTF crea los siguientes archivos y subdirectorios en el directorio cdktf-demo:

  • .gitignore, que es una lista de archivos y directorios que Git omite si desea insertar este proyecto en un repositorio de Git remoto.
  • cdktf.json, que contiene opciones de configuración para el proyecto de CDKTF. Consulte Archivo de configuración para obtener más información sobre los valores de configuración.
  • help, que contiene información sobre algunos próximos pasos que puede seguir para trabajar con su proyecto de CDKTF.
  • main-test.py, que contiene pruebas unitarias auxiliares que puede escribir para el proyecto de CDKTF. Consulte Pruebas unitarias para obtener más información sobre las pruebas unitarias.
  • main.py, que contiene el código de Python que escribes para tu proyecto de CDKTF.
  • Pipfile y Pipfile.lock, que gestionan las dependencias de código de tu proyecto CDKTF.

Paso 2: Definición de recursos

En este paso, usará el proveedor de Databricks de Terraform CDK para definir un cuaderno y un trabajo para ejecutar ese cuaderno.

  1. Instale las dependencias del proyecto: utilizando pipenv, instale en su proyecto CDKTF el proveedor Terraform CDK Databricks para generar recursos Azure Databricks. Para ello, ejecute lo siguiente:

    pipenv install cdktf-cdktf-provider-databricks

  2. Reemplace el contenido del archivo main.py por el código siguiente. Este código autentica el CDKTF con el área de trabajo de Azure Databricks y, a continuación, genera un cuaderno junto con un trabajo para ejecutar el cuaderno. Para ver la documentación de sintaxis de este código, consulte la referencia de construcción del proveedor Terraform CDK Databricks para Python.

    #!/usr/bin/env python
from constructs import Construct
from cdktf import (
  App, TerraformStack, TerraformOutput
)
from cdktf_cdktf_provider_databricks import (
  data_databricks_current_user,
  job, notebook, provider
)
import vars
from base64 import b64encode

class MyStack(TerraformStack):
  def __init__(self, scope: Construct, ns: str):
    super().__init__(scope, ns)

    provider.DatabricksProvider(
      scope = self,
      id    = "databricksAuth"
    )

    current_user = data_databricks_current_user.DataDatabricksCurrentUser(
      scope     = self,
      id_       = "currentUser"
    )

    # Define the notebook.
    my_notebook = notebook.Notebook(
      scope          = self,
      id_            = "notebook",
      path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
      language       = "PYTHON",
      content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
    )

    # Define the job to run the notebook.
    my_job = job.Job(
      scope = self,
      id_ = "job",
      name = f"{vars.resource_prefix}-job",
      task = [ 
        job.JobTask(
          task_key = f"{vars.resource_prefix}-task",
          new_cluster = job.JobTaskNewCluster(
            num_workers   = vars.num_workers,
            spark_version = vars.spark_version,
            node_type_id  = vars.node_type_id
          ),
          notebook_task = job.JobTaskNotebookTask(
            notebook_path = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py"
          ),
          email_notifications = job.JobTaskEmailNotifications(
            on_success = [ current_user.user_name ],
            on_failure = [ current_user.user_name ]
          )
        )
      ]
    )

    # Output the notebook and job URLs.
    TerraformOutput(
      scope = self,
      id    = "Notebook URL",
      value = my_notebook.url
    )

    TerraformOutput(
      scope = self,
      id    = "Job URL",
      value = my_job.url
    )

app = App()
MyStack(app, "cdktf-demo")
app.synth()

  3. Cree un archivo llamado vars.py en el mismo directorio que main.py. Reemplace los valores siguientes por sus propios valores para especificar un prefijo de recurso y una configuración del clúster, como el número de trabajos, la cadena de versión del entorno de ejecución de Spark y el tipo de nodo.

    #!/usr/bin/env python
resource_prefix = "cdktf-demo"
num_workers     = 1
spark_version   = "14.3.x-scala2.12"
node_type_id    = "Standard_D3_v2"

Paso 3: Implementar los recursos

En este paso, usará la CLI de CDKTF para implementar, en su área de trabajo existente de Azure Databricks, la libreta definida y la tarea para ejecutar esa libreta.

  1. Génere el código de Terraform equivalente para su proyecto de CDKTF. Para ello, ejecute el comando cdktf synth.

    cdktf synth

  2. Antes de realizar cambios, puede revisar los cambios de recursos pendientes. Ejecute lo siguiente:

    cdktf diff

  3. Implemente el cuaderno y el trabajo mediante la ejecución del comando cdktf deploy.

    cdktf deploy

  4. Si se le solicita Aprobar, pulse Intro. Terraform crea e implementa el cuaderno y el trabajo en el área de trabajo.

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 Dirección URL del cuaderno que aparece en la salida del comando y péguelo en la cdk deploy 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 en la salida del cdk deploy comando 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.

(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: Limpieza.

  1. En el main.py archivo, cambie la notebook declaración de variable de la siguiente manera:

    my_notebook = notebook.Notebook(
  scope          = self,
  id_            = "notebook",
  path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
  language       = "PYTHON",
  content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
)

    Por lo siguiente:

    my_notebook = notebook.Notebook(
  scope          = self,
  id_            = "notebook",
  path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
  language       = "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")
)

    Nota:

    Asegúrese de que las líneas de código entre comillas triples (''') estén alineadas con el borde del editor de código, tal como se muestra. De lo contrario, Terraform insertará espacios en blanco adicionales en el cuaderno que pueden hacer que el nuevo código Python no se ejecute.

  2. Regenerar el código equivalente de Terraform para tu proyecto de CDKTF. Para ello, ejecute lo siguiente:

    cdktf synth

  3. Antes de realizar cambios, puede revisar los cambios de recursos pendientes. Ejecute lo siguiente:

    cdktf diff

  4. Implemente los cambios del cuaderno mediante la ejecución del comando cdktf deploy.

    cdktf deploy

  5. Si se le solicita Aprobar, pulse Enter. Terraform cambia el contenido del cuaderno.

  6. Para ver el cuaderno modificado donde la tarea se ejecutará en su área de trabajo, actualice el cuaderno que abrió anteriormente o copie el vínculo de la Dirección URL del cuaderno que aparece en la salida del comando cdk deploy y péguelo en la barra de direcciones de su navegador web.

  7. Para ver el trabajo que ejecuta el cuaderno modificado en el área de trabajo, actualice el trabajo que abrió anteriormente o copie el vínculo Dirección URL del trabajo que aparece en la salida del comando y péguelo en la cdk deploy barra de direcciones del explorador web.

  8. Para ejecutar el trabajo, haga clic en el botón Ejecutar ahora en la página del trabajo.

Paso 6: Limpieza

En este paso, usará la CLI de CDKTF para quitar el cuaderno y el trabajo del área de trabajo de Azure Databricks.

  1. Quite los recursos del área de trabajo ejecutando el comando cdktf destroy:

    cdktf destroy

  2. Cuando se le pida Aprobar, pulse Intro. Terraform elimina los recursos del espacio de trabajo.

Prueba

Puede probar el proyecto CDKTF antes de implementarlo. Vea Pruebas unitarias en la documentación de CDKTF.

En el caso de los proyectos CDKTF basados en Python, puede escribir y ejecutar pruebas mediante el marco de pruebas de Python pytest junto con la cdktf clase del Testing paquete. El siguiente archivo de ejemplo denominado test_main.py prueba el código CDKTF del archivo anterior main.py de este artículo. La primera prueba comprueba si el cuaderno del proyecto contendrá la representación codificada en Base64 esperada del contenido del cuaderno. La segunda prueba comprueba si el trabajo del proyecto contendrá el nombre del trabajo esperado. Para ejecutar estas pruebas, ejecute el pytest comando desde el directorio raíz del proyecto.

from cdktf import App, Testing
from cdktf_cdktf_provider_databricks import job, notebook
from main import MyStack

class TestMain:
  app = App()
  stack = MyStack(app, "cdktf-demo")
  synthesized = Testing.synth(stack)

  def test_notebook_should_have_expected_base64_content(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = notebook.Notebook.TF_RESOURCE_TYPE,
      properties = {
        "content_base64": "ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp"
      }
    )

  def test_job_should_have_expected_job_name(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = job.Job.TF_RESOURCE_TYPE,
      properties = {
        "name": "cdktf-demo-job"
      }
    )

Más recursos

  • Last updated on