Databricks Terraform-provider

Artikel
11/14/2024

HashiCorp Terraform är ett populärt öppen källkod verktyg för att skapa säker och förutsägbar molninfrastruktur mellan flera molnleverantörer. Du kan använda Databricks Terraform-providern för att hantera dina Azure Databricks-arbetsytor och den associerade molninfrastrukturen med hjälp av ett flexibelt och kraftfullt verktyg. Målet med Databricks Terraform-providern är att stödja alla Databricks REST-API:er, vilket stöder automatisering av de mest komplicerade aspekterna av att distribuera och hantera dina dataplattformar. Databricks-kunder använder Databricks Terraform-providern för att distribuera och hantera kluster och jobb och för att konfigurera dataåtkomst. Du använder Azure-providern för att etablera Azure Databricks-arbetsytor.

Komma igång

I det här avsnittet installerar och konfigurerar du krav för att använda Terraform och Databricks Terraform-providern på din lokala utvecklingsdator. Sedan konfigurerar du Terraform-autentisering. I det här avsnittet innehåller den här artikeln en exempelkonfiguration som du kan experimentera med för att etablera en Azure Databricks-notebook-fil, ett kluster och ett jobb för att köra notebook-filen på klustret på en befintlig Azure Databricks-arbetsyta.

Krav

Du måste ha Terraform CLI. Se Ladda ned Terraform på Terraforms webbplats.
Du måste ha ett Terraform-projekt. Skapa en tom katalog i terminalen och växla sedan till den. (Varje separat uppsättning Terraform-konfigurationsfiler måste finnas i en egen katalog, som kallas för ett Terraform-projekt.) Till exempel: mkdir terraform_demo && cd terraform_demo.
```
mkdir terraform_demo && cd terraform_demo
```
Inkludera Terraform-konfigurationer för projektet i en eller flera konfigurationsfiler i Terraform-projektet. Information om syntaxen för konfigurationsfilen finns i Dokumentation om Terraform-språk på Terraforms webbplats.
Du måste lägga till ett beroende för Databricks Terraform-providern i Terraform-projektet. Lägg till följande i en av konfigurationsfilerna i Terraform-projektet:
```
terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}
```
Du måste konfigurera autentisering för Terraform-projektet. Se Autentisering i dokumentationen för Databricks Terraform-providern.

Exempelkonfiguration

Det här avsnittet innehåller en exempelkonfiguration som du kan experimentera med för att etablera en Azure Databricks-anteckningsbok, ett kluster och ett jobb för att köra notebook-filen i klustret på en befintlig Azure Databricks-arbetsyta. Det förutsätter att du redan har konfigurerat kraven, samt skapat ett Terraform-projekt och konfigurerat projektet med Terraform-autentisering enligt beskrivningen i föregående avsnitt.

Skapa en fil med namnet me.tf i Terraform-projektet och lägg till följande kod. Den här filen hämtar information om den aktuella användaren (du):
```
# Retrieve information about the current user.
data "databricks_current_user" "me" {}
```

Skapa en annan fil med namnet notebook.tfoch lägg till följande kod. Den här filen representerar anteckningsboken.

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
}

Skapa en annan fil med namnet notebook.auto.tfvarsoch lägg till följande kod. Den här filen anger notebook-filens egenskaper.
```
notebook_subdirectory = "Terraform"
notebook_filename     = "notebook-getting-started.py"
notebook_language     = "PYTHON"
```
Skapa en annan fil med namnet notebook-getting-started.pyoch lägg till följande kod. Den här filen representerar anteckningsbokens innehåll.
```
display(spark.range(10))
```

Skapa en annan fil med namnet cluster.tfoch lägg till följande kod. Den här filen representerar klustret.

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
}

Skapa en annan fil med namnet cluster.auto.tfvarsoch lägg till följande kod. Den här filen anger klustrets egenskaper.

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

Skapa en annan fil med namnet job.tfoch lägg till följande kod. Den här filen representerar det jobb som kör notebook-filen i klustret.

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
}

Skapa en annan fil med namnet job.auto.tfvarsoch lägg till följande kod. Den här filen anger jobbens egenskaper.
```
job_name = "My Job"
task_key = "my_task"
```
Kör terraform plan. Om det finns några fel kan du åtgärda dem och sedan köra kommandot igen.
Kör terraform apply.
Kontrollera att anteckningsboken, klustret och jobbet har skapats: i kommandots terraform apply utdata letar du upp URL:erna för notebook_url, cluster_urloch job_urloch går till dem.
Kör jobbet: På sidan Jobb klickar du på Kör nu. När jobbet är klart markerar du din e-postinkorg.
När du är klar med det här exemplet tar du bort notebook-filen, klustret och jobbet från Azure Databricks-arbetsytan genom att köra terraform destroy.

Kommentar

Mer information om kommandona terraform plan, terraform applyoch terraform destroy finns i Terraform CLI-dokumentationen i Terraform-dokumentationen.
Kontrollera att anteckningsboken, klustret och jobbet har tagits bort: uppdatera sidorna notebook, kluster och jobb för att visa ett meddelande om att resursen inte kan hittas.

