Proveedor Databricks Terraform

  • Artículo

HashiCorp Terraform es un herramienta de código abierto muy utilizada para crear una infraestructura de nube segura y predecible en varios proveedores de nube. El proveedor de Databricks Terraform se puede usar para administrar áreas de trabajo de Azure Databricks y la infraestructura en la nube asociada mediante una herramienta flexible y eficaz. El objetivo del proveedor Databricks Terraform es admitir todas las API REST de Databricks, lo que permite la automatización de los aspectos más complicados de la implementación y administración de las plataformas de datos. Los clientes de Databricks usan el proveedor de Databricks Terraform para implementar y administrar clústeres y trabajos y para configurar el acceso a los datos. Use el proveedor de Azure para aprovisionar áreas de trabajo de Azure Databricks.

Introducción

En esta sección, instalará y configurará los requisitos para utilizar Terraform y el proveedor Terraform de Databricks en su máquina de desarrollo local. A continuación, configurará la autenticación de Terraform. Después de esta sección, se proporciona una configuración de ejemplo con la que puede experimentar para aprovisionar un cuaderno, un clúster y un trabajo de Azure Databricks para ejecutar el cuaderno en el clúster, en un área de trabajo existente de Azure Databricks.

Requisitos

  1. Debe tener la CLI de Terraform. Consulte la sección de descarga de Terraform del sitio web de Terraform.

  2. Debe tener un proyecto de Terraform. En el terminal, cree un directorio vacío y, a continuación, cambie a él (Cada conjunto independiente de archivos de configuración de Terraform debe estar en su propio directorio, que se denomina proyecto de Terraform). Por ejemplo: mkdir terraform_demo && cd terraform_demo.

    mkdir terraform_demo && cd terraform_demo

    Incluya configuraciones de Terraform para el proyecto en uno o varios archivos de configuración del proyecto de Terraform. Para obtener información sobre la sintaxis del archivo de configuración, vea Documentación del lenguaje Terraform en el sitio web de Terraform.

  3. Debe agregar al proyecto de Terraform una dependencia para el proveedor de Terraform de Databricks. Agregue lo siguiente a uno de los archivos de configuración del proyecto de Terraform:

    terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}

  4. Debe configurar la autenticación para el proyecto de Terraform. Consulte Autenticación en la documentación del proveedor de Terraform de Databricks.

Configuración de ejemplo

Esta sección proporciona una configuración de ejemplo con la que puede experimentar para aprovisionar un cuaderno, un clúster y un trabajo de Azure Databricks para ejecutar el cuaderno en el clúster, en un área de trabajo existente de Azure Databricks. Se da por supuesto que ya ha configurado los requisitos y que ya ha creado un proyecto de Terraform y lo ha configurado con la autenticación de Terraform, como se describe en la sección anterior.

  1. Cree un archivo denominado me.tf en el proyecto de Terraform y agregue el código siguiente. Este archivo obtiene información sobre el usuario actual (es decir, usted):

    # Retrieve information about the current user.
data "databricks_current_user" "me" {}

  2. Cree otro archivo denominado notebook.tf y agregue el código siguiente. Este archivo representa el cuaderno.

    variable "notebook_subdirectory" {
  description = "A name for the subdirectory to store the notebook."
  type        = string
  default     = "Terraform"
}

variable "notebook_filename" {
  description = "The notebook's filename."
  type        = string
}

variable "notebook_language" {
  description = "The language of the notebook."
  type        = string
}

resource "databricks_notebook" "this" {
  path     = "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
  language = var.notebook_language
  source   = "./${var.notebook_filename}"
}

output "notebook_url" {
 value = databricks_notebook.this.url
}

  3. Cree otro archivo denominado notebook.auto.tfvars y agregue el código siguiente. Este archivo especifica las propiedades del cuaderno.

    notebook_subdirectory = "Terraform"
notebook_filename     = "notebook-getting-started.py"
notebook_language     = "PYTHON"

  4. Cree otro archivo denominado notebook-getting-started.py y agregue el código siguiente. Este archivo representa el contenido del cuaderno.

    display(spark.range(10))

  5. Cree otro archivo denominado cluster.tf y agregue el código siguiente. Este archivo representa el clúster.

    variable "cluster_name" {
  description = "A name for the cluster."
  type        = string
  default     = "My Cluster"
}

variable "cluster_autotermination_minutes" {
  description = "How many minutes before automatically terminating due to inactivity."
  type        = number
  default     = 60
}

variable "cluster_num_workers" {
  description = "The number of workers."
  type        = number
  default     = 1
}

