Fournisseur Databricks Terraform

Article
05/06/2024

HashiCorp Terraform est un outil open source populaire permettant de créer une infrastructure cloud sécurisée et prévisible sur plusieurs fournisseurs cloud. Vous pouvez utiliser le fournisseur Databricks Terraform pour gérer vos espaces de travail Azure Databricks et l’infrastructure cloud associée à l’aide d’un outil flexible et puissant. Le fournisseur Databricks Terraform a pour objectif de prendre en charge toutes les API REST Databricks, en supportant l’automatisation des aspects les plus complexes du déploiement et de la gestion de vos plateformes de données. Les clients Databricks utilisent le fournisseur Databricks Terraform pour déployer et gérer des clusters et des travaux, ainsi que pour configurer l’accès aux données. Vous utilisez le fournisseur Azure pour provisionner des espaces de travail Azure Databricks.

Bien démarrer

Dans cette section, vous installez et configurez les conditions requises pour utiliser Terraform et le fournisseur Databricks Terraform sur votre ordinateur de développement local. Vous pouvez ensuite configurer l’authentification Terraform. Après cette section, cet article fournit un exemple de configuration que vous pouvez expérimenter pour approvisionner un notebook Azure Databricks, un cluster et un travail pour exécuter le notebook sur le cluster dans un espace de travail Azure Databricks existant.

Spécifications

Vous devez disposer de l’interface CLI Terraform. Consultez Télécharger Terraform sur le site web de Terraform.
Vous devez disposer d’un projet Terraform. Dans votre terminal, créez un répertoire vide, puis basculez vers celui-ci. (Chaque ensemble distinct de fichiers de configuration Terraform doit se trouver dans son propre répertoire, ce qui s’appelle un projet Terraform.) Par exemple : mkdir terraform_demo && cd terraform_demo.
```
mkdir terraform_demo && cd terraform_demo
```
Incluez les configurations Terraform pour votre projet dans un ou plusieurs fichiers de configuration dans votre projet Terraform. Pour plus d’informations sur la syntaxe du fichier de configuration, consultez la documentation du langage Terraform sur le site web de Terraform.
Vous devez ajouter à votre projet Terraform une dépendance pour le fournisseur Databricks Terraform. Ajoutez ce qui suit à l’un des fichiers de configuration de votre projet Terraform :
```
terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}
```
Vous devez configurer l’authentification pour votre projet Terraform. Consultez Authentification dans la documentation du fournisseur Databricks Terraform.

Exemple de configuration

Cette section fournit un échantillon de configuration que vous pouvez tester pour approvisionner un notebook, un cluster et une tâche Azure Databricks. Vous pourrez ainsi exécuter le notebook sur le cluster, dans un espace de travail Azure Databricks existant. Il part du principe que vous avez déjà configuré les exigenceset que vous avez créé un projet Terraform et configuré le projet avec l’authentification Terraform, comme décrit dans la section précédente.

Créez un fichier nommé me.tf dans votre projet Terraform et ajoutez le code suivant. Ce fichier obtient des informations sur l’utilisateur actuel (vous) :
```
# Retrieve information about the current user.
data "databricks_current_user" "me" {}
```

Créez un autre fichier nommé notebook.tf, puis ajoutez le code suivant. Ce fichier représente le 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
}

Créez un autre fichier nommé notebook.auto.tfvars, puis ajoutez le code suivant. Ce fichier spécifie les propriétés du notebook.
```
notebook_subdirectory = "Terraform"
notebook_filename     = "notebook-getting-started.py"
notebook_language     = "PYTHON"
```
Créez un autre fichier nommé notebook-getting-started.py, puis ajoutez le code suivant. Ce fichier représente le contenu du notebook.
```
display(spark.range(10))
```

Créez un autre fichier nommé cluster.tf, puis ajoutez le code suivant. Ce fichier représente le 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
}

Créez un autre fichier nommé cluster.auto.tfvars, puis ajoutez le code suivant. Ce fichier spécifie les propriétés du cluster.
```
cluster_name                    = "My Cluster"
cluster_autotermination_minutes = 60
cluster_num_workers             = 1
```

Créez un autre fichier nommé job.tf, puis ajoutez le code suivant. Ce fichier représente la tâche qui exécute le notebook sur le 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
}

Créez un autre fichier nommé job.auto.tfvars, puis ajoutez le code suivant. Ce fichier spécifie les propriétés du cluster.
```
job_name = "My Job"
task_key = "my_task"
```
Exécutez terraform plan. S’il existe des erreurs, corrigez-les, puis réexécutez la commande.
Exécutez terraform apply.
Vérifiez que le notebook, le cluster et la tâche ont été créés : dans la sortie de la commande terraform apply, recherchez les URL pour notebook_url, cluster_url, job_url, puis accédez à celles-ci.
Exécutez le travail : dans la page Jobs, cliquez sur Run Now. Une fois le travail terminé, consultez votre messagerie.
Quand vous avez fini d’utiliser cet échantillon, exécutez terraform destroy pour supprimer le notebook et la tâche de l’espace de travail Azure Databricks.

Remarque

Pour plus d’informations sur les commandes terraform plan, terraform apply et terraform destroy, consultez la documentation sur l’interface CLI Terraform dans la documentation Terraform.
Vérifiez que le notebook, le cluster et la tâche ont été supprimés : actualisez le notebook et les pages Tâches pour afficher un message indiquant que la ressource est introuvable.