Testning

Testa Dina Terraform-konfigurationer före eller efter att du har distribuerat dem. Du kan köra tester som liknar enhetstestning innan du distribuerar resurser. Du kan också köra tester som motsvarar integreringstestning när resurser har distribuerats. Se Tester i Terraform-dokumentationen.

Kör tester som liknar integreringstester mot den här artikelns exempelkonfiguration genom att följa den här processen:

Skapa en fil med namnet cluster.tftest.hcloch lägg till följande kod. Den här filen testar om det distribuerade klustret har det förväntade klusternamnet.

# 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"
  }
}

Skapa en fil med namnet job.tftest.hcloch lägg till följande kod. Den här filen testar om det distribuerade jobbet har det förväntade jobbnamnet.

run "job_name_test" {
  command = apply

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

Skapa en fil med namnet notebook.tftest.hcloch lägg till följande kod. Den här filen testar om den distribuerade notebook-filen har den förväntade arbetsytans sökväg.

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

Kör terraform test. Terraform distribuerar varje resurs till Azure Databricks-arbetsytan, kör varje relaterat test och rapporterar testresultatet och river sedan ned den distribuerade resursen.

Kör tester som motsvarar enhetstester mot den här artikelns exempelkonfiguration med följande process:

Ändra raden command = apply i var och en av föregående tester till command = planoch kör terraform testsedan . Terraform kör varje relaterat test och rapporterar sitt testresultat men distribuerar inga resurser.
Håna Databricks Terraform-providern, som gör att du kan köra terraform test utan att distribuera resurser och även utan att kräva några autentiseringsuppgifter. Se Mocks i Terraform-dokumentationen. För att köra falska tester är en metod att lägga till raden mock_provider "databricks" {} i dina tester och ta bort raden command = apply eller command = plan, till exempel:

# 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"
  }
}

Nästa steg

Skapa en Azure Databricks-arbetsyta.
Hantera arbetsyteresurser för en Azure Databricks-arbetsyta.

Felsökning

Kommentar

Terraform-specifikt stöd finns i de senaste Terraform-ämnena på webbplatsen HashiCorp Discuss. Problem som är specifika för Databricks Terraform-providern finns i Problem i GitHub-lagringsplatsen databrickslabs/terraform-provider-databricks .

Fel: Det gick inte att installera providern

Problem: Om du inte checkade in en terraform.lock.hcl fil till versionskontrollsystemet och kör terraform init kommandot visas följande meddelande: Failed to install provider. Ytterligare utdata kan innehålla ett meddelande som liknar följande:

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"

Orsak: Terraform-konfigurationerna refererar till inaktuella Databricks Terraform-providers.

Lösning:

Ersätt databrickslabs/databricks med databricks/databricks i alla dina .tf filer.

Om du vill automatisera dessa ersättningar kör du följande Python-kommando från den överordnade mappen som innehåller de .tf filer som ska uppdateras:
```
python3 -c "$(curl -Ls https://dbricks.co/updtfns)"
```
Kör följande Terraform-kommando och godkänn sedan ändringarna när du uppmanas att göra det:
```
terraform state replace-provider databrickslabs/databricks databricks/databricks
```
Information om det här kommandot finns i Kommando: tillståndserbytningsprovider i Terraform-dokumentationen.
Kontrollera ändringarna genom att köra följande Terraform-kommando:
```
terraform init
```

Fel: Det gick inte att fråga efter tillgängliga providerpaket

Problem: Om du inte checkade in en terraform.lock.hcl fil till versionskontrollsystemet och kör terraform init kommandot visas följande meddelande: Failed to query available provider packages.

Orsak: Terraform-konfigurationerna refererar till inaktuella Databricks Terraform-providers.

Lösning: Följ lösningsinstruktionerna i Fel: Det gick inte att installera providern.

Aktivera loggning

Databricks Terraform-providern matar ut loggar som du kan aktivera genom att ange TF_LOG miljövariabeln till DEBUG eller någon annan loggnivå som Terraform stöder.

Som standard skickas loggar till stderr. Om du vill skicka loggar till en fil anger du TF_LOG_PATH miljövariabeln till målfilsökvägen.

Du kan till exempel köra följande kommando för att aktivera loggning på felsökningsnivå och för utdataloggar i monokromt format till en fil med namnet tf.log i förhållande till den aktuella arbetskatalogen terraform apply , medan kommandot körs:

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

Mer information om Terraform-loggning finns i Felsöka Terraform.

Ytterligare exempel

Ytterligare resurser

Dokumentation om Databricks-providern på Terraform Registrys webbplats
Terraform-dokumentation på Terraforms webbplats
Lagringsplatsen terraform-databricks-examples i GitHub

Dela via

Databricks Terraform-provider

Komma igång

Krav

Exempelkonfiguration

Testning

Nästa steg

Felsökning

Fel: Det gick inte att installera providern

Fel: Det gick inte att fråga efter tillgängliga providerpaket

Aktivera loggning

Ytterligare exempel

Ytterligare resurser

Feedback

Ytterligare resurser