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

  1. Você deve ter a CLI do Terraform. Consulte Baixe o Terraform no site do Terraform.

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

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

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

  1. 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" {}

  2. 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
}

  3. 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"

  4. 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))

  5. 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
}

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

  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. Este arquivo especifica as propriedades das tarefas.

    job_name = "My Job"
task_key = "my_task"

  9. Execute terraform plan. Se houver algum erro, corrija-o 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 para notebook_url, cluster_urle job_urle acesse-as.

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

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

  14. 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:

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

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

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

  4. 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 para command = plan e, em seguida, execute terraform 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 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"
  }
}

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:

  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, consulte Comando: state replace-provider na documentação do Terraform.

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