Provider Databricks Terraform

  • Articolo

HashiCorp Terraform è uno strumento open source conosciuto per la creazione di un'infrastruttura cloud sicura e prevedibile in diversi provider di servizi cloud. È possibile usare il provider Databricks Terraform per gestire le aree di lavoro di Databricks di Azure e l'infrastruttura cloud associata usando uno strumento versatile e potente. L'obiettivo del provider Databricks Terraform è supportare tutte le API REST di Databricks, ovvero l'automazione degli aspetti più complessi della distribuzione e gestione delle piattaforme dati. I clienti di Databricks usano il provider Databricks Terraform per distribuire e gestire cluster e processi e per configurare l'accesso ai dati. Usare il provider di Azure per effettuare il provisioning delle aree di lavoro di Databricks di Azure.

Introduzione

In questa sezione vengono installati e configurati i requisiti per l'uso di Terraform e del provider Databricks Terraform nel computer di sviluppo locale. Configurare quindi l'autenticazione Terraform. Dopo questa sezione, l’articolo che segue fornisce una configurazione di esempio da testare, per provare a eseguire il provisioning di un notebook, un cluster e un processo di Azure Databricks per eseguire il notebook nel cluster in un'area di lavoro di Azure Databricks esistente.

Requisiti

  1. È necessario disporre della CLI di Terraform. Vedere Scaricare Terraform nel sito web Terraform.

  2. È necessario avere un progetto Terraform. Nel terminale creare una directory vuota e quindi passare a essa. (Ogni set separato di file di configurazione Terraform deve trovarsi nella propria directory, denominata progetto Terraform.) Ad esempio: mkdir terraform_demo && cd terraform_demo.

    mkdir terraform_demo && cd terraform_demo

    Includere configurazioni Terraform per il progetto in uno o più file di configurazione nel progetto Terraform. Per informazioni sulla sintassi del file di configurazione, vedere Documentazione sul linguaggio Terraform nel sito web Terraform.

  3. È necessario aggiungere al progetto Terraform una dipendenza per il provider Databricks Terraform. Aggiungere quanto segue a uno dei file di configurazione nel progetto Terraform:

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

  4. È necessario configurare l'autenticazione per il progetto Terraform. Consultare Autenticazione nella documentazione del provider Databricks Terraform.

Configurazione di esempio

Questa sezione fornisce una configurazione di esempio con cui sperimentare, per eseguire il provisioning di un notebook, un cluster e un processo di Azure Databricks per eseguire il notebook nel cluster in un'area di lavoro di Azure Databricks esistente. Si presuppone che siano già stati configurati i requisiti, che sia stato creato un progetto Terraform e configurato il progetto con l'autenticazione Terraform, come descritto nella sezione precedente.

  1. Creare un file denominato me.tf nel progetto Terraform e aggiungere il codice seguente. Questo file ottiene informazioni sull'utente corrente (l'utente):

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

  2. Creare un altro file denominato notebook.tf e aggiungere il seguente codice. Questo file rappresenta il notebook.

    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. Creare un altro file denominato notebook.auto.tfvars e aggiungere il seguente codice. Questo file specifica le proprietà del notebook.

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

  4. Creare un altro file denominato notebook-getting-started.py e aggiungere il seguente codice. Questo file rappresenta i contenuti del notebook.

    display(spark.range(10))

  5. Creare un altro file denominato cluster.tf e aggiungere il seguente codice. Questo file rappresenta il cluster.

    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. Creare un altro file denominato cluster.auto.tfvars e aggiungere il seguente codice. Questo file specifica le proprietà del cluster.

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

  7. Creare un altro file denominato job.tf e aggiungere il seguente codice. Questo file rappresenta il processo che esegue il notebook nel cluster.

    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. Creare un altro file denominato job.auto.tfvars e aggiungere il seguente codice. Questo file specifica le proprietà dei processi.

    job_name = "My Job"
task_key = "my_task"

  9. Eseguire terraform plan. Se sono presenti errori, correggerli e quindi eseguire di nuovo il comando.

  10. Eseguire terraform apply.

  11. Verificare che il notebook, il cluster e il processo siano stati creati: nell'output del comando terraform apply trovare e andare agli URL per notebook_url, cluster_url e job_url.

  12. Eseguire il processo: nella pagina Processi, fare clic su Esegui ora. Al termine del processo, controllare la propria casella di posta elettronica.

  13. Al termine di questo esempio, eliminare il notebook, il cluster e il processo dall'area di lavoro di Databricks di Azure eseguendo terraform destroy.

    Nota

    Per altre informazioni sui comandi terraform plan, terraform apply e terraform destroy, vedere la documentazione CLI di Terraform nella documentazione di Terraform.

  14. Verificare che il notebook, il cluster e il processo siano stati eliminati: aggiornare le pagine notebook, cluster e Processi per visualizzare il messaggio che la risorsa non è stata trovata.