# Create the cluster with the "smallest" amount
# of resources allowed.
data "databricks_node_type" "smallest" {
  local_disk = true
}

# Use the latest Databricks Runtime
# Long Term Support (LTS) version.
data "databricks_spark_version" "latest_lts" {
  long_term_support = true
}

resource "databricks_cluster" "this" {
  cluster_name            = var.cluster_name
  node_type_id            = data.databricks_node_type.smallest.id
  spark_version           = data.databricks_spark_version.latest_lts.id
  autotermination_minutes = var.cluster_autotermination_minutes
  num_workers             = var.cluster_num_workers
}

output "cluster_url" {
 value = databricks_cluster.this.url
}

  6. Cree otro archivo denominado cluster.auto.tfvars y agregue el código siguiente. Este archivo especifica las propiedades del clúster.

    cluster_name                    = "My Cluster"
cluster_autotermination_minutes = 60
cluster_num_workers             = 1

  7. Cree otro archivo denominado job.tf y agregue el código siguiente. Este archivo representa el trabajo que ejecuta el cuaderno en el clúster.

    variable "job_name" {
  description = "A name for the job."
  type        = string
  default     = "My Job"
}

variable "task_key" {
  description = "A name for the task."
  type        = string
  default     = "my_task"
}

resource "databricks_job" "this" {
  name = var.job_name
  task {
    task_key = var.task_key
    existing_cluster_id = databricks_cluster.this.cluster_id
    notebook_task {
      notebook_path = databricks_notebook.this.path
    }
  }
  email_notifications {
    on_success = [ data.databricks_current_user.me.user_name ]
    on_failure = [ data.databricks_current_user.me.user_name ]
  }
}

output "job_url" {
  value = databricks_job.this.url
}

  8. Cree otro archivo denominado job.auto.tfvars y agregue el código siguiente. Este archivo especifica las propiedades del trabajo.

    job_name = "My Job"
task_key = "my_task"

  9. Ejecute terraform plan. Si se producen errores, corríjalos y vuelva a ejecutar el comando.

  10. Ejecute terraform apply.

  11. Compruebe que se han creado el cuaderno, el clúster y el trabajo. Para ello, en la salida del comando terraform apply, busque las direcciones URL de notebook_url, cluster_url y job_url y vaya a ellas.

  12. Ejecute el trabajo: en la página Trabajos, haga clic en Ejecutar ahora. Una vez que finalice el trabajo, compruebe la bandeja de entrada del correo electrónico.

  13. Cuando haya terminado con este ejemplo, elimine el cuaderno, el clúster y el trabajo del área de trabajo Azure Databricks mediante la ejecución de terraform destroy.

    Nota:

    Para obtener más información sobre los comandos terraform plan, terraform apply y terraform destroy consulte la documentación de la CLI de Terraform en la documentación de Terraform.

  14. Compruebe que se han eliminado el cuaderno, el clúster y el trabajo. Para ello, actualice las páginas del cuaderno, el clúster y Trabajos; cada una de ellas debería mostrar un mensaje que indica que no se pueden encontrar el recurso.

Prueba

Pruebe las configuraciones de Terraform antes o después de implementarlas. Puede ejecutar pruebas análogas a las pruebas unitarias antes de implementar recursos. También puede ejecutar pruebas análogas a las pruebas de integración una vez implementados los recursos. Consulte Pruebas en la documentación de Terraform.

Ejecute pruebas análogas en las pruebas de integración en la configuración de ejemplo de este artículo siguiendo este proceso:

  1. Cree un archivo llamado cluster.tftest.hcl y agregue el siguiente código. Este archivo comprueba si el clúster implementado tiene el nombre de clúster esperado.

    # Filename: cluster.tftest.hcl

run "cluster_name_test" {
  command = apply

  assert {
    condition     = databricks_cluster.this.cluster_name == var.cluster_name
    error_message = "Cluster name did not match expected name"
  }
}

  2. Cree un archivo llamado job.tftest.hcl y agregue el siguiente código. Este archivo comprueba si el trabajo implementado tiene el nombre de trabajo esperado.

    run "job_name_test" {
  command = apply

  assert {
    condition     = databricks_job.this.name == var.job_name
    error_message = "Job name did not match expected name"
  }
}

  3. Cree un archivo llamado notebook.tftest.hcl y agregue el siguiente código. Este archivo comprueba si el cuaderno implementado tiene la ruta de acceso esperada del área de trabajo.

    run "notebook_path_test" {
  command = apply

  assert {
    condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
    error_message = "Notebook path did not match expected path"
  }
}

  4. Ejecute terraform test. Terraform implementa cada recurso en el área de trabajo de Azure Databricks, ejecuta cada prueba relacionada e informa de su resultado de prueba y, a continuación, elimina el recurso implementado.

