Provedor Databricks Terraform
HashiCorp Terraform é uma ferramenta popular de código aberto para criar infraestrutura clouds segura e previsível em vários provedores clouds . Você pode usar o provedor Databricks Terraform para gerenciar seu workspace Databricks e a infraestrutura clouds associada usando uma ferramenta flexível e poderosa. O objetivo do provedor Databricks Terraform é oferecer suporte a todas as APIs REST do Databricks, apoiando a automação dos aspectos mais complicados de implantação e gerenciamento de suas plataformas de dados. Os clientes do Databricks estão usando o provedor Databricks Terraform para implantar e gerenciar clusters e Job e para configurar o acesso a dados. Você usa o provedor Databricks Terraform para provisionar workspace do Databricks, bem como o fornecedor Google da plataforma cloud para provisionar o recurso Google clouds Platform necessário para esses workspace.
Primeiros passos
Nesta seção, você instala e configura requisitos para usar o Terraform e o provedor Databricks Terraform em sua máquina de desenvolvimento local. Em seguida, você configura a autenticação do Terraform. Após esta seção, este artigo fornece um exemplo de configuração que você pode experimentar para provisionar um Databricks Notebook, clusters e um Job para executar o Notebook nos clusters em um espaço de trabalho existente do Databricks.
Requisitos
Você deve ter a CLI do Terraform. Consulte Baixe o Terraform no site do Terraform.
Você deve ter um projeto Terraform. No seu terminal, crie um diretório vazio e depois mude para ele. (Cada conjunto separado de arquivos de configuração do Terraform deve estar em seu próprio diretório, que é chamado de projeto Terraform.) Por exemplo:
mkdir terraform_demo && cd terraform_demo
.mkdir terraform_demo && cd terraform_demo
Inclua configurações do Terraform para seu projeto em um ou mais arquivos de configuração em seu projeto Terraform. Para obter informações sobre a sintaxe do arquivo de configuração, consulte a documentação da linguagem Terraform no site do Terraform.
Você deve adicionar ao seu projeto Terraform uma dependência para o provedor Databricks Terraform. Adicione o seguinte a um dos arquivos de configuração em seu projeto Terraform:
terraform { required_providers { databricks = { source = "databricks/databricks" } } }
Você deve configurar a autenticação para seu projeto Terraform. Consulte Autenticação na documentação do provedor Databricks Terraform.
Exemplo de configuração
Esta seção apresenta uma configuração de exemplo que você pode experimentar para provisionar um notebook, um cluster e um job do Databricks para executar o notebook no cluster em um Databricks workspace existente. Ele pressupõe que você já configurou os requisitos, bem como criou um projeto do Terraform e configurou o projeto com autenticação do Terraform conforme descrito na seção anterior.
Crie um arquivo chamado
me.tf
em seu projeto Terraform e adicione o código a seguir. Este arquivo obtém informações sobre o usuário atual (você):# Retrieve information about the current user. data "databricks_current_user" "me" {}
Crie outro arquivo denominado
notebook.tf
e adicione o código a seguir. Este 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 }
Crie outro arquivo chamado
notebook.auto.tfvars
e adicione o código a seguir. Este arquivo especifica as propriedades do notebook.notebook_subdirectory = "Terraform" notebook_filename = "notebook-getting-started.py" notebook_language = "PYTHON"
Crie outro arquivo chamado
notebook-getting-started.py
e adicione o código a seguir. Este arquivo representa o conteúdo do notebook.display(spark.range(10))
Crie outro arquivo chamado
cluster.tf
e adicione o código a seguir. Este 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 }
Crie outro arquivo chamado
cluster.auto.tfvars
e adicione o código a seguir. Este arquivo especifica as propriedades do cluster.cluster_name = "My Cluster" cluster_autotermination_minutes = 60 cluster_num_workers = 1
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 }
Crie outro arquivo chamado
job.auto.tfvars
e adicione o código a seguir. Este arquivo especifica as propriedades das tarefas.job_name = "My Job" task_key = "my_task"
Execute
terraform plan
. Se houver algum erro, corrija-o e execute o comando novamente.Execute
terraform apply
.Verifique se o notebook, o cluster e o trabalho foram criados: na saída do comando
terraform apply
, localize as URLs paranotebook_url
,cluster_url
ejob_url
e acesse-as.Execute o trabalho: na página Trabalhos, clique em Executar agora. Após a conclusão do trabalho, verifique sua caixa de entrada de e-mail.
Quando terminar este exemplo, exclua o bloco de anotações, o cluster e o trabalho do Databricks workspace executando
terraform destroy
.Observação
Para obter mais informações sobre o comando
terraform plan
,terraform apply
eterraform destroy
, consulte Documentação CLI do Terraform na documentação do Terraform.Verifique se o notebook, o cluster e o trabalho foram excluídos: atualize as páginas de notebook, cluster e trabalhos para que cada uma exiba uma mensagem informando que o recurso não pode ser encontrado.
Testes
Teste suas configurações de Terraform antes ou depois de implantá-las. O senhor pode executar testes análogos aos testes unitários antes de implantar o recurso. O senhor também pode executar testes análogos aos testes de integração depois que os recursos forem implantados. Consulte Testes na documentação do Terraform.
Execute testes análogos aos testes de integração na configuração de amostra deste artigo seguindo este processo:
Crie um arquivo chamado
cluster.tftest.hcl
e adicione o seguinte código. Esse arquivo testa se o cluster implantado 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" } }
Crie um arquivo chamado
job.tftest.hcl
e adicione o seguinte código. Esse arquivo testa se o site implantado Job tem o nome esperado Job.run "job_name_test" { command = apply assert { condition = databricks_job.this.name == var.job_name error_message = "Job name did not match expected name" } }
Crie um arquivo chamado
notebook.tftest.hcl
e adicione o seguinte código. Esse arquivo testa se o site Notebook implantado tem o caminho workspace esperado.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" } }
execução
terraform test
. Terraform O senhor pode implantar cada recurso no site Databricks workspace, executar cada teste relacionado e relatar o resultado do teste e, em seguida, remover o recurso implantado.
executar testes análogos aos testes de unidade na configuração de amostra deste artigo com o seguinte processo:
Altere a linha
command = apply
em cada um dos testes anteriores paracommand = plan
e, em seguida, executeterraform test
. Terraform executa cada teste relacionado e informa o resultado do teste, mas não implanta nenhum recurso.Simule o provedor Databricks Terraform , que permite que o senhor execute
terraform test
sem recurso implantado e também sem exigir nenhuma credencial de autenticação. Consulte Mocks na documentação do Terraform. Para executar testes simulados, uma abordagem é adicionar a linhamock_provider "databricks" {}
aos seus testes e remover a linhacommand = apply
oucommand = 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óximos passos
Gerenciar recursos de workspace para um Databricks workspace.
Solução de problemas
Observação
Para obter suporte específico do Terraform, consulte os tópicos mais recentes do Terraform no site HashiCorp Discuss. Para problemas específicos do Databricks Terraform Provider, consulte 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
em seu sistema de controle de versão e executou o comando terraform init
, a seguinte mensagem será exibida: 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 fazem referência a provedores Databricks Terraform desatualizados.
Solução:
Substitua
databrickslabs/databricks
pordatabricks/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)"
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, consulte Comando: state replace-provider na documentação do Terraform.
Verifique as alterações executando o seguinte comando do Terraform:
terraform init
Erro: falha na consulta de pacotes de provedores disponíveis
Problema: se você não fez check-in de um arquivo terraform.lock.hcl
em seu sistema de controle de versão e executou o comando terraform init
, será exibida a seguinte mensagem: Failed to query available provider packages
.
Causa: suas configurações do Terraform fazem referência a provedores Databricks Terraform desatualizados.
Solução: siga as instruções da solução em Erro: falha na instalação do provedor.
Ativar o registro
O provedor Databricks Terraform gera logs que o senhor pode ativar definindo a variável de ambiente TF_LOG
como DEBUG
ou qualquer outro nível de log compatível com o Terraform.
Por default, logs é enviado 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, o senhor pode executar o seguinte comando para ativar o registro no nível de depuração e gerar o registro em formato monocromático em um arquivo chamado tf.log
relativo 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 Terraform, consulte depuração Terraform.
Recursos adicionais
Documentação do provedor Databricks no site do Registro do Terraform
Documentação do Terraform no site do Terraform
O repositório terraform-databricks-examples no GitHub