Test

Testare le configurazioni di Terraform prima o dopo la distribuzione. È possibile eseguire test analoghi agli unit test prima di distribuire le risorse. È anche possibile eseguire test analoghi ai test di integrazione dopo la distribuzione delle risorse. Vedere Test nella documentazione di Terraform.

Eseguire test analoghi ai test di integrazione rispetto alla configurazione di esempio di questo articolo seguendo questo processo:

  1. Creare un file denominato cluster.tftest.hcl e aggiungere il seguente codice. Questo file verifica se il cluster distribuito ha il nome del cluster previsto.

    # 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. Creare un file denominato job.tftest.hcl e aggiungere il seguente codice. Questo file verifica se il processo distribuito ha il nome del processo previsto.

    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. Creare un file denominato notebook.tftest.hcl e aggiungere il seguente codice. Questo file verifica se il notebook distribuito ha il percorso previsto dell'area di lavoro.

    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. Eseguire terraform test. Terraform distribuisce ogni risorsa nell'area di lavoro di Databricks di Azure, esegue ogni test correlato e ne segnala il risultato e quindi rimuove la risorsa distribuita.

Eseguire test analoghi agli unit test rispetto alla configurazione di esempio di questo articolo seguendo questo processo:

  • Modificare la riga command = apply in ognuno dei test precedenti in command = plan e quindi eseguire terraform test. Terraform esegue ogni test correlato e ne segnala il risultato, ma non distribuisce alcuna risorsa.
  • Simulare il provider Databricks Terraform, che consente di eseguire terraform test senza distribuire risorse e senza richiedere credenziali di autenticazione. Vedere Simulazioni nella documentazione di Terraform. Per eseguire test di simulazione, un approccio consiste nell'aggiungere la riga mock_provider "databricks" {} ai test e rimuovere la riga command = apply o command = plan, ad esempio:
# 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"
  }
}

Passaggi successivi

  1. Creare un'area di lavoro di Azure Databricks.
  2. Gestire le risorse dell'area di lavoro per un'area di lavoro di Databricks di Azure.

Risoluzione dei problemi

Nota

Per il supporto specifico di Terraform, vedere gli argomenti più recenti di Terraform nel sito web HashiCorp Discuss. Per problemi specifici del provider Databricks Terraform, vedere Problemi nel repository GitHub databrickslabs/terraform-provider-databricks.

Errore: Impossibile installare il provider

Problema: se non è stato sincronizzato un terraform.lock.hcl file nel sistema di controllo della versione ed è stato eseguito il comando terraform init, viene visualizzato il messaggio seguente: Failed to install provider. Un output aggiuntivo può includere un messaggio simile al seguente:

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: le configurazioni di Terraform fanno riferimento a provider Databricks Terraform obsoleti.

Soluzione:

  1. Sostituire databrickslabs/databricks con databricks/databricks in tutti i .tf file.

    Per automatizzare queste sostituzioni, eseguire il comando Python seguente dalla cartella padre che contiene i .tf file da aggiornare:

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

  2. Eseguire il comando Terraform seguente e quindi approvare le modifiche quando richiesto:

    terraform state replace-provider databrickslabs/databricks databricks/databricks

    Per informazioni su questo comando, vedere Comando: indicare sostituisci-provider nella documentazione di Terraform.

  3. Verificare le modifiche eseguendo il comando Terraform seguente:

    terraform init

Errore: Impossibile eseguire query sui pacchetti del provider disponibili

Problema: se non è stato sincronizzato un terraform.lock.hcl file nel sistema di controllo della versione ed è stato eseguito il comando terraform init, viene visualizzato il messaggio seguente: Failed to query available provider packages.

Causa: le configurazioni di Terraform fanno riferimento a provider Databricks Terraform obsoleti.

Soluzione: seguire le istruzioni della soluzione in Errore: Impossibile installare il provider.

Abilitazione della registrazione

Il provider Databricks Terraform restituisce i log che è possibile abilitare impostando la TF_LOG variabile di ambiente su DEBUG o su qualsiasi altro livello di log supportato da Terraform.

Per impostazione predefinita, i log vengono inviati a stderr. Per inviare i log a un file, impostare la variabile di ambiente TF_LOG_PATH sul percorso del file di destinazione.

Ad esempio, è possibile eseguire il comando seguente per abilitare la registrazione a livello di debug e per l'output dei log in formato monocromatico in un file denominato tf.log relativo alla directory di lavoro corrente, mentre il comando terraform apply viene eseguito:

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

Per altre informazioni sulla registrazione di Terraform, vedere Debug di Terraform.

Esempi aggiuntivi

Risorse aggiuntive