Partilhar via

Fornecedor do Terraform do Databricks

  • Artigo

HashiCorp Terraform é uma ferramenta de código aberto popular 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 espaços de trabalho do Azure Databricks e a infraestrutura de nuvem associada usando uma ferramenta flexível e poderosa. O objetivo do provedor Databricks Terraform é oferecer suporte a todas as APIs REST do Databricks, suportando a automação dos aspetos mais complicados da 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 trabalhos e configurar o acesso aos dados. Você usa o Provedor do Azure para provisionar espaços de trabalho do Azure Databricks.

Introdução

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, configure a autenticação Terraform. Após esta seção, este artigo fornece uma configuração de exemplo que você pode experimentar para provisionar um bloco de anotações, cluster e um trabalho do Azure Databricks para executar o bloco de anotações no cluster em um espaço de trabalho existente do Azure Databricks.

Requisitos

  1. Você deve ter a CLI Terraform. Consulte Download Terraform no site Terraform.

  2. Você deve ter um projeto Terraform. No seu terminal, crie um diretório vazio e, em seguida, 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 Documentação da linguagem Terraform no site da 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.

Configuração de exemplo

Esta seção fornece uma configuração de exemplo que você pode experimentar para provisionar um bloco de anotações do Azure Databricks, um cluster e um trabalho para executar o bloco de anotações no cluster, em um espaço de trabalho existente do Azure Databricks. Ele pressupõe que você já tenha configurado os requisitos, bem como criado um projeto Terraform e configurado o projeto com autenticação Terraform, conforme descrito na seção anterior.

  1. Crie um arquivo nomeado 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 chamado notebook.tfe adicione o código a seguir. Este ficheiro representa o bloco de notas.

    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.tfvarse adicione o código a seguir. Este ficheiro especifica as propriedades do bloco de notas.

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

  4. Crie outro arquivo chamado notebook-getting-started.pye adicione o código a seguir. Este ficheiro representa o conteúdo do bloco de notas.

    display(spark.range(10))

  5. Crie outro arquivo chamado cluster.tfe 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.tfvarse 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.tfe adicione o código a seguir. Esse arquivo representa o trabalho que executa o bloco de anotações 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.tfvarse adicione o código a seguir. Este arquivo especifica as propriedades dos trabalhos.

    job_name = "My Job"
task_key = "my_task"

  9. Execute o terraform plan. Se houver erros, corrija-os e execute o comando novamente.

  10. Execute o terraform apply.

  11. Verifique se o bloco de anotações, o cluster e o trabalho foram criados: na saída do comando, localize as URLs de terraform apply notebook_url, cluster_urle job_url, e vá até elas.

  12. Executar o trabalho: na página Trabalhos, clique em Executar agora. Depois que o trabalho terminar, 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 espaço de trabalho do Azure Databricks executando terraform destroy.

    Nota

    Para obter mais informações sobre os terraform plancomandos , terraform applye , consulte terraform destroy Documentação da CLI do Terraform na documentação do Terraform.

  14. Verifique se o bloco de anotações, o cluster e o trabalho foram excluídos: atualize as páginas do bloco de anotações, do cluster e Trabalhos para que cada uma exiba uma mensagem informando que o recurso não pode ser encontrado.

Testar

Teste suas configurações do Terraform antes ou depois de implantá-las. Você pode executar testes análogos ao teste de unidade antes de implantar recursos. Você também pode executar testes análogos aos testes de integração depois que os recursos são implantados. Consulte 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.hcle adicione o código a seguir. 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.hcle adicione o código a seguir. Esse arquivo testa se o trabalho implantado 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.hcle adicione o código a seguir. Esse arquivo testa se o bloco de anotações implantado tem o caminho de espaço de trabalho 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. Execute o terraform test. O Terraform implanta cada recurso no espaço de trabalho do Azure Databricks, executa cada teste relacionado e relata seu resultado de teste e, em seguida, destrói o recurso implantado.

Execute testes análogos aos testes de unidade na configuração de exemplo deste artigo com o seguinte processo:

  • Altere a linha command = apply em cada um dos testes anteriores para command = plane, em seguida, execute terraform test. O Terraform executa cada teste relacionado e relata seu resultado de teste, mas não implanta nenhum recurso.
  • Simule o provedor Databricks Terraform, que permite terraform test executar sem implantar recursos e também sem exigir credenciais de autenticação. Consulte Mocks na documentação do Terraform. Para executar testes simulados, uma abordagem é adicionar a linha mock_provider "databricks" {} aos 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óximos passos

  1. Crie um espaço de trabalho do Azure Databricks.
  2. Gerencie recursos de espaço de trabalho para um espaço de trabalho do Azure Databricks.

Resolução de Problemas

Nota

Para obter suporte específico do Terraform, consulte os tópicos mais recentes do Terraform no site HashiCorp Discut. Para problemas específicos do Databricks Terraform Provider, consulte Problemas no repositório GitHub databrickslabs/terraform-provider-databricks .

Erro: Falha ao instalar o provedor

Problema: Se você não fez check-in de um terraform.lock.hcl arquivo no sistema de controle de versão e executou o terraform init comando, 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 .tf ficheiros.

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

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

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

    terraform state replace-provider databrickslabs/databricks databricks/databricks

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

  3. Verifique as alterações executando o seguinte comando Terraform:

    terraform init

Erro: Falha ao consultar pacotes de provedor disponíveis

Problema: Se você não fez check-in de um terraform.lock.hcl arquivo no sistema de controle de versão e executou o terraform init comando, a seguinte mensagem será exibida: 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 ao instalar o provedor.

Ativar registo

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

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

Por exemplo, você pode executar o seguinte comando para habilitar o registro em log no nível de depuração e para gerar logs em formato monocromático para um arquivo nomeado tf.log relativo ao diretório de trabalho atual, enquanto o terraform apply comando é 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.

Exemplos adicionais

Recursos adicionais