Databricks Terraform-provider

  • Artikel

HashiCorp Terraform is een populair opensource-hulpprogramma voor het maken van een veilige en voorspelbare cloudinfrastructuur tussen verschillende cloudproviders. U kunt de Databricks Terraform-provider gebruiken om uw Azure Databricks-werkruimten en de bijbehorende cloudinfrastructuur te beheren met behulp van een flexibel, krachtig hulpprogramma. Het doel van de Databricks Terraform-provider is het ondersteunen van alle Databricks REST API's, die automatisering ondersteunen van de meest gecompliceerde aspecten van het implementeren en beheren van uw gegevensplatforms. Databricks-klanten gebruiken de Databricks Terraform-provider om clusters en taken te implementeren en beheren en om gegevenstoegang te configureren. U gebruikt de Azure-provider om Azure Databricks-werkruimten in te richten.

Aan de slag

In deze sectie installeert en configureert u vereisten voor het gebruik van Terraform en de Databricks Terraform-provider op uw lokale ontwikkelcomputer. Vervolgens configureert u Terraform-verificatie. Na deze sectie bevat dit artikel een voorbeeldconfiguratie waarmee u kunt experimenteren om een Azure Databricks-notebook, -cluster en een taak in te richten voor het uitvoeren van het notebook op het cluster in een bestaande Azure Databricks-werkruimte.

Vereisten

  1. U moet de Terraform CLI hebben. Zie Terraform downloaden op de Terraform-website.

  2. U moet een Terraform-project hebben. Maak in uw terminal een lege map en ga vervolgens naar de map. (Elke afzonderlijke set Terraform-configuratiebestanden moet zich in een eigen map bevinden. Dit wordt een Terraform-project genoemd.) Bijvoorbeeld: mkdir terraform_demo && cd terraform_demo.

    mkdir terraform_demo && cd terraform_demo

    Neem Terraform-configuraties voor uw project op in een of meer configuratiebestanden in uw Terraform-project. Zie de terraform-taaldocumentatie op de Terraform-website voor informatie over de syntaxis van het configuratiebestand.

  3. U moet een afhankelijkheid toevoegen aan uw Terraform-project voor de Databricks Terraform-provider. Voeg het volgende toe aan een van de configuratiebestanden in uw Terraform-project:

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

  4. U moet verificatie configureren voor uw Terraform-project. Zie verificatie in de documentatie van de Databricks Terraform-provider.

Voorbeeldconfiguratie

Deze sectie bevat een voorbeeldconfiguratie waarmee u kunt experimenteren om een Azure Databricks-notebook, een cluster en een taak in te richten voor het uitvoeren van het notebook op het cluster in een bestaande Azure Databricks-werkruimte. Hierbij wordt ervan uitgegaan dat u de vereisten al hebt ingesteld, evenals een Terraform-project hebt gemaakt en het project hebt geconfigureerd met Terraform-verificatie, zoals beschreven in de vorige sectie.

  1. Maak een bestand met de naam me.tf in uw Terraform-project en voeg de volgende code toe. Dit bestand krijgt informatie over de huidige gebruiker (u):

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

  2. Maak een ander bestand met de naam notebook.tfen voeg de volgende code toe. Dit bestand vertegenwoordigt het 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. Maak een ander bestand met de naam notebook.auto.tfvarsen voeg de volgende code toe. Dit bestand geeft de eigenschappen van het notitieblok op.

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

  4. Maak een ander bestand met de naam notebook-getting-started.pyen voeg de volgende code toe. Dit bestand vertegenwoordigt de inhoud van het notitieblok.

    display(spark.range(10))

  5. Maak een ander bestand met de naam cluster.tfen voeg de volgende code toe. Dit bestand vertegenwoordigt het 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. Maak een ander bestand met de naam cluster.auto.tfvarsen voeg de volgende code toe. Dit bestand geeft de eigenschappen van het cluster op.

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

  7. Maak een ander bestand met de naam job.tfen voeg de volgende code toe. Dit bestand vertegenwoordigt de taak die het notebook uitvoert op het 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. Maak een ander bestand met de naam job.auto.tfvarsen voeg de volgende code toe. Dit bestand geeft de eigenschappen van de taken op.

    job_name = "My Job"
task_key = "my_task"

  9. Voer terraform plan uit. Als er fouten zijn, herstelt u deze en voert u de opdracht opnieuw uit.

  10. Voer terraform apply uit.

  11. Controleer of het notebook, het cluster en de taak zijn gemaakt: zoek in de uitvoer van de terraform apply opdracht de URL's voor notebook_url, cluster_urlen job_urlga naar de url's.

  12. Voer de taak uit: klik op de pagina Taken op Nu uitvoeren. Nadat de taak is voltooid, schakelt u het Postvak IN van uw e-mail in.

  13. Wanneer u klaar bent met dit voorbeeld, verwijdert u het notebook, het cluster en de taak uit de Azure Databricks-werkruimte door deze uit te voeren terraform destroy.

    Notitie

    Zie de Terraform CLI-documentatie in de Terraform-documentatie voor meer informatie over de terraform applyterraform planen terraform destroy opdrachten in de Terraform-documentatie.

  14. Controleer of het notebook, het cluster en de taak zijn verwijderd: vernieuw de pagina's notebook, cluster en taken om elk bericht weer te geven dat de resource niet kan worden gevonden.

