Provedor Databricks Terraform

O HashiCorp Terraform é uma ferramenta popular de código aberto para criar infraestrutura de nuvem segura e previsível em vários provedores de nuvem. Você pode usar o provedor Databricks Terraform para gerenciar seus Databricks workspaces e a infraestrutura de nuvem associada usando uma ferramenta flexível e poderosa. O objetivo do provedor Databricks Terraform é dar suporte a todas as APIs REST Databricks, dando suporte à automação dos aspectos mais complicados da implantação e gerenciamento de suas plataformas de dados. Os clientes Databricks estão usando o provedor Databricks Terraform para implantar e gerenciar clusters e trabalhos e configurar o acesso a dados. Você utiliza o provedor Databricks Terraform para provisionar Databricks workspaces, bem como o provedor AWS para provisionar os recursos necessários do AWS para esses espaços de trabalho.

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

resource "databricks_job" "this" {
  name = var.job_name
  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"
```
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 para notebook_url, cluster_urle job_urle 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 e terraform 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.

Próximos passos

Crie um workspace e infra-estrutura relacionada.
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 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)"
```
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.

Exemplos adicionais

Criar espaços de trabalho do Databricks com o Terraform

Criar um painel legado de amostra

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