Ejecute pruebas análogas a las pruebas unitarias en la configuración de ejemplo de este artículo con el siguiente proceso:

  • Cambie la línea command = apply de cada una de las pruebas anteriores a command = plan y, a continuación, ejecute terraform test. Terraform ejecuta cada prueba relacionada e informa del resultado de la prueba, pero no implementa ningún recurso.
  • Simule el proveedor Databricks Terraform, que permite ejecutar terraform test sin implementar recursos y sin necesidad de credenciales de autenticación. Consulte Simulaciones en la documentación de Terraform. Para ejecutar pruebas simuladas, un enfoque es agregar la línea mock_provider "databricks" {} a las pruebas y quitar la línea command = apply o command = plan, por ejemplo:
# Filename: cluster.tftest.hcl

mock_provider "databricks" {}

run "cluster_mock_name_test" {
  assert {
    condition     = databricks_cluster.this.cluster_name == var.cluster_name
    error_message = "Cluster name did not match expected name"
  }
}

# Filename: job.tftest.hcl

mock_provider "databricks" {}

run "job_mock_name_test" {
  assert {
    condition     = databricks_job.this.name == var.job_name
    error_message = "Job name did not match expected name"
  }
}

# Filename: notebook.tftest.hcl

mock_provider "databricks" {}

run "notebook_mock_path_test" {
  assert {
    condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
    error_message = "Notebook path did not match expected path"
  }
}

Pasos siguientes

  1. Creación de un área de trabajo de Azure Databricks.
  2. Administración de los recursos de un área de trabajo de Azure Databricks.

Solución de problemas

Nota:

Para obtener soporte técnico específico de Terraform, consulte los temas más recientes de Terraform en el sitio web de HashiCorp Discuss. Para problemas específicos del proveedor de Databricks Terraform, consulte Problemas en el repositorio de GitHub databrickslabs/terraform-provider-databricks.

Error: error al instalar el proveedor

Problema: si no ha registrado un terraform.lock.hcl archivo en el sistema de control de versiones y ejecuta el comando terraform init, aparece el siguiente mensaje: Failed to install provider. La salida adicional puede incluir un mensaje similar al siguiente:

Error while installing databrickslabs/databricks: v1.0.0: checksum list has no SHA-256 hash for "https://github.com/databricks/terraform-provider-databricks/releases/download/v1.0.0/terraform-provider-databricks_1.0.0_darwin_amd64.zip"

Causa: las configuraciones de Terraform hacen referencia a proveedores de Databricks Terraform obsoletos.

Solución:

  1. Reemplace databrickslabs/databricks por databricks/databricks en todos los archivos .tf.

    Para automatizar estos reemplazos, ejecute el siguiente comando de Python desde la carpeta principal que contiene los archivos .tf que se van a actualizar:

    python3 -c "$(curl -Ls https://dbricks.co/updtfns)"

  2. Ejecute el siguiente comando de Terraform y apruebe los cambios cuando se le solicite:

    terraform state replace-provider databrickslabs/databricks databricks/databricks

    Para obtener información sobre este comando, consulte Comando: state replace-provider en la documentación de Terraform.

  3. Para comprobar el cambio, ejecute el siguiente comando de Terraform:

    terraform init

Error: no se pudieron consultar los paquetes del proveedor disponibles

Problema: si no ha registrado un terraform.lock.hcl archivo en el sistema de control de versiones y ejecuta el comando terraform init, aparece el siguiente mensaje: Failed to query available provider packages.

Causa: las configuraciones de Terraform hacen referencia a proveedores de Databricks Terraform obsoletos.

Solución: siga las instrucciones de la solución que encontrará en Error: no se pudo instalar el proveedor.

Habilitar registro

El proveedor de Terraform de Databricks genera registros que puede habilitar estableciendo la variable de entorno TF_LOG en DEBUG o cualquier otro nivel de registro que Admita Terraform.

De manera predeterminada, los registros se envían a stderr. Para enviar registros a un archivo, establezca la variable de entorno TF_LOG_PATH en la ruta de acceso del archivo de destino.

Por ejemplo, puede ejecutar el siguiente comando para habilitar el registro en el nivel de depuración y generar registros en formato monocromático en un archivo denominado tf.log relativo al directorio de trabajo actual, mientras se ejecuta el comando terraform apply:

TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply -no-color

Para obtener más información sobre el registro de Terraform, consulte Depuración de Terraform.

Ejemplos adicionales

Recursos adicionales