Testen

Test uw Terraform-configuraties vóór of nadat u ze hebt geïmplementeerd. U kunt tests uitvoeren die vergelijkbaar zijn met eenheidstests voordat u resources implementeert. U kunt ook tests uitvoeren die vergelijkbaar zijn met integratietests nadat resources zijn geïmplementeerd. Zie Tests in de Terraform-documentatie.

Voer tests uit die vergelijkbaar zijn met integratietests op de voorbeeldconfiguratie van dit artikel door dit proces te volgen:

  1. Maak een bestand met de naam cluster.tftest.hclen voeg de volgende code toe. Met dit bestand wordt getest of het geïmplementeerde cluster de verwachte clusternaam heeft.

    # 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. Maak een bestand met de naam job.tftest.hclen voeg de volgende code toe. Met dit bestand wordt getest of de geïmplementeerde taak de verwachte taaknaam heeft.

    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. Maak een bestand met de naam notebook.tftest.hclen voeg de volgende code toe. Met dit bestand wordt getest of het geïmplementeerde notebook het verwachte werkruimtepad heeft.

    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. Voer terraform test uit. Terraform implementeert elke resource in de Azure Databricks-werkruimte, voert elke gerelateerde test uit en rapporteert het testresultaat en verwijdert vervolgens de geïmplementeerde resource.

Voer tests uit die vergelijkbaar zijn met eenheidstests op basis van de voorbeeldconfiguratie van dit artikel met het volgende proces:

  • Wijzig de regel command = apply in elk van de voorgaande tests command = planin en voer deze uit terraform test. Terraform voert elke gerelateerde test uit en rapporteert het testresultaat, maar implementeert geen resources.
  • Mock the Databricks Terraform provider, waarmee u kunt worden uitgevoerd terraform test zonder resources te implementeren en ook zonder verificatiereferenties. Zie Mocks in de Terraform-documentatie. Als u mocktests wilt uitvoeren, moet u de lijn mock_provider "databricks" {} aan uw tests toevoegen en de regel command = apply verwijderen of command = planbijvoorbeeld:
# 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"
  }
}

Volgende stappen

  1. Maak een Azure Databricks-werkruimte.
  2. Werkruimtebronnen beheren voor een Azure Databricks-werkruimte.

Probleemoplossing

Notitie

Zie de meest recente Terraform-onderwerpen op de website HashiCorp Discuss voor specifieke ondersteuning voor Terraform. Zie Problemen in de GitHub-opslagplaats databricks/terraform-provider-databricks voor problemen die specifiek zijn voor de Databricks Terraform-Provider.

Fout: Kan provider niet installeren

Probleem: Als u een terraform.lock.hcl bestand niet hebt ingecheckt bij uw versiebeheersysteem en u de terraform init opdracht uitvoert, wordt het volgende bericht weergegeven: Failed to install provider Aanvullende uitvoer kan een bericht bevatten dat er ongeveer als volgt uitziet:

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"

Oorzaak: Uw Terraform-configuraties verwijzen naar verouderde Databricks Terraform-providers.

Oplossing:

  1. Vervang databrickslabs/databricks door databricks/databricks al uw .tf bestanden.

    Als u deze vervangingen wilt automatiseren, voert u de volgende Python-opdracht uit vanuit de bovenliggende map die de .tf bestanden bevat die u wilt bijwerken:

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

  2. Voer de volgende Terraform-opdracht uit en keur de wijzigingen goed wanneer hierom wordt gevraagd:

    terraform state replace-provider databrickslabs/databricks databricks/databricks

    Zie Command: state replace-provider in de Terraform-documentatie voor meer informatie over deze opdracht.

  3. Controleer de wijzigingen door de volgende Terraform-opdracht uit te voeren:

    terraform init

Fout: Kan geen query uitvoeren op beschikbare providerpakketten

Probleem: Als u een terraform.lock.hcl bestand niet hebt ingecheckt bij uw versiebeheersysteem en u de terraform init opdracht uitvoert, wordt het volgende bericht weergegeven: Failed to query available provider packages

Oorzaak: Uw Terraform-configuraties verwijzen naar verouderde Databricks Terraform-providers.

Oplossing: Volg de oplossingsinstructies in Fout: Kan provider niet installeren.

Logboekregistratie inschakelen

De Databricks Terraform-provider voert logboeken uit die u kunt inschakelen door de TF_LOG omgevingsvariabele in te DEBUG stellen op of op een ander logboekniveau dat Door Terraform wordt ondersteund.

Logboeken worden standaard verzonden naar stderr. Als u logboeken naar een bestand wilt verzenden, stelt u de TF_LOG_PATH omgevingsvariabele in op het pad naar het doelbestand.

U kunt bijvoorbeeld de volgende opdracht uitvoeren om logboekregistratie op foutopsporingsniveau in te schakelen en logboeken in monochrome indeling uit te voeren naar een bestand met de naam tf.log ten opzichte van de huidige werkmap, terwijl de terraform apply opdracht wordt uitgevoerd:

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

Zie Terraform-foutopsporing voor meer informatie over Terraform-logboekregistratie.

Aanvullende voorbeelden

Aanvullende bronnen