Test

Testez vos configurations Terraform avant ou après leur déploiement. Vous pouvez exécuter des tests analogues aux tests unitaires avant de déployer des ressources. Vous pouvez également exécuter des tests analogues aux tests d’intégration après le déploiement des ressources. Consultez Tests dans la documentation de Terraform.

Exécutez des tests analogues aux tests d’intégration en fonction de l’exemple de configuration de cet article en suivant ce processus :

Créez un fichier nommé cluster.tftest.hcl, puis ajoutez le code suivant. Ce fichier teste si le cluster déployé porte le nom de cluster attendu.

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

Créez un fichier nommé job.tftest.hcl, puis ajoutez le code suivant. Ce fichier teste si le travail déployé porte le nom de travail attendu.

run "job_name_test" {
  command = apply

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

Créez un fichier nommé notebook.tftest.hcl, puis ajoutez le code suivant. Ce fichier teste si le notebook déployé dispose du chemin d’accès d’espace de travail attendu.

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

Exécutez terraform test. Terraform déploie chaque ressource sur l’espace de travail Azure Databricks, exécute chaque test associé, et rapporte le résultat de test, puis supprime la ressource déployée.

Exécutez des tests analogues aux tests unitaires en fonction de l’exemple de configuration de cet article à l’aide du processus suivant :

Remplacez la ligne command = apply dans chacun des tests précédents par command = plan, puis exécutez terraform test. Terraform exécute chaque test associé, puis rapporte le résultat de test, mais ne déploie aucune ressource.
Simulez le fournisseur Databricks Terraform pour pouvoir exécuter terraform test sans déployer de ressources, et sans nécessiter d’informations d’identification d’authentification. Consultez Mocks (simulations) dans la documentation de Terraform. Pour exécuter des tests fictifs, il existe une approche qui consiste à ajouter la ligne mock_provider "databricks" {} à vos tests et à supprimer la ligne command = apply ou command = plan, par exemple :

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

Étapes suivantes

Créez un espace de travail Azure Databricks.
Gérez les ressources d’espace de travail pour un espace de travail Azure Databricks.

Dépannage

Notes

Pour un support spécifique à Terraform, consultez les dernières rubriques sur Terraform sur le site web Discuss de HashiCorp. Pour les problèmes spécifiques au fournisseur Databricks Terraform, consultez les problèmes dans le dépôt GitHub databrickslabs/terraform-provider-databricks.

Erreur : échec d’installation du fournisseur

Problème : si vous n’avez pas enregistré de fichier terraform.lock.hcl dans votre système de gestion de version et que vous exécutez la commande terraform init, le message suivant s’affiche : Failed to install provider. Une sortie supplémentaire peut indiquer un message de ce type :

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"

Cause : vos configurations Terraform référencent des fournisseurs Terraform Databricks obsolètes.

Solution:

Remplacez databrickslabs/databricks par databricks/databricks dans tous vos fichiers .tf.

Pour automatiser ces remplacements, exécutez la commande Python suivante à partir du dossier parent qui contient les fichiers .tf à mettre à jour :
```
python3 -c "$(curl -Ls https://dbricks.co/updtfns)"
```
Exécutez la commande Terraform suivante, puis approuvez les changements quand vous y êtes invité :
```
terraform state replace-provider databrickslabs/databricks databricks/databricks
```
Pour plus d’informations sur cette commande, consultez Commande : state replace-provider dans la documentation Terraform.
Vérifiez les changements en exécutant la commande Terraform suivante :
```
terraform init
```

Erreur : échec d’interrogation des packages de fournisseur disponibles

Cause : vos configurations Terraform référencent des fournisseurs Terraform Databricks obsolètes.

Solution : suivez les instructions de la solution correspondant à Erreur : échec d’installation du fournisseur.

Activation de la journalisation

Le fournisseur Databricks Terraform génère des journaux d’activité activables en définissant la variable d’environnement TF_LOG sur DEBUG, ou sur tout autre niveau du journal pris en charge par Terraform.

Par défaut, les journaux sont envoyés à stderr. Pour envoyer des journaux à un fichier, définissez la variable d’environnement TF_LOG_PATH sur le chemin du fichier cible.

Par exemple, vous pouvez exécuter la commande suivante pour activer la journalisation au niveau du débogage et pour générer des journaux au format monochrome dans un fichier nommé tf.log par rapport au répertoire de travail actuel, tandis que la commande terraform apply s’exécute :

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

Pour plus d’informations sur la journalisation Terraform, consultez Débogage de Terraform.

Exemples supplémentaires

Ressources supplémentaires

Documentation sur le fournisseur Databricks sur le site web Registry de Terraform
Documentation Terraform sur le site web de Terraform
Dépôt terraform-databricks-examples dans GitHub

Fournisseur Databricks Terraform

Bien démarrer

Spécifications

Exemple de configuration

Test

Étapes suivantes

Dépannage

Erreur : échec d’installation du fournisseur

Erreur : échec d’interrogation des packages de fournisseur disponibles

Activation de la journalisation

Exemples supplémentaires

Ressources supplémentaires

Commentaires

Commentaires

Ressources supplémentaires