Provedor Terraform do Databricks

O HashiCorp Terraform é uma ferramenta de software livre popular para criar uma infraestrutura de nuvem segura e previsível em vários provedores de nuvem. Você pode usar o provedor Terraform do Databricks para gerenciar os seus workspaces do Azure Databricks e a infraestrutura de nuvem associada usando uma ferramenta avançada e flexível. A meta do provedor Terraform Databricks é dar suporte a todas as APIs REST do Databricks, com suporte para a automação dos aspectos mais complicados da implantação e do gerenciamento das suas plataformas de dados. Os clientes do Databricks estão usando o provedor Databricks Terraform para implantar e gerenciar clusters e trabalhos e configurar o acesso aos dados. Você usa o Provedor do Azure para provisionar workspaces do Azure Databricks.

Introdução

Nesta seção, instale e configure os requisitos para usar o Terraform e o provedor Terraform do Databricks em seu computador de desenvolvimento local. Em seguida, configure a autenticação do Terraform. Após esta seção, este artigo fornecerá uma configuração de amostraque você pode experimentar para provisionar um notebook do Azure Databricks, um cluster e um trabalho para executar o notebook no cluster em um espaço de trabalho existente do Azure Databricks.

Requisitos

1. Você deve ter a CLI do Terraform. Confira Download Terraform (Baixar o Terraform) no site do Terraform.

2. Você deve ter um projeto do Terraform. No seu terminal, crie um diretório vazio e alterne para ele. (Cada conjunto separado de arquivos de configuração do Terraform precisa estar no próprio diretório, que é chamado de projeto Terraform.) Por exemplo: mkdir terraform_demo && cd terraform_demo.

   mkdir terraform_demo && cd terraform_demo
   

   Inclua as configurações do Terraform para o seu projeto em um ou mais arquivos de configuração no seu projeto do Terraform. Para obter informações sobre a sintaxe do arquivo de configuração, confira Documentação da Linguagem do Terraform no site do Terraform.

3. Você deve adicionar ao seu projeto do Terraform uma dependência para o provedor Terraform do Databricks. Adicione o seguinte a um dos arquivos de configuração em seu projeto do Terraform:

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

4. Você deve configurar a autenticação para seu projeto do Terraform. Consulte Autenticação na documentação do provedor Terraform do Databricks.

Exemplo de configuração

Esta seção fornece uma configuração de exemplo que você pode experimentar para provisionar um notebook, um cluster e um trabalho do Azure Databricks para executar o notebook no cluster, em um workspace existente do Azure Databricks. Ela pressupõe que você já configurou os requisitos, bem como criou um projeto do Terraform e configurou o projeto com a autenticação do Terraform, conforme descrito na seção anterior.

1. Crie um arquivo chamado me.tf em seu projeto do Terraform e adicione o seguinte código. Esse arquivo obtém informações sobre o usuário atual (você):

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

2. Crie outro arquivo chamado notebook.tf e adicione o código a seguir. Esse arquivo representa o 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. Crie outro arquivo chamado notebook.auto.tfvars e adicione o código a seguir. Esse arquivo especifica as propriedades do bloco de anotações.

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

4. Crie outro arquivo chamado notebook-getting-started.py e adicione o código a seguir. Esse arquivo representa o conteúdo do bloco de anotações.

   display(spark.range(10))
   

5. Crie outro arquivo chamado cluster.tf e adicione o código a seguir. Esse arquivo representa o 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. Crie outro arquivo chamado cluster.auto.tfvars e adicione o código a seguir. Esse arquivo especifica as propriedades do cluster.

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

7. Crie outro arquivo chamado job.tf e adicione o código a seguir. Esse arquivo representa o trabalho que executa o notebook no 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. Crie outro arquivo chamado job.auto.tfvars e adicione o código a seguir. Esse arquivo especifica as propriedades dos trabalhos.

   job_name = "My Job"
   task_key = "my_task"
   

9. Execute terraform plan. Em caso de erros, corrija-os e execute o comando novamente.

10. Execute terraform apply.

11. Verifique se o notebook, o cluster e o trabalho foram criados: na saída do comando terraform apply, localize as URLs de notebook_url, cluster_url e job_url. Depois, acesse-as.

12. Execute o trabalho: na página Trabalhos, clique em Executar agora. Após a conclusão do trabalho, verifique a sua caixa de entrada de email.

13. Quando terminar este exemplo, exclua o notebook, o cluster e o trabalho do workspace do Azure Databricks executando terraform destroy.

    Observação

    Para obter mais informações sobre os comandos terraform plan, terraform apply e terraform destroy, confira Documentação da CLI do Terraform na documentação do Terraform.

14. Verifique se o notebook, o cluster e o trabalho foram excluídos: atualize o notebook, o cluster e as páginas dos Trabalhos para que cada um exiba uma mensagem informando que os recursos não foram encontrados.

Testando

Teste suas configurações do Terraform antes ou depois de implementá-las. Você pode executar testes análogos aos testes de unidade antes de implantar recursos. Você também pode executar testes análogos aos testes de integração após a implantação dos recursos. Veja Testes na documentação do Terraform.

Execute testes análogos aos testes de integração na configuração de exemplo deste artigo seguindo este processo:

1. Crie um arquivo chamado cluster.tftest.hcl e adicione o código a seguir. Esse arquivo testa se o cluster implementado tem o nome de cluster 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. Crie um arquivo chamado job.tftest.hcl e adicione o código a seguir. Esse arquivo testa se o trabalho implementado tem o nome de trabalho 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. Crie um arquivo chamado notebook.tftest.hcl e adicione o código a seguir. Esse arquivo testa se o notebook implantado tem o caminho esperado do espaço de trabalho.

   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. Execute terraform test. O Terraform implanta cada recurso no espaço de trabalho do Azure Databricks, executa cada teste relacionado e relata o resultado do teste e, em seguida, desmonta o recurso implantado.

Execute testes análogos a testes de unidade em relação à configuração de exemplo deste artigo com o seguinte processo:

• Altere a linha command = apply em cada um dos testes anteriores para command = plan e execute terraform test. O Terraform executa cada teste relacionado e relata o resultado do teste, mas não implanta nenhum recurso.
• Simule o provedor Databricks Terraform, que permite executar terraform test sem implantar recursos e também sem exigir credenciais de autenticação. Veja Simulações na documentação do Terraform. Para executar testes simulados, uma abordagem é adicionar a linha mock_provider "databricks" {} aos seus testes e remover a linha command = apply ou command = plan, por exemplo:

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

Próximas etapas

• Criar um workspace no Azure Databricks.

• Gerenciar recursos do workspace
• Criar um cluster, um notebook e um trabalho
• Automatizar a configuração do Catálogo do Unity
• Controlar o acesso a tabelas do Databricks SQL
• Criar uma amostra de painel

Recursos adicionais

• Databricks Provider Documentation (Documentação do provedor do Databricks) no site do Terraform Registry
• Terraform Documentation (Documentação do Terraform) no site do Terraform
• Repositório Github de exemplos do Terraform do Databricks