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 notebook.

   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 notebook.

   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 do cluster.

   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 esse 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 aos testes de unidade na configuração de exemplo desse 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

1. Criar um workspace no Azure Databricks.
2. Gerenciar recursos do workspace do Azure Databricks.

Solução de problemas

Observação

Para obter suporte específico para o Terraform, confira os Latest Terraform topics (Tópicos mais recentes sobre o Terraform) no site do HashiCorp Discuss. Para ver problemas específicos do Provedor Terraform do Databricks, confira Issues (Problemas) no repositório GitHub databrickslabs/terraform-provider-databricks.

Erro: falha na instalação do provedor

Problema: se você não fez check-in de um arquivo terraform.lock.hcl para o sistema de controle de versão e executou o comando terraform init, a seguinte mensagem aparece: Failed to install provider. A saída adicional pode incluir uma mensagem semelhante à seguinte:

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: suas configurações do Terraform referenciam provedores do Databricks Terraform desatualizados.

Solução:

1. Substitua databrickslabs/databricks por databricks/databricks em todos os seus arquivos .tf.

   Para automatizar essas substituições, execute o seguinte comando Python na pasta pai que contém os arquivos .tf a serem atualizados:

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

2. Execute o seguinte comando do Terraform e aprove as alterações quando solicitado:

   terraform state replace-provider databrickslabs/databricks databricks/databricks
   

   Para obter informações sobre esse comando, confira Comando: state replace-provider na documentação do Terraform.

3. Verifique a alteração ao executar o seguinte comando do Terraform:

   terraform init
   

Erro: falha na consulta de pacotes de provedor disponíveis

Problema: se você não fez check-in de um arquivo terraform.lock.hcl para o sistema de controle de versão e executou o comando terraform init, a seguinte mensagem aparece: Failed to query available provider packages.

Causa: suas configurações do Terraform referenciam provedores do Databricks Terraform desatualizados.

Solução: siga as instruções de solução em Erro: falha na instalação do provedor.

Habilitar o registro em log

O provedor Terraform do Databricks gera logs que você pode habilitar definindo a variável de ambiente TF_LOG para DEBUG ou qualquer outro nível de log compatível com o Terraform.

Por padrão, os logs são enviados para stderr. Para enviar logs para um arquivo, defina a variável de ambiente TF_LOG_PATH como o caminho do arquivo de destino.

Por exemplo, você pode executar o seguinte comando para habilitar o registro em log no nível de depuração e gerar logs no formato monocromático para um arquivo chamado tf.log em relação ao diretório de trabalho atual, enquanto o comando terraform apply é executado:

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

Para obter mais informações sobre o registro em log do Terraform, consulte Depurando o Terraform.

Mais exemplos

• Implantar um workspace do Azure Databricks usando o Terraform

• Gerenciar workspaces do Databricks usando o Terraform

• Criar clusters

• Criar um cluster, um notebook e um trabalho

• Controlar o acesso a tabelas do Databricks SQL

• Implementar pipelines de CI/CD para implantar recursos do Databricks usando o provedor Databricks Terraform

• 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
• O repositório terraform-databricks-examples no GitHub